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
11
extern
"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
*/
31
typedef
enum
dt_rstmgr
{
32
kDtRstmgrFirst
= 0,
/**< First instance */
33
kDtRstmgr
= 0,
/**< rstmgr */
34
}
dt_rstmgr_t
;
35
36
enum
{
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
*/
46
typedef
enum
dt_rstmgr_reg_block
{
47
kDtRstmgrRegBlockCore = 0,
/**< */
48
}
dt_rstmgr_reg_block_t
;
49
50
enum
{
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). */
56
static
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
*/
63
typedef
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. */
68
}
dt_rstmgr_alert_t
;
69
70
enum
{
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
*/
80
typedef
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 */
88
}
dt_rstmgr_clock_t
;
89
90
enum
{
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
*/
100
typedef
enum
dt_rstmgr_reset
{
101
kDtRstmgrResetRst
= 0,
/**< Reset port rst_ni */
102
kDtRstmgrResetPor
= 1,
/**< Reset port rst_por_ni */
103
}
dt_rstmgr_reset_t
;
104
105
enum
{
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
*/
155
dt_rstmgr_t
dt_rstmgr_from_instance_id
(
dt_instance_id_t
inst_id);
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
*/
163
dt_instance_id_t
dt_rstmgr_instance_id
(
dt_rstmgr_t
dt);
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
*/
172
uint32_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
*/
185
static
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
*/
201
dt_alert_id_t
dt_rstmgr_alert_to_alert_id
(
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
*/
217
dt_rstmgr_alert_t
dt_rstmgr_alert_from_alert_id
(
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
*/
230
dt_clock_t
dt_rstmgr_clock
(
231
dt_rstmgr_t
dt,
232
dt_rstmgr_clock_t
clk);
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
*/
241
dt_reset_t
dt_rstmgr_reset
(
242
dt_rstmgr_t
dt,
243
dt_rstmgr_reset_t
rst);
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
*/
253
size_t
dt_rstmgr_sw_reset_count
(
dt_rstmgr_t
dt);
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
*/
264
dt_reset_t
dt_rstmgr_sw_reset
(
dt_rstmgr_t
dt,
size_t
idx);
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
*/
281
typedef
struct
dt_rstmgr_reset_req_src
{
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. */
284
}
dt_rstmgr_reset_req_src_t
;
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
*/
293
size_t
dt_rstmgr_hw_reset_req_src_count
(
dt_rstmgr_t
dt);
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
*/
305
dt_rstmgr_reset_req_src_t
dt_rstmgr_hw_reset_req_src
(
dt_rstmgr_t
dt,
size_t
idx);
306
307
308
309
#ifdef __cplusplus
310
}
// extern "C"
311
#endif
// __cplusplus
312
313
#endif
// OPENTITAN_DT_RSTMGR_H_
(earlgrey)
hw
top
dt
rstmgr.h
Return to
OpenTitan Documentation