mirror of https://github.com/ARMmbed/mbed-os.git
Add Watchdog HAL API specification headers
HAL watchdog functionality will be implemented as two separate APIs. The reset reason API allows a user to detect the last system reset reason to identify if a Watchdog was triggered. The Watchdog API allows configuring and updating Watchdog timers on all boards. This commit defines the headers.pull/10657/head
Steven Cartmell
Filip Jagodzinski
parent
c4cc9c4f1b
commit
7fe3a387e3
|
|
@ -0,0 +1,71 @@
|
|||
/** \addtogroup hal */
|
||||
/** @{*/
|
||||
/* mbed Microcontroller Library
|
||||
* Copyright (c) 2017 ARM Limited
|
||||
*
|
||||
* Licensed under the Apache License, Version 2.0 (the "License");
|
||||
* you may not use this file except in compliance with the License.
|
||||
* You may obtain a copy of the License at
|
||||
*
|
||||
* http://www.apache.org/licenses/LICENSE-2.0
|
||||
*
|
||||
* Unless required by applicable law or agreed to in writing, software
|
||||
* distributed under the License is distributed on an "AS IS" BASIS,
|
||||
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||||
* See the License for the specific language governing permissions and
|
||||
* limitations under the License.
|
||||
*/
|
||||
#ifndef MBED_RESET_REASON_API_H
|
||||
#define MBED_RESET_REASON_API_H
|
||||
|
||||
#if DEVICE_RESET_REASON
|
||||
|
||||
#ifdef __cplusplus
|
||||
extern "C" {
|
||||
#endif
|
||||
|
||||
typedef enum {
|
||||
RESET_REASON_POWER_ON = (1 << 0), /**< Set when power is initially applied to the board. The power-on-reset circuit causes a POWER_ON reset when this occurs */
|
||||
RESET_REASON_PIN_RESET = (1 << 1), /**< Set when a reset is triggered by the hardware pin on the board */
|
||||
RESET_REASON_BROWN_OUT = (1 << 2), /**< Triggered when the voltage drops below the low voltage detect (LVD) threshold the system will be held in a reset until the voltage rises above the threshold */
|
||||
RESET_REASON_SOFTWARE = (1 << 3), /**< Set during software reset, typically triggered by writing the SYSRESETREQ bit in the Application Interrupt and Reset Control register */
|
||||
RESET_REASON_WATCHDOG = (1 << 4), /**< Set when a running watchdog timer fails to be refreshed */
|
||||
RESET_REASON_LOCKUP = (1 << 5), /**< Set when the core is locked because of an unrecoverable exception */
|
||||
RESET_REASON_MULTIPLE = (1 << 6), /**< Set if multiple reset reasons are set within the board. Occurs when the reset reason registers aren't cleared between resets */
|
||||
RESET_REASON_PLATFORM = (1 << 7), /**< Platform specific reset reason not captured in this enum */
|
||||
RESET_REASON_UNKNOWN = (1 << 8) /**< Unknown or unreadable reset reason **/
|
||||
} reset_reason_t;
|
||||
|
||||
/**
|
||||
* Fetch the reset reason for the last system reset
|
||||
*
|
||||
* Note: Some platforms contain reset reason registers that persist through
|
||||
* system resets. If the registers haven't been cleared before calling this
|
||||
* function multiple reasons may be set within the registers. If multiple reset
|
||||
* reasons are detected this function will return RESET_REASON_MULTIPLE.
|
||||
*
|
||||
* @return enum containing the last reset reason for the board.
|
||||
*/
|
||||
reset_reason_t hal_reset_reason_get(void);
|
||||
|
||||
/**
|
||||
* Clear the reset reason from registers
|
||||
*
|
||||
* Reset the value of the reset status registers, the reset reason will persist
|
||||
* between system resets on certain platforms so the registers should be cleared
|
||||
* before the system resets. Failing to do so may make it difficult to determine
|
||||
* the cause of any subsequent system resets.
|
||||
*/
|
||||
void hal_reset_reason_clear(void);
|
||||
|
||||
/**@}*/
|
||||
|
||||
#ifdef __cplusplus
|
||||
}
|
||||
#endif
|
||||
|
||||
#endif // DEVICE_RESET_REASON
|
||||
|
||||
#endif // MBED_RESET_REASON_API_H
|
||||
|
||||
/** @}*/
|
||||
|
|
@ -0,0 +1,167 @@
|
|||
/** \addtogroup hal */
|
||||
/** @{*/
|
||||
/* mbed Microcontroller Library
|
||||
* Copyright (c) 2017 ARM Limited
|
||||
*
|
||||
* Licensed under the Apache License, Version 2.0 (the "License");
|
||||
* you may not use this file except in compliance with the License.
|
||||
* You may obtain a copy of the License at
|
||||
*
|
||||
* http://www.apache.org/licenses/LICENSE-2.0
|
||||
*
|
||||
* Unless required by applicable law or agreed to in writing, software
|
||||
* distributed under the License is distributed on an "AS IS" BASIS,
|
||||
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||||
* See the License for the specific language governing permissions and
|
||||
* limitations under the License.
|
||||
*/
|
||||
|
||||
#ifndef MBED_WATCHDOG_API_H
|
||||
#define MBED_WATCHDOG_API_H
|
||||
|
||||
#if DEVICE_WATCHDOG
|
||||
|
||||
#include <stdbool.h>
|
||||
#include <stdint.h>
|
||||
|
||||
/** \file watchdog_api.h
|
||||
*
|
||||
* This module provides platform independent access to the system watchdog timer
|
||||
* which is an embedded peripheral that will reset the system in the case of
|
||||
* system failures or malfunctions.
|
||||
*
|
||||
* The watchdog timer initialises a system timer with a time period specified in
|
||||
* the configuration. This timer counts down and triggers a system reset when it
|
||||
* wraps. To prevent the system reset the timer must be continually
|
||||
* kicked/refreshed by calling hal_watchdog_kick which will reset the countdown
|
||||
* to the user specified reset value.
|
||||
*
|
||||
* The watchdog timer supports a second mode of operation called windowed mode.
|
||||
* When configured in this mode by setting enable_window to true, the timer
|
||||
* watchdog will enable a restriction on the kick. If the watchdog timer too
|
||||
* soon after it has last been refreshed a system reset occurs. The earliest
|
||||
* time in milliseconds the timer can be kicked without triggering a reset is
|
||||
* specified by window_ms.
|
||||
*
|
||||
*/
|
||||
|
||||
typedef struct
|
||||
{
|
||||
/**
|
||||
* Refresh value for the watchdog in milliseconds. The maximum value of this
|
||||
* setting is platform dependent, to find the maximum value for the current
|
||||
* platform call hal_watchdog_get_max_timeout(void)
|
||||
*/
|
||||
uint32_t timeout_ms;
|
||||
/**
|
||||
* Configures the watchdog for windowed mode of operation instead of running
|
||||
* the independent watchdog. In this mode a restriction is placed on the
|
||||
* time period in which the watchdog can be refreshed/kicked. If the
|
||||
* watchdog is kicked too soon after it has last been refreshed the system
|
||||
* will be reset. The period of time in which the reset will be triggered is
|
||||
* defined by window_ms. This value is false by default.
|
||||
*/
|
||||
bool enable_window;
|
||||
/**
|
||||
* Specifies the time window for the watchdog window in milliseconds. If the
|
||||
* watchdog is configured to run in windowed mode kicking the watchdog less
|
||||
* than this many milliseconds after it has last been kicked will trigger a
|
||||
* system reset. This value must be less than timeout_ms.
|
||||
*/
|
||||
uint32_t window_ms;
|
||||
/**
|
||||
* Configures the watchdog timer to run while the core is in sleep mode. By
|
||||
* default when the system is put into the sleep the watchdog timer is paused.
|
||||
* Enabling this setting causes the timer to countdown during this time. This
|
||||
* flag is disabled by default.
|
||||
*/
|
||||
bool enable_sleep;
|
||||
} watchdog_config_t;
|
||||
|
||||
|
||||
typedef enum {
|
||||
WATCHDOG_STATUS_OK,
|
||||
WATCHDOG_STATUS_NOT_SUPPORTED,
|
||||
WATCHDOG_STATUS_INVALID_ARGUMENT
|
||||
} watchdog_status_t;
|
||||
|
||||
#ifdef __cplusplus
|
||||
extern "C" {
|
||||
#endif
|
||||
|
||||
/** Initialise and start a watchdog timer with the given configuration.
|
||||
*
|
||||
* If the watchdog timer is configured and started successfully this
|
||||
* function will return WATCHDOG_STATUS_OK.
|
||||
*
|
||||
* If the enable_window is set but windowed mode is not supported by the
|
||||
* platform the function will return WATCHDOG_STATUS_NOT_SUPPORTED.
|
||||
*
|
||||
* If the timeout specified is outside the range supported by the platform,
|
||||
* or if the window period is greater than the timeout period it will return
|
||||
* WATCHDOG_STATUS_INVALID_ARGUMENT.
|
||||
*
|
||||
* @param[in] config Configuration settings for the watchdog timer
|
||||
*
|
||||
* @return WATCHDOG_STATUS_OK if the watchdog is configured correctly and
|
||||
* has started. Otherwise a status indicating the fault.
|
||||
*/
|
||||
watchdog_status_t hal_watchdog_init(const watchdog_config_t *config);
|
||||
|
||||
/** Refreshes the watchdog timer.
|
||||
*
|
||||
* This function should be called periodically before the watchdog times out.
|
||||
* Otherwise, the system is reset.
|
||||
*
|
||||
* If using the windowed operation mode this function must be called within the
|
||||
* configured timeout window. If the function is called before the window is
|
||||
* reached the system is reset.
|
||||
*
|
||||
* If a watchdog is not currently running this function does nothing
|
||||
*/
|
||||
void hal_watchdog_kick(void);
|
||||
|
||||
/** Stops the watchdog timer
|
||||
*
|
||||
* Calling this function will attempt to disable any currently running watchdog
|
||||
* timers if supported by the current platform
|
||||
*
|
||||
* @return Returns WATCHDOG_STATUS_OK if the watchdog timer was succesfully
|
||||
* stopped, or if the timer was never started. Returns
|
||||
* WATCHDOG_STATUS_NOT_SUPPORTED if the watchdog cannot be disabled on
|
||||
* the current platform.
|
||||
*/
|
||||
watchdog_status_t hal_watchdog_stop(void);
|
||||
|
||||
/** Get the watchdog timer refresh value
|
||||
*
|
||||
* This function returns the configured refresh timeout of the watchdog timer.
|
||||
*
|
||||
* @return Reload value for the watchdog timer in milliseconds.
|
||||
*/
|
||||
uint32_t hal_watchdog_get_reload_value(void);
|
||||
|
||||
/** Checks if the last system reset was caused by a watchdog timer.
|
||||
*
|
||||
* @return True if last reset was triggered by a watchdog, False if not.
|
||||
*/
|
||||
bool hal_watchdog_caused_last_reset(void);
|
||||
|
||||
/** Get the maximum refresh value for the current platform in milliseconds
|
||||
*
|
||||
* @return Maximum refresh value supported by the watchdog for the current
|
||||
* platform in milliseconds
|
||||
*/
|
||||
uint32_t hal_watchdog_get_max_timeout(void);
|
||||
|
||||
/**@}*/
|
||||
|
||||
#ifdef __cplusplus
|
||||
}
|
||||
#endif
|
||||
|
||||
#endif // DEVICE_WATCHDOG
|
||||
|
||||
#endif // MBED_WATCHDOG_API_H
|
||||
|
||||
/** @}*/
|
||||
Loading…
Reference in New Issue