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#ifdef __cplusplus
11extern "C" {
12#endif // __cplusplus
13
14/**
15 * @file
16 * @brief Device Tables (DT) for IP rstmgr and top englishbreakfast.
17 *
18 * This file contains the type definitions and global functions of the rstmgr.
19 */
20
21#include "hw/top/dt/dt_api.h"
22#include <stdint.h>
23
24
25
26
27
28/**
29 * List of instances.
30 */
31typedef enum dt_rstmgr {
32 kDtRstmgrAon = 0, /**< rstmgr_aon */
33 kDtRstmgrFirst = 0, /**< \internal First instance */
34 kDtRstmgrCount = 1, /**< \internal Number of instances */
36
37/**
38 * List of register blocks.
39 *
40 * Register blocks are guaranteed to start at 0 and to be consecutively numbered.
41 */
42typedef enum dt_rstmgr_reg_block {
43 kDtRstmgrRegBlockCore = 0, /**< */
44 kDtRstmgrRegBlockCount = 1, /**< \internal Number of register blocks */
46
47/**
48 * List of memories.
49 *
50 * Memories are guaranteed to start at 0 and to be consecutively numbered.
51 */
52typedef enum dt_rstmgr_memory {
53 kDtRstmgrMemoryCount = 0, /**< \internal Number of memories */
55
56/** Primary register block (associated with the "primary" set of registers that control the IP). */
57static const dt_rstmgr_reg_block_t kDtRstmgrRegBlockPrimary = kDtRstmgrRegBlockCore;
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_USB_REQUEST 1
96#define OPENTITAN_RSTMGR_HAS_SW_RST_USB_ENABLE 1
97#define OPENTITAN_RSTMGR_HAS_RESET_INFO_CAPTURE 1
98#define OPENTITAN_RSTMGR_HAS_RESET_INFO_CLEAR 1
99#define OPENTITAN_RSTMGR_HAS_ALERT_INFO_CAPTURE 1
100#define OPENTITAN_RSTMGR_HAS_ALERT_INFO_ENABLE 1
101#define OPENTITAN_RSTMGR_HAS_CPU_INFO_CAPTURE 1
102#define OPENTITAN_RSTMGR_HAS_CPU_INFO_ENABLE 1
103#define OPENTITAN_RSTMGR_HAS_ALERT_HANDLER_RESET_STATUS 1
104
105
106
107/**
108 * Get the rstmgr instance from an instance ID
109 *
110 * For example, `dt_uart_from_instance_id(kDtInstanceIdUart3) == kDtUart3`.
111 *
112 * @param inst_id Instance ID.
113 * @return A rstmgr instance.
114 *
115 * **Note:** This function only makes sense if the instance ID has device type rstmgr,
116 * otherwise the returned value is unspecified.
117 */
119
120/**
121 * Get the instance ID of an instance.
122 *
123 * @param dt Instance of rstmgr.
124 * @return The instance ID of that instance.
125 */
127
128/**
129 * Get the register base address of an instance.
130 *
131 * @param dt Instance of rstmgr.
132 * @param reg_block The register block requested.
133 * @return The register base address of the requested block.
134 */
135uint32_t dt_rstmgr_reg_block(
136 dt_rstmgr_t dt,
137 dt_rstmgr_reg_block_t reg_block);
138
139/**
140 * Get the primary register base address of an instance.
141 *
142 * This is just a convenience function, equivalent to
143 * `dt_rstmgr_reg_block(dt, kDtRstmgrRegBlockCore)`
144 *
145 * @param dt Instance of rstmgr.
146 * @return The register base address of the primary register block.
147 */
148static inline uint32_t dt_rstmgr_primary_reg_block(
149 dt_rstmgr_t dt) {
150 return dt_rstmgr_reg_block(dt, kDtRstmgrRegBlockCore);
151}
152
153/**
154 * Get the base address of a memory.
155 *
156 * @param dt Instance of rstmgr.
157 * @param mem The memory requested.
158 * @return The base address of the requested memory.
159 */
160uint32_t dt_rstmgr_memory_base(
161 dt_rstmgr_t dt,
163
164/**
165 * Get the size of a memory.
166 *
167 * @param dt Instance of rstmgr.
168 * @param mem The memory requested.
169 * @return The size of the requested memory.
170 */
171uint32_t dt_rstmgr_memory_size(
172 dt_rstmgr_t dt,
174
175
176
177
178/**
179 * Get the clock signal connected to a clock port of an instance.
180 *
181 * @param dt Instance of rstmgr.
182 * @param clk Clock port.
183 * @return Clock signal.
184 */
186 dt_rstmgr_t dt,
188
189/**
190 * Get the reset signal connected to a reset port of an instance.
191 *
192 * @param dt Instance of rstmgr.
193 * @param rst Reset port.
194 * @return Reset signal.
195 */
197 dt_rstmgr_t dt,
199
200
201
202/**
203 * Get the number of software resets.
204 *
205 * @param dt Instance of rstmgr.
206 * @return Number of software resets.
207 */
209
210/**
211 * Get the reset ID of a software reset.
212 *
213 * The resets are ordered in the same way as they appear in the registers.
214 *
215 * @param dt Instance of rstmgr.
216 * @param idx Index of the software reset, between 0 and `dt_rstmgr_sw_reset_count(dt)-1`.
217 * @return Reset ID, or `kDtResetUnknown` for invalid parameters.
218 */
220
221/**
222 * Description of a reset request source.
223 *
224 * A reset request source is always identified by the instance ID of the module where it comes
225 * from. In principle, some instances could have several reset requests. If this is the case,
226 * the `rst_req` can be used to distinguish between those. It should be cast to the
227 * `dt_<ip>_reset_req_t` type of the corresponding IP.
228 *
229 * WARNING At the moment, three hardcoded reset requests are treated specially and have their
230 * `reset_req` field set to `0` because there is no corresponding reset request declared by those
231 * IPs:
232 * - the main power glitch reset request, coming from the `pwrmgr`,
233 * - the escalation reset request, coming from the `alert_handler`,
234 * - the non-debug-module reset request, coming from the `rv_dm`.
235 */
236typedef struct dt_rstmgr_reset_req_src {
237 dt_instance_id_t inst_id; /**< Instance ID of the source of this reset request. */
238 size_t reset_req; /**< Index of the reset request signal for that instance. */
240
241
242/**
243 * Get the number of hardware reset requests.
244 *
245 * @param dt Instance of rstmgr.
246 * @return Number of reset requests.
247 */
249
250/**
251 * Get the description of a reset request.
252 *
253 * The reset requests are ordered as they appear in the registers.
254 *
255 * @param dt Instance of rstmgr.
256 * @param idx Index of the reset request source, between 0 and
257 * `dt_pwrmgr_hw_reset_req_src_count(dt)-1`.
258 * @return Description of the reset.
259 */
261
262
263
264#ifdef __cplusplus
265} // extern "C"
266#endif // __cplusplus
267
268#endif // OPENTITAN_DT_RSTMGR_H_