reset_reason_api.h

00001 /** \addtogroup hal */
00002 /** @{*/
00003 /*
00004  * Copyright (c) 2018-2019 Arm Limited and affiliates.
00005  * SPDX-License-Identifier: Apache-2.0
00006  *
00007  * Licensed under the Apache License, Version 2.0 (the "License");
00008  * you may not use this file except in compliance with the License.
00009  * You may obtain a copy of the License at
00010  *
00011  *     http://www.apache.org/licenses/LICENSE-2.0
00012  *
00013  * Unless required by applicable law or agreed to in writing, software
00014  * distributed under the License is distributed on an "AS IS" BASIS,
00015  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00016  * See the License for the specific language governing permissions and
00017  * limitations under the License.
00018  */
00019 #ifndef MBED_RESET_REASON_API_H
00020 #define MBED_RESET_REASON_API_H
00021 
00022 #if DEVICE_RESET_REASON
00023 
00024 #include <stdint.h>
00025 
00026 #ifdef __cplusplus
00027 extern "C" {
00028 #endif
00029 
00030 /**
00031  * \defgroup hal_reset_reason ResetReason HAL API
00032  * Low-level interface to the ResetReason of a target.
00033  *
00034  * This module provides a platform-independent method of checking the cause
00035  * of the last system reset.
00036  *
00037  * # Defined behavior
00038  * * The function ::hal_reset_reason_clear clears the ResetReason registers
00039  * for the next system boot.
00040  * * By the time the user calls ::hal_reset_reason_get to read the value,
00041  * some other part of the application may have cleared the value. Therefore,
00042  * though there may have been a reset reason in the registers when the system
00043  * started, the reason may not be available when the user comes to check it.
00044  *
00045  * # Undefined behavior
00046  * * There is no guarantee that the function ::hal_reset_reason_get will
00047  * return the same value when you call it repeatedly. Store the value for later
00048  * use instead of calling the function repeatedly.
00049  * * The function ::hal_reset_reason_clear may not clear the ResetReason
00050  * register in time for the next system boot.
00051  *
00052  * # Notes
00053  * * The contents of the targets ResetReason register may be cleared by some
00054  * subsystem before it first gets called. This returns a ::RESET_REASON_UNKNOWN
00055  * value to the user. To avoid this, the user should call the ResetReason API
00056  * as early as possible at boot time.
00057  * * If the target doesn't support clearing reset registers,
00058  * ::hal_reset_reason_get seems to erroneously return a reset reason even after
00059  * clearing.
00060  *
00061  * @{
00062  */
00063 
00064 /**
00065  * \defgroup hal_reset_reason_tests ResetReason HAL tests
00066  * Greentea tests for the ResetReason HAL.
00067  *
00068  * To run the ResetReason HAL tests, use the command:
00069  *
00070  *     mbed test -t <toolchain> -m <target> -n tests-mbed_hal-reset_reason
00071  *
00072  */
00073 
00074 /** Definitions of different reset reasons
00075  */
00076 typedef enum {
00077     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 */
00078     RESET_REASON_PIN_RESET,      /**< Set when a reset is triggered by the hardware pin on the board */
00079     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 */
00080     RESET_REASON_SOFTWARE,       /**< Set during software reset, typically triggered by writing the SYSRESETREQ bit in the Application Interrupt and Reset Control register */
00081     RESET_REASON_WATCHDOG,       /**< Set when a running watchdog timer fails to be refreshed */
00082     RESET_REASON_LOCKUP,         /**< Set when the core is locked because of an unrecoverable exception */
00083     RESET_REASON_WAKE_LOW_POWER, /**< Set when waking from deep sleep mode */
00084     RESET_REASON_ACCESS_ERROR,   /**< Umbrella value that encompasses any access related reset */
00085     RESET_REASON_BOOT_ERROR,     /**< Umbrella value that encompasses any boot related reset */
00086     RESET_REASON_MULTIPLE,       /**< Set if multiple reset reasons are set within the board. Occurs when the reset reason registers aren't cleared between resets */
00087     RESET_REASON_PLATFORM,       /**< Platform specific reset reason not captured in this enum */
00088     RESET_REASON_UNKNOWN         /**< Unknown or unreadable reset reason **/
00089 } reset_reason_t;
00090 
00091 /** Fetch the reset reason for the last system reset.
00092  *
00093  * This function must return the contents of the system reset reason registers
00094  * cast to an appropriate platform independent reset reason. If multiple reset
00095  * reasons are set, this function should return ::RESET_REASON_MULTIPLE. If the
00096  * reset reason does not match any existing platform independent value, this
00097  * function should return ::RESET_REASON_PLATFORM. If no reset reason can be
00098  * determined, this function should return ::RESET_REASON_UNKNOWN.
00099  *
00100  * This function is not idempotent; there is no guarantee the system
00101  * reset reason will not be cleared between calls to this function altering the
00102  * return value between calls.
00103  *
00104  * Note: Some platforms contain reset reason registers that persist through
00105  * system resets. If the registers haven't been cleared before calling this
00106  * function, multiple reasons may be set within the registers. If multiple reset
00107  * reasons are detected, this function returns ::RESET_REASON_MULTIPLE.
00108  *
00109  * @return enum containing the last reset reason for the board.
00110  */
00111 reset_reason_t hal_reset_reason_get(void);
00112 
00113 
00114 /** Fetch the raw platform specific reset reason register value.
00115  *
00116  * This function must return the raw contents of the system reset reason
00117  * registers cast to a uint32_t value. If the platform contains reset reasons
00118  * that span multiple registers/addresses, the value should be concatenated into
00119  * the return type.
00120  *
00121  * This function is not idempotent; there is no guarantee the system
00122  * reset reason will not be cleared between calls to this function altering the
00123  * return value between calls.
00124  *
00125  * @return value containing the reset reason register for the given platform.
00126  *         If the platform contains reset reasons across multiple registers, they
00127  *         will be concatenated here.
00128  */
00129 uint32_t hal_reset_reason_get_raw(void);
00130 
00131 /** Clear the reset reason from registers.
00132  *
00133  * Reset the value of the reset status registers. The reset reason persists
00134  * between system resets on certain platforms, so the registers should be cleared
00135  * before the system resets. Failing to do so may make it difficult to determine
00136  * the cause of any subsequent system resets.
00137  */
00138 void hal_reset_reason_clear(void);
00139 
00140 /**@}*/
00141 
00142 #ifdef __cplusplus
00143 }
00144 #endif
00145 
00146 #endif // DEVICE_RESET_REASON
00147 
00148 #endif // MBED_RESET_REASON_API_H
00149 
00150 /** @}*/