Software APIs
dt_usbdev.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_USBDEV_H_
8#define OPENTITAN_DT_USBDEV_H_
9
10/**
11 * @file
12 * @brief Device Tables (DT) for IP usbdev and top earlgrey.
13 *
14 * This file contains the type definitions and global functions of the usbdev.
15 */
16
17#include "dt_api.h"
18#include <stdint.h>
19
20
21
22/**
23 * List of instances.
24 */
25typedef enum dt_usbdev {
26 kDtUsbdev = 0, /**< usbdev */
27 kDtUsbdevFirst = 0, /**< \internal First instance */
28 kDtUsbdevCount = 1, /**< \internal Number of instances */
30
31/**
32 * List of register blocks.
33 *
34 * Register blocks are guaranteed to start at 0 and to be consecutively numbered.
35 */
36typedef enum dt_usbdev_reg_block {
37 kDtUsbdevRegBlockCore = 0, /**< */
38 kDtUsbdevRegBlockCount = 1, /**< \internal Number of register blocks */
40
41/** Primary register block (associated with the "primary" set of registers that control the IP). */
42static const dt_usbdev_reg_block_t kDtUsbdevRegBlockPrimary = kDtUsbdevRegBlockCore;
43
44/**
45 * List of IRQs.
46 *
47 * IRQs are guaranteed to be numbered consecutively from 0.
48 */
49typedef enum dt_usbdev_irq {
50 kDtUsbdevIrqPktReceived = 0, /**< Raised if a packet was received using an OUT or SETUP transaction.
51This interrupt is directly tied to whether the RX FIFO is empty, so it should be cleared only after handling the FIFO entry. */
52 kDtUsbdevIrqPktSent = 1, /**< Raised if a packet was sent as part of an IN transaction.
53This interrupt is directly tied to whether a sent packet has not been acknowledged in the !!in_sent register.
54It should be cleared only after clearing all bits in the !!in_sent register. */
55 kDtUsbdevIrqDisconnected = 2, /**< Raised if VBUS is lost, thus the link is disconnected. */
56 kDtUsbdevIrqHostLost = 3, /**< Raised if link is active but SOF was not received from host for 4.096 ms. The SOF should be every 1 ms. */
57 kDtUsbdevIrqLinkReset = 4, /**< Raised if the link is at SE0 longer than 3 us indicating a link reset (host asserts for min 10 ms, device can react after 2.5 us). */
58 kDtUsbdevIrqLinkSuspend = 5, /**< Raised if the line has signaled J for longer than 3ms and is therefore in suspend state. */
59 kDtUsbdevIrqLinkResume = 6, /**< Raised when the link becomes active again after being suspended. */
60 kDtUsbdevIrqAvOutEmpty = 7, /**< Raised when the Available OUT Buffer FIFO is empty and the device interface is enabled.
61This interrupt is directly tied to the FIFO status, so the Available OUT Buffer FIFO must be provided with a free buffer before the interrupt can be cleared. */
62 kDtUsbdevIrqRxFull = 8, /**< Raised when the RX FIFO is full and the device interface is enabled.
63This interrupt is directly tied to the FIFO status, so the RX FIFO must have an entry removed before the interrupt is cleared.
64If the condition is not cleared, the interrupt can re-assert. */
65 kDtUsbdevIrqAvOverflow = 9, /**< Raised if a write was done to either the Available OUT Buffer FIFO or the Available SETUP Buffer FIFO when the FIFO was full. */
66 kDtUsbdevIrqLinkInErr = 10, /**< Raised if a packet to an IN endpoint started to be received but was
67then dropped due to an error. After transmitting the IN payload,
68the USB device expects a valid ACK handshake packet. This error is
69raised if either the packet or CRC is invalid, leading to a NAK instead,
70or if a different token was received. */
71 kDtUsbdevIrqRxCrcErr = 11, /**< Raised if a CRC error occurred on a received packet. */
72 kDtUsbdevIrqRxPidErr = 12, /**< Raised if an invalid Packet IDentifier (PID) was received. */
73 kDtUsbdevIrqRxBitstuffErr = 13, /**< Raised if an invalid bitstuffing was received. */
74 kDtUsbdevIrqFrame = 14, /**< Raised when the USB frame number is updated with a valid SOF. */
75 kDtUsbdevIrqPowered = 15, /**< Raised if VBUS is applied. */
76 kDtUsbdevIrqLinkOutErr = 16, /**< Raised if a packet to an OUT endpoint started to be received but was then dropped due to an error.
77This error is raised if the data toggle, token, packet and/or CRC are invalid, or if the appropriate Available OUT Buffer FIFO is empty and/or the Received Buffer FIFO is full when a packet should have been received. */
78 kDtUsbdevIrqAvSetupEmpty = 17, /**< Raised when the Available SETUP Buffer FIFO is empty and the device interface is enabled.
79This interrupt is directly tied to the FIFO status, so the Available SETUP Buffer FIFO must be provided with a free buffer before the interrupt can be cleared. */
80 kDtUsbdevIrqCount = 18, /**< \internal Number of IRQs */
82
83/**
84 * List of Alerts.
85 *
86 * Alerts are guaranteed to be numbered consecutively from 0.
87 */
88typedef enum dt_usbdev_alert {
89 kDtUsbdevAlertFatalFault = 0, /**< This fatal alert is triggered when a fatal TL-UL bus integrity fault is detected. */
90 kDtUsbdevAlertCount = 1, /**< \internal Number of Alerts */
92
93/**
94 * List of clock ports.
95 *
96 * Clock ports are guaranteed to be numbered consecutively from 0.
97 */
98typedef enum dt_usbdev_clock {
99 kDtUsbdevClockClk = 0, /**< Clock port clk_i */
100 kDtUsbdevClockAon = 1, /**< Clock port clk_aon_i */
101 kDtUsbdevClockCount = 2, /**< \internal Number of clock ports */
103
104/**
105 * List of reset ports.
106 *
107 * Reset ports are guaranteed to be numbered consecutively from 0.
108 */
109typedef enum dt_usbdev_reset {
110 kDtUsbdevResetRst = 0, /**< Reset port rst_ni */
111 kDtUsbdevResetAon = 1, /**< Reset port rst_aon_ni */
112 kDtUsbdevResetCount = 2, /**< \internal Number of reset ports */
114
115/**
116 * List of peripheral I/O.
117 *
118 * Peripheral I/O are guaranteed to be numbered consecutively from 0.
119 */
121 kDtUsbdevPeriphIoSense = 0, /**< */
122 kDtUsbdevPeriphIoUsbDp = 1, /**< */
123 kDtUsbdevPeriphIoUsbDn = 2, /**< */
124 kDtUsbdevPeriphIoCount = 3, /**< \internal Number of peripheral I/O */
126
127/**
128 * List of supported hardware features.
129 */
130#define OPENTITAN_USBDEV_HAS_CONN_VBUS 1
131#define OPENTITAN_USBDEV_HAS_CONN_PULLUP 1
132#define OPENTITAN_USBDEV_HAS_CONN_REF_PULSE 1
133#define OPENTITAN_USBDEV_HAS_CONN_PIN_CONFIG 1
134#define OPENTITAN_USBDEV_HAS_CONN_RESET 1
135#define OPENTITAN_USBDEV_HAS_BUFFER_MEMORY 1
136#define OPENTITAN_USBDEV_HAS_TRANSFER_CONTROL_RX 1
137#define OPENTITAN_USBDEV_HAS_TRANSFER_CONTROL_TX 1
138#define OPENTITAN_USBDEV_HAS_TRANSFER_ENDPOINTS 1
139#define OPENTITAN_USBDEV_HAS_TRANSFER_BULK 1
140#define OPENTITAN_USBDEV_HAS_TRANSFER_ISOCHRONOUS 1
141#define OPENTITAN_USBDEV_HAS_TRANSFER_CONTROL 1
142#define OPENTITAN_USBDEV_HAS_TRANSFER_INTERRUPT 1
143#define OPENTITAN_USBDEV_HAS_POWER_SUSPEND 1
144#define OPENTITAN_USBDEV_HAS_POWER_RESUME 1
145#define OPENTITAN_USBDEV_HAS_POWER_AON 1
146#define OPENTITAN_USBDEV_HAS_POWER_WAKE_DISCONNECT 1
147#define OPENTITAN_USBDEV_HAS_POWER_WAKE_RESUME 1
148#define OPENTITAN_USBDEV_HAS_POWER_WAKE_BUS_RESET 1
149#define OPENTITAN_USBDEV_HAS_POWER_TOGGLE_RESTORE 1
150
151
152
153/**
154 * Get the usbdev instance from an instance ID
155 *
156 * For example, `dt_uart_from_instance_id(kDtInstanceIdUart3) == kDtUart3`.
157 *
158 * @param inst_id Instance ID.
159 * @return A usbdev instance.
160 *
161 * **Note:** This function only makes sense if the instance ID has device type usbdev,
162 * otherwise the returned value is unspecified.
163 */
165
166/**
167 * Get the instance ID of an instance.
168 *
169 * @param dt Instance of usbdev.
170 * @return The instance ID of that instance.
171 */
173
174/**
175 * Get the register base address of an instance.
176 *
177 * @param dt Instance of usbdev.
178 * @param reg_block The register block requested.
179 * @return The register base address of the requested block.
180 */
181uint32_t dt_usbdev_reg_block(
182 dt_usbdev_t dt,
183 dt_usbdev_reg_block_t reg_block);
184
185/**
186 * Get the primary register base address of an instance.
187 *
188 * This is just a convenience function, equivalent to
189 * `dt_usbdev_reg_block(dt, kDtUsbdevRegBlockCore)`
190 *
191 * @param dt Instance of usbdev.
192 * @return The register base address of the primary register block.
193 */
194static inline uint32_t dt_usbdev_primary_reg_block(
195 dt_usbdev_t dt) {
196 return dt_usbdev_reg_block(dt, kDtUsbdevRegBlockCore);
197}
198
199/**
200 * Get the PLIC ID of a usbdev IRQ for a given instance.
201 *
202 * If the instance is not connected to the PLIC, this function
203 * will return `kDtPlicIrqIdNone`.
204 *
205 * @param dt Instance of usbdev.
206 * @param irq A usbdev IRQ.
207 * @return The PLIC ID of the IRQ of this instance.
208 */
210 dt_usbdev_t dt,
211 dt_usbdev_irq_t irq);
212
213/**
214 * Convert a global IRQ ID to a local usbdev IRQ type.
215 *
216 * @param dt Instance of usbdev.
217 * @param irq A PLIC ID that belongs to this instance.
218 * @return The usbdev IRQ, or `kDtUsbdevIrqCount`.
219 *
220 * **Note:** This function assumes that the PLIC ID belongs to the instance
221 * of usbdev passed in parameter. In other words, it must be the case that
222 * `dt_usbdev_instance_id(dt) == dt_plic_id_to_instance_id(irq)`. Otherwise, this function
223 * will return `kDtUsbdevIrqCount`.
224 */
226 dt_usbdev_t dt,
227 dt_plic_irq_id_t irq);
228
229
230/**
231 * Get the alert ID of a usbdev alert for a given instance.
232 *
233 * **Note:** This function only makes sense if the instance is connected to the Alert Handler. For any
234 * instances where the instance is not connected, the return value is unspecified.
235 *
236 * @param dt Instance of usbdev.
237 * @param alert A usbdev alert.
238 * @return The Alert Handler alert ID of the alert of this instance.
239 */
241 dt_usbdev_t dt,
242 dt_usbdev_alert_t alert);
243
244/**
245 * Convert a global alert ID to a local usbdev alert type.
246 *
247 * @param dt Instance of usbdev.
248 * @param alert A global alert ID that belongs to this instance.
249 * @return The usbdev alert, or `kDtUsbdevAlertCount`.
250 *
251 * **Note:** This function assumes that the global alert ID belongs to the
252 * instance of usbdev passed in parameter. In other words, it must be the case
253 * that `dt_usbdev_instance_id(dt) == dt_alert_id_to_instance_id(alert)`. Otherwise,
254 * this function will return `kDtUsbdevAlertCount`.
255 */
257 dt_usbdev_t dt,
258 dt_alert_id_t alert);
259
260
261/**
262 * Get the peripheral I/O description of an instance.
263 *
264 * @param dt Instance of usbdev.
265 * @param sig Requested peripheral I/O.
266 * @return Description of the requested peripheral I/O for this instance.
267 */
269 dt_usbdev_t dt,
271
272/**
273 * Get the clock signal connected to a clock port of an instance.
274 *
275 * @param dt Instance of usbdev.
276 * @param clk Clock port.
277 * @return Clock signal.
278 */
280 dt_usbdev_t dt,
282
283/**
284 * Get the reset signal connected to a reset port of an instance.
285 *
286 * @param dt Instance of usbdev.
287 * @param rst Reset port.
288 * @return Reset signal.
289 */
291 dt_usbdev_t dt,
293
294
295
296#endif // OPENTITAN_DT_USBDEV_H_