Software APIs
dif_uart.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_UART_H_
6 #define OPENTITAN_SW_DEVICE_LIB_DIF_DIF_UART_H_
7 
8 /**
9  * @file
10  * @brief <a href="/hw/ip/uart/doc/">UART</a> Device Interface Functions
11  */
12 
13 #include <stdint.h>
14 
16 
18 
19 #ifdef __cplusplus
20 extern "C" {
21 #endif // __cplusplus
22 
23 /**
24  * A parity state: odd, or even.
25  */
26 typedef enum dif_uart_parity {
27  /**
28  * Indicates the "odd" parity.
29  */
31  /**
32  * Indicates the "even" parity.
33  */
36 
37 /**
38  * Runtime configuration for UART.
39  *
40  * This struct describes runtime information for one-time configuration of the
41  * hardware.
42  */
43 typedef struct dif_uart_config {
44  /**
45  * The UART baudrate.
46  */
47  uint32_t baudrate;
48  /**
49  * The frequency of the clock driving the UART.
50  */
51  uint32_t clk_freq_hz;
52  /**
53  * Whether to enable parity checking.
54  */
56  /**
57  * The parity to set.
58  */
59  dif_uart_parity_t parity;
61 
62 /**
63  * A UART FIFO watermark depth configuration.
64  */
65 typedef enum dif_uart_watermark {
66  /**
67  * Indicates a one-byte watermark.
68  */
70  /**
71  * Indicates a four-byte watermark.
72  */
74  /**
75  * Indicates an eight-byte watermark.
76  */
78  /**
79  * Indicates a sixteen-byte watermark.
80  */
82  /**
83  * Indicates a thirty-byte watermark.
84  */
87 
88 /**
89  * A UART FIFO reset selection.
90  */
91 typedef enum dif_uart_fifo_reset {
92  /**
93  * Indicates that the RX FIFO should be reset.
94  */
96  /**
97  * Indicates that the TX FIFO should be reset.
98  */
100  /**
101  * Indicates that both FIFOs should be reset.
102  */
105 
106 /**
107  * A UART system/line loopback configuration.
108  */
109 typedef enum dif_uart_loopback {
110  /**
111  * Indicates that outgoing TX bits should be recieved through RX.
112  */
114  /**
115  * Indicates that incoming RX bits should be forwarded to TX.
116  */
119 
120 /**
121  * The size of the UART TX and RX FIFOs, in bytes.
122  */
123 extern const uint32_t kDifUartFifoSizeBytes;
124 
125 /**
126  * Configures UART with runtime information.
127  *
128  * This function should need to be called once for the lifetime of `handle`.
129  *
130  * @param uart A UART handle.
131  * @param config Runtime configuration parameters.
132  * @return The result of the operation.
133  */
136  dif_uart_config_t config);
137 
138 /**
139  * Sets the RX FIFO watermark.
140  *
141  * This function is only useful when the corresponding interrupt is enabled.
142  * When the queued RX FIFO number of bytes rises to or above this
143  * level, the RX watermark interrupt is raised.
144  *
145  * @param uart A UART handle.
146  * @param watermark RX FIFO watermark.
147  * @return The result of the operation.
148  */
151  dif_uart_watermark_t watermark);
152 
153 /**
154  * Sets the TX FIFO watermark.
155  *
156  * This function is only useful when the corresponding interrupt is enabled.
157  * When the queued RX FIFO number of bytes rises to or above this
158  * level, the RX watermark interrupt is raised.
159  *
160  * @param uart A UART handle.
161  * @param watermark TX FIFO watermark.
162  * @return The result of the operation.
163  */
166  dif_uart_watermark_t watermark);
167 
168 /**
169  * Sends bytes over UART.
170  *
171  * Can be used from inside an UART ISR.
172  *
173  * This function attempts to write `bytes_requested` number of bytes to the
174  * UART TX FIFO from `bytes_requested`, and passes `bytes_written` back to
175  * the caller. `bytes_written` is optional, NULL should be passed in if the
176  * value is not needed.
177  *
178  * @param uart A UART handle.
179  * @param data Data to be written.
180  * @param bytes_requested Number of bytes requested to be written by the caller.
181  * @param[out] bytes_written Number of bytes written (optional).
182  * @return The result of the operation.
183  */
185 dif_result_t dif_uart_bytes_send(const dif_uart_t *uart, const uint8_t *data,
186  size_t bytes_requested, size_t *bytes_written);
187 
188 /**
189  * Recieves bytes over UART.
190  *
191  * Can be used from inside an UART ISR.
192  *
193  * This function attempts to read `bytes_requested` number of bytes from the
194  * UART RX FIFO into `data`, and passes `bytes_read` back to the caller.
195  * `bytes_read` is optional, NULL should be passed in if the value is not
196  * needed.
197  *
198  * @param uart A UART handle.
199  * @param bytes_requested Number of bytes requested to be read by the caller.
200  * @param[out] data Buffer for up to `bytes_requested` bytes of read data.
201  * @param[out] bytes_read Number of bytes read (optional).
202  * @return The result of the operation.
203  */
206  size_t bytes_requested, uint8_t *data,
207  size_t *bytes_read);
208 
209 /**
210  * Transmits a single UART byte (polled).
211  *
212  * This operation is polled, and will busy wait until a byte has been sent.
213  *
214  * Must not be used inside an ISR.
215  *
216  * @param uart A UART handle.
217  * @param byte Byte to be transmitted.
218  * @return The result of the operation.
219  */
221 dif_result_t dif_uart_byte_send_polled(const dif_uart_t *uart, uint8_t byte);
222 
223 /**
224  * Receives a single UART byte (polled).
225  *
226  * This operation is polled, and will busy wait until a byte has been read.
227  *
228  * Must not be used inside an ISR.
229  *
230  * @param uart A UART handle.
231  * @param[out] byte Received byte.
232  * @return The result of the operation.
233  */
236  uint8_t *byte);
237 
238 /**
239  * Gets the number of bytes available to be read from the UART RX FIFO.
240  *
241  * This function can be used to check FIFO full and empty conditions.
242  *
243  * @param uart A UART handle.
244  * @param[out] num_bytes Number of bytes available to be read.
245  * @return The result of the operation.
246  */
249  size_t *num_bytes);
250 
251 /**
252  * Gets the number of bytes available to be written from the UART TX FIFO.
253  *
254  * This function can be used to check FIFO full and empty conditions.
255  *
256  * @param uart A UART handle.
257  * @param[out] num_bytes Number of bytes available to be written.
258  * @return The result of the operation.
259  */
262  size_t *num_bytes);
263 
264 /**
265  * UART TX reset RX/TX FIFO.
266  *
267  * Resets one or both FIFOs. If the byte is in transit, this function will
268  * not abort the operation.
269  *
270  * @param uart A UART handle.
271  * @param reset FIFO to reset (RX, TX or both).
272  * @return The result of the operation.
273  */
275  dif_uart_fifo_reset_t reset);
276 
277 /**
278  * Enables or disables a transmit/receive loopback.
279  *
280  * This API can be used for testing, such as to validate transmit and receive
281  * routines.
282  *
283  * Loopback should only be enabled when device is in the IDLE state to prevent
284  * data loss/coruption. Behaviour depends on the `loopback` parameter:
285  * - `kDifUartLoopbackSystem`:
286  * Receives the data that is being transmitted. No external data can be
287  * received (from the RX line). When enabled the TX line goes high.
288  * - `kDifUartLoopbackLine`:
289  * Transmits the data that is being received. No internal data can be
290  * sent out (from the TX FIFO). When enabled the RX line goes high.
291  *
292  * @param uart A UART handle.
293  * @param loopback Loopback type (transmit/receive).
294  * @param enable Enable/disable control flag.
295  * @return The result of the operation.
296  */
298  dif_uart_loopback_t loopback,
299  dif_toggle_t enable);
300 
301 /**
302  * Enables the RX timeout with the given duration.
303  *
304  * @param uart A UART handle.
305  * @param duration_ticks RX timeout value in UART bit times (using the baud rate
306  * clock as reference) in the range [0,0xffffff].
307  * @return The result of the operation.
308  */
311  uint32_t duration_ticks);
312 
313 /**
314  * Disables the RX timeout.
315  *
316  * In addition to disabling the RX timeout the timeout duration is reset to 0
317  * ticks.
318  *
319  * @param uart A UART handle.
320  * @return The result of the operation.
321  */
324 
325 /**
326  * Gets the current status of the RX timeout control.
327  *
328  * @param uart A UART handle.
329  * @param[out] status The status of the RX timeout control (enabled or
330  * disabled).
331  * @param[out] duration_ticks RX timeout value in UART bit times (using the baud
332  * rate clock as reference) in the range [0,0xffffff] (optional).
333  * @return The result of the operation.
334  */
337  dif_toggle_t *status,
338  uint32_t *duration_ticks);
339 
340 #ifdef __cplusplus
341 } // extern "C"
342 #endif // __cplusplus
343 
344 #endif // OPENTITAN_SW_DEVICE_LIB_DIF_DIF_UART_H_