/** * @file rtems/score/watchdog.h * * This include file contains all the constants and structures associated * with watchdog timers. This Handler provides mechanisms which can be * used to initialize and manipulate watchdog timers. */ /* * COPYRIGHT (c) 1989-2009. * On-Line Applications Research Corporation (OAR). * * The license and distribution terms for this file may be * found in the file LICENSE in this distribution or at * http://www.rtems.com/license/LICENSE. * * $Id$ */ #ifndef _RTEMS_SCORE_WATCHDOG_H #define _RTEMS_SCORE_WATCHDOG_H /** * @defgroup ScoreWatchdog Watchdog Handler * * @ingroup Score * * This handler encapsulates functionality related to the scheduling of * watchdog functions to be called at specific times in the future. * * @note This handler does not have anything to do with hardware watchdog * timers. */ /**@{*/ #include #ifdef __cplusplus extern "C" { #endif /** * @brief Maximum Interval Length * * The following type defines the control block used to manage * intervals. */ #define WATCHDOG_MAXIMUM_INTERVAL ((Watchdog_Interval) 0xffffffff) /** * @brief Watchdog Interval Type * * This type is used to specify the length of intervals. */ typedef uint32_t Watchdog_Interval; /** * @brief Watchdog Nanoseconds Since Last Tick Extension * * This type defines a pointer to the BSP plugin to obtain the number * of nanoseconds since the last clock tick. */ typedef uint32_t (*Watchdog_Nanoseconds_since_last_tick_routine)(void); /** * @brief Watchdog Service Routine Return Type * * This type defines the return type from a Watchdog Service Routine. */ typedef void Watchdog_Service_routine; /** * @brief Watchdog Service Routine Pointer Type * * This type define a pointer to a watchdog service routine. */ typedef Watchdog_Service_routine ( *Watchdog_Service_routine_entry )( Objects_Id, void * ); /** * @brief No timeout constant * * This is the constant for indefinite wait. It is actually an * illegal interval. */ #define WATCHDOG_NO_TIMEOUT 0 /** * @brief Watchdog States Type * * This enumerated type is the set of the states in which a * watchdog timer may be at any given time. */ typedef enum { /** This is the state when the watchdog is off all chains */ WATCHDOG_INACTIVE, /** This is the state when the watchdog is off all chains, but we are * currently searching for the insertion point. */ WATCHDOG_BEING_INSERTED, /** This is the state when the watchdog is on a chain, and allowed to fire. */ WATCHDOG_ACTIVE, /** This is the state when the watchdog is on a chain, but we should * remove without firing if it expires. */ WATCHDOG_REMOVE_IT } Watchdog_States; /** * @brief Watchdog Adjustment Directions Type * * The following enumerated type details the manner in which * a watchdog chain may be adjusted by the @ref _Watchdog_Adjust * routine. The direction indicates a movement FORWARD * or BACKWARD in time. */ typedef enum { /** adjust delta value forward */ WATCHDOG_FORWARD, /** adjust delta value backward */ WATCHDOG_BACKWARD } Watchdog_Adjust_directions; /** * @brief Watchdog Control Structure * * The following record defines the control block used * to manage each watchdog timer. */ typedef struct { /** This field is a Chain Node structure and allows this to be placed on * chains for set management. */ Chain_Node Node; /** This field is the state of the watchdog. */ Watchdog_States state; /** This field is the initially requested interval. */ Watchdog_Interval initial; /** This field is the remaining portion of the interval. */ Watchdog_Interval delta_interval; /** This field is the number of system clock ticks when this was scheduled. */ Watchdog_Interval start_time; /** This field is the number of system clock ticks when this was suspended. */ Watchdog_Interval stop_time; /** This field is the function to invoke. */ Watchdog_Service_routine_entry routine; /** This field is the Id to pass as an argument to the routine. */ Objects_Id id; /** This field is an untyped pointer to user data that is passed to the * watchdog handler routine. */ void *user_data; } Watchdog_Control; /** * @brief Watchdog Synchronization Level * * This used for synchronization purposes * during an insert on a watchdog delta chain. */ SCORE_EXTERN volatile uint32_t _Watchdog_Sync_level; /** * @brief Watchdog Synchronization Count * * This used for synchronization purposes * during an insert on a watchdog delta chain. */ SCORE_EXTERN volatile uint32_t _Watchdog_Sync_count; /** * @brief Ticks Since System Boot * * This contains the number of ticks since the system was booted. */ SCORE_EXTERN volatile Watchdog_Interval _Watchdog_Ticks_since_boot; /** * @brief Watchdog Nanoseconds Since Last Tick Handler * * This is a pointer to the optional BSP plugin to obtain the number * of nanoseconds since the last clock tick. */ extern Watchdog_Nanoseconds_since_last_tick_routine _Watchdog_Nanoseconds_since_tick_handler; /** * @brief Per Ticks Watchdog List * * This is the watchdog chain which is managed at ticks. */ SCORE_EXTERN Chain_Control _Watchdog_Ticks_chain; /** * @brief Per Seconds Watchdog List * * This is the watchdog chain which is managed at second boundaries. */ SCORE_EXTERN Chain_Control _Watchdog_Seconds_chain; /** * @brief Watchdog Handler Initialization * * This routine initializes the watchdog handler. The watchdog * synchronization flag is initialized and the watchdog chains are * initialized and emptied. */ void _Watchdog_Handler_initialization( void ); /** * @brief Remove Watchdog from List * * This routine removes @a the_watchdog from the watchdog chain on which * it resides and returns the state @a the_watchdog timer was in. * * @param[in] the_watchdog will be removed * @return the state in which @a the_watchdog was in when removed */ Watchdog_States _Watchdog_Remove ( Watchdog_Control *the_watchdog ); /** * @brief Watchdog Adjust * * This routine adjusts the @a header watchdog chain in the forward * or backward @a direction for @a units ticks. * * @param[in] header is the watchdog chain to adjust * @param[in] direction is the direction to adjust @a header * @param[in] units is the number of units to adjust @a header */ void _Watchdog_Adjust ( Chain_Control *header, Watchdog_Adjust_directions direction, Watchdog_Interval units ); /** * @brief Watchdog Adjust to Chain * * This routine adjusts the @a header watchdog chain in the forward * @a direction for @a units_arg ticks. * * @param[in] header is the watchdog chain to adjust * @param[in] units_arg is the number of units to adjust @a header * @param[in] to_fire is a pointer to an initialized Chain_Control to which * all watchdog instances that are to be fired will be placed. * * @note This always adjusts forward. */ void _Watchdog_Adjust_to_chain( Chain_Control *header, Watchdog_Interval units_arg, Chain_Control *to_fire ); /** * @brief Watchdog Insert * * This routine inserts @a the_watchdog into the @a header watchdog chain * for a time of @a units. * * @param[in] header is @a the_watchdog list to insert @a the_watchdog on * @param[in] the_watchdog is the watchdog to insert */ void _Watchdog_Insert ( Chain_Control *header, Watchdog_Control *the_watchdog ); /** * @brief Watchdog Tickle * * This routine is invoked at appropriate intervals to update * the @a header watchdog chain. * * @param[in] header is the watchdog chain to tickle */ void _Watchdog_Tickle ( Chain_Control *header ); /** * @brief Report Information on a Single Watchdog Instance * * This method prints a one line report on the watchdog instance * provided. The @a name may be used to identify the watchdog and * a space will be printed after @a name if it is not NULL. * * @param[in] name is a string to prefix the line with. If NULL, * nothing is printed. * @param[in] watch is the watchdog instance to be printed. * * @note This is a debug routine. It uses printk() and prudence should * exercised when using it. */ void _Watchdog_Report( const char *name, Watchdog_Control *watch ); /** * @brief Report Information on a Watchdog Chain * * This method prints report on the watchdog chain provided. * The @a name may be used to identify the watchdog chain and * a space will be printed after @a name if it is not NULL. * * @param[in] name is a string to prefix the line with. If NULL, * nothing is printed. * @param[in] header is the watchdog chain to be printed. * * @note This is a debug routine. It uses printk() and prudence should * exercised when using it. It also disables interrupts so the * chain can be traversed in a single atomic pass. */ void _Watchdog_Report_chain( const char *name, Chain_Control *header ); /** * @brief Default nanoseconds since last tick handler. * * @retval 0 Always. */ uint32_t _Watchdog_Nanoseconds_since_tick_default_handler( void ); #ifndef __RTEMS_APPLICATION__ #include #endif #ifdef __cplusplus } #endif /**@}*/ #endif /* end of include file */