summaryrefslogtreecommitdiffstats
path: root/cpukit/rtems/include/rtems/rtems/timer.h
diff options
context:
space:
mode:
authorJoel Sherrill <joel.sherrill@OARcorp.com>2008-04-18 15:02:20 +0000
committerJoel Sherrill <joel.sherrill@OARcorp.com>2008-04-18 15:02:20 +0000
commit067a96ad0c3b0818d71d9aaadaee4b520d940de1 (patch)
treed04eed432a0534ebfb0830d6f7e49ce78ff098a4 /cpukit/rtems/include/rtems/rtems/timer.h
parent2008-04-18 Joel Sherrill <joel.sherrill@oarcorp.com> (diff)
downloadrtems-067a96ad0c3b0818d71d9aaadaee4b520d940de1.tar.bz2
2008-04-18 Joel Sherrill <joel.sherrill@oarcorp.com>
* rtems/include/rtems.h, rtems/include/rtems/rtems/asr.h, rtems/include/rtems/rtems/attr.h, rtems/include/rtems/rtems/barrier.h, rtems/include/rtems/rtems/barriermp.h, rtems/include/rtems/rtems/cache.h, rtems/include/rtems/rtems/clock.h, rtems/include/rtems/rtems/config.h, rtems/include/rtems/rtems/dpmem.h, rtems/include/rtems/rtems/event.h, rtems/include/rtems/rtems/eventmp.h, rtems/include/rtems/rtems/eventset.h, rtems/include/rtems/rtems/intr.h, rtems/include/rtems/rtems/message.h, rtems/include/rtems/rtems/modes.h, rtems/include/rtems/rtems/mp.h, rtems/include/rtems/rtems/msgmp.h, rtems/include/rtems/rtems/object.h, rtems/include/rtems/rtems/options.h, rtems/include/rtems/rtems/part.h, rtems/include/rtems/rtems/partmp.h, rtems/include/rtems/rtems/ratemon.h, rtems/include/rtems/rtems/region.h, rtems/include/rtems/rtems/regionmp.h, rtems/include/rtems/rtems/rtemsapi.h, rtems/include/rtems/rtems/sem.h, rtems/include/rtems/rtems/semmp.h, rtems/include/rtems/rtems/signal.h, rtems/include/rtems/rtems/signalmp.h, rtems/include/rtems/rtems/status.h, rtems/include/rtems/rtems/support.h, rtems/include/rtems/rtems/taskmp.h, rtems/include/rtems/rtems/tasks.h, rtems/include/rtems/rtems/timer.h, rtems/include/rtems/rtems/types.h, rtems/inline/rtems/rtems/asr.inl, rtems/inline/rtems/rtems/attr.inl, rtems/inline/rtems/rtems/barrier.inl, rtems/inline/rtems/rtems/dpmem.inl, rtems/inline/rtems/rtems/event.inl, rtems/inline/rtems/rtems/eventset.inl, rtems/inline/rtems/rtems/message.inl, rtems/inline/rtems/rtems/modes.inl, rtems/inline/rtems/rtems/options.inl, rtems/inline/rtems/rtems/part.inl, rtems/inline/rtems/rtems/ratemon.inl, rtems/inline/rtems/rtems/region.inl, rtems/inline/rtems/rtems/sem.inl, rtems/inline/rtems/rtems/status.inl, rtems/inline/rtems/rtems/support.inl, rtems/inline/rtems/rtems/tasks.inl, rtems/inline/rtems/rtems/timer.inl: Initial conversion of Classic API header files to Doxygen. * rtems/Doxyfile: New file.
Diffstat (limited to '')
-rw-r--r--cpukit/rtems/include/rtems/rtems/timer.h174
1 files changed, 78 insertions, 96 deletions
diff --git a/cpukit/rtems/include/rtems/rtems/timer.h b/cpukit/rtems/include/rtems/rtems/timer.h
index fdb9185d00..980132a448 100644
--- a/cpukit/rtems/include/rtems/rtems/timer.h
+++ b/cpukit/rtems/include/rtems/rtems/timer.h
@@ -1,8 +1,6 @@
/**
* @file rtems/rtems/timer.h
- */
-
-/*
+ *
* This include file contains all the constants, structures, and
* prototypes associated with the Timer Manager. This manager provides
* facilities to configure, initiate, cancel, and delete timers which will
@@ -10,20 +8,21 @@
*
* Directives provided are:
*
- * + create a timer
- * + get an ID of a timer
- * + delete a timer
- * + set timer to fire in context of clock tick
+ * - create a timer
+ * - get an ID of a timer
+ * - delete a timer
+ * - set timer to fire in context of clock tick
* - after a number of ticks have passed
* - when a specified date and time has been reached
- * + initiate the timer server task
- * + set timer to fire in context of the timer server task
+ * - initiate the timer server task
+ * - set timer to fire in context of the timer server task
* - after a number of ticks have passed
* - when a specified date and time has been reached
- * + reset a timer
- * + cancel a time
- *
- * COPYRIGHT (c) 1989-2007.
+ * - reset a timer
+ * - cancel a time
+ */
+
+/* COPYRIGHT (c) 1989-2007.
* On-Line Applications Research Corporation (OAR).
*
* The license and distribution terms for this file may be
@@ -50,11 +49,17 @@ extern "C" {
#include <rtems/rtems/clock.h>
#include <rtems/rtems/attr.h>
-/*
+/**
+ * @defgroup ClassicTimer Classic API Timer
+ *
+ * This encapsulates functionality which XXX
+ */
+/**@{*/
+
+/**
* The following enumerated type details the classes to which a timer
* may belong.
*/
-
typedef enum {
TIMER_INTERVAL,
TIMER_INTERVAL_ON_TASK,
@@ -63,10 +68,9 @@ typedef enum {
TIMER_DORMANT
} Timer_Classes;
-/*
+/**
* The following types define a pointer to a timer service routine.
*/
-
typedef void rtems_timer_service_routine;
typedef rtems_timer_service_routine ( *rtems_timer_service_routine_entry )(
@@ -74,22 +78,20 @@ typedef rtems_timer_service_routine ( *rtems_timer_service_routine_entry )(
void *
);
-/*
+/**
* The following defines the information control block used to manage
* this class of objects.
*/
-
RTEMS_TIMER_EXTERN Objects_Information _Timer_Information;
-/*
+/**
* Pointer to TCB of the Timer Server. This is NULL before the
* server is executing and task-based timers are not allowed to be
* initiated until the server is started.
*/
-
RTEMS_TIMER_EXTERN Thread_Control *_Timer_Server;
-/*
+/**
* The following chains contain the list of interval timers that are
* executed in the context of the Timer Server.
*
@@ -100,109 +102,87 @@ RTEMS_TIMER_EXTERN Thread_Control *_Timer_Server;
* do not have to be initialized until then. They are declared
* in the same file as _Timer_Server_body.
*/
-
extern Chain_Control _Timer_Ticks_chain;
extern Chain_Control _Timer_Seconds_chain;
-/*
+/**
* The following records define the control block used to manage
* each timer.
*/
-
typedef struct {
Objects_Control Object;
Watchdog_Control Ticker;
Timer_Classes the_class;
} Timer_Control;
-/*
- * _Timer_Manager_initialization
- *
- * DESCRIPTION:
+/**
+ * @brief _Timer_Manager_initialization
*
* This routine performs the initialization necessary for this manager.
*/
-
void _Timer_Manager_initialization(
uint32_t maximum_timers
);
-/*
- * _Timer_Server_body
- *
- * DESCRIPTION:
+/**
+ * @brief _Timer_Server_body
*
* This is the server for task based timers. This task executes whenever
* a task-based timer should fire. It services both "after" and "when"
* timers. It is not created automatically but must be created explicitly
* by the application before task-based timers may be initiated.
*/
-
Thread _Timer_Server_body(
uint32_t ignored
);
-/*
- * rtems_timer_create
- *
- * DESCRIPTION:
+/**
+ * @brief rtems_timer_create
*
* This routine implements the rtems_timer_create directive. The
* timer will have the name name. It returns the id of the
* created timer in ID.
*/
-
rtems_status_code rtems_timer_create(
rtems_name name,
Objects_Id *id
);
-/*
- * rtems_timer_ident
- *
- * DESCRIPTION:
+/**
+ * @brief rtems_timer_ident
*
* This routine implements the rtems_timer_ident directive.
* This directive returns the timer ID associated with name.
* If more than one timer is named name, then the timer
* to which the ID belongs is arbitrary.
*/
-
rtems_status_code rtems_timer_ident(
rtems_name name,
Objects_Id *id
);
-/*
- * rtems_timer_cancel
- *
- * DESCRIPTION:
+/**
+ * @brief rtems_timer_cancel
*
* This routine implements the rtems_timer_cancel directive. It is used
* to stop the timer associated with ID from firing.
*/
-
rtems_status_code rtems_timer_cancel(
Objects_Id id
);
-/*
- * rtems_timer_delete
- *
- * DESCRIPTION:
+/**
+ * @brief rtems_timer_delete
*
* This routine implements the rtems_timer_delete directive. The
* timer indicated by ID is deleted.
*/
-
rtems_status_code rtems_timer_delete(
Objects_Id id
);
-/*
- * rtems_timer_fire_after
- *
- * DESCRIPTION:
+/**
+ * @brief rtems_timer_fire_after
*
* This routine implements the rtems_timer_fire_after directive. It
* initiates the timer associated with ID to fire in ticks clock ticks.
@@ -210,7 +190,6 @@ rtems_status_code rtems_timer_delete(
* of the rtems_clock_tick directive which is normally invoked as
* part of servicing a periodic interupt.
*/
-
rtems_status_code rtems_timer_fire_after(
Objects_Id id,
rtems_interval ticks,
@@ -218,10 +197,8 @@ rtems_status_code rtems_timer_fire_after(
void *user_data
);
-/*
- * rtems_timer_server_fire_after
- *
- * DESCRIPTION:
+/**
+ * @brief rtems_timer_server_fire_after
*
* This routine implements the rtems_timer_server_fire_after directive. It
* initiates the timer associated with ID to fire in ticks clock
@@ -229,7 +206,6 @@ rtems_status_code rtems_timer_fire_after(
* Timer Server in the context of a task NOT IN THE CONTEXT of the
* clock tick interrupt.
*/
-
rtems_status_code rtems_timer_server_fire_after(
Objects_Id id,
rtems_interval ticks,
@@ -237,10 +213,8 @@ rtems_status_code rtems_timer_server_fire_after(
void *user_data
);
-/*
- * rtems_timer_fire_when
- *
- * DESCRIPTION:
+/**
+ * @brief rtems_timer_fire_when
*
* This routine implements the rtems_timer_fire_when directive. It
* initiates the timer associated with ID to fire at wall_time
@@ -248,7 +222,6 @@ rtems_status_code rtems_timer_server_fire_after(
* of the rtems_clock_tick directive which is normally invoked as
* part of servicing a periodic interupt.
*/
-
rtems_status_code rtems_timer_fire_when(
Objects_Id id,
rtems_time_of_day *wall_time,
@@ -256,10 +229,8 @@ rtems_status_code rtems_timer_fire_when(
void *user_data
);
-/*
- * rtems_timer_server_fire_when
- *
- * DESCRIPTION:
+/**
+ * @brief rtems_timer_server_fire_when
*
* This routine implements the rtems_timer_server_fire_when directive. It
* initiates the timer associated with ID to fire at wall_time
@@ -267,7 +238,6 @@ rtems_status_code rtems_timer_fire_when(
* Timer Server in the context of a task NOT IN THE CONTEXT of the
* clock tick interrupt.
*/
-
rtems_status_code rtems_timer_server_fire_when(
Objects_Id id,
rtems_time_of_day *wall_time,
@@ -275,48 +245,42 @@ rtems_status_code rtems_timer_server_fire_when(
void *user_data
);
-/*
- * rtems_timer_reset
- *
- * DESCRIPTION:
+/**
+ * @brief rtems_timer_reset
*
* This routine implements the rtems_timer_reset directive. It is used
* to reinitialize the interval timer associated with ID just as if
* rtems_timer_fire_after were re-invoked with the same arguments that
* were used to initiate this timer.
*/
-
rtems_status_code rtems_timer_reset(
Objects_Id id
);
-/*
- * rtems_timer_initiate_server
- *
- * DESCRIPTION:
+/**
+ * @brief rtems_timer_initiate_server
*
* This routine implements the rtems_timer_initiate_server directive.
* It creates and starts the server that executes task-based timers.
* It must be invoked before any task-based timers can be initiated.
*/
-
-#define RTEMS_TIMER_SERVER_DEFAULT_PRIORITY -1
-
rtems_status_code rtems_timer_initiate_server(
uint32_t priority,
uint32_t stack_size,
rtems_attribute attribute_set
);
-/*
- * rtems_timer_get_information
- *
- * DESCRIPTION:
- *
- * This routine implements the rtems_timer_get_information directive.
- * This directive returns information about the timer.
+/**
+ * This is the default value for the priority of the Timer Server.
+ * When given this priority, a special high priority not accessible
+ * via the Classic API is used.
*/
+#define RTEMS_TIMER_SERVER_DEFAULT_PRIORITY -1
+/**
+ * This is the structure filled in by the timer get information
+ * service.
+ */
typedef struct {
Timer_Classes the_class;
Watchdog_Interval initial;
@@ -324,17 +288,22 @@ typedef struct {
Watchdog_Interval stop_time;
} rtems_timer_information;
+/**
+ * @brief rtems_timer_get_information
+ *
+ * This routine implements the rtems_timer_get_information directive.
+ * This directive returns information about the timer.
+ */
rtems_status_code rtems_timer_get_information(
Objects_Id id,
rtems_timer_information *the_info
);
-/*
+/**
* Macros and routines that expose the mechanisms required to service
* the Timer Server timer. These stop the timer, synchronize it with
* the current time, and restart it.
*/
-
extern Watchdog_Control _Timer_Seconds_timer;
#define _Timer_Server_stop_ticks_timer() \
@@ -343,7 +312,18 @@ extern Watchdog_Control _Timer_Seconds_timer;
#define _Timer_Server_stop_seconds_timer() \
_Watchdog_Remove( &_Timer_Seconds_timer );
+/**
+ * This is a helper function which processes the ticks chain when
+ * needed. It advances time for the ticks chain which results in
+ * timers firing.
+ */
void _Timer_Server_process_ticks_chain(void);
+
+/**
+ * This is a helper function which processes the seconds chain when
+ * needed. It advances time for the seconds chain which results in
+ * timers firing.
+ */
void _Timer_Server_process_seconds_chain(void);
#define _Timer_Server_reset_ticks_timer() \
@@ -370,5 +350,7 @@ void _Timer_Server_process_seconds_chain(void);
}
#endif
+/**@}*/
+
#endif
/* end of include file */