1 /*
2 * Copyright (c) 2019-2020 Nordic Semiconductor ASA
3 * Copyright (c) 2019 Piotr Mienkowski
4 * Copyright (c) 2017 ARM Ltd
5 * Copyright (c) 2015-2016 Intel Corporation.
6 *
7 * SPDX-License-Identifier: Apache-2.0
8 */
9
10 /**
11 * @file
12 * @brief Public APIs for GPIO drivers
13 */
14
15 #ifndef ZEPHYR_INCLUDE_DRIVERS_GPIO_H_
16 #define ZEPHYR_INCLUDE_DRIVERS_GPIO_H_
17
18 #include <errno.h>
19
20 #include <zephyr/sys/__assert.h>
21 #include <zephyr/sys/slist.h>
22
23 #include <zephyr/types.h>
24 #include <stddef.h>
25 #include <zephyr/device.h>
26 #include <zephyr/dt-bindings/gpio/gpio.h>
27
28 #ifdef __cplusplus
29 extern "C" {
30 #endif
31
32 /**
33 * @brief GPIO Driver APIs
34 * @defgroup gpio_interface GPIO Driver APIs
35 * @ingroup io_interfaces
36 * @{
37 */
38
39 /**
40 * @name GPIO input/output configuration flags
41 * @{
42 */
43
44 /** Enables pin as input. */
45 #define GPIO_INPUT (1U << 16)
46
47 /** Enables pin as output, no change to the output state. */
48 #define GPIO_OUTPUT (1U << 17)
49
50 /** Disables pin for both input and output. */
51 #define GPIO_DISCONNECTED 0
52
53 /** @cond INTERNAL_HIDDEN */
54
55 /* Initializes output to a low state. */
56 #define GPIO_OUTPUT_INIT_LOW (1U << 18)
57
58 /* Initializes output to a high state. */
59 #define GPIO_OUTPUT_INIT_HIGH (1U << 19)
60
61 /* Initializes output based on logic level */
62 #define GPIO_OUTPUT_INIT_LOGICAL (1U << 20)
63
64 /** @endcond */
65
66 /** Configures GPIO pin as output and initializes it to a low state. */
67 #define GPIO_OUTPUT_LOW (GPIO_OUTPUT | GPIO_OUTPUT_INIT_LOW)
68 /** Configures GPIO pin as output and initializes it to a high state. */
69 #define GPIO_OUTPUT_HIGH (GPIO_OUTPUT | GPIO_OUTPUT_INIT_HIGH)
70 /** Configures GPIO pin as output and initializes it to a logic 0. */
71 #define GPIO_OUTPUT_INACTIVE (GPIO_OUTPUT | \
72 GPIO_OUTPUT_INIT_LOW | \
73 GPIO_OUTPUT_INIT_LOGICAL)
74 /** Configures GPIO pin as output and initializes it to a logic 1. */
75 #define GPIO_OUTPUT_ACTIVE (GPIO_OUTPUT | \
76 GPIO_OUTPUT_INIT_HIGH | \
77 GPIO_OUTPUT_INIT_LOGICAL)
78
79 /** @} */
80
81 /**
82 * @name GPIO interrupt configuration flags
83 * The `GPIO_INT_*` flags are used to specify how input GPIO pins will trigger
84 * interrupts. The interrupts can be sensitive to pin physical or logical level.
85 * Interrupts sensitive to pin logical level take into account GPIO_ACTIVE_LOW
86 * flag. If a pin was configured as Active Low, physical level low will be
87 * considered as logical level 1 (an active state), physical level high will
88 * be considered as logical level 0 (an inactive state).
89 * The GPIO controller should reset the interrupt status, such as clearing the
90 * pending bit, etc, when configuring the interrupt triggering properties.
91 * Applications should use the `GPIO_INT_MODE_ENABLE_ONLY` and
92 * `GPIO_INT_MODE_DISABLE_ONLY` flags to enable and disable interrupts on the
93 * pin without changing any GPIO settings.
94 * @{
95 */
96
97 /** Disables GPIO pin interrupt. */
98 #define GPIO_INT_DISABLE (1U << 21)
99
100 /** @cond INTERNAL_HIDDEN */
101
102 /* Enables GPIO pin interrupt. */
103 #define GPIO_INT_ENABLE (1U << 22)
104
105 /* GPIO interrupt is sensitive to logical levels.
106 *
107 * This is a component flag that should be combined with other
108 * `GPIO_INT_*` flags to produce a meaningful configuration.
109 */
110 #define GPIO_INT_LEVELS_LOGICAL (1U << 23)
111
112 /* GPIO interrupt is edge sensitive.
113 *
114 * Note: by default interrupts are level sensitive.
115 *
116 * This is a component flag that should be combined with other
117 * `GPIO_INT_*` flags to produce a meaningful configuration.
118 */
119 #define GPIO_INT_EDGE (1U << 24)
120
121 /* Trigger detection when input state is (or transitions to) physical low or
122 * logical 0 level.
123 *
124 * This is a component flag that should be combined with other
125 * `GPIO_INT_*` flags to produce a meaningful configuration.
126 */
127 #define GPIO_INT_LOW_0 (1U << 25)
128
129 /* Trigger detection on input state is (or transitions to) physical high or
130 * logical 1 level.
131 *
132 * This is a component flag that should be combined with other
133 * `GPIO_INT_*` flags to produce a meaningful configuration.
134 */
135 #define GPIO_INT_HIGH_1 (1U << 26)
136
137 #ifdef CONFIG_GPIO_ENABLE_DISABLE_INTERRUPT
138 /* Disable/Enable interrupt functionality without changing other interrupt
139 * related register, such as clearing the pending register.
140 *
141 * This is a component flag that should be combined with `GPIO_INT_ENABLE` or
142 * `GPIO_INT_DISABLE` flags to produce a meaningful configuration.
143 */
144 #define GPIO_INT_ENABLE_DISABLE_ONLY (1u << 27)
145 #endif /* CONFIG_GPIO_ENABLE_DISABLE_INTERRUPT */
146
147 #define GPIO_INT_MASK (GPIO_INT_DISABLE | \
148 GPIO_INT_ENABLE | \
149 GPIO_INT_LEVELS_LOGICAL | \
150 GPIO_INT_EDGE | \
151 GPIO_INT_LOW_0 | \
152 GPIO_INT_HIGH_1)
153
154 /** @endcond */
155
156 /** Configures GPIO interrupt to be triggered on pin rising edge and enables it.
157 */
158 #define GPIO_INT_EDGE_RISING (GPIO_INT_ENABLE | \
159 GPIO_INT_EDGE | \
160 GPIO_INT_HIGH_1)
161
162 /** Configures GPIO interrupt to be triggered on pin falling edge and enables
163 * it.
164 */
165 #define GPIO_INT_EDGE_FALLING (GPIO_INT_ENABLE | \
166 GPIO_INT_EDGE | \
167 GPIO_INT_LOW_0)
168
169 /** Configures GPIO interrupt to be triggered on pin rising or falling edge and
170 * enables it.
171 */
172 #define GPIO_INT_EDGE_BOTH (GPIO_INT_ENABLE | \
173 GPIO_INT_EDGE | \
174 GPIO_INT_LOW_0 | \
175 GPIO_INT_HIGH_1)
176
177 /** Configures GPIO interrupt to be triggered on pin physical level low and
178 * enables it.
179 */
180 #define GPIO_INT_LEVEL_LOW (GPIO_INT_ENABLE | \
181 GPIO_INT_LOW_0)
182
183 /** Configures GPIO interrupt to be triggered on pin physical level high and
184 * enables it.
185 */
186 #define GPIO_INT_LEVEL_HIGH (GPIO_INT_ENABLE | \
187 GPIO_INT_HIGH_1)
188
189 /** Configures GPIO interrupt to be triggered on pin state change to logical
190 * level 0 and enables it.
191 */
192 #define GPIO_INT_EDGE_TO_INACTIVE (GPIO_INT_ENABLE | \
193 GPIO_INT_LEVELS_LOGICAL | \
194 GPIO_INT_EDGE | \
195 GPIO_INT_LOW_0)
196
197 /** Configures GPIO interrupt to be triggered on pin state change to logical
198 * level 1 and enables it.
199 */
200 #define GPIO_INT_EDGE_TO_ACTIVE (GPIO_INT_ENABLE | \
201 GPIO_INT_LEVELS_LOGICAL | \
202 GPIO_INT_EDGE | \
203 GPIO_INT_HIGH_1)
204
205 /** Configures GPIO interrupt to be triggered on pin logical level 0 and enables
206 * it.
207 */
208 #define GPIO_INT_LEVEL_INACTIVE (GPIO_INT_ENABLE | \
209 GPIO_INT_LEVELS_LOGICAL | \
210 GPIO_INT_LOW_0)
211
212 /** Configures GPIO interrupt to be triggered on pin logical level 1 and enables
213 * it.
214 */
215 #define GPIO_INT_LEVEL_ACTIVE (GPIO_INT_ENABLE | \
216 GPIO_INT_LEVELS_LOGICAL | \
217 GPIO_INT_HIGH_1)
218
219 /** @} */
220
221 /** @cond INTERNAL_HIDDEN */
222 #define GPIO_DIR_MASK (GPIO_INPUT | GPIO_OUTPUT)
223 /** @endcond */
224
225 /**
226 * @brief Identifies a set of pins associated with a port.
227 *
228 * The pin with index n is present in the set if and only if the bit
229 * identified by (1U << n) is set.
230 */
231 typedef uint32_t gpio_port_pins_t;
232
233 /**
234 * @brief Provides values for a set of pins associated with a port.
235 *
236 * The value for a pin with index n is high (physical mode) or active
237 * (logical mode) if and only if the bit identified by (1U << n) is set.
238 * Otherwise the value for the pin is low (physical mode) or inactive
239 * (logical mode).
240 *
241 * Values of this type are often paired with a `gpio_port_pins_t` value
242 * that specifies which encoded pin values are valid for the operation.
243 */
244 typedef uint32_t gpio_port_value_t;
245
246 /**
247 * @brief Provides a type to hold a GPIO pin index.
248 *
249 * This reduced-size type is sufficient to record a pin number,
250 * e.g. from a devicetree GPIOS property.
251 */
252 typedef uint8_t gpio_pin_t;
253
254 /**
255 * @brief Provides a type to hold GPIO devicetree flags.
256 *
257 * All GPIO flags that can be expressed in devicetree fit in the low 16
258 * bits of the full flags field, so use a reduced-size type to record
259 * that part of a GPIOS property.
260 *
261 * The lower 8 bits are used for standard flags. The upper 8 bits are reserved
262 * for SoC specific flags.
263 */
264 typedef uint16_t gpio_dt_flags_t;
265
266 /**
267 * @brief Provides a type to hold GPIO configuration flags.
268 *
269 * This type is sufficient to hold all flags used to control GPIO
270 * configuration, whether pin or interrupt.
271 */
272 typedef uint32_t gpio_flags_t;
273
274 /**
275 * @brief Container for GPIO pin information specified in devicetree
276 *
277 * This type contains a pointer to a GPIO device, pin number for a pin
278 * controlled by that device, and the subset of pin configuration
279 * flags which may be given in devicetree.
280 *
281 * @see GPIO_DT_SPEC_GET_BY_IDX
282 * @see GPIO_DT_SPEC_GET_BY_IDX_OR
283 * @see GPIO_DT_SPEC_GET
284 * @see GPIO_DT_SPEC_GET_OR
285 */
286 struct gpio_dt_spec {
287 /** GPIO device controlling the pin */
288 const struct device *port;
289 /** The pin's number on the device */
290 gpio_pin_t pin;
291 /** The pin's configuration flags as specified in devicetree */
292 gpio_dt_flags_t dt_flags;
293 };
294
295 /**
296 * @brief Static initializer for a @p gpio_dt_spec
297 *
298 * This returns a static initializer for a @p gpio_dt_spec structure given a
299 * devicetree node identifier, a property specifying a GPIO and an index.
300 *
301 * Example devicetree fragment:
302 *
303 * n: node {
304 * foo-gpios = <&gpio0 1 GPIO_ACTIVE_LOW>,
305 * <&gpio1 2 GPIO_ACTIVE_LOW>;
306 * }
307 *
308 * Example usage:
309 *
310 * const struct gpio_dt_spec spec = GPIO_DT_SPEC_GET_BY_IDX(DT_NODELABEL(n),
311 * foo_gpios, 1);
312 * // Initializes 'spec' to:
313 * // {
314 * // .port = DEVICE_DT_GET(DT_NODELABEL(gpio1)),
315 * // .pin = 2,
316 * // .dt_flags = GPIO_ACTIVE_LOW
317 * // }
318 *
319 * The 'gpio' field must still be checked for readiness, e.g. using
320 * device_is_ready(). It is an error to use this macro unless the node
321 * exists, has the given property, and that property specifies a GPIO
322 * controller, pin number, and flags as shown above.
323 *
324 * @param node_id devicetree node identifier
325 * @param prop lowercase-and-underscores property name
326 * @param idx logical index into "prop"
327 * @return static initializer for a struct gpio_dt_spec for the property
328 */
329 #define GPIO_DT_SPEC_GET_BY_IDX(node_id, prop, idx) \
330 { \
331 .port = DEVICE_DT_GET(DT_GPIO_CTLR_BY_IDX(node_id, prop, idx)),\
332 .pin = DT_GPIO_PIN_BY_IDX(node_id, prop, idx), \
333 .dt_flags = DT_GPIO_FLAGS_BY_IDX(node_id, prop, idx), \
334 }
335
336 /**
337 * @brief Like GPIO_DT_SPEC_GET_BY_IDX(), with a fallback to a default value
338 *
339 * If the devicetree node identifier 'node_id' refers to a node with a
340 * property 'prop', this expands to
341 * <tt>GPIO_DT_SPEC_GET_BY_IDX(node_id, prop, idx)</tt>. The @p
342 * default_value parameter is not expanded in this case.
343 *
344 * Otherwise, this expands to @p default_value.
345 *
346 * @param node_id devicetree node identifier
347 * @param prop lowercase-and-underscores property name
348 * @param idx logical index into "prop"
349 * @param default_value fallback value to expand to
350 * @return static initializer for a struct gpio_dt_spec for the property,
351 * or default_value if the node or property do not exist
352 */
353 #define GPIO_DT_SPEC_GET_BY_IDX_OR(node_id, prop, idx, default_value) \
354 COND_CODE_1(DT_NODE_HAS_PROP(node_id, prop), \
355 (GPIO_DT_SPEC_GET_BY_IDX(node_id, prop, idx)), \
356 (default_value))
357
358 /**
359 * @brief Equivalent to GPIO_DT_SPEC_GET_BY_IDX(node_id, prop, 0).
360 *
361 * @param node_id devicetree node identifier
362 * @param prop lowercase-and-underscores property name
363 * @return static initializer for a struct gpio_dt_spec for the property
364 * @see GPIO_DT_SPEC_GET_BY_IDX()
365 */
366 #define GPIO_DT_SPEC_GET(node_id, prop) \
367 GPIO_DT_SPEC_GET_BY_IDX(node_id, prop, 0)
368
369 /**
370 * @brief Equivalent to
371 * GPIO_DT_SPEC_GET_BY_IDX_OR(node_id, prop, 0, default_value).
372 *
373 * @param node_id devicetree node identifier
374 * @param prop lowercase-and-underscores property name
375 * @param default_value fallback value to expand to
376 * @return static initializer for a struct gpio_dt_spec for the property
377 * @see GPIO_DT_SPEC_GET_BY_IDX_OR()
378 */
379 #define GPIO_DT_SPEC_GET_OR(node_id, prop, default_value) \
380 GPIO_DT_SPEC_GET_BY_IDX_OR(node_id, prop, 0, default_value)
381
382 /**
383 * @brief Static initializer for a @p gpio_dt_spec from a DT_DRV_COMPAT
384 * instance's GPIO property at an index.
385 *
386 * @param inst DT_DRV_COMPAT instance number
387 * @param prop lowercase-and-underscores property name
388 * @param idx logical index into "prop"
389 * @return static initializer for a struct gpio_dt_spec for the property
390 * @see GPIO_DT_SPEC_GET_BY_IDX()
391 */
392 #define GPIO_DT_SPEC_INST_GET_BY_IDX(inst, prop, idx) \
393 GPIO_DT_SPEC_GET_BY_IDX(DT_DRV_INST(inst), prop, idx)
394
395 /**
396 * @brief Static initializer for a @p gpio_dt_spec from a DT_DRV_COMPAT
397 * instance's GPIO property at an index, with fallback
398 *
399 * @param inst DT_DRV_COMPAT instance number
400 * @param prop lowercase-and-underscores property name
401 * @param idx logical index into "prop"
402 * @param default_value fallback value to expand to
403 * @return static initializer for a struct gpio_dt_spec for the property
404 * @see GPIO_DT_SPEC_GET_BY_IDX()
405 */
406 #define GPIO_DT_SPEC_INST_GET_BY_IDX_OR(inst, prop, idx, default_value) \
407 COND_CODE_1(DT_PROP_HAS_IDX(DT_DRV_INST(inst), prop, idx), \
408 (GPIO_DT_SPEC_GET_BY_IDX(DT_DRV_INST(inst), prop, idx)), \
409 (default_value))
410
411 /**
412 * @brief Equivalent to GPIO_DT_SPEC_INST_GET_BY_IDX(inst, prop, 0).
413 *
414 * @param inst DT_DRV_COMPAT instance number
415 * @param prop lowercase-and-underscores property name
416 * @return static initializer for a struct gpio_dt_spec for the property
417 * @see GPIO_DT_SPEC_INST_GET_BY_IDX()
418 */
419 #define GPIO_DT_SPEC_INST_GET(inst, prop) \
420 GPIO_DT_SPEC_INST_GET_BY_IDX(inst, prop, 0)
421
422 /**
423 * @brief Equivalent to
424 * GPIO_DT_SPEC_INST_GET_BY_IDX_OR(inst, prop, 0, default_value).
425 *
426 * @param inst DT_DRV_COMPAT instance number
427 * @param prop lowercase-and-underscores property name
428 * @param default_value fallback value to expand to
429 * @return static initializer for a struct gpio_dt_spec for the property
430 * @see GPIO_DT_SPEC_INST_GET_BY_IDX()
431 */
432 #define GPIO_DT_SPEC_INST_GET_OR(inst, prop, default_value) \
433 GPIO_DT_SPEC_INST_GET_BY_IDX_OR(inst, prop, 0, default_value)
434
435 /**
436 * @brief Maximum number of pins that are supported by `gpio_port_pins_t`.
437 */
438 #define GPIO_MAX_PINS_PER_PORT (sizeof(gpio_port_pins_t) * __CHAR_BIT__)
439
440 /**
441 * This structure is common to all GPIO drivers and is expected to be
442 * the first element in the object pointed to by the config field
443 * in the device structure.
444 */
445 struct gpio_driver_config {
446 /* Mask identifying pins supported by the controller.
447 *
448 * Initialization of this mask is the responsibility of device
449 * instance generation in the driver.
450 */
451 gpio_port_pins_t port_pin_mask;
452 };
453
454 /**
455 * This structure is common to all GPIO drivers and is expected to be the first
456 * element in the driver's struct driver_data declaration.
457 */
458 struct gpio_driver_data {
459 /* Mask identifying pins that are configured as active low.
460 *
461 * Management of this mask is the responsibility of the
462 * wrapper functions in this header.
463 */
464 gpio_port_pins_t invert;
465 };
466
467 struct gpio_callback;
468
469 /**
470 * @typedef gpio_callback_handler_t
471 * @brief Define the application callback handler function signature
472 *
473 * @param port Device struct for the GPIO device.
474 * @param cb Original struct gpio_callback owning this handler
475 * @param pins Mask of pins that triggers the callback handler
476 *
477 * Note: cb pointer can be used to retrieve private data through
478 * CONTAINER_OF() if original struct gpio_callback is stored in
479 * another private structure.
480 */
481 typedef void (*gpio_callback_handler_t)(const struct device *port,
482 struct gpio_callback *cb,
483 gpio_port_pins_t pins);
484
485 /**
486 * @brief GPIO callback structure
487 *
488 * Used to register a callback in the driver instance callback list.
489 * As many callbacks as needed can be added as long as each of them
490 * are unique pointers of struct gpio_callback.
491 * Beware such structure should not be allocated on stack.
492 *
493 * Note: To help setting it, see gpio_init_callback() below
494 */
495 struct gpio_callback {
496 /** This is meant to be used in the driver and the user should not
497 * mess with it (see drivers/gpio/gpio_utils.h)
498 */
499 sys_snode_t node;
500
501 /** Actual callback function being called when relevant. */
502 gpio_callback_handler_t handler;
503
504 /** A mask of pins the callback is interested in, if 0 the callback
505 * will never be called. Such pin_mask can be modified whenever
506 * necessary by the owner, and thus will affect the handler being
507 * called or not. The selected pins must be configured to trigger
508 * an interrupt.
509 */
510 gpio_port_pins_t pin_mask;
511 };
512
513 /**
514 * @cond INTERNAL_HIDDEN
515 *
516 * For internal use only, skip these in public documentation.
517 */
518
519 /* Used by driver api function pin_interrupt_configure, these are defined
520 * in terms of the public flags so we can just mask and pass them
521 * through to the driver api
522 */
523 enum gpio_int_mode {
524 GPIO_INT_MODE_DISABLED = GPIO_INT_DISABLE,
525 GPIO_INT_MODE_LEVEL = GPIO_INT_ENABLE,
526 GPIO_INT_MODE_EDGE = GPIO_INT_ENABLE | GPIO_INT_EDGE,
527 #ifdef CONFIG_GPIO_ENABLE_DISABLE_INTERRUPT
528 GPIO_INT_MODE_DISABLE_ONLY = GPIO_INT_DISABLE | GPIO_INT_ENABLE_DISABLE_ONLY,
529 GPIO_INT_MODE_ENABLE_ONLY = GPIO_INT_ENABLE | GPIO_INT_ENABLE_DISABLE_ONLY,
530 #endif /* CONFIG_GPIO_ENABLE_DISABLE_INTERRUPT */
531 };
532
533 enum gpio_int_trig {
534 /* Trigger detection when input state is (or transitions to)
535 * physical low. (Edge Falling or Active Low)
536 */
537 GPIO_INT_TRIG_LOW = GPIO_INT_LOW_0,
538 /* Trigger detection when input state is (or transitions to)
539 * physical high. (Edge Rising or Active High) */
540 GPIO_INT_TRIG_HIGH = GPIO_INT_HIGH_1,
541 /* Trigger detection on pin rising or falling edge. */
542 GPIO_INT_TRIG_BOTH = GPIO_INT_LOW_0 | GPIO_INT_HIGH_1,
543 };
544
545 __subsystem struct gpio_driver_api {
546 int (*pin_configure)(const struct device *port, gpio_pin_t pin,
547 gpio_flags_t flags);
548 #ifdef CONFIG_GPIO_GET_CONFIG
549 int (*pin_get_config)(const struct device *port, gpio_pin_t pin,
550 gpio_flags_t *flags);
551 #endif
552 int (*port_get_raw)(const struct device *port,
553 gpio_port_value_t *value);
554 int (*port_set_masked_raw)(const struct device *port,
555 gpio_port_pins_t mask,
556 gpio_port_value_t value);
557 int (*port_set_bits_raw)(const struct device *port,
558 gpio_port_pins_t pins);
559 int (*port_clear_bits_raw)(const struct device *port,
560 gpio_port_pins_t pins);
561 int (*port_toggle_bits)(const struct device *port,
562 gpio_port_pins_t pins);
563 int (*pin_interrupt_configure)(const struct device *port,
564 gpio_pin_t pin,
565 enum gpio_int_mode, enum gpio_int_trig);
566 int (*manage_callback)(const struct device *port,
567 struct gpio_callback *cb,
568 bool set);
569 uint32_t (*get_pending_int)(const struct device *dev);
570 #ifdef CONFIG_GPIO_GET_DIRECTION
571 int (*port_get_direction)(const struct device *port, gpio_port_pins_t map,
572 gpio_port_pins_t *inputs, gpio_port_pins_t *outputs);
573 #endif /* CONFIG_GPIO_GET_DIRECTION */
574 };
575
576 /**
577 * @endcond
578 */
579
580 /**
581 * @brief Validate that GPIO port is ready.
582 *
583 * @param spec GPIO specification from devicetree
584 *
585 * @retval true if the GPIO spec is ready for use.
586 * @retval false if the GPIO spec is not ready for use.
587 */
gpio_is_ready_dt(const struct gpio_dt_spec * spec)588 static inline bool gpio_is_ready_dt(const struct gpio_dt_spec *spec)
589 {
590 /* Validate port is ready */
591 return device_is_ready(spec->port);
592 }
593
594 /**
595 * @brief Configure pin interrupt.
596 *
597 * @note This function can also be used to configure interrupts on pins
598 * not controlled directly by the GPIO module. That is, pins which are
599 * routed to other modules such as I2C, SPI, UART.
600 *
601 * @param port Pointer to device structure for the driver instance.
602 * @param pin Pin number.
603 * @param flags Interrupt configuration flags as defined by GPIO_INT_*.
604 *
605 * @retval 0 If successful.
606 * @retval -ENOTSUP If any of the configuration options is not supported
607 * (unless otherwise directed by flag documentation).
608 * @retval -EINVAL Invalid argument.
609 * @retval -EBUSY Interrupt line required to configure pin interrupt is
610 * already in use.
611 * @retval -EIO I/O error when accessing an external GPIO chip.
612 * @retval -EWOULDBLOCK if operation would block.
613 */
614 __syscall int gpio_pin_interrupt_configure(const struct device *port,
615 gpio_pin_t pin,
616 gpio_flags_t flags);
617
z_impl_gpio_pin_interrupt_configure(const struct device * port,gpio_pin_t pin,gpio_flags_t flags)618 static inline int z_impl_gpio_pin_interrupt_configure(const struct device *port,
619 gpio_pin_t pin,
620 gpio_flags_t flags)
621 {
622 const struct gpio_driver_api *api =
623 (const struct gpio_driver_api *)port->api;
624 __unused const struct gpio_driver_config *const cfg =
625 (const struct gpio_driver_config *)port->config;
626 const struct gpio_driver_data *const data =
627 (const struct gpio_driver_data *)port->data;
628 enum gpio_int_trig trig;
629 enum gpio_int_mode mode;
630
631 __ASSERT((flags & (GPIO_INT_DISABLE | GPIO_INT_ENABLE))
632 != (GPIO_INT_DISABLE | GPIO_INT_ENABLE),
633 "Cannot both enable and disable interrupts");
634
635 __ASSERT((flags & (GPIO_INT_DISABLE | GPIO_INT_ENABLE)) != 0U,
636 "Must either enable or disable interrupts");
637
638 __ASSERT(((flags & GPIO_INT_ENABLE) == 0) ||
639 ((flags & GPIO_INT_EDGE) != 0) ||
640 ((flags & (GPIO_INT_LOW_0 | GPIO_INT_HIGH_1)) !=
641 (GPIO_INT_LOW_0 | GPIO_INT_HIGH_1)),
642 "Only one of GPIO_INT_LOW_0, GPIO_INT_HIGH_1 can be "
643 "enabled for a level interrupt.");
644
645 __ASSERT(((flags & GPIO_INT_ENABLE) == 0) ||
646 #ifdef CONFIG_GPIO_ENABLE_DISABLE_INTERRUPT
647 ((flags & (GPIO_INT_LOW_0 | GPIO_INT_HIGH_1)) != 0) ||
648 (flags & GPIO_INT_ENABLE_DISABLE_ONLY) != 0,
649 #else
650 ((flags & (GPIO_INT_LOW_0 | GPIO_INT_HIGH_1)) != 0),
651 #endif /* CONFIG_GPIO_ENABLE_DISABLE_INTERRUPT */
652 "At least one of GPIO_INT_LOW_0, GPIO_INT_HIGH_1 has to be "
653 "enabled.");
654
655 __ASSERT((cfg->port_pin_mask & (gpio_port_pins_t)BIT(pin)) != 0U,
656 "Unsupported pin");
657
658 if (((flags & GPIO_INT_LEVELS_LOGICAL) != 0) &&
659 ((data->invert & (gpio_port_pins_t)BIT(pin)) != 0)) {
660 /* Invert signal bits */
661 flags ^= (GPIO_INT_LOW_0 | GPIO_INT_HIGH_1);
662 }
663
664 trig = (enum gpio_int_trig)(flags & (GPIO_INT_LOW_0 | GPIO_INT_HIGH_1));
665 #ifdef CONFIG_GPIO_ENABLE_DISABLE_INTERRUPT
666 mode = (enum gpio_int_mode)(flags & (GPIO_INT_EDGE | GPIO_INT_DISABLE | GPIO_INT_ENABLE |
667 GPIO_INT_ENABLE_DISABLE_ONLY));
668 #else
669 mode = (enum gpio_int_mode)(flags & (GPIO_INT_EDGE | GPIO_INT_DISABLE | GPIO_INT_ENABLE));
670 #endif /* CONFIG_GPIO_ENABLE_DISABLE_INTERRUPT */
671
672 return api->pin_interrupt_configure(port, pin, mode, trig);
673 }
674
675 /**
676 * @brief Configure pin interrupts from a @p gpio_dt_spec.
677 *
678 * This is equivalent to:
679 *
680 * gpio_pin_interrupt_configure(spec->port, spec->pin, flags);
681 *
682 * The <tt>spec->dt_flags</tt> value is not used.
683 *
684 * @param spec GPIO specification from devicetree
685 * @param flags interrupt configuration flags
686 * @return a value from gpio_pin_interrupt_configure()
687 */
gpio_pin_interrupt_configure_dt(const struct gpio_dt_spec * spec,gpio_flags_t flags)688 static inline int gpio_pin_interrupt_configure_dt(const struct gpio_dt_spec *spec,
689 gpio_flags_t flags)
690 {
691 return gpio_pin_interrupt_configure(spec->port, spec->pin, flags);
692 }
693
694 /**
695 * @brief Configure a single pin.
696 *
697 * @param port Pointer to device structure for the driver instance.
698 * @param pin Pin number to configure.
699 * @param flags Flags for pin configuration: 'GPIO input/output configuration
700 * flags', 'GPIO pin drive flags', 'GPIO pin bias flags'.
701 *
702 * @retval 0 If successful.
703 * @retval -ENOTSUP if any of the configuration options is not supported
704 * (unless otherwise directed by flag documentation).
705 * @retval -EINVAL Invalid argument.
706 * @retval -EIO I/O error when accessing an external GPIO chip.
707 * @retval -EWOULDBLOCK if operation would block.
708 */
709 __syscall int gpio_pin_configure(const struct device *port,
710 gpio_pin_t pin,
711 gpio_flags_t flags);
712
z_impl_gpio_pin_configure(const struct device * port,gpio_pin_t pin,gpio_flags_t flags)713 static inline int z_impl_gpio_pin_configure(const struct device *port,
714 gpio_pin_t pin,
715 gpio_flags_t flags)
716 {
717 const struct gpio_driver_api *api =
718 (const struct gpio_driver_api *)port->api;
719 __unused const struct gpio_driver_config *const cfg =
720 (const struct gpio_driver_config *)port->config;
721 struct gpio_driver_data *data =
722 (struct gpio_driver_data *)port->data;
723
724 __ASSERT((flags & GPIO_INT_MASK) == 0,
725 "Interrupt flags are not supported");
726
727 __ASSERT((flags & (GPIO_PULL_UP | GPIO_PULL_DOWN)) !=
728 (GPIO_PULL_UP | GPIO_PULL_DOWN),
729 "Pull Up and Pull Down should not be enabled simultaneously");
730
731 __ASSERT(!((flags & GPIO_INPUT) && !(flags & GPIO_OUTPUT) && (flags & GPIO_SINGLE_ENDED)),
732 "Input cannot be enabled for 'Open Drain', 'Open Source' modes without Output");
733
734 __ASSERT_NO_MSG((flags & GPIO_SINGLE_ENDED) != 0 ||
735 (flags & GPIO_LINE_OPEN_DRAIN) == 0);
736
737 __ASSERT((flags & (GPIO_OUTPUT_INIT_LOW | GPIO_OUTPUT_INIT_HIGH)) == 0
738 || (flags & GPIO_OUTPUT) != 0,
739 "Output needs to be enabled to be initialized low or high");
740
741 __ASSERT((flags & (GPIO_OUTPUT_INIT_LOW | GPIO_OUTPUT_INIT_HIGH))
742 != (GPIO_OUTPUT_INIT_LOW | GPIO_OUTPUT_INIT_HIGH),
743 "Output cannot be initialized low and high");
744
745 if (((flags & GPIO_OUTPUT_INIT_LOGICAL) != 0)
746 && ((flags & (GPIO_OUTPUT_INIT_LOW | GPIO_OUTPUT_INIT_HIGH)) != 0)
747 && ((flags & GPIO_ACTIVE_LOW) != 0)) {
748 flags ^= GPIO_OUTPUT_INIT_LOW | GPIO_OUTPUT_INIT_HIGH;
749 }
750
751 flags &= ~GPIO_OUTPUT_INIT_LOGICAL;
752
753 __ASSERT((cfg->port_pin_mask & (gpio_port_pins_t)BIT(pin)) != 0U,
754 "Unsupported pin");
755
756 if ((flags & GPIO_ACTIVE_LOW) != 0) {
757 data->invert |= (gpio_port_pins_t)BIT(pin);
758 } else {
759 data->invert &= ~(gpio_port_pins_t)BIT(pin);
760 }
761
762 return api->pin_configure(port, pin, flags);
763 }
764
765 /**
766 * @brief Configure a single pin from a @p gpio_dt_spec and some extra flags.
767 *
768 * This is equivalent to:
769 *
770 * gpio_pin_configure(spec->port, spec->pin, spec->dt_flags | extra_flags);
771 *
772 * @param spec GPIO specification from devicetree
773 * @param extra_flags additional flags
774 * @return a value from gpio_pin_configure()
775 */
gpio_pin_configure_dt(const struct gpio_dt_spec * spec,gpio_flags_t extra_flags)776 static inline int gpio_pin_configure_dt(const struct gpio_dt_spec *spec,
777 gpio_flags_t extra_flags)
778 {
779 return gpio_pin_configure(spec->port,
780 spec->pin,
781 spec->dt_flags | extra_flags);
782 }
783
784 /*
785 * @brief Get direction of select pins in a port.
786 *
787 * Retrieve direction of each pin specified in @p map.
788 *
789 * If @p inputs or @p outputs is NULL, then this function does not get the
790 * respective input or output direction information.
791 *
792 * @param port Pointer to the device structure for the driver instance.
793 * @param map Bitmap of pin directions to query.
794 * @param inputs Pointer to a variable where input directions will be stored.
795 * @param outputs Pointer to a variable where output directions will be stored.
796 *
797 * @retval 0 If successful.
798 * @retval -ENOSYS if the underlying driver does not support this call.
799 * @retval -EIO I/O error when accessing an external GPIO chip.
800 * @retval -EWOULDBLOCK if operation would block.
801 */
802 __syscall int gpio_port_get_direction(const struct device *port, gpio_port_pins_t map,
803 gpio_port_pins_t *inputs, gpio_port_pins_t *outputs);
804
805 #ifdef CONFIG_GPIO_GET_DIRECTION
z_impl_gpio_port_get_direction(const struct device * port,gpio_port_pins_t map,gpio_port_pins_t * inputs,gpio_port_pins_t * outputs)806 static inline int z_impl_gpio_port_get_direction(const struct device *port, gpio_port_pins_t map,
807 gpio_port_pins_t *inputs,
808 gpio_port_pins_t *outputs)
809 {
810 const struct gpio_driver_api *api = (const struct gpio_driver_api *)port->api;
811
812 if (api->port_get_direction == NULL) {
813 return -ENOSYS;
814 }
815
816 return api->port_get_direction(port, map, inputs, outputs);
817 }
818 #endif /* CONFIG_GPIO_GET_DIRECTION */
819
820 /**
821 * @brief Check if @p pin is configured for input
822 *
823 * @param port Pointer to device structure for the driver instance.
824 * @param pin Pin number to query the direction of
825 *
826 * @retval 1 if @p pin is configured as @ref GPIO_INPUT.
827 * @retval 0 if @p pin is not configured as @ref GPIO_INPUT.
828 * @retval -ENOSYS if the underlying driver does not support this call.
829 * @retval -EIO I/O error when accessing an external GPIO chip.
830 * @retval -EWOULDBLOCK if operation would block.
831 */
gpio_pin_is_input(const struct device * port,gpio_pin_t pin)832 static inline int gpio_pin_is_input(const struct device *port, gpio_pin_t pin)
833 {
834 int rv;
835 gpio_port_pins_t pins;
836 __unused const struct gpio_driver_config *cfg =
837 (const struct gpio_driver_config *)port->config;
838
839 __ASSERT((cfg->port_pin_mask & (gpio_port_pins_t)BIT(pin)) != 0U, "Unsupported pin");
840
841 rv = gpio_port_get_direction(port, BIT(pin), &pins, NULL);
842 if (rv < 0) {
843 return rv;
844 }
845
846 return (int)!!((gpio_port_pins_t)BIT(pin) & pins);
847 }
848
849 /**
850 * @brief Check if a single pin from @p gpio_dt_spec is configured for input
851 *
852 * This is equivalent to:
853 *
854 * gpio_pin_is_input(spec->port, spec->pin);
855 *
856 * @param spec GPIO specification from devicetree.
857 *
858 * @return A value from gpio_pin_is_input().
859 */
gpio_pin_is_input_dt(const struct gpio_dt_spec * spec)860 static inline int gpio_pin_is_input_dt(const struct gpio_dt_spec *spec)
861 {
862 return gpio_pin_is_input(spec->port, spec->pin);
863 }
864
865 /**
866 * @brief Check if @p pin is configured for output
867 *
868 * @param port Pointer to device structure for the driver instance.
869 * @param pin Pin number to query the direction of
870 *
871 * @retval 1 if @p pin is configured as @ref GPIO_OUTPUT.
872 * @retval 0 if @p pin is not configured as @ref GPIO_OUTPUT.
873 * @retval -ENOSYS if the underlying driver does not support this call.
874 * @retval -EIO I/O error when accessing an external GPIO chip.
875 * @retval -EWOULDBLOCK if operation would block.
876 */
gpio_pin_is_output(const struct device * port,gpio_pin_t pin)877 static inline int gpio_pin_is_output(const struct device *port, gpio_pin_t pin)
878 {
879 int rv;
880 gpio_port_pins_t pins;
881 __unused const struct gpio_driver_config *cfg =
882 (const struct gpio_driver_config *)port->config;
883
884 __ASSERT((cfg->port_pin_mask & (gpio_port_pins_t)BIT(pin)) != 0U, "Unsupported pin");
885
886 rv = gpio_port_get_direction(port, BIT(pin), NULL, &pins);
887 if (rv < 0) {
888 return rv;
889 }
890
891 return (int)!!((gpio_port_pins_t)BIT(pin) & pins);
892 }
893
894 /**
895 * @brief Check if a single pin from @p gpio_dt_spec is configured for output
896 *
897 * This is equivalent to:
898 *
899 * gpio_pin_is_output(spec->port, spec->pin);
900 *
901 * @param spec GPIO specification from devicetree.
902 *
903 * @return A value from gpio_pin_is_output().
904 */
gpio_pin_is_output_dt(const struct gpio_dt_spec * spec)905 static inline int gpio_pin_is_output_dt(const struct gpio_dt_spec *spec)
906 {
907 return gpio_pin_is_output(spec->port, spec->pin);
908 }
909
910 /**
911 * @brief Get a configuration of a single pin.
912 *
913 * @param port Pointer to device structure for the driver instance.
914 * @param pin Pin number which configuration is get.
915 * @param flags Pointer to variable in which the current configuration will
916 * be stored if function is successful.
917 *
918 * @retval 0 If successful.
919 * @retval -ENOSYS if getting current pin configuration is not implemented
920 * by the driver.
921 * @retval -EINVAL Invalid argument.
922 * @retval -EIO I/O error when accessing an external GPIO chip.
923 * @retval -EWOULDBLOCK if operation would block.
924 */
925 __syscall int gpio_pin_get_config(const struct device *port, gpio_pin_t pin,
926 gpio_flags_t *flags);
927
928 #ifdef CONFIG_GPIO_GET_CONFIG
z_impl_gpio_pin_get_config(const struct device * port,gpio_pin_t pin,gpio_flags_t * flags)929 static inline int z_impl_gpio_pin_get_config(const struct device *port,
930 gpio_pin_t pin,
931 gpio_flags_t *flags)
932 {
933 const struct gpio_driver_api *api =
934 (const struct gpio_driver_api *)port->api;
935
936 if (api->pin_get_config == NULL)
937 return -ENOSYS;
938
939 return api->pin_get_config(port, pin, flags);
940 }
941 #endif
942
943 /**
944 * @brief Get a configuration of a single pin from a @p gpio_dt_spec.
945 *
946 * This is equivalent to:
947 *
948 * gpio_pin_get_config(spec->port, spec->pin, flags);
949 *
950 * @param spec GPIO specification from devicetree
951 * @param flags Pointer to variable in which the current configuration will
952 * be stored if function is successful.
953 * @return a value from gpio_pin_configure()
954 */
gpio_pin_get_config_dt(const struct gpio_dt_spec * spec,gpio_flags_t * flags)955 static inline int gpio_pin_get_config_dt(const struct gpio_dt_spec *spec,
956 gpio_flags_t *flags)
957 {
958 return gpio_pin_get_config(spec->port, spec->pin, flags);
959 }
960
961 /**
962 * @brief Get physical level of all input pins in a port.
963 *
964 * A low physical level on the pin will be interpreted as value 0. A high
965 * physical level will be interpreted as value 1. This function ignores
966 * GPIO_ACTIVE_LOW flag.
967 *
968 * Value of a pin with index n will be represented by bit n in the returned
969 * port value.
970 *
971 * @param port Pointer to the device structure for the driver instance.
972 * @param value Pointer to a variable where pin values will be stored.
973 *
974 * @retval 0 If successful.
975 * @retval -EIO I/O error when accessing an external GPIO chip.
976 * @retval -EWOULDBLOCK if operation would block.
977 */
978 __syscall int gpio_port_get_raw(const struct device *port,
979 gpio_port_value_t *value);
980
z_impl_gpio_port_get_raw(const struct device * port,gpio_port_value_t * value)981 static inline int z_impl_gpio_port_get_raw(const struct device *port,
982 gpio_port_value_t *value)
983 {
984 const struct gpio_driver_api *api =
985 (const struct gpio_driver_api *)port->api;
986
987 return api->port_get_raw(port, value);
988 }
989
990 /**
991 * @brief Get logical level of all input pins in a port.
992 *
993 * Get logical level of an input pin taking into account GPIO_ACTIVE_LOW flag.
994 * If pin is configured as Active High, a low physical level will be interpreted
995 * as logical value 0. If pin is configured as Active Low, a low physical level
996 * will be interpreted as logical value 1.
997 *
998 * Value of a pin with index n will be represented by bit n in the returned
999 * port value.
1000 *
1001 * @param port Pointer to the device structure for the driver instance.
1002 * @param value Pointer to a variable where pin values will be stored.
1003 *
1004 * @retval 0 If successful.
1005 * @retval -EIO I/O error when accessing an external GPIO chip.
1006 * @retval -EWOULDBLOCK if operation would block.
1007 */
gpio_port_get(const struct device * port,gpio_port_value_t * value)1008 static inline int gpio_port_get(const struct device *port,
1009 gpio_port_value_t *value)
1010 {
1011 const struct gpio_driver_data *const data =
1012 (const struct gpio_driver_data *)port->data;
1013 int ret;
1014
1015 ret = gpio_port_get_raw(port, value);
1016 if (ret == 0) {
1017 *value ^= data->invert;
1018 }
1019
1020 return ret;
1021 }
1022
1023 /**
1024 * @brief Set physical level of output pins in a port.
1025 *
1026 * Writing value 0 to the pin will set it to a low physical level. Writing
1027 * value 1 will set it to a high physical level. This function ignores
1028 * GPIO_ACTIVE_LOW flag.
1029 *
1030 * Pin with index n is represented by bit n in mask and value parameter.
1031 *
1032 * @param port Pointer to the device structure for the driver instance.
1033 * @param mask Mask indicating which pins will be modified.
1034 * @param value Value assigned to the output pins.
1035 *
1036 * @retval 0 If successful.
1037 * @retval -EIO I/O error when accessing an external GPIO chip.
1038 * @retval -EWOULDBLOCK if operation would block.
1039 */
1040 __syscall int gpio_port_set_masked_raw(const struct device *port,
1041 gpio_port_pins_t mask,
1042 gpio_port_value_t value);
1043
z_impl_gpio_port_set_masked_raw(const struct device * port,gpio_port_pins_t mask,gpio_port_value_t value)1044 static inline int z_impl_gpio_port_set_masked_raw(const struct device *port,
1045 gpio_port_pins_t mask,
1046 gpio_port_value_t value)
1047 {
1048 const struct gpio_driver_api *api =
1049 (const struct gpio_driver_api *)port->api;
1050
1051 return api->port_set_masked_raw(port, mask, value);
1052 }
1053
1054 /**
1055 * @brief Set logical level of output pins in a port.
1056 *
1057 * Set logical level of an output pin taking into account GPIO_ACTIVE_LOW flag.
1058 * Value 0 sets the pin in logical 0 / inactive state. Value 1 sets the pin in
1059 * logical 1 / active state. If pin is configured as Active High, the default,
1060 * setting it in inactive state will force the pin to a low physical level. If
1061 * pin is configured as Active Low, setting it in inactive state will force the
1062 * pin to a high physical level.
1063 *
1064 * Pin with index n is represented by bit n in mask and value parameter.
1065 *
1066 * @param port Pointer to the device structure for the driver instance.
1067 * @param mask Mask indicating which pins will be modified.
1068 * @param value Value assigned to the output pins.
1069 *
1070 * @retval 0 If successful.
1071 * @retval -EIO I/O error when accessing an external GPIO chip.
1072 * @retval -EWOULDBLOCK if operation would block.
1073 */
gpio_port_set_masked(const struct device * port,gpio_port_pins_t mask,gpio_port_value_t value)1074 static inline int gpio_port_set_masked(const struct device *port,
1075 gpio_port_pins_t mask,
1076 gpio_port_value_t value)
1077 {
1078 const struct gpio_driver_data *const data =
1079 (const struct gpio_driver_data *)port->data;
1080
1081 value ^= data->invert;
1082
1083 return gpio_port_set_masked_raw(port, mask, value);
1084 }
1085
1086 /**
1087 * @brief Set physical level of selected output pins to high.
1088 *
1089 * @param port Pointer to the device structure for the driver instance.
1090 * @param pins Value indicating which pins will be modified.
1091 *
1092 * @retval 0 If successful.
1093 * @retval -EIO I/O error when accessing an external GPIO chip.
1094 * @retval -EWOULDBLOCK if operation would block.
1095 */
1096 __syscall int gpio_port_set_bits_raw(const struct device *port,
1097 gpio_port_pins_t pins);
1098
z_impl_gpio_port_set_bits_raw(const struct device * port,gpio_port_pins_t pins)1099 static inline int z_impl_gpio_port_set_bits_raw(const struct device *port,
1100 gpio_port_pins_t pins)
1101 {
1102 const struct gpio_driver_api *api =
1103 (const struct gpio_driver_api *)port->api;
1104
1105 return api->port_set_bits_raw(port, pins);
1106 }
1107
1108 /**
1109 * @brief Set logical level of selected output pins to active.
1110 *
1111 * @param port Pointer to the device structure for the driver instance.
1112 * @param pins Value indicating which pins will be modified.
1113 *
1114 * @retval 0 If successful.
1115 * @retval -EIO I/O error when accessing an external GPIO chip.
1116 * @retval -EWOULDBLOCK if operation would block.
1117 */
gpio_port_set_bits(const struct device * port,gpio_port_pins_t pins)1118 static inline int gpio_port_set_bits(const struct device *port,
1119 gpio_port_pins_t pins)
1120 {
1121 return gpio_port_set_masked(port, pins, pins);
1122 }
1123
1124 /**
1125 * @brief Set physical level of selected output pins to low.
1126 *
1127 * @param port Pointer to the device structure for the driver instance.
1128 * @param pins Value indicating which pins will be modified.
1129 *
1130 * @retval 0 If successful.
1131 * @retval -EIO I/O error when accessing an external GPIO chip.
1132 * @retval -EWOULDBLOCK if operation would block.
1133 */
1134 __syscall int gpio_port_clear_bits_raw(const struct device *port,
1135 gpio_port_pins_t pins);
1136
z_impl_gpio_port_clear_bits_raw(const struct device * port,gpio_port_pins_t pins)1137 static inline int z_impl_gpio_port_clear_bits_raw(const struct device *port,
1138 gpio_port_pins_t pins)
1139 {
1140 const struct gpio_driver_api *api =
1141 (const struct gpio_driver_api *)port->api;
1142
1143 return api->port_clear_bits_raw(port, pins);
1144 }
1145
1146 /**
1147 * @brief Set logical level of selected output pins to inactive.
1148 *
1149 * @param port Pointer to the device structure for the driver instance.
1150 * @param pins Value indicating which pins will be modified.
1151 *
1152 * @retval 0 If successful.
1153 * @retval -EIO I/O error when accessing an external GPIO chip.
1154 * @retval -EWOULDBLOCK if operation would block.
1155 */
gpio_port_clear_bits(const struct device * port,gpio_port_pins_t pins)1156 static inline int gpio_port_clear_bits(const struct device *port,
1157 gpio_port_pins_t pins)
1158 {
1159 return gpio_port_set_masked(port, pins, 0);
1160 }
1161
1162 /**
1163 * @brief Toggle level of selected output pins.
1164 *
1165 * @param port Pointer to the device structure for the driver instance.
1166 * @param pins Value indicating which pins will be modified.
1167 *
1168 * @retval 0 If successful.
1169 * @retval -EIO I/O error when accessing an external GPIO chip.
1170 * @retval -EWOULDBLOCK if operation would block.
1171 */
1172 __syscall int gpio_port_toggle_bits(const struct device *port,
1173 gpio_port_pins_t pins);
1174
z_impl_gpio_port_toggle_bits(const struct device * port,gpio_port_pins_t pins)1175 static inline int z_impl_gpio_port_toggle_bits(const struct device *port,
1176 gpio_port_pins_t pins)
1177 {
1178 const struct gpio_driver_api *api =
1179 (const struct gpio_driver_api *)port->api;
1180
1181 return api->port_toggle_bits(port, pins);
1182 }
1183
1184 /**
1185 * @brief Set physical level of selected output pins.
1186 *
1187 * @param port Pointer to the device structure for the driver instance.
1188 * @param set_pins Value indicating which pins will be set to high.
1189 * @param clear_pins Value indicating which pins will be set to low.
1190 *
1191 * @retval 0 If successful.
1192 * @retval -EIO I/O error when accessing an external GPIO chip.
1193 * @retval -EWOULDBLOCK if operation would block.
1194 */
gpio_port_set_clr_bits_raw(const struct device * port,gpio_port_pins_t set_pins,gpio_port_pins_t clear_pins)1195 static inline int gpio_port_set_clr_bits_raw(const struct device *port,
1196 gpio_port_pins_t set_pins,
1197 gpio_port_pins_t clear_pins)
1198 {
1199 __ASSERT((set_pins & clear_pins) == 0, "Set and Clear pins overlap");
1200
1201 return gpio_port_set_masked_raw(port, set_pins | clear_pins, set_pins);
1202 }
1203
1204 /**
1205 * @brief Set logical level of selected output pins.
1206 *
1207 * @param port Pointer to the device structure for the driver instance.
1208 * @param set_pins Value indicating which pins will be set to active.
1209 * @param clear_pins Value indicating which pins will be set to inactive.
1210 *
1211 * @retval 0 If successful.
1212 * @retval -EIO I/O error when accessing an external GPIO chip.
1213 * @retval -EWOULDBLOCK if operation would block.
1214 */
gpio_port_set_clr_bits(const struct device * port,gpio_port_pins_t set_pins,gpio_port_pins_t clear_pins)1215 static inline int gpio_port_set_clr_bits(const struct device *port,
1216 gpio_port_pins_t set_pins,
1217 gpio_port_pins_t clear_pins)
1218 {
1219 __ASSERT((set_pins & clear_pins) == 0, "Set and Clear pins overlap");
1220
1221 return gpio_port_set_masked(port, set_pins | clear_pins, set_pins);
1222 }
1223
1224 /**
1225 * @brief Get physical level of an input pin.
1226 *
1227 * A low physical level on the pin will be interpreted as value 0. A high
1228 * physical level will be interpreted as value 1. This function ignores
1229 * GPIO_ACTIVE_LOW flag.
1230 *
1231 * @param port Pointer to the device structure for the driver instance.
1232 * @param pin Pin number.
1233 *
1234 * @retval 1 If pin physical level is high.
1235 * @retval 0 If pin physical level is low.
1236 * @retval -EIO I/O error when accessing an external GPIO chip.
1237 * @retval -EWOULDBLOCK if operation would block.
1238 */
gpio_pin_get_raw(const struct device * port,gpio_pin_t pin)1239 static inline int gpio_pin_get_raw(const struct device *port, gpio_pin_t pin)
1240 {
1241 __unused const struct gpio_driver_config *const cfg =
1242 (const struct gpio_driver_config *)port->config;
1243 gpio_port_value_t value;
1244 int ret;
1245
1246 __ASSERT((cfg->port_pin_mask & (gpio_port_pins_t)BIT(pin)) != 0U,
1247 "Unsupported pin");
1248
1249 ret = gpio_port_get_raw(port, &value);
1250 if (ret == 0) {
1251 ret = (value & (gpio_port_pins_t)BIT(pin)) != 0 ? 1 : 0;
1252 }
1253
1254 return ret;
1255 }
1256
1257 /**
1258 * @brief Get logical level of an input pin.
1259 *
1260 * Get logical level of an input pin taking into account GPIO_ACTIVE_LOW flag.
1261 * If pin is configured as Active High, a low physical level will be interpreted
1262 * as logical value 0. If pin is configured as Active Low, a low physical level
1263 * will be interpreted as logical value 1.
1264 *
1265 * Note: If pin is configured as Active High, the default, gpio_pin_get()
1266 * function is equivalent to gpio_pin_get_raw().
1267 *
1268 * @param port Pointer to the device structure for the driver instance.
1269 * @param pin Pin number.
1270 *
1271 * @retval 1 If pin logical value is 1 / active.
1272 * @retval 0 If pin logical value is 0 / inactive.
1273 * @retval -EIO I/O error when accessing an external GPIO chip.
1274 * @retval -EWOULDBLOCK if operation would block.
1275 */
gpio_pin_get(const struct device * port,gpio_pin_t pin)1276 static inline int gpio_pin_get(const struct device *port, gpio_pin_t pin)
1277 {
1278 __unused const struct gpio_driver_config *const cfg =
1279 (const struct gpio_driver_config *)port->config;
1280 gpio_port_value_t value;
1281 int ret;
1282
1283 __ASSERT((cfg->port_pin_mask & (gpio_port_pins_t)BIT(pin)) != 0U,
1284 "Unsupported pin");
1285
1286 ret = gpio_port_get(port, &value);
1287 if (ret == 0) {
1288 ret = (value & (gpio_port_pins_t)BIT(pin)) != 0 ? 1 : 0;
1289 }
1290
1291 return ret;
1292 }
1293
1294 /**
1295 * @brief Get logical level of an input pin from a @p gpio_dt_spec.
1296 *
1297 * This is equivalent to:
1298 *
1299 * gpio_pin_get(spec->port, spec->pin);
1300 *
1301 * @param spec GPIO specification from devicetree
1302 * @return a value from gpio_pin_get()
1303 */
gpio_pin_get_dt(const struct gpio_dt_spec * spec)1304 static inline int gpio_pin_get_dt(const struct gpio_dt_spec *spec)
1305 {
1306 return gpio_pin_get(spec->port, spec->pin);
1307 }
1308
1309 /**
1310 * @brief Set physical level of an output pin.
1311 *
1312 * Writing value 0 to the pin will set it to a low physical level. Writing any
1313 * value other than 0 will set it to a high physical level. This function
1314 * ignores GPIO_ACTIVE_LOW flag.
1315 *
1316 * @param port Pointer to the device structure for the driver instance.
1317 * @param pin Pin number.
1318 * @param value Value assigned to the pin.
1319 *
1320 * @retval 0 If successful.
1321 * @retval -EIO I/O error when accessing an external GPIO chip.
1322 * @retval -EWOULDBLOCK if operation would block.
1323 */
gpio_pin_set_raw(const struct device * port,gpio_pin_t pin,int value)1324 static inline int gpio_pin_set_raw(const struct device *port, gpio_pin_t pin,
1325 int value)
1326 {
1327 __unused const struct gpio_driver_config *const cfg =
1328 (const struct gpio_driver_config *)port->config;
1329 int ret;
1330
1331 __ASSERT((cfg->port_pin_mask & (gpio_port_pins_t)BIT(pin)) != 0U,
1332 "Unsupported pin");
1333
1334 if (value != 0) {
1335 ret = gpio_port_set_bits_raw(port, (gpio_port_pins_t)BIT(pin));
1336 } else {
1337 ret = gpio_port_clear_bits_raw(port, (gpio_port_pins_t)BIT(pin));
1338 }
1339
1340 return ret;
1341 }
1342
1343 /**
1344 * @brief Set logical level of an output pin.
1345 *
1346 * Set logical level of an output pin taking into account GPIO_ACTIVE_LOW flag.
1347 * Value 0 sets the pin in logical 0 / inactive state. Any value other than 0
1348 * sets the pin in logical 1 / active state. If pin is configured as Active
1349 * High, the default, setting it in inactive state will force the pin to a low
1350 * physical level. If pin is configured as Active Low, setting it in inactive
1351 * state will force the pin to a high physical level.
1352 *
1353 * Note: If pin is configured as Active High, gpio_pin_set() function is
1354 * equivalent to gpio_pin_set_raw().
1355 *
1356 * @param port Pointer to the device structure for the driver instance.
1357 * @param pin Pin number.
1358 * @param value Value assigned to the pin.
1359 *
1360 * @retval 0 If successful.
1361 * @retval -EIO I/O error when accessing an external GPIO chip.
1362 * @retval -EWOULDBLOCK if operation would block.
1363 */
gpio_pin_set(const struct device * port,gpio_pin_t pin,int value)1364 static inline int gpio_pin_set(const struct device *port, gpio_pin_t pin,
1365 int value)
1366 {
1367 __unused const struct gpio_driver_config *const cfg =
1368 (const struct gpio_driver_config *)port->config;
1369 const struct gpio_driver_data *const data =
1370 (const struct gpio_driver_data *)port->data;
1371
1372 __ASSERT((cfg->port_pin_mask & (gpio_port_pins_t)BIT(pin)) != 0U,
1373 "Unsupported pin");
1374
1375 if (data->invert & (gpio_port_pins_t)BIT(pin)) {
1376 value = (value != 0) ? 0 : 1;
1377 }
1378
1379 return gpio_pin_set_raw(port, pin, value);
1380 }
1381
1382 /**
1383 * @brief Set logical level of a output pin from a @p gpio_dt_spec.
1384 *
1385 * This is equivalent to:
1386 *
1387 * gpio_pin_set(spec->port, spec->pin, value);
1388 *
1389 * @param spec GPIO specification from devicetree
1390 * @param value Value assigned to the pin.
1391 * @return a value from gpio_pin_set()
1392 */
gpio_pin_set_dt(const struct gpio_dt_spec * spec,int value)1393 static inline int gpio_pin_set_dt(const struct gpio_dt_spec *spec, int value)
1394 {
1395 return gpio_pin_set(spec->port, spec->pin, value);
1396 }
1397
1398 /**
1399 * @brief Toggle pin level.
1400 *
1401 * @param port Pointer to the device structure for the driver instance.
1402 * @param pin Pin number.
1403 *
1404 * @retval 0 If successful.
1405 * @retval -EIO I/O error when accessing an external GPIO chip.
1406 * @retval -EWOULDBLOCK if operation would block.
1407 */
gpio_pin_toggle(const struct device * port,gpio_pin_t pin)1408 static inline int gpio_pin_toggle(const struct device *port, gpio_pin_t pin)
1409 {
1410 __unused const struct gpio_driver_config *const cfg =
1411 (const struct gpio_driver_config *)port->config;
1412
1413 __ASSERT((cfg->port_pin_mask & (gpio_port_pins_t)BIT(pin)) != 0U,
1414 "Unsupported pin");
1415
1416 return gpio_port_toggle_bits(port, (gpio_port_pins_t)BIT(pin));
1417 }
1418
1419 /**
1420 * @brief Toggle pin level from a @p gpio_dt_spec.
1421 *
1422 * This is equivalent to:
1423 *
1424 * gpio_pin_toggle(spec->port, spec->pin);
1425 *
1426 * @param spec GPIO specification from devicetree
1427 * @return a value from gpio_pin_toggle()
1428 */
gpio_pin_toggle_dt(const struct gpio_dt_spec * spec)1429 static inline int gpio_pin_toggle_dt(const struct gpio_dt_spec *spec)
1430 {
1431 return gpio_pin_toggle(spec->port, spec->pin);
1432 }
1433
1434 /**
1435 * @brief Helper to initialize a struct gpio_callback properly
1436 * @param callback A valid Application's callback structure pointer.
1437 * @param handler A valid handler function pointer.
1438 * @param pin_mask A bit mask of relevant pins for the handler
1439 */
gpio_init_callback(struct gpio_callback * callback,gpio_callback_handler_t handler,gpio_port_pins_t pin_mask)1440 static inline void gpio_init_callback(struct gpio_callback *callback,
1441 gpio_callback_handler_t handler,
1442 gpio_port_pins_t pin_mask)
1443 {
1444 __ASSERT(callback, "Callback pointer should not be NULL");
1445 __ASSERT(handler, "Callback handler pointer should not be NULL");
1446
1447 callback->handler = handler;
1448 callback->pin_mask = pin_mask;
1449 }
1450
1451 /**
1452 * @brief Add an application callback.
1453 * @param port Pointer to the device structure for the driver instance.
1454 * @param callback A valid Application's callback structure pointer.
1455 * @return 0 if successful, negative errno code on failure.
1456 *
1457 * @note Callbacks may be added to the device from within a callback
1458 * handler invocation, but whether they are invoked for the current
1459 * GPIO event is not specified.
1460 *
1461 * Note: enables to add as many callback as needed on the same port.
1462 */
gpio_add_callback(const struct device * port,struct gpio_callback * callback)1463 static inline int gpio_add_callback(const struct device *port,
1464 struct gpio_callback *callback)
1465 {
1466 const struct gpio_driver_api *api =
1467 (const struct gpio_driver_api *)port->api;
1468
1469 if (api->manage_callback == NULL) {
1470 return -ENOTSUP;
1471 }
1472
1473 return api->manage_callback(port, callback, true);
1474 }
1475
1476 /**
1477 * @brief Add an application callback.
1478 *
1479 * This is equivalent to:
1480 *
1481 * gpio_add_callback(spec->port, callback);
1482 *
1483 * @param spec GPIO specification from devicetree.
1484 * @param callback A valid application's callback structure pointer.
1485 * @return a value from gpio_add_callback().
1486 */
gpio_add_callback_dt(const struct gpio_dt_spec * spec,struct gpio_callback * callback)1487 static inline int gpio_add_callback_dt(const struct gpio_dt_spec *spec,
1488 struct gpio_callback *callback)
1489 {
1490 return gpio_add_callback(spec->port, callback);
1491 }
1492
1493 /**
1494 * @brief Remove an application callback.
1495 * @param port Pointer to the device structure for the driver instance.
1496 * @param callback A valid application's callback structure pointer.
1497 * @return 0 if successful, negative errno code on failure.
1498 *
1499 * @warning It is explicitly permitted, within a callback handler, to
1500 * remove the registration for the callback that is running, i.e. @p
1501 * callback. Attempts to remove other registrations on the same
1502 * device may result in undefined behavior, including failure to
1503 * invoke callbacks that remain registered and unintended invocation
1504 * of removed callbacks.
1505 *
1506 * Note: enables to remove as many callbacks as added through
1507 * gpio_add_callback().
1508 */
gpio_remove_callback(const struct device * port,struct gpio_callback * callback)1509 static inline int gpio_remove_callback(const struct device *port,
1510 struct gpio_callback *callback)
1511 {
1512 const struct gpio_driver_api *api =
1513 (const struct gpio_driver_api *)port->api;
1514
1515 if (api->manage_callback == NULL) {
1516 return -ENOTSUP;
1517 }
1518
1519 return api->manage_callback(port, callback, false);
1520 }
1521
1522 /**
1523 * @brief Remove an application callback.
1524 *
1525 * This is equivalent to:
1526 *
1527 * gpio_remove_callback(spec->port, callback);
1528 *
1529 * @param spec GPIO specification from devicetree.
1530 * @param callback A valid application's callback structure pointer.
1531 * @return a value from gpio_remove_callback().
1532 */
gpio_remove_callback_dt(const struct gpio_dt_spec * spec,struct gpio_callback * callback)1533 static inline int gpio_remove_callback_dt(const struct gpio_dt_spec *spec,
1534 struct gpio_callback *callback)
1535 {
1536 return gpio_remove_callback(spec->port, callback);
1537 }
1538
1539 /**
1540 * @brief Function to get pending interrupts
1541 *
1542 * The purpose of this function is to return the interrupt
1543 * status register for the device.
1544 * This is especially useful when waking up from
1545 * low power states to check the wake up source.
1546 *
1547 * @param dev Pointer to the device structure for the driver instance.
1548 *
1549 * @retval status != 0 if at least one gpio interrupt is pending.
1550 * @retval 0 if no gpio interrupt is pending.
1551 */
1552 __syscall int gpio_get_pending_int(const struct device *dev);
1553
z_impl_gpio_get_pending_int(const struct device * dev)1554 static inline int z_impl_gpio_get_pending_int(const struct device *dev)
1555 {
1556 const struct gpio_driver_api *api =
1557 (const struct gpio_driver_api *)dev->api;
1558
1559 if (api->get_pending_int == NULL) {
1560 return -ENOTSUP;
1561 }
1562
1563 return api->get_pending_int(dev);
1564 }
1565
1566 /**
1567 * @}
1568 */
1569
1570 #ifdef __cplusplus
1571 }
1572 #endif
1573
1574 #include <syscalls/gpio.h>
1575
1576 #endif /* ZEPHYR_INCLUDE_DRIVERS_GPIO_H_ */
1577
