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  *
45  * # Undefined behavior
46  * * There is no guarantee that the function ::hal_reset_reason_get will
47  * return the same value when you call it repeatedly. Store the value for later
48  * use instead of calling the function repeatedly.
49  * * The function ::hal_reset_reason_clear may not clear the ResetReason
50  * register in time for the next system boot.
51  *
52  * # Notes
53  * * The contents of the targets ResetReason register may be cleared by some
54  * subsystem before it first gets called. This returns a ::RESET_REASON_UNKNOWN
55  * value to the user. To avoid this, the user should call the ResetReason API
56  * as early as possible at boot time.
57  * * If the target doesn't support clearing reset registers,
58  * ::hal_reset_reason_get seems to erroneously return a reset reason even after
59  * clearing.
60  *
61  * @{
62  */
63 
64 /**
65  * \defgroup hal_reset_reason_tests ResetReason HAL tests
66  * Greentea tests for the ResetReason HAL.
67  *
68  * To run the ResetReason HAL tests, use the command:
69  *
70  * mbed test -t <toolchain> -m <target> -n tests-mbed_hal-reset_reason
71  *
72  */
73 
74 /** Definitions of different reset reasons
75  */
76 typedef enum {
77  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 */
78  RESET_REASON_PIN_RESET, /**< Set when a reset is triggered by the hardware pin on the board */
79  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 */
80  RESET_REASON_SOFTWARE, /**< Set during software reset, typically triggered by writing the SYSRESETREQ bit in the Application Interrupt and Reset Control register */
81  RESET_REASON_WATCHDOG, /**< Set when a running watchdog timer fails to be refreshed */
82  RESET_REASON_LOCKUP, /**< Set when the core is locked because of an unrecoverable exception */
83  RESET_REASON_WAKE_LOW_POWER, /**< Set when waking from deep sleep mode */
84  RESET_REASON_ACCESS_ERROR, /**< Umbrella value that encompasses any access related reset */
85  RESET_REASON_BOOT_ERROR, /**< Umbrella value that encompasses any boot related reset */
86  RESET_REASON_MULTIPLE, /**< Set if multiple reset reasons are set within the board. Occurs when the reset reason registers aren't cleared between resets */
87  RESET_REASON_PLATFORM, /**< Platform specific reset reason not captured in this enum */
88  RESET_REASON_UNKNOWN /**< Unknown or unreadable reset reason **/
89 } reset_reason_t;
90 
91 /** Fetch the reset reason for the last system reset.
92  *
93  * This function must return the contents of the system reset reason registers
94  * cast to an appropriate platform independent reset reason. If multiple reset
95  * reasons are set, this function should return ::RESET_REASON_MULTIPLE. If the
96  * reset reason does not match any existing platform independent value, this
97  * function should return ::RESET_REASON_PLATFORM. If no reset reason can be
98  * determined, this function should return ::RESET_REASON_UNKNOWN.
99  *
100  * This function is not idempotent; there is no guarantee the system
101  * reset reason will not be cleared between calls to this function altering the
102  * return value between calls.
103  *
104  * Note: Some platforms contain reset reason registers that persist through
105  * system resets. If the registers haven't been cleared before calling this
106  * function, multiple reasons may be set within the registers. If multiple reset
107  * reasons are detected, this function returns ::RESET_REASON_MULTIPLE.
108  *
109  * @return enum containing the last reset reason for the board.
110  */
111 reset_reason_t hal_reset_reason_get(void);
112 
113 
114 /** Fetch the raw platform specific reset reason register value.
115  *
116  * This function must return the raw contents of the system reset reason
117  * registers cast to a uint32_t value. If the platform contains reset reasons
118  * that span multiple registers/addresses, the value should be concatenated into
119  * the return type.
120  *
121  * This function is not idempotent; there is no guarantee the system
122  * reset reason will not be cleared between calls to this function altering the
123  * return value between calls.
124  *
125  * @return value containing the reset reason register for the given platform.
126  * If the platform contains reset reasons across multiple registers, they
127  * will be concatenated here.
128  */
129 uint32_t hal_reset_reason_get_raw(void);
130 
131 /** Clear the reset reason from registers.
132  *
133  * Reset the value of the reset status registers. The reset reason persists
134  * between system resets on certain platforms, so the registers should be cleared
135  * before the system resets. Failing to do so may make it difficult to determine
136  * the cause of any subsequent system resets.
137  */
138 void hal_reset_reason_clear(void);
139 
140 /**@}*/
141 
142 #ifdef __cplusplus
143 }
144 #endif
145 
146 #endif // DEVICE_RESET_REASON
147 
148 #endif // MBED_RESET_REASON_API_H
149 
150 /** @}*/
RESET_REASON_BOOT_ERROR
Umbrella value that encompasses any boot related reset.
Definition: reset_reason_api.h:85
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:88
RESET_REASON_WAKE_LOW_POWER
Set when waking from deep sleep mode.
Definition: reset_reason_api.h:83
RESET_REASON_PIN_RESET
Set when a reset is triggered by the hardware pin on the board.
Definition: reset_reason_api.h:78
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:79
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:81
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:82
RESET_REASON_POWER_ON
Set when power is initially applied to the board.
Definition: reset_reason_api.h:77
RESET_REASON_ACCESS_ERROR
Umbrella value that encompasses any access related reset.
Definition: reset_reason_api.h:84
RESET_REASON_PLATFORM
Platform specific reset reason not captured in this enum.
Definition: reset_reason_api.h:87
RESET_REASON_SOFTWARE
Set during software reset, typically triggered by writing the SYSRESETREQ bit in the Application Inte...
Definition: reset_reason_api.h:80
RESET_REASON_MULTIPLE
Set if multiple reset reasons are set within the board.
Definition: reset_reason_api.h:86
reset_reason_t
reset_reason_t
Definitions of different reset reasons.
Definition: reset_reason_api.h:76
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.