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