Software APIs
dt_rstmgr.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_RSTMGR_H_
8#define OPENTITAN_DT_RSTMGR_H_
9
10/**
11 * @file
12 * @brief Device Tables (DT) for IP rstmgr and top earlgrey.
13 *
14 * This file contains the type definitions and global functions of the rstmgr.
15 */
16
17#include "dt_api.h"
18#include <stdint.h>
19
20
21
22
23
24/**
25 * List of instances.
26 */
27typedef enum dt_rstmgr {
28 kDtRstmgrAon = 0, /**< rstmgr_aon */
29 kDtRstmgrFirst = 0, /**< \internal First instance */
30 kDtRstmgrCount = 1, /**< \internal Number of instances */
32
33/**
34 * List of register blocks.
35 *
36 * Register blocks are guaranteed to start at 0 and to be consecutively numbered.
37 */
38typedef enum dt_rstmgr_reg_block {
39 kDtRstmgrRegBlockCore = 0, /**< */
40 kDtRstmgrRegBlockCount = 1, /**< \internal Number of register blocks */
42
43/** Primary register block (associated with the "primary" set of registers that control the IP). */
44static const dt_rstmgr_reg_block_t kDtRstmgrRegBlockPrimary = kDtRstmgrRegBlockCore;
45
46/**
47 * List of Alerts.
48 *
49 * Alerts are guaranteed to be numbered consecutively from 0.
50 */
51typedef enum dt_rstmgr_alert {
52 kDtRstmgrAlertFatalFault = 0, /**< This fatal alert is triggered when a fatal structural fault is detected.
53Structural faults include errors such as sparse fsm errors and tlul integrity errors. */
54 kDtRstmgrAlertFatalCnstyFault = 1, /**< This fatal alert is triggered when a reset consistency fault is detected.
55It is separated from the category above for clearer error collection and debug. */
56 kDtRstmgrAlertCount = 2, /**< \internal Number of Alerts */
58
59/**
60 * List of clock ports.
61 *
62 * Clock ports are guaranteed to be numbered consecutively from 0.
63 */
64typedef enum dt_rstmgr_clock {
65 kDtRstmgrClockClk = 0, /**< Clock port clk_i */
66 kDtRstmgrClockAon = 1, /**< Clock port clk_aon_i */
67 kDtRstmgrClockIoDiv4 = 2, /**< Clock port clk_io_div4_i */
68 kDtRstmgrClockMain = 3, /**< Clock port clk_main_i */
69 kDtRstmgrClockIo = 4, /**< Clock port clk_io_i */
70 kDtRstmgrClockIoDiv2 = 5, /**< Clock port clk_io_div2_i */
71 kDtRstmgrClockUsb = 6, /**< Clock port clk_usb_i */
72 kDtRstmgrClockPor = 7, /**< Clock port clk_por_i */
73 kDtRstmgrClockCount = 8, /**< \internal Number of clock ports */
75
76/**
77 * List of reset ports.
78 *
79 * Reset ports are guaranteed to be numbered consecutively from 0.
80 */
81typedef enum dt_rstmgr_reset {
82 kDtRstmgrResetRst = 0, /**< Reset port rst_ni */
83 kDtRstmgrResetPor = 1, /**< Reset port rst_por_ni */
84 kDtRstmgrResetCount = 2, /**< \internal Number of reset ports */
86
87/**
88 * List of supported hardware features.
89 */
90#define OPENTITAN_RSTMGR_HAS_SW_RST_CHIP_RESET 1
91#define OPENTITAN_RSTMGR_HAS_SW_RST_SPI_DEVICE_REQUEST 1
92#define OPENTITAN_RSTMGR_HAS_SW_RST_SPI_DEVICE_ENABLE 1
93#define OPENTITAN_RSTMGR_HAS_SW_RST_SPI_HOST0_REQUEST 1
94#define OPENTITAN_RSTMGR_HAS_SW_RST_SPI_HOST0_ENABLE 1
95#define OPENTITAN_RSTMGR_HAS_SW_RST_SPI_HOST1_REQUEST 1
96#define OPENTITAN_RSTMGR_HAS_SW_RST_SPI_HOST1_ENABLE 1
97#define OPENTITAN_RSTMGR_HAS_SW_RST_USB_REQUEST 1
98#define OPENTITAN_RSTMGR_HAS_SW_RST_USB_ENABLE 1
99#define OPENTITAN_RSTMGR_HAS_SW_RST_USB_AON_REQUEST 1
100#define OPENTITAN_RSTMGR_HAS_SW_RST_USB_AON_ENABLE 1
101#define OPENTITAN_RSTMGR_HAS_SW_RST_I2C0_REQUEST 1
102#define OPENTITAN_RSTMGR_HAS_SW_RST_I2C0_ENABLE 1
103#define OPENTITAN_RSTMGR_HAS_SW_RST_I2C1_REQUEST 1
104#define OPENTITAN_RSTMGR_HAS_SW_RST_I2C1_ENABLE 1
105#define OPENTITAN_RSTMGR_HAS_SW_RST_I2C2_REQUEST 1
106#define OPENTITAN_RSTMGR_HAS_SW_RST_I2C2_ENABLE 1
107#define OPENTITAN_RSTMGR_HAS_RESET_INFO_CAPTURE 1
108#define OPENTITAN_RSTMGR_HAS_RESET_INFO_CLEAR 1
109#define OPENTITAN_RSTMGR_HAS_ALERT_INFO_CAPTURE 1
110#define OPENTITAN_RSTMGR_HAS_ALERT_INFO_ENABLE 1
111#define OPENTITAN_RSTMGR_HAS_CPU_INFO_CAPTURE 1
112#define OPENTITAN_RSTMGR_HAS_CPU_INFO_ENABLE 1
113#define OPENTITAN_RSTMGR_HAS_ALERT_HANDLER_RESET_STATUS 1
114
115
116
117/**
118 * Get the rstmgr instance from an instance ID
119 *
120 * For example, `dt_uart_from_instance_id(kDtInstanceIdUart3) == kDtUart3`.
121 *
122 * @param inst_id Instance ID.
123 * @return A rstmgr instance.
124 *
125 * **Note:** This function only makes sense if the instance ID has device type rstmgr,
126 * otherwise the returned value is unspecified.
127 */
129
130/**
131 * Get the instance ID of an instance.
132 *
133 * @param dt Instance of rstmgr.
134 * @return The instance ID of that instance.
135 */
137
138/**
139 * Get the register base address of an instance.
140 *
141 * @param dt Instance of rstmgr.
142 * @param reg_block The register block requested.
143 * @return The register base address of the requested block.
144 */
145uint32_t dt_rstmgr_reg_block(
146 dt_rstmgr_t dt,
147 dt_rstmgr_reg_block_t reg_block);
148
149/**
150 * Get the primary register base address of an instance.
151 *
152 * This is just a convenience function, equivalent to
153 * `dt_rstmgr_reg_block(dt, kDtRstmgrRegBlockCore)`
154 *
155 * @param dt Instance of rstmgr.
156 * @return The register base address of the primary register block.
157 */
158static inline uint32_t dt_rstmgr_primary_reg_block(
159 dt_rstmgr_t dt) {
160 return dt_rstmgr_reg_block(dt, kDtRstmgrRegBlockCore);
161}
162
163
164/**
165 * Get the alert ID of a rstmgr alert for a given instance.
166 *
167 * **Note:** This function only makes sense if the instance is connected to the Alert Handler. For any
168 * instances where the instance is not connected, the return value is unspecified.
169 *
170 * @param dt Instance of rstmgr.
171 * @param alert A rstmgr alert.
172 * @return The Alert Handler alert ID of the alert of this instance.
173 */
175 dt_rstmgr_t dt,
176 dt_rstmgr_alert_t alert);
177
178/**
179 * Convert a global alert ID to a local rstmgr alert type.
180 *
181 * @param dt Instance of rstmgr.
182 * @param alert A global alert ID that belongs to this instance.
183 * @return The rstmgr alert, or `kDtRstmgrAlertCount`.
184 *
185 * **Note:** This function assumes that the global alert ID belongs to the
186 * instance of rstmgr passed in parameter. In other words, it must be the case
187 * that `dt_rstmgr_instance_id(dt) == dt_alert_id_to_instance_id(alert)`. Otherwise,
188 * this function will return `kDtRstmgrAlertCount`.
189 */
191 dt_rstmgr_t dt,
192 dt_alert_id_t alert);
193
194
195
196/**
197 * Get the clock signal connected to a clock port of an instance.
198 *
199 * @param dt Instance of rstmgr.
200 * @param clk Clock port.
201 * @return Clock signal.
202 */
204 dt_rstmgr_t dt,
206
207/**
208 * Get the reset signal connected to a reset port of an instance.
209 *
210 * @param dt Instance of rstmgr.
211 * @param rst Reset port.
212 * @return Reset signal.
213 */
215 dt_rstmgr_t dt,
217
218
219
220/**
221 * Get the number of software resets.
222 *
223 * @param dt Instance of rstmgr.
224 * @return Number of software resets.
225 */
227
228/**
229 * Get the reset ID of a software reset.
230 *
231 * The resets are ordered in the same way as they appear in the registers.
232 *
233 * @param dt Instance of rstmgr.
234 * @param idx Index of the software reset, between 0 and `dt_rstmgr_sw_reset_count(dt)-1`.
235 * @return Reset ID, or `kDtResetUnknown` for invalid parameters.
236 */
238
239/**
240 * Description of a reset request source.
241 *
242 * A reset request source is always identified by the instance ID of the module where it comes
243 * from. In principle, some instances could have several reset requests. If this is the case,
244 * the `rst_req` can be used to distinguish between those. It should be cast to the
245 * `dt_<ip>_reset_req_t` type of the corresponding IP.
246 *
247 * WARNING At the moment, three hardcoded reset requests are treated specially and have their
248 * `rst_req` field set to `0` because there is no corresponding reset request declared by those IPs:
249 * - the main power glitch reset request, coming from the `pwrmgr`,
250 * - the escalation reset request, coming from the `alert_handler`,
251 * - the non-debug-module reset request, coming from the `rv_dm`.
252 */
254 dt_instance_id_t inst_id; /**< Instance ID of the source of this reset request. */
255 size_t reset_req; /**< Index of the reset request signal for that instance. */
257
258
259/**
260 * Get the number of hardware reset requests.
261 *
262 * @param dt Instance of rstmgr.
263 * @return Number of reset requests.
264 */
266
267/**
268 * Get the description of a reset request.
269 *
270 * The reset requests are ordered as they appear in the registers.
271 *
272 * @param dt Instance of rstmgr.
273 * @param idx Index of the reset request source, between 0 and
274 * `dt_pwrmgr_hw_reset_req_src_count(dt)-1`.
275 * @return Description of the reset.
276 */
278
279
280
281#endif // OPENTITAN_DT_RSTMGR_H_