Software APIs
dt_spi_device.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_SPI_DEVICE_H_
8#define OPENTITAN_DT_SPI_DEVICE_H_
9
10/**
11 * @file
12 * @brief Device Tables (DT) for IP spi_device and top earlgrey.
13 *
14 * This file contains the type definitions and global functions of the spi_device.
15 */
16
17#include "dt_api.h"
18#include <stdint.h>
19
20
21
22/**
23 * List of instances.
24 */
25typedef enum dt_spi_device {
26 kDtSpiDevice = 0, /**< spi_device */
27 kDtSpiDeviceFirst = 0, /**< \internal First instance */
28 kDtSpiDeviceCount = 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 */
37 kDtSpiDeviceRegBlockCore = 0, /**< */
38 kDtSpiDeviceRegBlockCount = 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_spi_device_reg_block_t kDtSpiDeviceRegBlockPrimary = kDtSpiDeviceRegBlockCore;
43
44/**
45 * List of IRQs.
46 *
47 * IRQs are guaranteed to be numbered consecutively from 0.
48 */
49typedef enum dt_spi_device_irq {
50 kDtSpiDeviceIrqUploadCmdfifoNotEmpty = 0, /**< Upload Command FIFO is not empty */
51 kDtSpiDeviceIrqUploadPayloadNotEmpty = 1, /**< Upload payload is not empty.
52
53The event occurs after SPI transaction completed */
54 kDtSpiDeviceIrqUploadPayloadOverflow = 2, /**< Upload payload overflow event.
55
56When a SPI Host system issues a command with payload more than 256B,
57this event is reported. When it happens, SW should read the last
58written payload index CSR to figure out the starting address of the
59last 256B. */
60 kDtSpiDeviceIrqReadbufWatermark = 3, /**< Read Buffer Threshold event.
61
62The host system accesses greater than or equal to the threshold of a
63buffer. */
64 kDtSpiDeviceIrqReadbufFlip = 4, /**< Read buffer flipped event.
65
66The host system accesses other side of buffer. */
67 kDtSpiDeviceIrqTpmHeaderNotEmpty = 5, /**< TPM Header(Command/Address) buffer available */
68 kDtSpiDeviceIrqTpmRdfifoCmdEnd = 6, /**< TPM RdFIFO command ended.
69
70The TPM Read command targeting the RdFIFO ended.
71Check TPM_STATUS.rdfifo_aborted to see if the transaction completed. */
72 kDtSpiDeviceIrqTpmRdfifoDrop = 7, /**< TPM RdFIFO data dropped.
73
74Data was dropped from the RdFIFO.
75Data was written while a read command was not active, and it was not accepted.
76This can occur when the host aborts a read command. */
77 kDtSpiDeviceIrqCount = 8, /**< \internal Number of IRQs */
79
80/**
81 * List of Alerts.
82 *
83 * Alerts are guaranteed to be numbered consecutively from 0.
84 */
85typedef enum dt_spi_device_alert {
86 kDtSpiDeviceAlertFatalFault = 0, /**< This fatal alert is triggered when a fatal TL-UL bus integrity fault is detected. */
87 kDtSpiDeviceAlertCount = 1, /**< \internal Number of Alerts */
89
90/**
91 * List of clock ports.
92 *
93 * Clock ports are guaranteed to be numbered consecutively from 0.
94 */
95typedef enum dt_spi_device_clock {
96 kDtSpiDeviceClockClk = 0, /**< Clock port clk_i */
97 kDtSpiDeviceClockCount = 1, /**< \internal Number of clock ports */
99
100/**
101 * List of reset ports.
102 *
103 * Reset ports are guaranteed to be numbered consecutively from 0.
104 */
106 kDtSpiDeviceResetRst = 0, /**< Reset port rst_ni */
107 kDtSpiDeviceResetCount = 1, /**< \internal Number of reset ports */
109
110/**
111 * List of peripheral I/O.
112 *
113 * Peripheral I/O are guaranteed to be numbered consecutively from 0.
114 */
116 kDtSpiDevicePeriphIoSck = 0, /**< */
117 kDtSpiDevicePeriphIoCsb = 1, /**< */
118 kDtSpiDevicePeriphIoTpmCsb = 2, /**< */
119 kDtSpiDevicePeriphIoSd0 = 3, /**< */
120 kDtSpiDevicePeriphIoSd1 = 4, /**< */
121 kDtSpiDevicePeriphIoSd2 = 5, /**< */
122 kDtSpiDevicePeriphIoSd3 = 6, /**< */
123 kDtSpiDevicePeriphIoCount = 7, /**< \internal Number of peripheral I/O */
125
126/**
127 * List of supported hardware features.
128 */
129#define OPENTITAN_SPI_DEVICE_HAS_MODE_FLASH_EMULATION 1
130#define OPENTITAN_SPI_DEVICE_HAS_MODE_PASSTHROUGH 1
131#define OPENTITAN_SPI_DEVICE_HAS_MODE_TPM 1
132#define OPENTITAN_SPI_DEVICE_HAS_HW_LANES 1
133#define OPENTITAN_SPI_DEVICE_HAS_HW_SERDES_ORDERING 1
134#define OPENTITAN_SPI_DEVICE_HAS_HW_CSB_STATUS 1
135#define OPENTITAN_SPI_DEVICE_HAS_MODE_FLASH_EMULATION_COMMANDS 1
136#define OPENTITAN_SPI_DEVICE_HAS_HW_FLASH_EMULATION_BLOCKS 1
137#define OPENTITAN_SPI_DEVICE_HAS_MODE_FLASH_EMULATION_READ_COMMAND_PROCESSOR 1
138#define OPENTITAN_SPI_DEVICE_HAS_MODE_FLASH_EMULATION_DUMMY_CYCLE 1
139#define OPENTITAN_SPI_DEVICE_HAS_MODE_FLASH_EMULATION_WRITE_ENABLE_DISABLE 1
140#define OPENTITAN_SPI_DEVICE_HAS_HW_LAST_READ_ADDR 1
141#define OPENTITAN_SPI_DEVICE_HAS_HW_CMDINFOS 1
142#define OPENTITAN_SPI_DEVICE_HAS_HW_COMMAND_UPLOAD 1
143#define OPENTITAN_SPI_DEVICE_HAS_HW_3B4B_ADDRESSING 1
144#define OPENTITAN_SPI_DEVICE_HAS_MODE_PASSTHROUGH_CMD_FILTER 1
145#define OPENTITAN_SPI_DEVICE_HAS_MODE_PASSTHROUGH_ADDRESS_MANIPULATION 1
146#define OPENTITAN_SPI_DEVICE_HAS_MODE_PASSTHROUGH_STATUS_MANIPULATION 1
147#define OPENTITAN_SPI_DEVICE_HAS_MODE_PASSTHROUGH_OUTPUT_ENABLE_CONTROL 1
148#define OPENTITAN_SPI_DEVICE_HAS_MODE_PASSTHROUGH_INTERCEPT_EN 1
149#define OPENTITAN_SPI_DEVICE_HAS_MODE_PASSTHROUGH_MAILBOX 1
150#define OPENTITAN_SPI_DEVICE_HAS_MODE_TPM_RETURN_BY_HW_REGS 1
151#define OPENTITAN_SPI_DEVICE_HAS_MODE_TPM_AUTO_WAIT 1
152#define OPENTITAN_SPI_DEVICE_HAS_MODE_TPM_READ_FIFO_MODE 1
153#define OPENTITAN_SPI_DEVICE_HAS_MODE_TPM_CAPABILITY 1
154
155
156
157/**
158 * Get the spi_device instance from an instance ID
159 *
160 * For example, `dt_uart_from_instance_id(kDtInstanceIdUart3) == kDtUart3`.
161 *
162 * @param inst_id Instance ID.
163 * @return A spi_device instance.
164 *
165 * **Note:** This function only makes sense if the instance ID has device type spi_device,
166 * otherwise the returned value is unspecified.
167 */
169
170/**
171 * Get the instance ID of an instance.
172 *
173 * @param dt Instance of spi_device.
174 * @return The instance ID of that instance.
175 */
177
178/**
179 * Get the register base address of an instance.
180 *
181 * @param dt Instance of spi_device.
182 * @param reg_block The register block requested.
183 * @return The register base address of the requested block.
184 */
187 dt_spi_device_reg_block_t reg_block);
188
189/**
190 * Get the primary register base address of an instance.
191 *
192 * This is just a convenience function, equivalent to
193 * `dt_spi_device_reg_block(dt, kDtSpiDeviceRegBlockCore)`
194 *
195 * @param dt Instance of spi_device.
196 * @return The register base address of the primary register block.
197 */
198static inline uint32_t dt_spi_device_primary_reg_block(
199 dt_spi_device_t dt) {
200 return dt_spi_device_reg_block(dt, kDtSpiDeviceRegBlockCore);
201}
202
203/**
204 * Get the PLIC ID of a spi_device IRQ for a given instance.
205 *
206 * If the instance is not connected to the PLIC, this function
207 * will return `kDtPlicIrqIdNone`.
208 *
209 * @param dt Instance of spi_device.
210 * @param irq A spi_device IRQ.
211 * @return The PLIC ID of the IRQ of this instance.
212 */
216
217/**
218 * Convert a global IRQ ID to a local spi_device IRQ type.
219 *
220 * @param dt Instance of spi_device.
221 * @param irq A PLIC ID that belongs to this instance.
222 * @return The spi_device IRQ, or `kDtSpiDeviceIrqCount`.
223 *
224 * **Note:** This function assumes that the PLIC ID belongs to the instance
225 * of spi_device passed in parameter. In other words, it must be the case that
226 * `dt_spi_device_instance_id(dt) == dt_plic_id_to_instance_id(irq)`. Otherwise, this function
227 * will return `kDtSpiDeviceIrqCount`.
228 */
231 dt_plic_irq_id_t irq);
232
233
234/**
235 * Get the alert ID of a spi_device alert for a given instance.
236 *
237 * **Note:** This function only makes sense if the instance is connected to the Alert Handler. For any
238 * instances where the instance is not connected, the return value is unspecified.
239 *
240 * @param dt Instance of spi_device.
241 * @param alert A spi_device alert.
242 * @return The Alert Handler alert ID of the alert of this instance.
243 */
247
248/**
249 * Convert a global alert ID to a local spi_device alert type.
250 *
251 * @param dt Instance of spi_device.
252 * @param alert A global alert ID that belongs to this instance.
253 * @return The spi_device alert, or `kDtSpiDeviceAlertCount`.
254 *
255 * **Note:** This function assumes that the global alert ID belongs to the
256 * instance of spi_device passed in parameter. In other words, it must be the case
257 * that `dt_spi_device_instance_id(dt) == dt_alert_id_to_instance_id(alert)`. Otherwise,
258 * this function will return `kDtSpiDeviceAlertCount`.
259 */
262 dt_alert_id_t alert);
263
264
265/**
266 * Get the peripheral I/O description of an instance.
267 *
268 * @param dt Instance of spi_device.
269 * @param sig Requested peripheral I/O.
270 * @return Description of the requested peripheral I/O for this instance.
271 */
275
276/**
277 * Get the clock signal connected to a clock port of an instance.
278 *
279 * @param dt Instance of spi_device.
280 * @param clk Clock port.
281 * @return Clock signal.
282 */
286
287/**
288 * Get the reset signal connected to a reset port of an instance.
289 *
290 * @param dt Instance of spi_device.
291 * @param rst Reset port.
292 * @return Reset signal.
293 */
297
298
299
300#endif // OPENTITAN_DT_SPI_DEVICE_H_