Software APIs
dif_uart_autogen.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_AUTOGEN_DIF_UART_AUTOGEN_H_
6 #define OPENTITAN_SW_DEVICE_LIB_DIF_AUTOGEN_DIF_UART_AUTOGEN_H_
7 
8 // This file is auto-generated.
9 
10 /**
11  * @file
12  * @brief <a href="/hw/ip/uart/doc/">UART</a> Device Interface Functions
13  */
14 
15 #include <stdbool.h>
16 #include <stdint.h>
17 
21 
22 #ifdef __cplusplus
23 extern "C" {
24 #endif // __cplusplus
25 
26 /**
27  * A handle to uart.
28  *
29  * This type should be treated as opaque by users.
30  */
31 typedef struct dif_uart {
32  /**
33  * The base address for the uart hardware registers.
34  */
36 } dif_uart_t;
37 
38 /**
39  * Creates a new handle for a(n) uart peripheral.
40  *
41  * This function does not actuate the hardware.
42  *
43  * @param base_addr The MMIO base address of the uart peripheral.
44  * @param[out] uart Out param for the initialized handle.
45  * @return The result of the operation.
46  */
49 
50 /**
51  * A uart interrupt request type.
52  */
53 typedef enum dif_uart_irq {
54  /**
55  * Raised if the transmit FIFO is past the high-water mark.
56  */
58  /**
59  * Raised if the receive FIFO is past the high-water mark.
60  */
62  /**
63  * Raised if the transmit FIFO has emptied and no transmit is ongoing.
64  */
66  /**
67  * Raised if the receive FIFO has overflowed.
68  */
70  /**
71  * Raised if a framing error has been detected on receive.
72  */
74  /**
75  * Raised if break condition has been detected on receive.
76  */
78  /**
79  * Raised if RX FIFO has characters remaining in the FIFO without being
80  * retrieved for the programmed time period.
81  */
83  /**
84  * Raised if the receiver has detected a parity error.
85  */
88 
89 /**
90  * A snapshot of the state of the interrupts for this IP.
91  *
92  * This is an opaque type, to be used with the `dif_uart_irq_get_state()`
93  * function.
94  */
96 
97 /**
98  * Returns the state of all interrupts (i.e., pending or not) for this IP.
99  *
100  * @param uart A uart handle.
101  * @param[out] snapshot Out-param for interrupt state snapshot.
102  * @return The result of the operation.
103  */
106  dif_uart_irq_state_snapshot_t *snapshot);
107 
108 /**
109  * Returns whether a particular interrupt is currently pending.
110  *
111  * @param uart A uart handle.
112  * @param irq An interrupt request.
113  * @param[out] is_pending Out-param for whether the interrupt is pending.
114  * @return The result of the operation.
115  */
118  bool *is_pending);
119 
120 /**
121  * Acknowledges all interrupts, indicating to the hardware that all
122  * interrupts have been successfully serviced.
123  *
124  * @param uart A uart handle.
125  * @return The result of the operation.
126  */
129 
130 /**
131  * Acknowledges a particular interrupt, indicating to the hardware that it has
132  * been successfully serviced.
133  *
134  * @param uart A uart handle.
135  * @param irq An interrupt request.
136  * @return The result of the operation.
137  */
140  dif_uart_irq_t irq);
141 
142 /**
143  * Forces a particular interrupt, causing it to be serviced as if hardware had
144  * asserted it.
145  *
146  * @param uart A uart handle.
147  * @param irq An interrupt request.
148  * @return The result of the operation.
149  */
152 
153 /**
154  * A snapshot of the enablement state of the interrupts for this IP.
155  *
156  * This is an opaque type, to be used with the
157  * `dif_uart_irq_disable_all()` and `dif_uart_irq_restore_all()`
158  * functions.
159  */
161 
162 /**
163  * Checks whether a particular interrupt is currently enabled or disabled.
164  *
165  * @param uart A uart handle.
166  * @param irq An interrupt request.
167  * @param[out] state Out-param toggle state of the interrupt.
168  * @return The result of the operation.
169  */
172  dif_uart_irq_t irq, dif_toggle_t *state);
173 
174 /**
175  * Sets whether a particular interrupt is currently enabled or disabled.
176  *
177  * @param uart A uart handle.
178  * @param irq An interrupt request.
179  * @param state The new toggle state for the interrupt.
180  * @return The result of the operation.
181  */
184  dif_uart_irq_t irq, dif_toggle_t state);
185 
186 /**
187  * Disables all interrupts, optionally snapshotting all enable states for later
188  * restoration.
189  *
190  * @param uart A uart handle.
191  * @param[out] snapshot Out-param for the snapshot; may be `NULL`.
192  * @return The result of the operation.
193  */
196  dif_uart_irq_enable_snapshot_t *snapshot);
197 
198 /**
199  * Restores interrupts from the given (enable) snapshot.
200  *
201  * @param uart A uart handle.
202  * @param snapshot A snapshot to restore from.
203  * @return The result of the operation.
204  */
207  const dif_uart_t *uart, const dif_uart_irq_enable_snapshot_t *snapshot);
208 
209 #ifdef __cplusplus
210 } // extern "C"
211 #endif // __cplusplus
212 
213 #endif // OPENTITAN_SW_DEVICE_LIB_DIF_AUTOGEN_DIF_UART_AUTOGEN_H_