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 
18 
19 #ifdef __cplusplus
20 extern "C" {
21 #endif // __cplusplus
22 
23 /**
24  * A toggle state: enabled, or disabled.
25  *
26  * This enum may be used instead of a `bool` when describing an enabled/disabled
27  * state.
28  *
29  * This enum may be used with `dif_gpio_toggle_vec_t` to set individual bits
30  * within it; `dif_gpio_toggle_t`'s variants are guaranteed to be compatible
31  * with `dif_gpio_toggle_vec_t`.
32  */
33 typedef enum dif_gpio_toggle {
34  /*
35  * The "enabled" state.
36  */
37  kDifGpioToggleEnabled = true,
38  /**
39  * The "disabled" state.
40  */
43 
44 /**
45  * Hardware instantiation parameters for GPIO.
46  *
47  * This struct describes information about the underlying hardware that is
48  * not determined until the hardware design is used as part of a top-level
49  * design.
50  */
51 typedef struct dif_gpio_params {
52  /**
53  * The base address for the GPIO hardware registers.
54  */
57 
58 /**
59  * A handle to GPIO.
60  *
61  * This type should be treated as opaque by users.
62  */
63 typedef struct dif_gpio { dif_gpio_params_t params; } dif_gpio_t;
64 
65 /**
66  * The result of a GPIO operation.
67  */
68 typedef enum dif_gpio_result {
69  /**
70  * Indicates that the operation succeeded.
71  */
73  /**
74  * Indicates some unspecified failure.
75  */
77  /**
78  * Indicates that some parameter passed into a function failed a
79  * precondition.
80  *
81  * When this value is returned, no hardware operations occurred.
82  */
85 
86 /**
87  * A GPIO interrupt request trigger.
88  *
89  * Each GPIO pin has an associated interrupt that can be independently
90  * configured
91  * to be edge and/or level sensitive. This enum defines supported configurations
92  * for
93  * these interrupts.
94  */
95 typedef enum dif_gpio_irq_trigger {
96  /**
97  * Trigger on rising edge.
98  */
100  /**
101  * Trigger on falling edge.
102  */
104  /**
105  * Trigger when input is low.
106  */
108  /**
109  * Trigger when input is high.
110  */
112  /**
113  * Trigger on rising and falling edges.
114  */
116  /**
117  * Trigger on rising edge or when the input is low.
118  */
120  /**
121  * Trigger on falling edge or when the input is high.
122  */
125 
126 /**
127  * A GPIO pin index, ranging from 0 to 31.
128  *
129  * This type serves as the GPIO interrupt request type.
130  */
131 typedef uint32_t dif_gpio_pin_t;
132 
133 /**
134  * State for all 32 GPIO pins, given as bit fields.
135  *
136  * The Nth bit represents the state of the Nth pin.
137  *
138  * This type is also used as a vector of `dif_gpio_toggle_t`s, to indicate
139  * toggle state across all 32 pins. A set bit corresponds to
140  * `kDifGpioToggleEnabled`.
141  *
142  * It is also used with `dif_gpio_irq_disable_all()` and
143  * `dif_gpio_irq_restore_all()`.
144  */
145 typedef uint32_t dif_gpio_state_t;
146 
147 /**
148  * A mask for selecting GPIO pins.
149  *
150  * If the Nth bit is enabled, then the Nth pin is selected by the mask.
151  */
152 typedef uint32_t dif_gpio_mask_t;
153 
154 /**
155  * Creates a new handle for GPIO.
156  *
157  * This function does not actuate the hardware.
158  *
159  * @param params Hardware instantiation parameters.
160  * @param[out] gpio Out param for the initialized handle.
161  * @return The result of the operation.
162  */
165 
166 /**
167  * Resets a GPIO device.
168  *
169  * Resets the given GPIO device by setting its configuration registers to
170  * reset values. Disables interrupts, output, and input filter.
171  *
172  * @param gpio A GPIO handle.
173  * @return The result of the operation.
174  */
177 
178 /**
179  * Returns whether a particular pin's interrupt is currently pending.
180  *
181  * @param gpio A GPIO handle.
182  * @param pin A GPIO pin.
183  * @param[out] is_pending Out-param for whether the interrupt is pending.
184  * @return The result of the operation.
185  */
188  dif_gpio_pin_t pin, bool *is_pending);
189 
190 /**
191  * Returns a GPIO state representing which pins have interrupts enabled.
192  *
193  * @param gpio A GPIO handle.
194  * @param[out] is_pending Out-param for which interrupts are pending.
195  * @return The result of the operation.
196  */
199  dif_gpio_state_t *is_pending);
200 
201 /**
202  * Acknowledges a particular pin's interrupt, indicating to the hardware that it
203  * has
204  * been successfully serviced.
205  *
206  * @param gpio A GPIO handle.
207  * @param pin A GPIO pin.
208  * @return The result of the operation.
209  */
212  dif_gpio_pin_t pin);
213 
214 /**
215  * Checks whether a particular pin's interrupt is currently enabled or disabled.
216  *
217  * @param gpio A GPIO handle.
218  * @param pin A GPIO pin.
219  * @param[out] state Out-param toggle state of the interrupt.
220  * @return The result of the operation.
221  */
224  dif_gpio_pin_t pin,
225  dif_gpio_toggle_t *state);
226 
227 /**
228  * Sets whether a particular pin's interrupt is currently enabled or disabled.
229  *
230  * @param gpio A GPIO handle.
231  * @param pin A GPIO pin.
232  * @param state The new toggle state for the interrupt.
233  * @return The result of the operation.
234  */
237  dif_gpio_pin_t pin,
238  dif_gpio_toggle_t state);
239 
240 /**
241  * Sets whether a particular pin's interrupt is currently enabled or disabled.
242  *
243  * @param gpio A GPIO handle.
244  * @param mask Mask that identifies the pins whose interrupt triggers will be
245  * configured.
246  * @param state The new toggle state for the interrupt.
247  * @return The result of the operation.
248  */
251  dif_gpio_mask_t mask,
252  dif_gpio_toggle_t state);
253 
254 /**
255  * Forces a particular pin's interrupt, causing it to be serviced as if hardware
256  * had asserted it.
257  *
258  * @param gpio A GPIO handle.
259  * @param pin A GPIO pin.
260  * @return The result of the operation.
261  */
264  dif_gpio_pin_t pin);
265 
266 /**
267  * Disables all interrupts, optionally snapshotting all toggle state for later
268  * restoration.
269  *
270  * @param gpio A GPIO handle.
271  * @param[out] snapshot Out-param for the snapshot; may be `NULL`.
272  * @return The result of the operation.
273  */
276  dif_gpio_state_t *snapshot);
277 
278 /**
279  * Restores interrupts from the given snapshot.
280  *
281  * This function can be used with `dif_gpio_irq_disable_all()` to temporary
282  * interrupt save-and-restore.
283  *
284  * @param gpio A GPIO handle.
285  * @param snapshot A snapshot to restore from.
286  * @return The result of the operation.
287  */
290  const dif_gpio_state_t *snapshot);
291 
292 /**
293  * Configures interrupt triggers for a set of pins.
294  *
295  * This function configures interrupt triggers, i.e. rising-edge, falling-edge,
296  * level-high, and level-low, for the pins given by the mask. Note that
297  * interrupt of the pin must also be enabled to generate interrupts.
298  *
299  * @param gpio A GPIO handle.
300  * @param mask Mask that identifies the pins whose interrupt triggers will be
301  * configured.
302  * @param trigger New configuration of interrupt triggers.
303  * @return The result of the operation.
304  */
307  dif_gpio_mask_t mask,
308  dif_gpio_irq_trigger_t trigger);
309 
310 /**
311  * Reads from a pin.
312  *
313  * The value returned by this function is independent of the output enable
314  * setting and includes the effects of the input noise filter and the load on
315  * the pin.
316  *
317  * @param gpio A GPIO handle.
318  * @param pin A GPIO pin.
319  * @param[out] state Pin value.
320  * @return The result of the operation.
321  */
323 dif_gpio_result_t dif_gpio_read(const dif_gpio_t *gpio, dif_gpio_pin_t pin,
324  bool *state);
325 
326 /**
327  * Reads from all pins.
328  *
329  * The value returned by this function is independent of the output enable
330  * setting and includes the effects of the input noise filter and the load on
331  * the pins.
332  *
333  * @param gpio A GPIO handle.
334  * @param[out] state Pin values.
335  * @return The result of the operation.
336  */
339  dif_gpio_state_t *state);
340 
341 /**
342  * Writes to a pin.
343  *
344  * The actual value on the pin depends on the output enable setting.
345  *
346  * @param gpio A GPIO handle.
347  * @param pin A GPIO pin.
348  * @param state Value to write.
349  * @return The result of the operation.
350  */
352 dif_gpio_result_t dif_gpio_write(const dif_gpio_t *gpio, dif_gpio_pin_t pin,
353  bool state);
354 
355 /**
356  * Writes to all pins.
357  *
358  * The actual values on the pins depend on the output enable setting.
359  *
360  * @param gpio A GPIO handle.
361  * @param state Value to write.
362  * @return The result of the operation.
363  */
366  dif_gpio_state_t state);
367 
368 /**
369  * Writes to the pins identified by a mask.
370  *
371  * The actual values on the pins depend on the output enable setting.
372  *
373  * @param gpio A GPIO handle.
374  * @param mask Mask that identifies the pins to write to.
375  * @param state Value to write.
376  * @return The result of the operation.
377  */
380  dif_gpio_mask_t mask,
381  dif_gpio_state_t state);
382 
383 /**
384  * Sets output enable mode of a pin.
385  *
386  * @param gpio A GPIO handle.
387  * @param pin A GPIO pin.
388  * @param state Output mode of the pin.
389  * @return The result of the operation.
390  */
393  dif_gpio_pin_t pin,
394  dif_gpio_toggle_t state);
395 
396 /**
397  * Sets output modes of all pins.
398  *
399  * @param gpio A GPIO handle.
400  * @param state Output modes of the pins.
401  * @return The result of the operation.
402  */
405  dif_gpio_state_t state);
406 
407 /**
408  * Sets the output modes of the pins identified by a mask.
409  *
410  * @param gpio A GPIO handle.
411  * @param mask Mask that identifies the pins whose output modes will be set.
412  * @param state Output modes of the pins.
413  * @return The result of the operation.
414  */
417  dif_gpio_mask_t mask,
418  dif_gpio_state_t state);
419 
420 /**
421  * Enable noise filter for GPIO inputs.
422  *
423  * When enabled, changes in the pin value will be ignored unless stable
424  * for 16 cycles.
425  *
426  * @param gpio A GPIO handle.
427  * @param mask Mask that identifies pins to set the filter state of.
428  * @param state The new toggle state for the filter.
429  * @return The result of the operation.
430  */
433  const dif_gpio_t *gpio, dif_gpio_mask_t mask, dif_gpio_toggle_t state);
434 
435 #ifdef __cplusplus
436 } // extern "C"
437 #endif // __cplusplus
438 
439 #endif // OPENTITAN_SW_DEVICE_LIB_DIF_DIF_GPIO_H_