Keil Studio Cloud
Mistake on this page?
Report an issue in GitHub or email us
reset_reason_api.h
1 /** \addtogroup hal */
2 /** @{*/
3 /*
4  * Copyright (c) 2018-2019 Arm Limited and affiliates.
5  * SPDX-License-Identifier: Apache-2.0
6  *
7  * Licensed under the Apache License, Version 2.0 (the "License");
8  * you may not use this file except in compliance with the License.
9  * You may obtain a copy of the License at
10  *
11  * http://www.apache.org/licenses/LICENSE-2.0
12  *
13  * Unless required by applicable law or agreed to in writing, software
14  * distributed under the License is distributed on an "AS IS" BASIS,
15  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16  * See the License for the specific language governing permissions and
17  * limitations under the License.
18  */
19 #ifndef MBED_RESET_REASON_API_H
20 #define MBED_RESET_REASON_API_H
21 
22 #if DEVICE_RESET_REASON
23 
24 #include <stdint.h>
25 
26 #ifdef __cplusplus
27 extern "C" {
28 #endif
29 
30 /**
31  * \defgroup hal_reset_reason ResetReason HAL API
32  * Low-level interface to the ResetReason of a target.
33  *
34  * This module provides a platform-independent method of checking the cause
35  * of the last system reset.
36  *
37  * # Defined behavior
38  * * The function ::hal_reset_reason_clear clears the ResetReason registers
39  * for the next system boot.
40  * * By the time the user calls ::hal_reset_reason_get to read the value,
41  * some other part of the application may have cleared the value. Therefore,
42  * though there may have been a reset reason in the registers when the system
43  * started, the reason may not be available when the user comes to check it.
44  * * The function ::hal_reset_reason_get_capabilities fills the given
45  * `reset_reason_capabilities_t` instance.
46  *
47  * # Undefined behavior
48  * * There is no guarantee that the function ::hal_reset_reason_get will
49  * return the same value when you call it repeatedly. Store the value for later
50  * use instead of calling the function repeatedly.
51  * * The function ::hal_reset_reason_clear may not clear the ResetReason
52  * register in time for the next system boot.
53  *
54  * # Notes
55  * * The contents of the targets ResetReason register may be cleared by some
56  * subsystem before it first gets called. This returns a ::RESET_REASON_UNKNOWN
57  * value to the user. To avoid this, the user should call the ResetReason API
58  * as early as possible at boot time.
59  * * If the target doesn't support clearing reset registers,
60  * ::hal_reset_reason_get seems to erroneously return a reset reason even after
61  * clearing.
62  *
63  * @{
64  */
65 
66 /**
67  * \defgroup hal_reset_reason_tests ResetReason HAL tests
68  * Greentea tests for the ResetReason HAL.
69  *
70  * To run the ResetReason HAL tests, use the command:
71  *
72  * mbed test -t <toolchain> -m <target> -n tests-mbed_hal-reset_reason
73  *
74  */
75 
76 /** Definitions of different reset reasons
77  */
78 typedef enum {
79  RESET_REASON_POWER_ON, /**< Set when power is initially applied to the board. The power-on-reset circuit causes a POWER_ON reset when this occurs */
80  RESET_REASON_PIN_RESET, /**< Set when a reset is triggered by the hardware pin on the board */
81  RESET_REASON_BROWN_OUT, /**< Triggered when the voltage drops below the low voltage detect (LVD) threshold; the system is held in a reset until the voltage rises above the threshold */
82  RESET_REASON_SOFTWARE, /**< Set during software reset, typically triggered by writing the SYSRESETREQ bit in the Application Interrupt and Reset Control register */
83  RESET_REASON_WATCHDOG, /**< Set when a running watchdog timer fails to be refreshed */
84  RESET_REASON_LOCKUP, /**< Set when the core is locked because of an unrecoverable exception */
85  RESET_REASON_WAKE_LOW_POWER, /**< Set when waking from deep sleep mode */
86  RESET_REASON_ACCESS_ERROR, /**< Umbrella value that encompasses any access related reset */
87  RESET_REASON_BOOT_ERROR, /**< Umbrella value that encompasses any boot related reset */
88  RESET_REASON_MULTIPLE, /**< Set if multiple reset reasons are set within the board. Occurs when the reset reason registers aren't cleared between resets */
89  RESET_REASON_PLATFORM, /**< Platform specific reset reason not captured in this enum */
90  RESET_REASON_UNKNOWN /**< Unknown or unreadable reset reason **/
91 } reset_reason_t;
92 
93 /** Reset reason capabilities of the platform
94  */
95 typedef struct {
96  uint32_t reasons; /**< Supported reset reasons. Each bit represents a corresponding reset_reason_t value.**/
97 } reset_reason_capabilities_t;
98 
99 /** Fetch the reset reason for the last system reset.
100  *
101  * This function must return the contents of the system reset reason registers
102  * cast to an appropriate platform independent reset reason. If multiple reset
103  * reasons are set, this function should return ::RESET_REASON_MULTIPLE. If the
104  * reset reason does not match any existing platform independent value, this
105  * function should return ::RESET_REASON_PLATFORM. If no reset reason can be
106  * determined, this function should return ::RESET_REASON_UNKNOWN.
107  *
108  * This function is not idempotent; there is no guarantee the system
109  * reset reason will not be cleared between calls to this function altering the
110  * return value between calls.
111  *
112  * Note: Some platforms contain reset reason registers that persist through
113  * system resets. If the registers haven't been cleared before calling this
114  * function, multiple reasons may be set within the registers. If multiple reset
115  * reasons are detected, this function returns ::RESET_REASON_MULTIPLE.
116  *
117  * @return enum containing the last reset reason for the board.
118  */
119 reset_reason_t hal_reset_reason_get(void);
120 
121 
122 /** Fetch the raw platform specific reset reason register value.
123  *
124  * This function must return the raw contents of the system reset reason
125  * registers cast to a uint32_t value. If the platform contains reset reasons
126  * that span multiple registers/addresses, the value should be concatenated into
127  * the return type.
128  *
129  * This function is not idempotent; there is no guarantee the system
130  * reset reason will not be cleared between calls to this function altering the
131  * return value between calls.
132  *
133  * @return value containing the reset reason register for the given platform.
134  * If the platform contains reset reasons across multiple registers, they
135  * will be concatenated here.
136  */
137 uint32_t hal_reset_reason_get_raw(void);
138 
139 /** Clear the reset reason from registers.
140  *
141  * Reset the value of the reset status registers. The reset reason persists
142  * between system resets on certain platforms, so the registers should be cleared
143  * before the system resets. Failing to do so may make it difficult to determine
144  * the cause of any subsequent system resets.
145  */
146 void hal_reset_reason_clear(void);
147 
148 /** Fill the given reset_reason_capabilities_t instance according to platform capabilities.
149  */
150 void hal_reset_reason_get_capabilities(reset_reason_capabilities_t *cap);
151 
152 /**@}*/
153 
154 #ifdef __cplusplus
155 }
156 #endif
157 
158 #endif // DEVICE_RESET_REASON
159 
160 #endif // MBED_RESET_REASON_API_H
161 
162 /** @}*/
RESET_REASON_BOOT_ERROR
Umbrella value that encompasses any boot related reset.
Definition: reset_reason_api.h:87
hal_reset_reason_get
reset_reason_t hal_reset_reason_get(void)
Fetch the reset reason for the last system reset.
RESET_REASON_UNKNOWN
Unknown or unreadable reset reason.
Definition: reset_reason_api.h:90
RESET_REASON_WAKE_LOW_POWER
Set when waking from deep sleep mode.
Definition: reset_reason_api.h:85
RESET_REASON_PIN_RESET
Set when a reset is triggered by the hardware pin on the board.
Definition: reset_reason_api.h:80
RESET_REASON_BROWN_OUT
Triggered when the voltage drops below the low voltage detect (LVD) threshold; the system is held in ...
Definition: reset_reason_api.h:81
hal_reset_reason_get_raw
uint32_t hal_reset_reason_get_raw(void)
Fetch the raw platform specific reset reason register value.
RESET_REASON_WATCHDOG
Set when a running watchdog timer fails to be refreshed.
Definition: reset_reason_api.h:83
hal_reset_reason_get_capabilities
void hal_reset_reason_get_capabilities(reset_reason_capabilities_t *cap)
Fill the given reset_reason_capabilities_t instance according to platform capabilities.
reset_reason_capabilities_t::reasons
uint32_t reasons
Supported reset reasons.
Definition: reset_reason_api.h:96
hal_reset_reason_clear
void hal_reset_reason_clear(void)
Clear the reset reason from registers.
RESET_REASON_LOCKUP
Set when the core is locked because of an unrecoverable exception.
Definition: reset_reason_api.h:84
RESET_REASON_POWER_ON
Set when power is initially applied to the board.
Definition: reset_reason_api.h:79
RESET_REASON_ACCESS_ERROR
Umbrella value that encompasses any access related reset.
Definition: reset_reason_api.h:86
RESET_REASON_PLATFORM
Platform specific reset reason not captured in this enum.
Definition: reset_reason_api.h:89
reset_reason_capabilities_t
Reset reason capabilities of the platform.
Definition: reset_reason_api.h:95
RESET_REASON_SOFTWARE
Set during software reset, typically triggered by writing the SYSRESETREQ bit in the Application Inte...
Definition: reset_reason_api.h:82
RESET_REASON_MULTIPLE
Set if multiple reset reasons are set within the board.
Definition: reset_reason_api.h:88
reset_reason_t
reset_reason_t
Definitions of different reset reasons.
Definition: reset_reason_api.h:78
Important Information for this Arm website

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies. If you are not happy with the use of these cookies, please review our Cookie Policy to learn how they can be disabled. By disabling cookies, some features of the site will not work.