Software APIs
dif_gpio.h
Go to the documentation of this file.
1 // Copyright lowRISC contributors.
2 // Licensed under the Apache License, Version 2.0, see LICENSE for details.
3 // SPDX-License-Identifier: Apache-2.0
4 
5 #ifndef OPENTITAN_SW_DEVICE_LIB_DIF_DIF_GPIO_H_
6 #define OPENTITAN_SW_DEVICE_LIB_DIF_DIF_GPIO_H_
7 
8 /**
9  * @file
10  * @brief <a href="/hw/ip/gpio/doc/">GPIO</a> Device Interface Functions
11  */
12 
13 #include <stddef.h>
14 #include <stdint.h>
15 
19 
21 
22 #ifdef __cplusplus
23 extern "C" {
24 #endif // __cplusplus
25 
26 /**
27  * A GPIO interrupt request trigger.
28  *
29  * Each GPIO pin has an associated interrupt that can be independently
30  * configured
31  * to be edge and/or level sensitive. This enum defines supported configurations
32  * for
33  * these interrupts.
34  */
35 typedef enum dif_gpio_irq_trigger {
36  /**
37  * Trigger on rising edge.
38  */
40  /**
41  * Trigger on falling edge.
42  */
44  /**
45  * Trigger when input is low.
46  */
48  /**
49  * Trigger when input is high.
50  */
52  /**
53  * Trigger on rising and falling edges.
54  */
56  /**
57  * Trigger on rising edge or when the input is low.
58  */
60  /**
61  * Trigger on falling edge or when the input is high.
62  */
65 
66 /**
67  * A GPIO pin index, ranging from 0 to 31.
68  *
69  * This type serves as the GPIO interrupt request type.
70  */
71 typedef uint32_t dif_gpio_pin_t;
72 
73 /**
74  * State for all 32 GPIO pins, given as bit fields.
75  *
76  * The Nth bit represents the state of the Nth pin.
77  *
78  * This type is also used as a vector of `dif_toggle_t`s, to indicate
79  * toggle state across all 32 pins. A set bit corresponds to
80  * `kDifGpioToggleEnabled`.
81  */
82 typedef uint32_t dif_gpio_state_t;
83 
84 /**
85  * A mask for selecting GPIO pins.
86  *
87  * If the Nth bit is enabled, then the Nth pin is selected by the mask.
88  */
89 typedef uint32_t dif_gpio_mask_t;
90 
91 /**
92  * Resets a GPIO device.
93  *
94  * Resets the given GPIO device by setting its configuration registers to
95  * reset values. Disables interrupts, output, and input filter.
96  *
97  * @param gpio A GPIO handle.
98  * @return The result of the operation.
99  */
102 
103 /**
104  * Configures interrupt triggers for a set of pins.
105  *
106  * This function configures interrupt triggers, i.e. rising-edge, falling-edge,
107  * level-high, and level-low, for the pins given by the mask. Note that
108  * interrupt of the pin must also be enabled to generate interrupts.
109  *
110  * @param gpio A GPIO handle.
111  * @param mask Mask that identifies the pins whose interrupt triggers will be
112  * configured.
113  * @param trigger New configuration of interrupt triggers.
114  * @return The result of the operation.
115  */
118  dif_gpio_mask_t mask,
119  dif_gpio_irq_trigger_t trigger);
120 
121 /**
122  * Reads from a pin.
123  *
124  * The value returned by this function is independent of the output enable
125  * setting and includes the effects of the input noise filter and the load on
126  * the pin.
127  *
128  * @param gpio A GPIO handle.
129  * @param pin A GPIO pin.
130  * @param[out] state Pin value.
131  * @return The result of the operation.
132  */
134 dif_result_t dif_gpio_read(const dif_gpio_t *gpio, dif_gpio_pin_t pin,
135  bool *state);
136 
137 /**
138  * Reads from all pins.
139  *
140  * The value returned by this function is independent of the output enable
141  * setting and includes the effects of the input noise filter and the load on
142  * the pins.
143  *
144  * @param gpio A GPIO handle.
145  * @param[out] state Pin values.
146  * @return The result of the operation.
147  */
149 dif_result_t dif_gpio_read_all(const dif_gpio_t *gpio, dif_gpio_state_t *state);
150 
151 /**
152  * Writes to a pin.
153  *
154  * The actual value on the pin depends on the output enable setting.
155  *
156  * @param gpio A GPIO handle.
157  * @param pin A GPIO pin.
158  * @param state Value to write.
159  * @return The result of the operation.
160  */
162 dif_result_t dif_gpio_write(const dif_gpio_t *gpio, dif_gpio_pin_t pin,
163  bool state);
164 
165 /**
166  * Writes to all pins.
167  *
168  * The actual values on the pins depend on the output enable setting.
169  *
170  * @param gpio A GPIO handle.
171  * @param state Value to write.
172  * @return The result of the operation.
173  */
175 dif_result_t dif_gpio_write_all(const dif_gpio_t *gpio, dif_gpio_state_t state);
176 
177 /**
178  * Writes to the pins identified by a mask.
179  *
180  * The actual values on the pins depend on the output enable setting.
181  *
182  * @param gpio A GPIO handle.
183  * @param mask Mask that identifies the pins to write to.
184  * @param state Value to write.
185  * @return The result of the operation.
186  */
188 dif_result_t dif_gpio_write_masked(const dif_gpio_t *gpio, dif_gpio_mask_t mask,
189  dif_gpio_state_t state);
190 
191 /**
192  * Sets output enable mode of a pin.
193  *
194  * @param gpio A GPIO handle.
195  * @param pin A GPIO pin.
196  * @param state Output mode of the pin.
197  * @return The result of the operation.
198  */
201  dif_gpio_pin_t pin,
202  dif_toggle_t state);
203 
204 /**
205  * Sets output modes of all pins.
206  *
207  * @param gpio A GPIO handle.
208  * @param state Output modes of the pins.
209  * @return The result of the operation.
210  */
213  dif_gpio_state_t state);
214 
215 /**
216  * Sets the output modes of the pins identified by a mask.
217  *
218  * @param gpio A GPIO handle.
219  * @param mask Mask that identifies the pins whose output modes will be set.
220  * @param state Output modes of the pins.
221  * @return The result of the operation.
222  */
225  dif_gpio_mask_t mask,
226  dif_gpio_state_t state);
227 
228 /**
229  * Enable noise filter for GPIO inputs.
230  *
231  * When enabled, changes in the pin value will be ignored unless stable
232  * for 16 cycles.
233  *
234  * @param gpio A GPIO handle.
235  * @param mask Mask that identifies pins to set the filter state of.
236  * @param state The new toggle state for the filter.
237  * @return The result of the operation.
238  */
241  dif_gpio_mask_t mask,
242  dif_toggle_t state);
243 
244 #ifdef __cplusplus
245 } // extern "C"
246 #endif // __cplusplus
247 
248 #endif // OPENTITAN_SW_DEVICE_LIB_DIF_DIF_GPIO_H_