Line data Source code
1 1 : /*
2 : * Copyright (c) 2020 Friedt Professional Engineering Services, Inc
3 : *
4 : * SPDX-License-Identifier: Apache-2.0
5 : */
6 :
7 : /**
8 : * @file
9 : * @brief Backend API for emulated GPIO
10 : */
11 :
12 : #ifndef ZEPHYR_INCLUDE_DRIVERS_GPIO_GPIO_EMUL_H_
13 : #define ZEPHYR_INCLUDE_DRIVERS_GPIO_GPIO_EMUL_H_
14 :
15 : #include <zephyr/types.h>
16 : #include <zephyr/drivers/gpio.h>
17 :
18 : #ifdef __cplusplus
19 : extern "C" {
20 : #endif
21 :
22 : /**
23 : * @brief Emulated GPIO backend API
24 : * @defgroup gpio_emul Emulated GPIO
25 : * @ingroup io_emulators
26 : * @ingroup gpio_interface
27 : * @{
28 : *
29 : * Behaviour of emulated GPIO is application-defined. As-such, each
30 : * application may
31 : *
32 : * - define a Device Tree overlay file to indicate the number of GPIO
33 : * controllers as well as the number of pins for each controller
34 : * - register a callback with the GPIO controller using
35 : * @ref gpio_add_callback to emulate "wiring"
36 : * - asynchronously call @ref gpio_emul_input_set and / or
37 : * @ref gpio_emul_input_set_masked in order to emulate GPIO events
38 : *
39 : * An example of an appropriate Device Tree overlay file is in
40 : * tests/drivers/gpio/gpio_basic_api/boards/native_sim.overlay.
41 : *
42 : * An example of registering a callback to emulate "wiring" as well as
43 : * an example of calling @ref gpio_emul_input_set is in the file
44 : * tests/drivers/gpio/gpio_basic_api/src/main.c .
45 : */
46 :
47 : /**
48 : * @brief Modify the values of one or more emulated GPIO input @p pins
49 : *
50 : * @param port The emulated GPIO port
51 : * @param pins The mask of pins that have changed
52 : * @param values New values to assign to @p pins
53 : *
54 : * @return 0 on success
55 : * @return -EINVAL if an invalid argument is provided
56 : */
57 1 : int gpio_emul_input_set_masked(const struct device *port, gpio_port_pins_t pins,
58 : gpio_port_value_t values);
59 :
60 : /**
61 : * @brief Modify the value of one emulated GPIO input @p pin
62 : *
63 : * @param port The emulated GPIO port
64 : * @param pin The pin to modify
65 : * @param value New values to assign to @p pin
66 : *
67 : * @return 0 on success
68 : * @return -EINVAL if an invalid argument is provided
69 : */
70 1 : static inline int gpio_emul_input_set(const struct device *port, gpio_pin_t pin,
71 : int value)
72 : {
73 : return gpio_emul_input_set_masked(port, BIT(pin), value ? BIT(pin) : 0);
74 : }
75 :
76 : /**
77 : * @brief Modify the value of one emulated GPIO input pin from a @p gpio_dt_spec
78 : *
79 : * This is equivalent to:
80 : *
81 : * gpio_emul_input_set(spec->port, spec->pin, value);
82 : *
83 : * @param spec The emulated GPIO specification from devicetree
84 : * @param value New values to assign to the pin
85 : *
86 : * @return a value from gpio_emul_input_set()
87 : */
88 1 : static inline int gpio_emul_input_set_dt(const struct gpio_dt_spec *spec, int value)
89 : {
90 : return gpio_emul_input_set(spec->port, spec->pin, value);
91 : }
92 :
93 : /**
94 : * @brief Read the value of one or more emulated GPIO output @p pins
95 : *
96 : * @param port The emulated GPIO port
97 : * @param pins The mask of pins that have changed
98 : * @param values A pointer to where the value of @p pins will be stored
99 : *
100 : * @return 0 on success
101 : * @return -EINVAL if an invalid argument is provided
102 : */
103 1 : int gpio_emul_output_get_masked(const struct device *port, gpio_port_pins_t pins,
104 : gpio_port_value_t *values);
105 :
106 : /**
107 : * @brief Read the value of one emulated GPIO output @p pin
108 : *
109 : * @param port The emulated GPIO port
110 : * @param pin The pin to read
111 : *
112 : * @return 0 or 1 on success
113 : * @return -EINVAL if an invalid argument is provided
114 : */
115 1 : static inline int gpio_emul_output_get(const struct device *port, gpio_pin_t pin)
116 : {
117 : int ret;
118 : gpio_port_value_t values;
119 :
120 : ret = gpio_emul_output_get_masked(port, BIT(pin), &values);
121 : if (ret == 0) {
122 : ret = (values & BIT(pin)) ? 1 : 0;
123 : }
124 :
125 : return ret;
126 : }
127 :
128 : /**
129 : * @brief Read the value of one emulated GPIO output pin from a @p gpio_dt_spec
130 : *
131 : * This is equivalent to:
132 : *
133 : * gpio_emul_output_get(spec->port, spec->pin);
134 : *
135 : * @param spec The emulated GPIO specification from devicetree
136 : *
137 : * @return a value from gpio_emul_output_get()
138 : */
139 1 : static inline int gpio_emul_output_get_dt(const struct gpio_dt_spec *spec)
140 : {
141 : return gpio_emul_output_get(spec->port, spec->pin);
142 : }
143 :
144 : /**
145 : * @brief Get @p flags for a given emulated GPIO @p pin
146 : *
147 : * For more information on available flags, see @ref gpio_interface.
148 : *
149 : * @param port The emulated GPIO port
150 : * @param pin The pin to retrieve @p flags for
151 : * @param flags a pointer to where the flags for @p pin will be stored
152 : *
153 : * @return 0 on success
154 : * @return -EINVAL if an invalid argument is provided
155 : */
156 1 : int gpio_emul_flags_get(const struct device *port, gpio_pin_t pin, gpio_flags_t *flags);
157 :
158 : /**
159 : * @brief Get @p flags for a given emulated GPIO pin from a @p gpio_dt_spec
160 : *
161 : * This is equivalent to:
162 : *
163 : * gpio_emul_flags_get(spec->port, spec->pin, flags);
164 : *
165 : * For more information on available flags, see @ref gpio_interface.
166 : *
167 : * @param spec The emulated GPIO specification from devicetree
168 : * @param flags a pointer to where the flags for the pin will be stored
169 : *
170 : * @return a value from gpio_emul_flags_get()
171 : */
172 1 : static inline int gpio_emul_flags_get_dt(const struct gpio_dt_spec *spec, gpio_flags_t *flags)
173 : {
174 : return gpio_emul_flags_get(spec->port, spec->pin, flags);
175 : }
176 :
177 : /**
178 : * @}
179 : */
180 :
181 : #ifdef __cplusplus
182 : }
183 : #endif
184 :
185 : #endif /* ZEPHYR_INCLUDE_DRIVERS_GPIO_GPIO_EMUL_H_ */
|
