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