Software APIs
dt_spi_host.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_HOST_H_
8#define OPENTITAN_DT_SPI_HOST_H_
9
10/**
11 * @file
12 * @brief Device Tables (DT) for IP spi_host and top earlgrey.
13 *
14 * This file contains the type definitions and global functions of the spi_host.
15 */
16
17#include "dt_api.h"
18#include <stdint.h>
19
20
21
22/**
23 * List of instances.
24 */
25typedef enum dt_spi_host {
26 kDtSpiHost0 = 0, /**< spi_host0 */
27 kDtSpiHost1 = 1, /**< spi_host1 */
28 kDtSpiHostFirst = 0, /**< \internal First instance */
29 kDtSpiHostCount = 2, /**< \internal Number of instances */
31
32/**
33 * List of register blocks.
34 *
35 * Register blocks are guaranteed to start at 0 and to be consecutively numbered.
36 */
38 kDtSpiHostRegBlockCore = 0, /**< */
39 kDtSpiHostRegBlockCount = 1, /**< \internal Number of register blocks */
41
42/** Primary register block (associated with the "primary" set of registers that control the IP). */
43static const dt_spi_host_reg_block_t kDtSpiHostRegBlockPrimary = kDtSpiHostRegBlockCore;
44
45/**
46 * List of IRQs.
47 *
48 * IRQs are guaranteed to be numbered consecutively from 0.
49 */
50typedef enum dt_spi_host_irq {
51 kDtSpiHostIrqError = 0, /**< Error-related interrupts, see !!ERROR_ENABLE register for more
52 information. */
53 kDtSpiHostIrqSpiEvent = 1, /**< Event-related interrupts, see !!EVENT_ENABLE register for more
54 information. */
55 kDtSpiHostIrqCount = 2, /**< \internal Number of IRQs */
57
58/**
59 * List of Alerts.
60 *
61 * Alerts are guaranteed to be numbered consecutively from 0.
62 */
63typedef enum dt_spi_host_alert {
64 kDtSpiHostAlertFatalFault = 0, /**< This fatal alert is triggered when a fatal TL-UL bus integrity fault is detected. */
65 kDtSpiHostAlertCount = 1, /**< \internal Number of Alerts */
67
68/**
69 * List of clock ports.
70 *
71 * Clock ports are guaranteed to be numbered consecutively from 0.
72 */
73typedef enum dt_spi_host_clock {
74 kDtSpiHostClockClk = 0, /**< Clock port clk_i */
75 kDtSpiHostClockCount = 1, /**< \internal Number of clock ports */
77
78/**
79 * List of reset ports.
80 *
81 * Reset ports are guaranteed to be numbered consecutively from 0.
82 */
83typedef enum dt_spi_host_reset {
84 kDtSpiHostResetRst = 0, /**< Reset port rst_ni */
85 kDtSpiHostResetCount = 1, /**< \internal Number of reset ports */
87
88/**
89 * List of peripheral I/O.
90 *
91 * Peripheral I/O are guaranteed to be numbered consecutively from 0.
92 */
94 kDtSpiHostPeriphIoSck = 0, /**< */
95 kDtSpiHostPeriphIoCsb = 1, /**< */
96 kDtSpiHostPeriphIoSd0 = 2, /**< */
97 kDtSpiHostPeriphIoSd1 = 3, /**< */
98 kDtSpiHostPeriphIoSd2 = 4, /**< */
99 kDtSpiHostPeriphIoSd3 = 5, /**< */
100 kDtSpiHostPeriphIoCount = 6, /**< \internal Number of peripheral I/O */
102
103/**
104 * List of supported hardware features.
105 */
106#define OPENTITAN_SPI_HOST_HAS_USECASE_SERIALNORFLASH 1
107#define OPENTITAN_SPI_HOST_HAS_USECASE_PASSTHROUGH 1
108#define OPENTITAN_SPI_HOST_HAS_RATE_STANDARD 1
109#define OPENTITAN_SPI_HOST_HAS_RATE_DUAL 1
110#define OPENTITAN_SPI_HOST_HAS_RATE_QUAD 1
111#define OPENTITAN_SPI_HOST_HAS_CONFIG_CPOL 1
112#define OPENTITAN_SPI_HOST_HAS_CONFIG_CLOCKDIV 1
113#define OPENTITAN_SPI_HOST_HAS_EVENT_WATERMARK 1
114#define OPENTITAN_SPI_HOST_HAS_EVENT_FULL 1
115#define OPENTITAN_SPI_HOST_HAS_EVENT_EMPTY 1
116
117
118
119/**
120 * Get the spi_host instance from an instance ID
121 *
122 * For example, `dt_uart_from_instance_id(kDtInstanceIdUart3) == kDtUart3`.
123 *
124 * @param inst_id Instance ID.
125 * @return A spi_host instance.
126 *
127 * **Note:** This function only makes sense if the instance ID has device type spi_host,
128 * otherwise the returned value is unspecified.
129 */
131
132/**
133 * Get the instance ID of an instance.
134 *
135 * @param dt Instance of spi_host.
136 * @return The instance ID of that instance.
137 */
139
140/**
141 * Get the register base address of an instance.
142 *
143 * @param dt Instance of spi_host.
144 * @param reg_block The register block requested.
145 * @return The register base address of the requested block.
146 */
147uint32_t dt_spi_host_reg_block(
148 dt_spi_host_t dt,
149 dt_spi_host_reg_block_t reg_block);
150
151/**
152 * Get the primary register base address of an instance.
153 *
154 * This is just a convenience function, equivalent to
155 * `dt_spi_host_reg_block(dt, kDtSpiHostRegBlockCore)`
156 *
157 * @param dt Instance of spi_host.
158 * @return The register base address of the primary register block.
159 */
160static inline uint32_t dt_spi_host_primary_reg_block(
161 dt_spi_host_t dt) {
162 return dt_spi_host_reg_block(dt, kDtSpiHostRegBlockCore);
163}
164
165/**
166 * Get the PLIC ID of a spi_host IRQ for a given instance.
167 *
168 * If the instance is not connected to the PLIC, this function
169 * will return `kDtPlicIrqIdNone`.
170 *
171 * @param dt Instance of spi_host.
172 * @param irq A spi_host IRQ.
173 * @return The PLIC ID of the IRQ of this instance.
174 */
176 dt_spi_host_t dt,
178
179/**
180 * Convert a global IRQ ID to a local spi_host IRQ type.
181 *
182 * @param dt Instance of spi_host.
183 * @param irq A PLIC ID that belongs to this instance.
184 * @return The spi_host IRQ, or `kDtSpiHostIrqCount`.
185 *
186 * **Note:** This function assumes that the PLIC ID belongs to the instance
187 * of spi_host passed in parameter. In other words, it must be the case that
188 * `dt_spi_host_instance_id(dt) == dt_plic_id_to_instance_id(irq)`. Otherwise, this function
189 * will return `kDtSpiHostIrqCount`.
190 */
192 dt_spi_host_t dt,
193 dt_plic_irq_id_t irq);
194
195
196/**
197 * Get the alert ID of a spi_host alert for a given instance.
198 *
199 * **Note:** This function only makes sense if the instance is connected to the Alert Handler. For any
200 * instances where the instance is not connected, the return value is unspecified.
201 *
202 * @param dt Instance of spi_host.
203 * @param alert A spi_host alert.
204 * @return The Alert Handler alert ID of the alert of this instance.
205 */
207 dt_spi_host_t dt,
208 dt_spi_host_alert_t alert);
209
210/**
211 * Convert a global alert ID to a local spi_host alert type.
212 *
213 * @param dt Instance of spi_host.
214 * @param alert A global alert ID that belongs to this instance.
215 * @return The spi_host alert, or `kDtSpiHostAlertCount`.
216 *
217 * **Note:** This function assumes that the global alert ID belongs to the
218 * instance of spi_host passed in parameter. In other words, it must be the case
219 * that `dt_spi_host_instance_id(dt) == dt_alert_id_to_instance_id(alert)`. Otherwise,
220 * this function will return `kDtSpiHostAlertCount`.
221 */
223 dt_spi_host_t dt,
224 dt_alert_id_t alert);
225
226
227/**
228 * Get the peripheral I/O description of an instance.
229 *
230 * @param dt Instance of spi_host.
231 * @param sig Requested peripheral I/O.
232 * @return Description of the requested peripheral I/O for this instance.
233 */
235 dt_spi_host_t dt,
237
238/**
239 * Get the clock signal connected to a clock port of an instance.
240 *
241 * @param dt Instance of spi_host.
242 * @param clk Clock port.
243 * @return Clock signal.
244 */
246 dt_spi_host_t dt,
248
249/**
250 * Get the reset signal connected to a reset port of an instance.
251 *
252 * @param dt Instance of spi_host.
253 * @param rst Reset port.
254 * @return Reset signal.
255 */
257 dt_spi_host_t dt,
259
260
261
262#endif // OPENTITAN_DT_SPI_HOST_H_