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