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 gpio_interface
26 * @{
27 *
28 * Behaviour of emulated GPIO is application-defined. As-such, each
29 * application may
30 *
31 * - define a Device Tree overlay file to indicate the number of GPIO
32 * controllers as well as the number of pins for each controller
33 * - register a callback with the GPIO controller using
34 * @ref gpio_add_callback to emulate "wiring"
35 * - asynchronously call @ref gpio_emul_input_set and / or
36 * @ref gpio_emul_input_set_masked in order to emulate GPIO events
37 *
38 * An example of an appropriate Device Tree overlay file is in
39 * tests/drivers/gpio/gpio_basic_api/boards/native_posix_64.overlay.
40 *
41 * An example of registering a callback to emulate "wiring" as well as
42 * an example of calling @ref gpio_emul_input_set is in the file
43 * tests/drivers/gpio/gpio_basic_api/src/main.c .
44 */
45
46 /**
47 * @brief Modify the values of one or more emulated GPIO input @p pins
48 *
49 * @param port The emulated GPIO port
50 * @param pins The mask of pins that have changed
51 * @param values New values to assign to @p pins
52 *
53 * @return 0 on success
54 * @return -EINVAL if an invalid argument is provided
55 */
56 int gpio_emul_input_set_masked(const struct device *port, gpio_port_pins_t pins,
57 gpio_port_value_t values);
58
59 /**
60 * @brief Modify the value of one emulated GPIO input @p pin
61 *
62 * @param port The emulated GPIO port
63 * @param pin The pin to modify
64 * @param value New values to assign to @p pin
65 *
66 * @return 0 on success
67 * @return -EINVAL if an invalid argument is provided
68 */
gpio_emul_input_set(const struct device * port,gpio_pin_t pin,int value)69 static inline int gpio_emul_input_set(const struct device *port, gpio_pin_t pin,
70 int value)
71 {
72 return gpio_emul_input_set_masked(port, BIT(pin), value ? BIT(pin) : 0);
73 }
74
75 /**
76 * @brief Read the value of one or more emulated GPIO output @p pins
77 *
78 * @param port The emulated GPIO port
79 * @param pins The mask of pins that have changed
80 * @param values A pointer to where the value of @p pins will be stored
81 *
82 * @return 0 on success
83 * @return -EINVAL if an invalid argument is provided
84 */
85 int gpio_emul_output_get_masked(const struct device *port, gpio_port_pins_t pins,
86 gpio_port_value_t *values);
87
88 /**
89 * @brief Read the value of one emulated GPIO output @p pin
90 *
91 * @param port The emulated GPIO port
92 * @param pin The pin to read
93 *
94 * @return 0 or 1 on success
95 * @return -EINVAL if an invalid argument is provided
96 */
gpio_emul_output_get(const struct device * port,gpio_pin_t pin)97 static inline int gpio_emul_output_get(const struct device *port, gpio_pin_t pin)
98 {
99 int ret;
100 gpio_port_value_t values;
101
102 ret = gpio_emul_output_get_masked(port, BIT(pin), &values);
103 if (ret == 0) {
104 ret = (values & BIT(pin)) ? 1 : 0;
105 }
106
107 return ret;
108 }
109
110 /**
111 * @brief Get @p flags for a given emulated GPIO @p pin
112 *
113 * For more information on available flags, see @ref gpio_interface.
114 *
115 * @param port The emulated GPIO port
116 * @param pin The pin to retrieve @p flags for
117 * @param flags a pointer to where the flags for @p pin will be stored
118 *
119 * @return 0 on success
120 * @return -EINVAL if an invalid argument is provided
121 */
122 int gpio_emul_flags_get(const struct device *port, gpio_pin_t pin, gpio_flags_t *flags);
123
124 /**
125 * @}
126 */
127
128 #ifdef __cplusplus
129 }
130 #endif
131
132 #endif /* ZEPHYR_INCLUDE_DRIVERS_GPIO_GPIO_EMUL_H_ */
133
