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