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