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