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 "hw/top/dt/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/**
46 * List of memories.
47 *
48 * Memories are guaranteed to start at 0 and to be consecutively numbered.
49 */
51 kDtSpiDeviceMemoryCount = 0, /**< \internal Number of memories */
53
54/** Primary register block (associated with the "primary" set of registers that control the IP). */
55static const dt_spi_device_reg_block_t kDtSpiDeviceRegBlockPrimary = kDtSpiDeviceRegBlockCore;
56
57/**
58 * List of IRQs.
59 *
60 * IRQs are guaranteed to be numbered consecutively from 0.
61 */
62typedef enum dt_spi_device_irq {
63 kDtSpiDeviceIrqUploadCmdfifoNotEmpty = 0, /**< Upload Command FIFO is not empty */
64 kDtSpiDeviceIrqUploadPayloadNotEmpty = 1, /**< Upload payload is not empty.
65
66The event occurs after SPI transaction completed */
67 kDtSpiDeviceIrqUploadPayloadOverflow = 2, /**< Upload payload overflow event.
68
69When a SPI Host system issues a command with payload more than 256B,
70this event is reported. When it happens, SW should read the last
71written payload index CSR to figure out the starting address of the
72last 256B. */
73 kDtSpiDeviceIrqReadbufWatermark = 3, /**< Read Buffer Threshold event.
74
75The host system accesses greater than or equal to the threshold of a
76buffer. */
77 kDtSpiDeviceIrqReadbufFlip = 4, /**< Read buffer flipped event.
78
79The host system accesses other side of buffer. */
80 kDtSpiDeviceIrqTpmHeaderNotEmpty = 5, /**< TPM Header(Command/Address) buffer available */
81 kDtSpiDeviceIrqTpmRdfifoCmdEnd = 6, /**< TPM RdFIFO command ended.
82
83The TPM Read command targeting the RdFIFO ended.
84Check TPM_STATUS.rdfifo_aborted to see if the transaction completed. */
85 kDtSpiDeviceIrqTpmRdfifoDrop = 7, /**< TPM RdFIFO data dropped.
86
87Data was dropped from the RdFIFO.
88Data was written while a read command was not active, and it was not accepted.
89This can occur when the host aborts a read command. */
90 kDtSpiDeviceIrqCount = 8, /**< \internal Number of IRQs */
92
93/**
94 * List of clock ports.
95 *
96 * Clock ports are guaranteed to be numbered consecutively from 0.
97 */
98typedef enum dt_spi_device_clock {
99 kDtSpiDeviceClockClk = 0, /**< Clock port clk_i */
100 kDtSpiDeviceClockCount = 1, /**< \internal Number of clock ports */
102
103/**
104 * List of reset ports.
105 *
106 * Reset ports are guaranteed to be numbered consecutively from 0.
107 */
109 kDtSpiDeviceResetRst = 0, /**< Reset port rst_ni */
110 kDtSpiDeviceResetCount = 1, /**< \internal Number of reset ports */
112
113/**
114 * List of peripheral I/O.
115 *
116 * Peripheral I/O are guaranteed to be numbered consecutively from 0.
117 */
119 kDtSpiDevicePeriphIoSck = 0, /**< */
120 kDtSpiDevicePeriphIoCsb = 1, /**< */
121 kDtSpiDevicePeriphIoTpmCsb = 2, /**< */
122 kDtSpiDevicePeriphIoSd0 = 3, /**< */
123 kDtSpiDevicePeriphIoSd1 = 4, /**< */
124 kDtSpiDevicePeriphIoSd2 = 5, /**< */
125 kDtSpiDevicePeriphIoSd3 = 6, /**< */
126 kDtSpiDevicePeriphIoCount = 7, /**< \internal Number of peripheral I/O */
128
129/**
130 * List of supported hardware features.
131 */
132#define OPENTITAN_SPI_DEVICE_HAS_MODE_FLASH_EMULATION 1
133#define OPENTITAN_SPI_DEVICE_HAS_MODE_PASSTHROUGH 1
134#define OPENTITAN_SPI_DEVICE_HAS_MODE_TPM 1
135#define OPENTITAN_SPI_DEVICE_HAS_HW_LANES 1
136#define OPENTITAN_SPI_DEVICE_HAS_HW_SERDES_ORDERING 1
137#define OPENTITAN_SPI_DEVICE_HAS_HW_CSB_STATUS 1
138#define OPENTITAN_SPI_DEVICE_HAS_MODE_FLASH_EMULATION_COMMANDS 1
139#define OPENTITAN_SPI_DEVICE_HAS_HW_FLASH_EMULATION_BLOCKS 1
140#define OPENTITAN_SPI_DEVICE_HAS_MODE_FLASH_EMULATION_READ_COMMAND_PROCESSOR 1
141#define OPENTITAN_SPI_DEVICE_HAS_MODE_FLASH_EMULATION_DUMMY_CYCLE 1
142#define OPENTITAN_SPI_DEVICE_HAS_MODE_FLASH_EMULATION_WRITE_ENABLE_DISABLE 1
143#define OPENTITAN_SPI_DEVICE_HAS_HW_LAST_READ_ADDR 1
144#define OPENTITAN_SPI_DEVICE_HAS_HW_CMDINFOS 1
145#define OPENTITAN_SPI_DEVICE_HAS_HW_COMMAND_UPLOAD 1
146#define OPENTITAN_SPI_DEVICE_HAS_HW_3B4B_ADDRESSING 1
147#define OPENTITAN_SPI_DEVICE_HAS_MODE_PASSTHROUGH_CMD_FILTER 1
148#define OPENTITAN_SPI_DEVICE_HAS_MODE_PASSTHROUGH_ADDRESS_MANIPULATION 1
149#define OPENTITAN_SPI_DEVICE_HAS_MODE_PASSTHROUGH_STATUS_MANIPULATION 1
150#define OPENTITAN_SPI_DEVICE_HAS_MODE_PASSTHROUGH_OUTPUT_ENABLE_CONTROL 1
151#define OPENTITAN_SPI_DEVICE_HAS_MODE_PASSTHROUGH_INTERCEPT_EN 1
152#define OPENTITAN_SPI_DEVICE_HAS_MODE_PASSTHROUGH_MAILBOX 1
153#define OPENTITAN_SPI_DEVICE_HAS_MODE_TPM_RETURN_BY_HW_REGS 1
154#define OPENTITAN_SPI_DEVICE_HAS_MODE_TPM_AUTO_WAIT 1
155#define OPENTITAN_SPI_DEVICE_HAS_MODE_TPM_READ_FIFO_MODE 1
156#define OPENTITAN_SPI_DEVICE_HAS_MODE_TPM_CAPABILITY 1
157
158
159
160/**
161 * Get the spi_device instance from an instance ID
162 *
163 * For example, `dt_uart_from_instance_id(kDtInstanceIdUart3) == kDtUart3`.
164 *
165 * @param inst_id Instance ID.
166 * @return A spi_device instance.
167 *
168 * **Note:** This function only makes sense if the instance ID has device type spi_device,
169 * otherwise the returned value is unspecified.
170 */
172
173/**
174 * Get the instance ID of an instance.
175 *
176 * @param dt Instance of spi_device.
177 * @return The instance ID of that instance.
178 */
180
181/**
182 * Get the register base address of an instance.
183 *
184 * @param dt Instance of spi_device.
185 * @param reg_block The register block requested.
186 * @return The register base address of the requested block.
187 */
190 dt_spi_device_reg_block_t reg_block);
191
192/**
193 * Get the primary register base address of an instance.
194 *
195 * This is just a convenience function, equivalent to
196 * `dt_spi_device_reg_block(dt, kDtSpiDeviceRegBlockCore)`
197 *
198 * @param dt Instance of spi_device.
199 * @return The register base address of the primary register block.
200 */
201static inline uint32_t dt_spi_device_primary_reg_block(
202 dt_spi_device_t dt) {
203 return dt_spi_device_reg_block(dt, kDtSpiDeviceRegBlockCore);
204}
205
206/**
207 * Get the base address of a memory.
208 *
209 * @param dt Instance of spi_device.
210 * @param mem The memory requested.
211 * @return The base address of the requested memory.
212 */
216
217/**
218 * Get the size of a memory.
219 *
220 * @param dt Instance of spi_device.
221 * @param mem The memory requested.
222 * @return The size of the requested memory.
223 */
227
228/**
229 * Get the PLIC ID of a spi_device IRQ for a given instance.
230 *
231 * If the instance is not connected to the PLIC, this function
232 * will return `kDtPlicIrqIdNone`.
233 *
234 * @param dt Instance of spi_device.
235 * @param irq A spi_device IRQ.
236 * @return The PLIC ID of the IRQ of this instance.
237 */
241
242/**
243 * Convert a global IRQ ID to a local spi_device IRQ type.
244 *
245 * @param dt Instance of spi_device.
246 * @param irq A PLIC ID that belongs to this instance.
247 * @return The spi_device IRQ, or `kDtSpiDeviceIrqCount`.
248 *
249 * **Note:** This function assumes that the PLIC ID belongs to the instance
250 * of spi_device passed in parameter. In other words, it must be the case that
251 * `dt_spi_device_instance_id(dt) == dt_plic_id_to_instance_id(irq)`. Otherwise, this function
252 * will return `kDtSpiDeviceIrqCount`.
253 */
256 dt_plic_irq_id_t irq);
257
258
259
260/**
261 * Get the peripheral I/O description of an instance.
262 *
263 * @param dt Instance of spi_device.
264 * @param sig Requested peripheral I/O.
265 * @return Description of the requested peripheral I/O for this instance.
266 */
270
271/**
272 * Get the clock signal connected to a clock port of an instance.
273 *
274 * @param dt Instance of spi_device.
275 * @param clk Clock port.
276 * @return Clock signal.
277 */
281
282/**
283 * Get the reset signal connected to a reset port of an instance.
284 *
285 * @param dt Instance of spi_device.
286 * @param rst Reset port.
287 * @return Reset signal.
288 */
292
293
294
295#ifdef __cplusplus
296} // extern "C"
297#endif // __cplusplus
298
299#endif // OPENTITAN_DT_SPI_DEVICE_H_