Software APIs
dif_rstmgr.h
Go to the documentation of this file.
1 // Copyright lowRISC contributors.
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_LIB_DIF_DIF_RSTMGR_H_
6 #define OPENTITAN_SW_DEVICE_LIB_DIF_DIF_RSTMGR_H_
7 
8 /**
9  * @file
10  * @brief <a href="/hw/ip/rstmgr/doc/">Reset Manager</a> Device Interface
11  * Functions
12  */
13 
14 #include <stdbool.h>
15 #include <stdint.h>
16 
19 
20 #ifdef __cplusplus
21 extern "C" {
22 #endif // __cplusplus
23 
24 /**
25  * The maximal size of the alert crash info dump.
26  *
27  * Note: must match the autogenerated register definition.
28  */
29 #define DIF_RSTMGR_ALERT_INFO_MAX_SIZE 0xf
30 
31 /**
32  * Enumeration for enabling/disabling various functionality.
33  */
34 typedef enum dif_rstmgr_toggle {
35  /**
36  * Enabled state.
37  */
39  /**
40  * Disabled state.
41  */
44 
45 /**
46  * Reset Manager peripheral software reset control.
47  */
49  /**
50  * Simple reset (release straight away).
51  */
53  kDifRstmgrSoftwareResetHold, /**< Hold peripheral in reset. */
54  kDifRstmgrSoftwareResetRelease, /**< Release peripheral from reset. */
56 
57 /**
58  * Reset Manager reset information bitfield.
59  */
61 
62 /**
63  * Reset Manager possible reset information enumeration.
64  *
65  * Invariants are used to extract information encoded in
66  * `dif_rstmgr_reset_info_bitfield_t`, which means that the values must
67  * correspond
68  * to the individual bits (0x1, 0x2, 0x4, ..., 0x80000000).
69  *
70  * Note: these must match the autogenerated register definitions.
71  */
72 typedef enum dif_rstmgr_reset_info {
73  /**
74  * Device has reset due to power up.
75  */
77  /**
78  * Device has reset due to lowe power exit.
79  */
81  /**
82  * Device has reset due to non-debug-module request.
83  */
84  kDifRstmgrResetInfoNdm = (0x1 << 2),
85  /**
86  * Device has reset due to a peripheral request. This can be an alert
87  * escalation, watchdog or anything else.
88  */
91 
92 /**
93  * Reset Manager software reset available peripherals.
94  */
95 typedef uint32_t dif_rstmgr_peripheral_t;
96 
97 /**
98  * The result of a Reset Manager operation.
99  */
100 typedef enum dif_rstmgr_result {
101  /**
102  * Indicates that the operation succeeded.
103  */
105  /**
106  * Indicates some unspecified failure.
107  */
109  /**
110  * Indicates that some parameter passed into a function failed a
111  * precondition.
112  *
113  * When this value is returned, no hardware operations occurred.
114  */
117 
118 /**
119  * Hardware instantiation parameters for Reset Manager.
120  *
121  * This struct describes information about the underlying hardware that is
122  * not determined until the hardware design is used as part of a top-level
123  * design.
124  */
125 typedef struct dif_rstmgr_params {
126  /**
127  * The base address for the rstmgr hardware registers.
128  */
131 
132 /**
133  * A handle to rstmgr.
134  *
135  * This type should be treated as opaque by users.
136  */
137 typedef struct dif_rstmgr {
138  dif_rstmgr_params_t params;
139 } dif_rstmgr_t;
140 
141 /**
142  * Creates a new handle for Reset Manager.
143  *
144  * This function does not actuate the hardware.
145  *
146  * @param params Hardware instantiation parameters.
147  * @param handle Out param for the initialized handle.
148  * @return The result of the operation.
149  */
152  dif_rstmgr_t *handle);
153 
154 /**
155  * Resets the Reset Manager registers to sane defaults.
156  *
157  * Note that software reset enable registers cannot be cleared once have been
158  * locked.
159  *
160  * @param handle A Reset Manager handle.
161  * @return The result of the operation.
162  */
165 
166 /**
167  * Locks out requested peripheral reset functionality.
168  *
169  * Calling this function when software reset is locked will have no effect
170  * and return `kDifRstmgrOk`.
171  *
172  * @param handle A Reset Manager handle.
173  * @param peripheral Peripheral to lock the reset functionality for.
174  * @return The result of the operation.
175  */
178  dif_rstmgr_peripheral_t peripheral);
179 
180 /**
181  * Checks whether requested peripheral reset functionality is locked.
182  *
183  * @param handle A Reset Manager handle.
184  * @param peripheral Peripheral to check the reset lock for.
185  * @param is_locked Out-param for the locked state.
186  * @return The result of the operation.
187  */
190  const dif_rstmgr_t *handle, dif_rstmgr_peripheral_t peripheral,
191  bool *is_locked);
192 
193 /**
194  * Obtains the complete Reset Manager reset information.
195  *
196  * The reset info are parsed and presented to the caller as an
197  * array of flags in 'info'.
198  *
199  * @param handle A Reset Manager handle.
200  * @param info Reset information.
201  * @return The result of the operation.
202  */
205  const dif_rstmgr_t *handle, dif_rstmgr_reset_info_bitfield_t *info);
206 
207 /**
208  * Clears the reset information in Reset Manager.
209  *
210  * @param handle A Reset Manager handle.
211  * @return `dif_rstmgr_result_t`.
212  * @return The result of the operation.
213  */
216 
217 /**
218  * Enables or disables the alert crash dump capture.
219  *
220  * When enabled, will capture the alert crash dump prior to a triggered reset.
221  *
222  * The alert info crash dump capture is automatically disabled upon system reset
223  * (even if the Reset Manager is not reset).
224  *
225  * @param handle A Reset Manager handle.
226  * @param state The new toggle state for the crash dump capture.
227  * @return The result of the operation.
228  */
231  const dif_rstmgr_t *handle, dif_rstmgr_toggle_t state);
232 
233 /**
234  * Retrieves the alert info crash dump capture state.
235  *
236  * The alert info crash dump capture is automatically disabled upon system reset
237  * (even if the Reset Manager is not reset).
238  *
239  * @param handle A Reset Manager handle.
240  * @param state The state of the crash dump capture.
241  * @return The result of the operation.
242  */
244  const dif_rstmgr_t *handle, dif_rstmgr_toggle_t *state);
245 
246 /**
247  * Alert info crash dump segment.
248  *
249  * The alert info crash dump consists of 32-bit data segments
250  */
252 
253 /**
254  * Reads the entire alert info crash dump.
255  *
256  * The crash dump is always retained after any kind of reset, except on
257  * Power-On-Reset (POR).
258  *
259  * @param handle A Reset Manager handle.
260  * @param dump Alert info crash dump.
261  * @param dump_size Size of the crash dump buffer. The entire crash dump will be
262  * read, and the actual size can be determined through
263  * the `segments_read` parameter.
264  * @param segments_read Number of read segments.
265  *
266  * @return The result of the operation.
267  */
270  const dif_rstmgr_t *handle, dif_rstmgr_alert_info_dump_segment_t *dump,
271  size_t dump_size, size_t *segments_read);
272 
273 /**
274  * The result of a Reset Manager software reset operation.
275  */
277  /**
278  * Indicates that the operation succeeded.
279  */
281  /**
282  * Indicates some unspecified failure.
283  */
285  /**
286  * Indicates that some parameter passed into a function failed a
287  * precondition.
288  *
289  * When this value is returned, no hardware operations occurred.
290  */
292  /**
293  * Indicates that this operation has been locked out, and can never
294  * succeed until hardware reset.
295  */
298 
299 /**
300  * Asserts or de-asserts software reset for the requested peripheral.
301  *
302  * @param handle A Reset Manager handle.
303  * @param peripheral Peripheral to assert/de-assert reset for.
304  * @param reset Reset control.
305  * @return The result of the operation.
306  */
308 dif_rstmgr_software_reset_result_t dif_rstmgr_software_reset(
309  const dif_rstmgr_t *handle, dif_rstmgr_peripheral_t peripheral,
310  dif_rstmgr_software_reset_t reset);
311 
312 /**
313  * Queries whether the requested peripheral is held in reset.
314  *
315  * @param handle A Reset Manager handle.
316  * @param peripheral Peripheral to query.
317  * @param asserted 'true' when held in reset, `false` otherwise.
318  * @return The result of the operation.
319  */
322  const dif_rstmgr_t *handle, dif_rstmgr_peripheral_t peripheral,
323  bool *asserted);
324 
325 #ifdef __cplusplus
326 } // extern "C"
327 #endif // __cplusplus
328 
329 #endif // OPENTITAN_SW_DEVICE_LIB_DIF_DIF_RSTMGR_H_