Software APIs
dif_gpio.h
Go to the documentation of this file.
1// Copyright lowRISC contributors (OpenTitan project).
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
20#include "sw/device/lib/dif/autogen/dif_gpio_autogen.h"
21
22#ifdef __cplusplus
23extern "C" {
24#endif // __cplusplus
25
26enum {
27 /**
28 * Number of pins.
29 *
30 * This constant is used to check that arguments of type `dif_gpio_pin_t` are
31 * within bounds.
32 */
34};
35
36/**
37 * A GPIO interrupt request trigger.
38 *
39 * Each GPIO pin has an associated interrupt that can be independently
40 * configured to be edge and/or level sensitive. This enum defines supported
41 * configurations for these interrupts.
42 */
44 /**
45 * Trigger on rising edge.
46 */
48 /**
49 * Trigger on falling edge.
50 */
52 /**
53 * Trigger when input is low.
54 */
56 /**
57 * Trigger when input is high.
58 */
60 /**
61 * Trigger on rising and falling edges.
62 */
64 /**
65 * Trigger on rising edge or when the input is low.
66 */
68 /**
69 * Trigger on falling edge or when the input is high.
70 */
73
74/**
75 * A GPIO pin index, ranging from 0 to `kDifGpioNumPins - 1`.
76 */
77typedef uint32_t dif_gpio_pin_t;
78
79/**
80 * State for all 32 GPIO pins, given as bit fields.
81 *
82 * The Nth bit represents the state of the Nth pin.
83 *
84 * This type is also used as a vector of `dif_toggle_t`s, to indicate
85 * toggle state across all 32 pins. A set bit corresponds to
86 * `kDifGpioToggleEnabled`.
87 */
88typedef uint32_t dif_gpio_state_t;
89
90/**
91 * A mask for selecting GPIO pins.
92 *
93 * If the Nth bit is enabled, then the Nth pin is selected by the mask.
94 */
95typedef uint32_t dif_gpio_mask_t;
96
97/**
98 * Resets a GPIO device.
99 *
100 * Resets the given GPIO device by setting its configuration registers to
101 * reset values. Disables interrupts, output, and input filter.
102 *
103 * @param gpio A GPIO handle.
104 * @return The result of the operation.
105 */
108
109/**
110 * Configures interrupt triggers for a set of pins.
111 *
112 * This function configures interrupt triggers, i.e. rising-edge, falling-edge,
113 * level-high, and level-low, for the pins given by the mask. Note that
114 * interrupt of the pin must also be enabled to generate interrupts.
115 *
116 * @param gpio A GPIO handle.
117 * @param mask Mask that identifies the pins whose interrupt triggers will be
118 * configured.
119 * @param trigger New configuration of interrupt triggers.
120 * @return The result of the operation.
121 */
124 dif_gpio_mask_t mask,
125 dif_gpio_irq_trigger_t trigger);
126
127/**
128 * Reads from a pin.
129 *
130 * The value returned by this function is independent of the output enable
131 * setting and includes the effects of the input noise filter and the load on
132 * the pin.
133 *
134 * @param gpio A GPIO handle.
135 * @param pin A GPIO pin.
136 * @param[out] state Pin value.
137 * @return The result of the operation.
138 */
141 bool *state);
142
143/**
144 * Reads from all pins.
145 *
146 * The value returned by this function is independent of the output enable
147 * setting and includes the effects of the input noise filter and the load on
148 * the pins.
149 *
150 * @param gpio A GPIO handle.
151 * @param[out] state Pin values.
152 * @return The result of the operation.
153 */
156
157/**
158 * Writes to a pin.
159 *
160 * The actual value on the pin depends on the output enable setting.
161 *
162 * @param gpio A GPIO handle.
163 * @param pin A GPIO pin.
164 * @param state Value to write.
165 * @return The result of the operation.
166 */
169 bool state);
170
171/**
172 * Writes to all pins.
173 *
174 * The actual values on the pins depend on the output enable setting.
175 *
176 * @param gpio A GPIO handle.
177 * @param state Value to write.
178 * @return The result of the operation.
179 */
182
183/**
184 * Writes to the pins identified by a mask.
185 *
186 * The actual values on the pins depend on the output enable setting.
187 *
188 * @param gpio A GPIO handle.
189 * @param mask Mask that identifies the pins to write to.
190 * @param state Value to write.
191 * @return The result of the operation.
192 */
195 dif_gpio_state_t state);
196
197/**
198 * Sets output enable mode of a pin.
199 *
200 * @param gpio A GPIO handle.
201 * @param pin A GPIO pin.
202 * @param state Output mode of the pin.
203 * @return The result of the operation.
204 */
207 dif_gpio_pin_t pin,
208 dif_toggle_t state);
209
210/**
211 * Sets output modes of all pins.
212 *
213 * @param gpio A GPIO handle.
214 * @param state Output modes of the pins.
215 * @return The result of the operation.
216 */
219 dif_gpio_state_t state);
220
221/**
222 * Sets the output modes of the pins identified by a mask.
223 *
224 * @param gpio A GPIO handle.
225 * @param mask Mask that identifies the pins whose output modes will be set.
226 * @param state Output modes of the pins.
227 * @return The result of the operation.
228 */
231 dif_gpio_mask_t mask,
232 dif_gpio_state_t state);
233
234/**
235 * Enable noise filter for GPIO inputs.
236 *
237 * When enabled, changes in the pin value will be ignored unless stable
238 * for 16 cycles.
239 *
240 * @param gpio A GPIO handle.
241 * @param mask Mask that identifies pins to set the filter state of.
242 * @param state The new toggle state for the filter.
243 * @return The result of the operation.
244 */
247 dif_gpio_mask_t mask,
248 dif_toggle_t state);
249
250#ifdef __cplusplus
251} // extern "C"
252#endif // __cplusplus
253
254#endif // OPENTITAN_SW_DEVICE_LIB_DIF_DIF_GPIO_H_