Software APIs
dt_uart.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
// Device table API auto-generated by `dtgen`
6
7
#ifndef OPENTITAN_DT_UART_H_
8
#define OPENTITAN_DT_UART_H_
9
10
#ifdef __cplusplus
11
extern
"C"
{
12
#endif
// __cplusplus
13
14
/**
15
* @file
16
* @brief Device Tables (DT) for IP uart and top earlgrey.
17
*
18
* This file contains the type definitions and global functions of the uart.
19
*/
20
21
#include "hw/top/dt/dt_api.h"
22
#include <stdint.h>
23
24
25
26
/**
27
* List of instances.
28
*/
29
typedef
enum
dt_uart
{
30
kDtUart0
= 0,
/**< uart0 */
31
kDtUart1
= 1,
/**< uart1 */
32
kDtUart2
= 2,
/**< uart2 */
33
kDtUart3
= 3,
/**< uart3 */
34
kDtUartFirst = 0,
/**< \internal First instance */
35
kDtUartCount = 4,
/**< \internal Number of instances */
36
}
dt_uart_t
;
37
38
/**
39
* List of register blocks.
40
*
41
* Register blocks are guaranteed to start at 0 and to be consecutively numbered.
42
*/
43
typedef
enum
dt_uart_reg_block
{
44
kDtUartRegBlockCore = 0,
/**< */
45
kDtUartRegBlockCount = 1,
/**< \internal Number of register blocks */
46
}
dt_uart_reg_block_t
;
47
48
/** Primary register block (associated with the "primary" set of registers that control the IP). */
49
static
const
dt_uart_reg_block_t
kDtUartRegBlockPrimary = kDtUartRegBlockCore;
50
51
/**
52
* List of IRQs.
53
*
54
* IRQs are guaranteed to be numbered consecutively from 0.
55
*/
56
typedef
enum
dt_uart_irq
{
57
kDtUartIrqTxWatermark
= 0,
/**< raised if the transmit FIFO is past the high-water mark. */
58
kDtUartIrqRxWatermark
= 1,
/**< raised if the receive FIFO is past the high-water mark. */
59
kDtUartIrqTxDone
= 2,
/**< raised if the transmit FIFO has emptied and no transmit is ongoing. */
60
kDtUartIrqRxOverflow
= 3,
/**< raised if the receive FIFO has overflowed. */
61
kDtUartIrqRxFrameErr
= 4,
/**< raised if a framing error has been detected on receive. */
62
kDtUartIrqRxBreakErr
= 5,
/**< raised if break condition has been detected on receive. */
63
kDtUartIrqRxTimeout
= 6,
/**< raised if RX FIFO has characters remaining in the FIFO without being
64
retrieved for the programmed time period. */
65
kDtUartIrqRxParityErr
= 7,
/**< raised if the receiver has detected a parity error. */
66
kDtUartIrqTxEmpty
= 8,
/**< raised if the transmit FIFO is empty. */
67
kDtUartIrqCount = 9,
/**< \internal Number of IRQs */
68
}
dt_uart_irq_t
;
69
70
/**
71
* List of Alerts.
72
*
73
* Alerts are guaranteed to be numbered consecutively from 0.
74
*/
75
typedef
enum
dt_uart_alert
{
76
kDtUartAlertFatalFault
= 0,
/**< This fatal alert is triggered when a fatal TL-UL bus integrity fault is detected. */
77
kDtUartAlertCount = 1,
/**< \internal Number of Alerts */
78
}
dt_uart_alert_t
;
79
80
/**
81
* List of clock ports.
82
*
83
* Clock ports are guaranteed to be numbered consecutively from 0.
84
*/
85
typedef
enum
dt_uart_clock
{
86
kDtUartClockClk
= 0,
/**< Clock port clk_i */
87
kDtUartClockCount = 1,
/**< \internal Number of clock ports */
88
}
dt_uart_clock_t
;
89
90
/**
91
* List of reset ports.
92
*
93
* Reset ports are guaranteed to be numbered consecutively from 0.
94
*/
95
typedef
enum
dt_uart_reset
{
96
kDtUartResetRst
= 0,
/**< Reset port rst_ni */
97
kDtUartResetCount = 1,
/**< \internal Number of reset ports */
98
}
dt_uart_reset_t
;
99
100
/**
101
* List of peripheral I/O.
102
*
103
* Peripheral I/O are guaranteed to be numbered consecutively from 0.
104
*/
105
typedef
enum
dt_uart_periph_io
{
106
kDtUartPeriphIoRx = 0,
/**< */
107
kDtUartPeriphIoTx = 1,
/**< */
108
kDtUartPeriphIoCount = 2,
/**< \internal Number of peripheral I/O */
109
}
dt_uart_periph_io_t
;
110
111
/**
112
* List of supported hardware features.
113
*/
114
#define OPENTITAN_UART_HAS_PARITY 1
115
#define OPENTITAN_UART_HAS_LINE_LOOPBACK 1
116
#define OPENTITAN_UART_HAS_SYSTEM_LOOPBACK 1
117
#define OPENTITAN_UART_HAS_BAUD_RATE_CONTROL 1
118
#define OPENTITAN_UART_HAS_LINE_BREAK 1
119
#define OPENTITAN_UART_HAS_FIFO_INTERRUPTS 1
120
121
122
123
/**
124
* Get the uart instance from an instance ID
125
*
126
* For example, `dt_uart_from_instance_id(kDtInstanceIdUart3) == kDtUart3`.
127
*
128
* @param inst_id Instance ID.
129
* @return A uart instance.
130
*
131
* **Note:** This function only makes sense if the instance ID has device type uart,
132
* otherwise the returned value is unspecified.
133
*/
134
dt_uart_t
dt_uart_from_instance_id
(
dt_instance_id_t
inst_id);
135
136
/**
137
* Get the instance ID of an instance.
138
*
139
* @param dt Instance of uart.
140
* @return The instance ID of that instance.
141
*/
142
dt_instance_id_t
dt_uart_instance_id
(
dt_uart_t
dt);
143
144
/**
145
* Get the register base address of an instance.
146
*
147
* @param dt Instance of uart.
148
* @param reg_block The register block requested.
149
* @return The register base address of the requested block.
150
*/
151
uint32_t
dt_uart_reg_block
(
152
dt_uart_t
dt,
153
dt_uart_reg_block_t
reg_block);
154
155
/**
156
* Get the primary register base address of an instance.
157
*
158
* This is just a convenience function, equivalent to
159
* `dt_uart_reg_block(dt, kDtUartRegBlockCore)`
160
*
161
* @param dt Instance of uart.
162
* @return The register base address of the primary register block.
163
*/
164
static
inline
uint32_t dt_uart_primary_reg_block(
165
dt_uart_t
dt) {
166
return
dt_uart_reg_block
(dt, kDtUartRegBlockCore);
167
}
168
169
/**
170
* Get the PLIC ID of a uart IRQ for a given instance.
171
*
172
* If the instance is not connected to the PLIC, this function
173
* will return `kDtPlicIrqIdNone`.
174
*
175
* @param dt Instance of uart.
176
* @param irq A uart IRQ.
177
* @return The PLIC ID of the IRQ of this instance.
178
*/
179
dt_plic_irq_id_t
dt_uart_irq_to_plic_id
(
180
dt_uart_t
dt,
181
dt_uart_irq_t
irq);
182
183
/**
184
* Convert a global IRQ ID to a local uart IRQ type.
185
*
186
* @param dt Instance of uart.
187
* @param irq A PLIC ID that belongs to this instance.
188
* @return The uart IRQ, or `kDtUartIrqCount`.
189
*
190
* **Note:** This function assumes that the PLIC ID belongs to the instance
191
* of uart passed in parameter. In other words, it must be the case that
192
* `dt_uart_instance_id(dt) == dt_plic_id_to_instance_id(irq)`. Otherwise, this function
193
* will return `kDtUartIrqCount`.
194
*/
195
dt_uart_irq_t
dt_uart_irq_from_plic_id
(
196
dt_uart_t
dt,
197
dt_plic_irq_id_t
irq);
198
199
200
/**
201
* Get the alert ID of a uart alert for a given instance.
202
*
203
* **Note:** This function only makes sense if the instance is connected to the Alert Handler. For any
204
* instances where the instance is not connected, the return value is unspecified.
205
*
206
* @param dt Instance of uart.
207
* @param alert A uart alert.
208
* @return The Alert Handler alert ID of the alert of this instance.
209
*/
210
dt_alert_id_t
dt_uart_alert_to_alert_id
(
211
dt_uart_t
dt,
212
dt_uart_alert_t
alert);
213
214
/**
215
* Convert a global alert ID to a local uart alert type.
216
*
217
* @param dt Instance of uart.
218
* @param alert A global alert ID that belongs to this instance.
219
* @return The uart alert, or `kDtUartAlertCount`.
220
*
221
* **Note:** This function assumes that the global alert ID belongs to the
222
* instance of uart passed in parameter. In other words, it must be the case
223
* that `dt_uart_instance_id(dt) == dt_alert_id_to_instance_id(alert)`. Otherwise,
224
* this function will return `kDtUartAlertCount`.
225
*/
226
dt_uart_alert_t
dt_uart_alert_from_alert_id
(
227
dt_uart_t
dt,
228
dt_alert_id_t
alert);
229
230
231
/**
232
* Get the peripheral I/O description of an instance.
233
*
234
* @param dt Instance of uart.
235
* @param sig Requested peripheral I/O.
236
* @return Description of the requested peripheral I/O for this instance.
237
*/
238
dt_periph_io_t
dt_uart_periph_io
(
239
dt_uart_t
dt,
240
dt_uart_periph_io_t
sig);
241
242
/**
243
* Get the clock signal connected to a clock port of an instance.
244
*
245
* @param dt Instance of uart.
246
* @param clk Clock port.
247
* @return Clock signal.
248
*/
249
dt_clock_t
dt_uart_clock
(
250
dt_uart_t
dt,
251
dt_uart_clock_t
clk);
252
253
/**
254
* Get the reset signal connected to a reset port of an instance.
255
*
256
* @param dt Instance of uart.
257
* @param rst Reset port.
258
* @return Reset signal.
259
*/
260
dt_reset_t
dt_uart_reset
(
261
dt_uart_t
dt,
262
dt_uart_reset_t
rst);
263
264
265
266
#ifdef __cplusplus
267
}
// extern "C"
268
#endif
// __cplusplus
269
270
#endif
// OPENTITAN_DT_UART_H_
(earlgrey)
hw
top
dt
dt_uart.h
Return to
OpenTitan Documentation