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