Software APIs
dt_flash_ctrl.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_FLASH_CTRL_H_
8#define OPENTITAN_DT_FLASH_CTRL_H_
9
10#ifdef __cplusplus
11extern "C" {
12#endif // __cplusplus
13
14/**
15 * @file
16 * @brief Device Tables (DT) for IP flash_ctrl and top earlgrey.
17 *
18 * This file contains the type definitions and global functions of the flash_ctrl.
19 */
20
21#include "dt_api.h"
22#include <stdint.h>
23
24
25
26/**
27 * List of instances.
28 */
29typedef enum dt_flash_ctrl {
30 kDtFlashCtrl = 0, /**< flash_ctrl */
31 kDtFlashCtrlFirst = 0, /**< \internal First instance */
32 kDtFlashCtrlCount = 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 kDtFlashCtrlRegBlockCore = 0, /**< */
42 kDtFlashCtrlRegBlockPrim = 1, /**< */
43 kDtFlashCtrlRegBlockMem = 2, /**< */
44 kDtFlashCtrlRegBlockCount = 3, /**< \internal Number of register blocks */
46
47/** Primary register block (associated with the "primary" set of registers that control the IP). */
48static const dt_flash_ctrl_reg_block_t kDtFlashCtrlRegBlockPrimary = kDtFlashCtrlRegBlockCore;
49
50/**
51 * List of IRQs.
52 *
53 * IRQs are guaranteed to be numbered consecutively from 0.
54 */
55typedef enum dt_flash_ctrl_irq {
56 kDtFlashCtrlIrqProgEmpty = 0, /**< Program FIFO empty */
57 kDtFlashCtrlIrqProgLvl = 1, /**< Program FIFO drained to level */
58 kDtFlashCtrlIrqRdFull = 2, /**< Read FIFO full */
59 kDtFlashCtrlIrqRdLvl = 3, /**< Read FIFO filled to level */
60 kDtFlashCtrlIrqOpDone = 4, /**< Operation complete */
61 kDtFlashCtrlIrqCorrErr = 5, /**< Correctable error encountered */
62 kDtFlashCtrlIrqCount = 6, /**< \internal Number of IRQs */
64
65/**
66 * List of Alerts.
67 *
68 * Alerts are guaranteed to be numbered consecutively from 0.
69 */
70typedef enum dt_flash_ctrl_alert {
71 kDtFlashCtrlAlertRecovErr = 0, /**< flash recoverable errors */
72 kDtFlashCtrlAlertFatalStdErr = 1, /**< flash standard fatal errors */
73 kDtFlashCtrlAlertFatalErr = 2, /**< Flash fatal errors including uncorrectable ECC errors.
74
75Note that this alert is not always fatal.
76The underlying error bits in the !!FAULT_STATUS register remain set until reset, meaning the alert keeps firing.
77This doesn't hold for !!FAULT_STATUS.PHY_RELBL_ERR and !!FAULT_STATUS.PHY_STORAGE_ERR.
78To enable firmware dealing with multi-bit ECC and ICV errors during firmware selection and verification, these error bits can be cleared.
79After passing this stage, it is recommended that firmware classifies the corresponding alert as fatal on the receiver end, i.e, inside the alert handler. */
80 kDtFlashCtrlAlertFatalPrimFlashAlert = 3, /**< Fatal alert triggered inside the flash primitive, including fatal TL-UL bus integrity faults of the test interface. */
81 kDtFlashCtrlAlertRecovPrimFlashAlert = 4, /**< Recoverable alert triggered inside the flash primitive. */
82 kDtFlashCtrlAlertCount = 5, /**< \internal Number of Alerts */
84
85/**
86 * List of clock ports.
87 *
88 * Clock ports are guaranteed to be numbered consecutively from 0.
89 */
90typedef enum dt_flash_ctrl_clock {
91 kDtFlashCtrlClockClk = 0, /**< Clock port clk_i */
92 kDtFlashCtrlClockOtp = 1, /**< Clock port clk_otp_i */
93 kDtFlashCtrlClockCount = 2, /**< \internal Number of clock ports */
95
96/**
97 * List of reset ports.
98 *
99 * Reset ports are guaranteed to be numbered consecutively from 0.
100 */
102 kDtFlashCtrlResetRst = 0, /**< Reset port rst_ni */
103 kDtFlashCtrlResetOtp = 1, /**< Reset port rst_otp_ni */
104 kDtFlashCtrlResetCount = 2, /**< \internal Number of reset ports */
106
107/**
108 * List of peripheral I/O.
109 *
110 * Peripheral I/O are guaranteed to be numbered consecutively from 0.
111 */
113 kDtFlashCtrlPeriphIoTck = 0, /**< */
114 kDtFlashCtrlPeriphIoTms = 1, /**< */
115 kDtFlashCtrlPeriphIoTdi = 2, /**< */
116 kDtFlashCtrlPeriphIoTdo = 3, /**< */
117 kDtFlashCtrlPeriphIoCount = 4, /**< \internal Number of peripheral I/O */
119
120/**
121 * List of supported hardware features.
122 */
123#define OPENTITAN_FLASH_CTRL_HAS_ESCALATION 1
124#define OPENTITAN_FLASH_CTRL_HAS_FETCH_CODE 1
125#define OPENTITAN_FLASH_CTRL_HAS_INFO_CREATOR_PARTITION 1
126#define OPENTITAN_FLASH_CTRL_HAS_INFO_ISOLATED_PARTITION 1
127#define OPENTITAN_FLASH_CTRL_HAS_INFO_OWNER_PARTITION 1
128#define OPENTITAN_FLASH_CTRL_HAS_INIT_ROOT_SEEDS 1
129#define OPENTITAN_FLASH_CTRL_HAS_INIT_SCRAMBLING_KEYS 1
130#define OPENTITAN_FLASH_CTRL_HAS_MEM_PROTECTION 1
131#define OPENTITAN_FLASH_CTRL_HAS_OP_HOST_READ 1
132#define OPENTITAN_FLASH_CTRL_HAS_OP_PROTOCOL_CTRL 1
133#define OPENTITAN_FLASH_CTRL_HAS_RMA 1
134
135
136
137/**
138 * Get the flash_ctrl instance from an instance ID
139 *
140 * For example, `dt_uart_from_instance_id(kDtInstanceIdUart3) == kDtUart3`.
141 *
142 * @param inst_id Instance ID.
143 * @return A flash_ctrl instance.
144 *
145 * **Note:** This function only makes sense if the instance ID has device type flash_ctrl,
146 * otherwise the returned value is unspecified.
147 */
149
150/**
151 * Get the instance ID of an instance.
152 *
153 * @param dt Instance of flash_ctrl.
154 * @return The instance ID of that instance.
155 */
157
158/**
159 * Get the register base address of an instance.
160 *
161 * @param dt Instance of flash_ctrl.
162 * @param reg_block The register block requested.
163 * @return The register base address of the requested block.
164 */
167 dt_flash_ctrl_reg_block_t reg_block);
168
169/**
170 * Get the primary register base address of an instance.
171 *
172 * This is just a convenience function, equivalent to
173 * `dt_flash_ctrl_reg_block(dt, kDtFlashCtrlRegBlockCore)`
174 *
175 * @param dt Instance of flash_ctrl.
176 * @return The register base address of the primary register block.
177 */
178static inline uint32_t dt_flash_ctrl_primary_reg_block(
179 dt_flash_ctrl_t dt) {
180 return dt_flash_ctrl_reg_block(dt, kDtFlashCtrlRegBlockCore);
181}
182
183/**
184 * Get the PLIC ID of a flash_ctrl IRQ for a given instance.
185 *
186 * If the instance is not connected to the PLIC, this function
187 * will return `kDtPlicIrqIdNone`.
188 *
189 * @param dt Instance of flash_ctrl.
190 * @param irq A flash_ctrl IRQ.
191 * @return The PLIC ID of the IRQ of this instance.
192 */
196
197/**
198 * Convert a global IRQ ID to a local flash_ctrl IRQ type.
199 *
200 * @param dt Instance of flash_ctrl.
201 * @param irq A PLIC ID that belongs to this instance.
202 * @return The flash_ctrl IRQ, or `kDtFlashCtrlIrqCount`.
203 *
204 * **Note:** This function assumes that the PLIC ID belongs to the instance
205 * of flash_ctrl passed in parameter. In other words, it must be the case that
206 * `dt_flash_ctrl_instance_id(dt) == dt_plic_id_to_instance_id(irq)`. Otherwise, this function
207 * will return `kDtFlashCtrlIrqCount`.
208 */
211 dt_plic_irq_id_t irq);
212
213
214/**
215 * Get the alert ID of a flash_ctrl alert for a given instance.
216 *
217 * **Note:** This function only makes sense if the instance is connected to the Alert Handler. For any
218 * instances where the instance is not connected, the return value is unspecified.
219 *
220 * @param dt Instance of flash_ctrl.
221 * @param alert A flash_ctrl alert.
222 * @return The Alert Handler alert ID of the alert of this instance.
223 */
227
228/**
229 * Convert a global alert ID to a local flash_ctrl alert type.
230 *
231 * @param dt Instance of flash_ctrl.
232 * @param alert A global alert ID that belongs to this instance.
233 * @return The flash_ctrl alert, or `kDtFlashCtrlAlertCount`.
234 *
235 * **Note:** This function assumes that the global alert ID belongs to the
236 * instance of flash_ctrl passed in parameter. In other words, it must be the case
237 * that `dt_flash_ctrl_instance_id(dt) == dt_alert_id_to_instance_id(alert)`. Otherwise,
238 * this function will return `kDtFlashCtrlAlertCount`.
239 */
242 dt_alert_id_t alert);
243
244
245/**
246 * Get the peripheral I/O description of an instance.
247 *
248 * @param dt Instance of flash_ctrl.
249 * @param sig Requested peripheral I/O.
250 * @return Description of the requested peripheral I/O for this instance.
251 */
255
256/**
257 * Get the clock signal connected to a clock port of an instance.
258 *
259 * @param dt Instance of flash_ctrl.
260 * @param clk Clock port.
261 * @return Clock signal.
262 */
266
267/**
268 * Get the reset signal connected to a reset port of an instance.
269 *
270 * @param dt Instance of flash_ctrl.
271 * @param rst Reset port.
272 * @return Reset signal.
273 */
277
278
279
280#ifdef __cplusplus
281} // extern "C"
282#endif // __cplusplus
283
284#endif // OPENTITAN_DT_FLASH_CTRL_H_