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