Software APIs
rstmgr.h
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 #ifndef OPENTITAN_SW_DEVICE_SILICON_CREATOR_LIB_DRIVERS_RSTMGR_H_
6 #define OPENTITAN_SW_DEVICE_SILICON_CREATOR_LIB_DRIVERS_RSTMGR_H_
7 
8 #include <limits.h>
9 #include <stddef.h>
10 #include <stdint.h>
11 #include <stdnoreturn.h>
12 
13 #include "sw/device/lib/base/macros.h"
14 #include "sw/device/silicon_creator/lib/error.h"
15 
16 #ifdef __cplusplus
17 extern "C" {
18 #endif
19 
20 /**
21  * Alert information or CPU crash dump captured by the reset manager during the
22  * last reset.
23  */
24 typedef struct rstmgr_info {
25  /**
26  * Length.
27  */
28  uint32_t length;
29  /**
30  * Alert information or CPU crash dump words.
31  */
32  uint32_t info[16];
33 } rstmgr_info_t;
34 
35 /**
36  * Reset reason bitfield indices.
37  *
38  * Note that the reset reasons are not necessarily mutually exclusive.
39  */
40 typedef enum rstmgr_reason {
41  /**
42  * Power on reset (POR).
43  */
44  kRstmgrReasonPowerOn = 0,
45 
46  /**
47  * Low power exit (LOW_POWER_EXIT).
48  */
49  kRstmgrReasonLowPowerExit = 1,
50 
51  /**
52  * Software issued request (SW).
53  */
54  kRstmgrReasonSoftwareRequest = 2,
55 
56  /**
57  * Hardware requests (HW_REQ).
58  */
59  kRstmgrReasonSysrstCtrl = 3,
60  kRstmgrReasonWatchdog = 4,
61  kRstmgrReasonPowerUnstable = 5,
62  kRstmgrReasonEscalation = 6,
63  /**
64  * Non-debug module (NDM).
65  */
66  kRstmgrReasonNonDebugModule = 7,
67 
68  /**
69  * Last used bit index (inclusive).
70  */
71  kRstmgrReasonLast = 7,
72 } rstmgr_reason_t;
73 
74 /**
75  * Get alert information captured during last reset.
76  *
77  * @param[out] info Alert information.
78  */
79 void rstmgr_alert_info_collect(rstmgr_info_t *info);
80 
81 /**
82  * Get CPU crash dump captured during last reset.
83  *
84  * @param[out] info CPU crash dump.
85  */
86 void rstmgr_cpu_info_collect(rstmgr_info_t *info);
87 
88 /**
89  * Get the reason(s) for the last reset.
90  *
91  * The reset reason is a bitfield. Individual bits may be extracted using
92  * the indices provided by the `rstmgr_reason_t` enumeration. The reset
93  * reasons are not necessarily mutually exclusive.
94  */
95 OT_WARN_UNUSED_RESULT
96 uint32_t rstmgr_reason_get(void);
97 
98 /**
99  * Clear the reset reason(s) set in the given mask.
100  *
101  * A value of all ones will clear all the reset reasons while zero will
102  * leave the register unchanged.
103  *
104  * @param reasons A mask containing the bit fields to clear.
105  */
106 void rstmgr_reason_clear(uint32_t reasons);
107 
108 /**
109  * Enable capturing of alert info in the event of an alert escalation.
110  */
111 void rstmgr_alert_info_enable(void);
112 
113 /**
114  * Enable capturing of CPU crash dump in the event of a crash.
115  */
116 void rstmgr_cpu_info_enable(void);
117 
118 /**
119  * Requests a system reset.
120  */
121 #ifdef OT_PLATFORM_RV32
122 // Omit `noreturn` to be able to test this function in off-target tests.
123 noreturn
124 #endif
125  void
126  rstmgr_reset(void);
127 
128 /**
129  * Verifies that info collection is initialized properly.
130  *
131  * In order not to interfere with the operation of other software on the chip,
132  * this check is not enforced if `reasons` includes low power exit.
133  *
134  * @param reset_reasons Reset reasons.
135  */
136 OT_WARN_UNUSED_RESULT
137 rom_error_t rstmgr_info_en_check(uint32_t reset_reasons);
138 
139 /**
140  * Bitfields for `OWNER_SW_CFG_ROM_RSTMGR_INFO_EN" OTP item.
141  *
142  * Defined here to be able to use in tests.
143  */
144 #define RSTMGR_OTP_FIELD_ALERT_INFO_EN \
145  (bitfield_field32_t) { .mask = UINT8_MAX, .index = CHAR_BIT * 0 }
146 #define RSTMGR_OTP_FIELD_CPU_INFO_EN \
147  (bitfield_field32_t) { .mask = UINT8_MAX, .index = CHAR_BIT * 1 }
148 
149 #ifdef __cplusplus
150 }
151 #endif
152 #endif // OPENTITAN_SW_DEVICE_SILICON_CREATOR_LIB_DRIVERS_RSTMGR_H_
Return to OpenTitan Documentation