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