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 englishbreakfast.
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 clock ports.
82 *
83 * Clock ports are guaranteed to be numbered consecutively from 0.
84 */
85typedef enum dt_spi_device_clock {
86 kDtSpiDeviceClockClk = 0, /**< Clock port clk_i */
87 kDtSpiDeviceClockCount = 1, /**< \internal Number of clock ports */
89
90/**
91 * List of reset ports.
92 *
93 * Reset ports are guaranteed to be numbered consecutively from 0.
94 */
95typedef enum dt_spi_device_reset {
96 kDtSpiDeviceResetRst = 0, /**< Reset port rst_ni */
97 kDtSpiDeviceResetCount = 1, /**< \internal Number of reset ports */
99
100/**
101 * List of peripheral I/O.
102 *
103 * Peripheral I/O are guaranteed to be numbered consecutively from 0.
104 */
106 kDtSpiDevicePeriphIoSck = 0, /**< */
107 kDtSpiDevicePeriphIoCsb = 1, /**< */
108 kDtSpiDevicePeriphIoTpmCsb = 2, /**< */
109 kDtSpiDevicePeriphIoSd0 = 3, /**< */
110 kDtSpiDevicePeriphIoSd1 = 4, /**< */
111 kDtSpiDevicePeriphIoSd2 = 5, /**< */
112 kDtSpiDevicePeriphIoSd3 = 6, /**< */
113 kDtSpiDevicePeriphIoCount = 7, /**< \internal Number of peripheral I/O */
115
116/**
117 * List of supported hardware features.
118 */
119#define OPENTITAN_SPI_DEVICE_HAS_MODE_FLASH_EMULATION 1
120#define OPENTITAN_SPI_DEVICE_HAS_MODE_PASSTHROUGH 1
121#define OPENTITAN_SPI_DEVICE_HAS_MODE_TPM 1
122#define OPENTITAN_SPI_DEVICE_HAS_HW_LANES 1
123#define OPENTITAN_SPI_DEVICE_HAS_HW_SERDES_ORDERING 1
124#define OPENTITAN_SPI_DEVICE_HAS_HW_CSB_STATUS 1
125#define OPENTITAN_SPI_DEVICE_HAS_MODE_FLASH_EMULATION_COMMANDS 1
126#define OPENTITAN_SPI_DEVICE_HAS_HW_FLASH_EMULATION_BLOCKS 1
127#define OPENTITAN_SPI_DEVICE_HAS_MODE_FLASH_EMULATION_READ_COMMAND_PROCESSOR 1
128#define OPENTITAN_SPI_DEVICE_HAS_MODE_FLASH_EMULATION_DUMMY_CYCLE 1
129#define OPENTITAN_SPI_DEVICE_HAS_MODE_FLASH_EMULATION_WRITE_ENABLE_DISABLE 1
130#define OPENTITAN_SPI_DEVICE_HAS_HW_LAST_READ_ADDR 1
131#define OPENTITAN_SPI_DEVICE_HAS_HW_CMDINFOS 1
132#define OPENTITAN_SPI_DEVICE_HAS_HW_COMMAND_UPLOAD 1
133#define OPENTITAN_SPI_DEVICE_HAS_HW_3B4B_ADDRESSING 1
134#define OPENTITAN_SPI_DEVICE_HAS_MODE_PASSTHROUGH_CMD_FILTER 1
135#define OPENTITAN_SPI_DEVICE_HAS_MODE_PASSTHROUGH_ADDRESS_MANIPULATION 1
136#define OPENTITAN_SPI_DEVICE_HAS_MODE_PASSTHROUGH_STATUS_MANIPULATION 1
137#define OPENTITAN_SPI_DEVICE_HAS_MODE_PASSTHROUGH_OUTPUT_ENABLE_CONTROL 1
138#define OPENTITAN_SPI_DEVICE_HAS_MODE_PASSTHROUGH_INTERCEPT_EN 1
139#define OPENTITAN_SPI_DEVICE_HAS_MODE_PASSTHROUGH_MAILBOX 1
140#define OPENTITAN_SPI_DEVICE_HAS_MODE_TPM_RETURN_BY_HW_REGS 1
141#define OPENTITAN_SPI_DEVICE_HAS_MODE_TPM_AUTO_WAIT 1
142#define OPENTITAN_SPI_DEVICE_HAS_MODE_TPM_READ_FIFO_MODE 1
143#define OPENTITAN_SPI_DEVICE_HAS_MODE_TPM_CAPABILITY 1
144
145
146
147/**
148 * Get the spi_device 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 spi_device instance.
154 *
155 * **Note:** This function only makes sense if the instance ID has device type spi_device,
156 * otherwise the returned value is unspecified.
157 */
159
160/**
161 * Get the instance ID of an instance.
162 *
163 * @param dt Instance of spi_device.
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 spi_device.
172 * @param reg_block The register block requested.
173 * @return The register base address of the requested block.
174 */
177 dt_spi_device_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_spi_device_reg_block(dt, kDtSpiDeviceRegBlockCore)`
184 *
185 * @param dt Instance of spi_device.
186 * @return The register base address of the primary register block.
187 */
188static inline uint32_t dt_spi_device_primary_reg_block(
189 dt_spi_device_t dt) {
190 return dt_spi_device_reg_block(dt, kDtSpiDeviceRegBlockCore);
191}
192
193/**
194 * Get the PLIC ID of a spi_device 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 spi_device.
200 * @param irq A spi_device IRQ.
201 * @return The PLIC ID of the IRQ of this instance.
202 */
206
207/**
208 * Convert a global IRQ ID to a local spi_device IRQ type.
209 *
210 * @param dt Instance of spi_device.
211 * @param irq A PLIC ID that belongs to this instance.
212 * @return The spi_device IRQ, or `kDtSpiDeviceIrqCount`.
213 *
214 * **Note:** This function assumes that the PLIC ID belongs to the instance
215 * of spi_device passed in parameter. In other words, it must be the case that
216 * `dt_spi_device_instance_id(dt) == dt_plic_id_to_instance_id(irq)`. Otherwise, this function
217 * will return `kDtSpiDeviceIrqCount`.
218 */
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 spi_device.
229 * @param sig Requested peripheral I/O.
230 * @return Description of the requested peripheral I/O for this instance.
231 */
235
236/**
237 * Get the clock signal connected to a clock port of an instance.
238 *
239 * @param dt Instance of spi_device.
240 * @param clk Clock port.
241 * @return Clock signal.
242 */
246
247/**
248 * Get the reset signal connected to a reset port of an instance.
249 *
250 * @param dt Instance of spi_device.
251 * @param rst Reset port.
252 * @return Reset signal.
253 */
257
258
259
260#endif // OPENTITAN_DT_SPI_DEVICE_H_