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