diff options
Diffstat (limited to 'cpukit/include/rtems/rtems/timer.h')
| -rw-r--r-- | cpukit/include/rtems/rtems/timer.h | 384 |
1 files changed, 384 insertions, 0 deletions
diff --git a/cpukit/include/rtems/rtems/timer.h b/cpukit/include/rtems/rtems/timer.h new file mode 100644 index 0000000000..032c49525a --- /dev/null +++ b/cpukit/include/rtems/rtems/timer.h @@ -0,0 +1,384 @@ +/** + * @file rtems/rtems/timer.h + * + * @defgroup ClassicTimer Timers + * + * @ingroup ClassicRTEMS + * @brief Instantiate RTEMS Timer Data + * + * 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 + * fire at specified intervals of time. + * + * Directives provided are: + * + * - 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 + * - 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-2011. + * On-Line Applications Research Corporation (OAR). + * + * Copyright (c) 2009, 2016 embedded brains GmbH. + * + * The license and distribution terms for this file may be + * found in the file LICENSE in this distribution or at + * http://www.rtems.org/license/LICENSE. + */ + +#ifndef _RTEMS_RTEMS_TIMER_H +#define _RTEMS_RTEMS_TIMER_H + +#include <rtems/rtems/attr.h> +#include <rtems/rtems/status.h> +#include <rtems/rtems/tasks.h> +#include <rtems/rtems/types.h> + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * @defgroup ClassicTimer Timers + * + * @ingroup ClassicRTEMS + * + * This encapsulates functionality related to the Classic API Timer + * Manager. This manager provides functionality which allows the + * application to schedule the execution of methods at a specified + * time in the future. These methods may be scheduled based upon + * interval or wall time and may be executed in either the clock tick + * ISR or in a special dedicated timer server task. + */ +/**@{*/ + +#define TIMER_CLASS_BIT_TIME_OF_DAY 0x1 + +#define TIMER_CLASS_BIT_ON_TASK 0x2 + +#define TIMER_CLASS_BIT_NOT_DORMANT 0x4 + +/** + * The following enumerated type details the classes to which a timer + * may belong. + */ +typedef enum { + /** + * This value indicates the timer is currently not in use. + */ + TIMER_DORMANT, + + /** + * This value indicates the timer is currently in use as an interval + * timer which will fire in the clock tick ISR. + */ + TIMER_INTERVAL = TIMER_CLASS_BIT_NOT_DORMANT, + + /** + * This value indicates the timer is currently in use as an interval + * timer which will fire in the timer server task. + */ + TIMER_INTERVAL_ON_TASK = + TIMER_CLASS_BIT_NOT_DORMANT | TIMER_CLASS_BIT_ON_TASK, + + /** + * This value indicates the timer is currently in use as an time of day + * timer which will fire in the clock tick ISR. + */ + TIMER_TIME_OF_DAY = + TIMER_CLASS_BIT_NOT_DORMANT | TIMER_CLASS_BIT_TIME_OF_DAY, + + /** + * This value indicates the timer is currently in use as an time of day + * timer which will fire in the timer server task. + */ + TIMER_TIME_OF_DAY_ON_TASK = + TIMER_CLASS_BIT_NOT_DORMANT | TIMER_CLASS_BIT_TIME_OF_DAY | + TIMER_CLASS_BIT_ON_TASK +} Timer_Classes; + +/** + * The following types define a pointer to a timer service routine. + */ +typedef void rtems_timer_service_routine; + +/** + * This type defines the type used to manage and indirectly invoke + * Timer Service Routines (TSRs). This defines the prototype and interface + * for a function which is to be used as a TSR. + */ +typedef rtems_timer_service_routine ( *rtems_timer_service_routine_entry )( + rtems_id, + void * + ); + +/** + * The following records define the control block used to manage + * each timer. + */ +typedef struct { + /** This field is the object management portion of a Timer instance. */ + Objects_Control Object; + /** This field is the Watchdog instance which will be the scheduled. */ + Watchdog_Control Ticker; + /** This field indicates what type of timer this currently is. */ + Timer_Classes the_class; + /** This field is the timer service routine. */ + rtems_timer_service_routine_entry routine; + /** This field is the timer service routine user data. */ + void *user_data; + /** This field is the timer interval in ticks or seconds. */ + Watchdog_Interval initial; + /** This field is the timer start time point in ticks. */ + Watchdog_Interval start_time; + /** This field is the timer stop time point in ticks. */ + Watchdog_Interval stop_time; +} Timer_Control; + +/** + * @brief RTEMS Create Timer + * + * 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. + * + * @param[in] name is the timer name + * @param[out] id is the pointer to timer id + * + * @retval RTEMS_SUCCESSFUL if successful or error code if unsuccessful + */ +rtems_status_code rtems_timer_create( + rtems_name name, + rtems_id *id +); + +/** + * @brief RTEMS Timer Name to Id + * + * 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. + * + * @param[in] name is the user defined message queue name + * @param[in] id is the pointer to timer id + * + * @retval RTEMS_SUCCESSFUL if successful or error code if unsuccessful and + * id filled with the message queue id + */ +rtems_status_code rtems_timer_ident( + rtems_name name, + rtems_id *id +); + +/** + * @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( + rtems_id id +); + +/** + * @brief RTEMS Delete Timer + * + * This routine implements the rtems_timer_delete directive. The + * timer indicated by ID is deleted. + * + * @param[in] id is the timer id + * + * @retval This method returns RTEMS_SUCCESSFUL if there was not an + * error. Otherwise, a status code is returned indicating the + * source of the error. + */ +rtems_status_code rtems_timer_delete( + rtems_id id +); + +/** + * @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. + * When the timer fires, the routine will be invoked in the context + * of the rtems_clock_tick directive which is normally invoked as + * part of servicing a periodic interupt. + * + * @param[in] id is the timer id + * @param[in] ticks is the interval until routine is fired + * @param[in] routine is the routine to schedule + * @param[in] user_data is the passed as argument to routine when it is fired + * + * @retval This method returns RTEMS_SUCCESSFUL if there was not an + * error. Otherwise, a status code is returned indicating the + * source of the error. + */ +rtems_status_code rtems_timer_fire_after( + rtems_id id, + rtems_interval ticks, + rtems_timer_service_routine_entry routine, + void *user_data +); + +/** + * @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 + * ticks. When the timer fires, the routine will be invoked by the + * Timer Server in the context of a task NOT IN THE CONTEXT of the + * clock tick interrupt. + * + * @param[in] id is the timer id + * @param[in] ticks is the interval until routine is fired + * @param[in] routine is the routine to schedule + * @param[in] user_data is the passed as argument to routine when it is fired + * + * @retval This method returns RTEMS_SUCCESSFUL if there was not an + * error. Otherwise, a status code is returned indicating the + * source of the error. + */ +rtems_status_code rtems_timer_server_fire_after( + rtems_id id, + rtems_interval ticks, + rtems_timer_service_routine_entry routine, + void *user_data +); + +/** + * @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 + * When the timer fires, the routine will be invoked in the context + * of the rtems_clock_tick directive which is normally invoked as + * part of servicing a periodic interupt. + * + * @param[in] id is the timer id + * @param[in] wall_time is the time of day to fire timer + * @param[in] routine is the routine to schedule + * @param[in] user_data is the passed as argument to routine when it is fired + * + * @retval This method returns RTEMS_SUCCESSFUL if there was not an + * error. Otherwise, a status code is returned indicating the + * source of the error. + */ +rtems_status_code rtems_timer_fire_when( + rtems_id id, + rtems_time_of_day *wall_time, + rtems_timer_service_routine_entry routine, + void *user_data +); + +/** + * @brief RTEMS Timer Server Fire When Directive + * + * Timer Manager - RTEMS Timer Server Fire When Directive + * + * This routine implements the rtems_timer_server_fire_when directive. It + * initiates the timer associated with ID to fire at wall_time + * When the timer fires, the routine will be invoked by the + * 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( + rtems_id id, + rtems_time_of_day *wall_time, + rtems_timer_service_routine_entry routine, + void *user_data +); + +/** + * @brief RTEMS Timer Reset + * + * Timer Manager - 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( + rtems_id id +); + +/** + * @brief Initiates the timer server. + * + * This directive creates and starts the server for task-based timers. + * It must be invoked before any task-based timers can be initiated. + * + * @param priority The timer server task priority. + * @param stack_size The stack size in bytes for the timer server task. + * @param attribute_set The timer server task attributes. + * + * @return This method returns RTEMS_SUCCESSFUL if successful and an + * error code otherwise. + */ +rtems_status_code rtems_timer_initiate_server( + rtems_task_priority priority, + size_t stack_size, + rtems_attribute attribute_set +); + +/** + * 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 (uint32_t) -1 + +/** + * This is the structure filled in by the timer get information + * service. + */ +typedef struct { + /** This indicates the current type of the timer. */ + Timer_Classes the_class; + /** This indicates the initial requested interval. */ + Watchdog_Interval initial; + /** This indicates the time the timer was initially scheduled. */ + Watchdog_Interval start_time; + /** This indicates the time the timer is scheduled to fire. */ + Watchdog_Interval stop_time; +} rtems_timer_information; + +/** + * @brief RTEMS Get Timer Information + * + * This routine implements the rtems_timer_get_information directive. + * This directive returns information about the timer. + * + * @param[in] id is the timer id + * @param[in] the_info is the pointer to timer information block + * + * @retval RTEMS_SUCCESSFUL if successful or error code if unsuccessful and + * *the_info region information block filled in + */ +rtems_status_code rtems_timer_get_information( + rtems_id id, + rtems_timer_information *the_info +); + +/**@}*/ + +#ifdef __cplusplus +} +#endif + +#endif +/* end of include file */ |