From baff4dafe1ff85d128a55e7b73780ca28f5c7faf Mon Sep 17 00:00:00 2001 From: Joel Sherrill Date: Mon, 1 Nov 2004 13:22:41 +0000 Subject: 2004-11-01 Joel Sherrill * score/cpu/no_cpu/rtems/score/cpu.h, score/include/rtems/debug.h, score/include/rtems/seterr.h, score/include/rtems/system.h, score/include/rtems/score/address.h, score/include/rtems/score/apiext.h, score/include/rtems/score/apimutex.h, score/include/rtems/score/bitfield.h, score/include/rtems/score/chain.h, score/include/rtems/score/context.h, score/include/rtems/score/copyrt.h, score/include/rtems/score/coremsg.h, score/include/rtems/score/coremutex.h, score/include/rtems/score/coresem.h, score/include/rtems/score/heap.h, score/include/rtems/score/interr.h, score/include/rtems/score/isr.h, score/include/rtems/score/mpci.h, score/include/rtems/score/mppkt.h, score/include/rtems/score/objectmp.h, score/include/rtems/score/priority.h, score/include/rtems/score/stack.h, score/include/rtems/score/states.h, score/include/rtems/score/sysstate.h, score/include/rtems/score/thread.h, score/include/rtems/score/threadmp.h, score/include/rtems/score/threadq.h, score/include/rtems/score/tod.h, score/include/rtems/score/tqdata.h, score/include/rtems/score/userext.h, score/include/rtems/score/watchdog.h, score/include/rtems/score/wkspace.h, score/inline/rtems/score/address.inl, score/inline/rtems/score/chain.inl, score/inline/rtems/score/coremsg.inl, score/inline/rtems/score/coremutex.inl, score/inline/rtems/score/coresem.inl, score/inline/rtems/score/heap.inl, score/inline/rtems/score/isr.inl, score/inline/rtems/score/mppkt.inl, score/inline/rtems/score/objectmp.inl, score/inline/rtems/score/priority.inl, score/inline/rtems/score/stack.inl, score/inline/rtems/score/states.inl, score/inline/rtems/score/sysstate.inl, score/inline/rtems/score/thread.inl, score/inline/rtems/score/threadmp.inl, score/inline/rtems/score/tod.inl, score/inline/rtems/score/tqdata.inl, score/inline/rtems/score/userext.inl, score/inline/rtems/score/watchdog.inl, score/inline/rtems/score/wkspace.inl: Add Doxygen comments -- working modifications which are not complete and may have broken code. Committing so work and testing can proceed. * score/Doxyfile, score/mainpage.h: New files. --- cpukit/score/include/rtems/score/watchdog.h | 166 +++++++++++++++++----------- 1 file changed, 99 insertions(+), 67 deletions(-) (limited to 'cpukit/score/include/rtems/score/watchdog.h') diff --git a/cpukit/score/include/rtems/score/watchdog.h b/cpukit/score/include/rtems/score/watchdog.h index cb70d13120..91d2a166c0 100644 --- a/cpukit/score/include/rtems/score/watchdog.h +++ b/cpukit/score/include/rtems/score/watchdog.h @@ -1,10 +1,13 @@ -/* watchdog.h +/** + * @file 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-1999. + * used to initialize and manipulate watchdog timers. + */ + +/* + * COPYRIGHT (c) 1989-2004. * On-Line Applications Research Corporation (OAR). * * The license and distribution terms for this file may be @@ -17,67 +20,94 @@ #ifndef __WATCHDOG_h #define __WATCHDOG_h +/** + * @defgroup ScoreWatchdog Watchdog Handler + * + * This group contains functionality which XXX + */ +/**@{*/ + #ifdef __cplusplus extern "C" { #endif #include -/* +/** @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; -/* - * The following types define a pointer to a watchdog service routine. +/** @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 * ); -/* - * Constant for indefinite wait. (actually an illegal interval) +/** @brief No timeout constant + * + * This is the constant for indefinite wait. It is actually an + * illegal interval. */ - #define WATCHDOG_NO_TIMEOUT 0 -/* - * The following enumerated type lists the states in which a +/** @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 { - WATCHDOG_INACTIVE, /* off all chains */ - WATCHDOG_BEING_INSERTED, /* off all chains, searching for insertion point */ - WATCHDOG_ACTIVE, /* on chain, allowed to fire */ - WATCHDOG_REMOVE_IT /* on chain, remove without firing if expires */ + /** 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 Watchdog_Adjust + * a watchdog chain may be adjusted by the @ref _Watchdog_Adjust * routine. The direction indicates a movement FORWARD * or BACKWARD in time. */ - typedef enum { - WATCHDOG_FORWARD, /* adjust delta value forward */ - WATCHDOG_BACKWARD /* adjust delta value backward */ + /** 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 { Chain_Node Node; Watchdog_States state; @@ -90,93 +120,93 @@ typedef struct { void *user_data; } Watchdog_Control; -/* - * The following are used for synchronization purposes +/** @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; -/* - * The following contains the number of ticks since the - * system was booted. +/** @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; -/* - * The following defines the watchdog chains which are managed - * on ticks and second boundaries. +/** @brief Per Ticks Watchdog List + * + * This is the watchdog chain which is managed at ticks. */ - SCORE_EXTERN Chain_Control _Watchdog_Ticks_chain; -SCORE_EXTERN Chain_Control _Watchdog_Seconds_chain; -/* - * _Watchdog_Handler_initialization +/** @brief Per Seconds Watchdog List * - * DESCRIPTION: + * 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 ); -/* - * _Watchdog_Remove - * - * DESCRIPTION: +/** @brief Remove Watchdog from List * - * This routine removes THE_WATCHDOG from the watchdog chain on which - * it resides and returns the state THE_WATCHDOG timer was in. + * 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 the_watchdog (in) will be removed + * @return the state in which @a the_watchdog was in when removed */ - Watchdog_States _Watchdog_Remove ( Watchdog_Control *the_watchdog ); -/* - * _Watchdog_Adjust +/** @brief Watchdog Adjust * - * DESCRIPTION: + * This routine adjusts the @a header watchdog chain in the forward + * or backward @a direction for @a units ticks. * - * This routine adjusts the HEADER watchdog chain in the forward - * or backward DIRECTION for UNITS ticks. + * @param header (in) is the watchdog chain to adjust + * @param direction (in) is the direction to adjust @a header + * @param units (in) is the number of units to adjust @a header */ - void _Watchdog_Adjust ( Chain_Control *header, Watchdog_Adjust_directions direction, Watchdog_Interval units ); -/* - * _Watchdog_Insert - * - * DESCRIPTION: +/** @brief Watchdog Insert * - * This routine inserts THE_WATCHDOG into the HEADER watchdog chain - * for a time of UNITS. The INSERT_MODE indicates whether - * THE_WATCHDOG is to be activated automatically or later, explicitly - * by the caller. + * This routine inserts @a the_watchdog into the @a header watchdog chain + * for a time of @a units. * + * @param header (in) is @a the_watchdog list to insert @a the_watchdog on + * @param the_watchdog (in) is the watchdog to insert */ - void _Watchdog_Insert ( Chain_Control *header, Watchdog_Control *the_watchdog ); -/* - * _Watchdog_Tickle - * - * DESCRIPTION: +/** @brief Watchdog Tickle * * This routine is invoked at appropriate intervals to update - * the HEADER watchdog chain. + * the @a header watchdog chain. + * + * @param header (in) is the watchdog chain to tickle */ void _Watchdog_Tickle ( @@ -191,5 +221,7 @@ void _Watchdog_Tickle ( } #endif +/**@}*/ + #endif /* end of include file */ -- cgit v1.2.3