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