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