Software APIs
dif_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#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="/book/hw/top_earlgrey/ip_autogen/rstmgr/">Reset Manager</a>
11 * Device Interface Functions
12 */
13
14#include <stdbool.h>
15#include <stdint.h>
16
17#include "dt/dt_rstmgr.h" // Generated.
21
22#include "sw/device/lib/dif/autogen/dif_rstmgr_autogen.h"
23
24#ifdef __cplusplus
25extern "C" {
26#endif // __cplusplus
27
28/**
29 * The maximal size of the alert crash info dump.
30 *
31 * Note: must match the autogenerated register definition.
32 */
33#define DIF_RSTMGR_ALERT_INFO_MAX_SIZE 0xf
34
35/**
36 * The maximal size of the CPU crash info dump.
37 *
38 * Note: must match the autogenerated register definition.
39 */
40#define DIF_RSTMGR_CPU_INFO_MAX_SIZE 0xf
41
42/**
43 * Reset Manager peripheral software reset control.
44 */
46 /**
47 * Simple reset (release straight away).
48 */
50 kDifRstmgrSoftwareResetHold, /**< Hold peripheral in reset. */
51 kDifRstmgrSoftwareResetRelease, /**< Release peripheral from reset. */
53
54/**
55 * Reset Manager reset information bitfield.
56 */
58
59/**
60 * Reset Manager possible reset information enumeration.
61 *
62 * Invariants are used to extract information encoded in
63 * `dif_rstmgr_reset_info_bitfield_t`, which means that the values must
64 * correspond
65 * to the individual bits (0x1, 0x2, 0x4, ..., 0x80000000).
66 *
67 * Note: these must match the autogenerated register definitions.
68 */
70 /**
71 * Device has reset due to power up.
72 */
74 /**
75 * Device has reset due to low power exit.
76 */
78 /**
79 * Device has reset due to software request.
80 */
82 /**
83 * Device has reset due to a peripheral request. This can be an alert
84 * escalation, watchdog or anything else.
85 */
87#if defined(OPENTITAN_IS_EARLGREY)
88 /**
89 * Device has reset due to the peripheral system reset control request.
90 */
91 kDifRstmgrResetInfoSysRstCtrl = (1 << 3),
92 /**
93 * Device has reset due to watchdog bite.
94 */
95 kDifRstmgrResetInfoWatchdog = (1 << 4),
96#elif defined(OPENTITAN_IS_DARJEELING)
97 /**
98 * Device has reset due to watchdog bite.
99 */
100 kDifRstmgrResetInfoWatchdog = (1 << 3),
101 /**
102 * Device has reset due to an external reset request via soc_proxy.
103 */
104 kDifRstmgrResetInfoExternalRst = (1 << 4),
105#else
106#error "dif_rstmgr does not support this top"
107#endif
108 /**
109 * Device has reset due to power unstable.
110 */
112 /**
113 * Device has reset due to alert escalation.
114 */
116 /**
117 * Device has reset due to non-debug-module request.
118 */
121
122/**
123 * Reset Manager software reset available peripherals.
124 */
125typedef uint32_t dif_rstmgr_peripheral_t;
126
128 /**
129 * A fatal error for regfile integrity.
130 */
132 /**
133 * A fatal error for reset consistency.
134 */
136} dif_rstmgr_fatal_err_type_t;
137
138/**
139 * A set of fatal errors.
140 *
141 * This type is used to read the fatal error codes.
142 */
144
145/**
146 * Resets the Reset Manager registers to sane defaults.
147 *
148 * Note that software reset enable registers cannot be cleared once have been
149 * locked.
150 *
151 * @param handle A Reset Manager handle.
152 * @return The result of the operation.
153 */
156
157/**
158 * Locks out requested peripheral reset functionality.
159 *
160 * Calling this function when software reset is locked will have no effect
161 * and return `kDifOk`.
162 *
163 * @param handle A Reset Manager handle.
164 * @param peripheral Peripheral to lock the reset functionality for.
165 * @return The result of the operation.
166 */
169 dif_rstmgr_peripheral_t peripheral);
170
171/**
172 * Checks whether requested peripheral reset functionality is locked.
173 *
174 * @param handle A Reset Manager handle.
175 * @param peripheral Peripheral to check the reset lock for.
176 * @param is_locked Out-param for the locked state.
177 * @return The result of the operation.
178 */
181 dif_rstmgr_peripheral_t peripheral,
182 bool *is_locked);
183
184/**
185 * Obtains the complete Reset Manager reset information.
186 *
187 * The reset info are parsed and presented to the caller as an
188 * array of flags in 'info'.
189 *
190 * @param handle A Reset Manager handle.
191 * @param info Reset information.
192 * @return The result of the operation.
193 */
197
198/**
199 * Clears the reset information in Reset Manager.
200 *
201 * @param handle A Reset Manager handle.
202 * @return `dif_result_t`.
203 * @return The result of the operation.
204 */
207
208/**
209 * Enables or disables the alert crash dump capture.
210 *
211 * When enabled, will capture the alert crash dump prior to a triggered reset.
212 *
213 * The alert info crash dump capture is automatically disabled upon system reset
214 * (even if the Reset Manager is not reset).
215 *
216 * @param handle A Reset Manager handle.
217 * @param state The new toggle state for the crash dump capture.
218 * @return The result of the operation.
219 */
222 dif_toggle_t state);
223
224/**
225 * Retrieves the alert info crash dump capture state.
226 *
227 * The alert info crash dump capture is automatically disabled upon system reset
228 * (even if the Reset Manager is not reset).
229 *
230 * @param handle A Reset Manager handle.
231 * @param[out] state The state of the crash dump capture.
232 * @return The result of the operation.
233 */
236 dif_toggle_t *state);
237
238/**
239 * Get alert info dump size.
240 *
241 *
242 * @param handle A Reset Manager handle.
243 * @param[out] size The size of the alert info dump in 32 bit words.
244 * @return The result of the operation.
245 */
248 size_t *size);
249
250/**
251 * Alert info crash dump segment.
252 *
253 * The alert info crash dump consists of 32-bit data segments
254 */
256
257/**
258 * Reads the entire alert info crash dump.
259 *
260 * The crash dump is always retained after any kind of reset, except on
261 * Power-On-Reset (POR).
262 *
263 * @param handle A Reset Manager handle.
264 * @param dump Address of buffer where the alert dump will be written.
265 * @param dump_size Size of the alert dump buffer. The entire crash dump will be
266 * read, and the actual size can be determined through the
267 * `segments_read` parameter. It is an error if dump_size is
268 * not large enough.
269 * @param[out] segments_read Number of segments read.
270 *
271 * @return The result of the operation.
272 */
276 size_t dump_size, size_t *segments_read);
277
278/**
279 * Enables or disables the CPU crash dump capture.
280 *
281 * When enabled, will capture the CPU crash dump prior to a triggered reset.
282 *
283 * The CPU info crash dump capture is automatically disabled upon system reset
284 * (even if the Reset Manager is not reset).
285 *
286 * @param handle A Reset Manager handle.
287 * @param state The new toggle state for the CPU crash dump capture.
288 * @return The result of the operation.
289 */
292 dif_toggle_t state);
293
294/**
295 * Retrieves the CPU info crash dump capture state.
296 *
297 * The CPU info crash dump capture is automatically disabled upon system reset
298 * (even if the Reset Manager is not reset).
299 *
300 * @param handle A Reset Manager handle.
301 * @param[out] state The state of the crash dump capture.
302 * @return The result of the operation.
303 */
306 dif_toggle_t *state);
307
308/**
309 * Get cpu info dump size.
310 *
311 *
312 * @param handle A Reset Manager handle.
313 * @param[out] size The size of the cpu info dump in 32 bit words.
314 * @return The result of the operation.
315 */
318 size_t *size);
319
320/**
321 * CPU info crash dump segment.
322 *
323 * The CPU info crash dump consists of 32-bit data segments
324 */
326
327/**
328 * Reads the entire CPU info crash dump.
329 *
330 * The crash dump is always retained after any kind of reset, except on
331 * Power-On-Reset (POR).
332 *
333 * @param handle A Reset Manager handle.
334 * @param dump Address of buffer where the crash dump will be written.
335 * @param dump_size Size of the crash dump buffer. The entire crash dump will
336 * be read, and the actual size can be determined through the
337 * `segments_read` parameter. It is an error if dump_size is
338 * not large enough.
339 * @param[out] segments_read Number of segments read.
340 *
341 * @return The result of the operation.
342 */
346 size_t dump_size, size_t *segments_read);
347
348/**
349 * Asserts or de-asserts software reset for the requested peripheral.
350 *
351 * @param handle A Reset Manager handle.
352 * @param peripheral Peripheral to assert/de-assert reset for.
353 * @param reset Reset control.
354 * @return The result of the operation.
355 */
358 dif_rstmgr_peripheral_t peripheral,
360
361/**
362 * Queries whether the requested peripheral is held in reset.
363 *
364 * @param handle A Reset Manager handle.
365 * @param peripheral Peripheral to query.
366 * @param asserted 'true' when held in reset, `false` otherwise.
367 * @return The result of the operation.
368 */
371 const dif_rstmgr_t *handle, dif_rstmgr_peripheral_t peripheral,
372 bool *asserted);
373
374/**
375 * Software request for system reset
376 *
377 * @param handle A Reset Manager handle.
378 * @return The result of the operation.
379 */
382
383/**
384 * Get the software reset index corresponding to a given DT rstmgr reset.
385 *
386 * Retrieved via a short linear search, due to the small number of sw resets.
387 *
388 * @param dt The rstmgr DT instance index
389 * @param reset The rstmgr DT reset index.
390 * @param[out] sw_rst_idx The corresponding software reset index.
391 * @return The result of the operation.
392 */
395 size_t *sw_rst_idx);
396
397/**
398 * Read the fatal error codes.
399 *
400 * @param rstmgr Reset Manager Handle.
401 * @param[out] codes The fatal error codes.
402 * @returns The result of the operation.
403 */
406 const dif_rstmgr_t *rstmgr, dif_rstmgr_fatal_err_codes_t *codes);
407
408#ifdef __cplusplus
409} // extern "C"
410#endif // __cplusplus
411
412#endif // OPENTITAN_SW_DEVICE_LIB_DIF_DIF_RSTMGR_H_