From 768327d06de3fbcf372ae2fe04199a036bc3234a Mon Sep 17 00:00:00 2001 From: Sebastian Huber Date: Mon, 22 Jun 2020 13:36:21 +0200 Subject: rtems: Generate Change license to BSD-2-Clause according to file histories and documentation re-licensing agreement. Update #3899. Update #3993. --- cpukit/include/rtems/rtems/timer.h | 705 ++++++++++++++++++++++++++----------- 1 file changed, 494 insertions(+), 211 deletions(-) (limited to 'cpukit/include/rtems/rtems') diff --git a/cpukit/include/rtems/rtems/timer.h b/cpukit/include/rtems/rtems/timer.h index 244d5603ba..3d454e39ec 100644 --- a/cpukit/include/rtems/rtems/timer.h +++ b/cpukit/include/rtems/rtems/timer.h @@ -1,289 +1,493 @@ +/* SPDX-License-Identifier: BSD-2-Clause */ + /** * @file * - * @ingroup ClassicTimer + * @ingroup RTEMSImplClassicTimer * - * @brief Classic Timer Manager API + * @brief This header file provides the Timer Manager API. + */ + +/* + * Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de) + * Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * 1. Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in the + * documentation and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + * POSSIBILITY OF SUCH DAMAGE. */ /* - * COPYRIGHT (c) 1989-2011. - * On-Line Applications Research Corporation (OAR). + * This file is part of the RTEMS quality process and was automatically + * generated. If you find something that needs to be fixed or + * worded better please post a report or patch to an RTEMS mailing list + * or raise a bug report: + * + * https://docs.rtems.org/branches/master/user/support/bugs.html * - * Copyright (c) 2009, 2016 embedded brains GmbH. + * For information on updating and regenerating please refer to: * - * 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. + * https://docs.rtems.org/branches/master/eng/req/howto.html */ +/* Generated from spec:/rtems/timer/if/header */ + #ifndef _RTEMS_RTEMS_TIMER_H #define _RTEMS_RTEMS_TIMER_H +#include #include #include #include #include +#include #ifdef __cplusplus extern "C" { #endif +/* Generated from spec:/rtems/timer/if/group */ + /** - * @defgroup ClassicTimer Timers + * @defgroup RTEMSAPIClassicTimer Timer Manager * - * @ingroup RTEMSAPIClassic + * @ingroup RTEMSAPIClassic * - * 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. + * @brief The Timer Manager provides support for timer facilities. */ -/**@{*/ -#define TIMER_CLASS_BIT_TIME_OF_DAY 0x1 +/* Generated from spec:/rtems/timer/if/class-bit-not-dormant */ + +/** + * @ingroup RTEMSAPIClassicTimer + * + * @brief This timer class bit indicates that the timer is not dormant. + */ +#define TIMER_CLASS_BIT_NOT_DORMANT 0x4 + +/* Generated from spec:/rtems/timer/if/class-bit-on-task */ +/** + * @ingroup RTEMSAPIClassicTimer + * + * @brief This timer class bit indicates that the timer routine executes in a + * task context. + */ #define TIMER_CLASS_BIT_ON_TASK 0x2 -#define TIMER_CLASS_BIT_NOT_DORMANT 0x4 +/* Generated from spec:/rtems/timer/if/class-bit-time-of-day */ + +/** + * @ingroup RTEMSAPIClassicTimer + * + * @brief This timer class bit indicates that the timer uses a time of day. + */ +#define TIMER_CLASS_BIT_TIME_OF_DAY 0x1 + +/* Generated from spec:/rtems/timer/if/classes */ /** - * The following enumerated type details the classes to which a timer - * may belong. + * @ingroup RTEMSAPIClassicTimer + * + * @brief The timer class indicates how the timer was most recently fired. */ typedef enum { /** - * This value indicates the timer is currently not in use. + * @brief This timer class indicates that the timer was never 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. + * @brief This timer class indicates that the timer is currently in use as an + * interval timer which will fire in the context of 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. + * @brief This timer class indicates that the timer is currently in use as an + * interval timer which will fire in the context of the Timer Server task. */ - TIMER_INTERVAL_ON_TASK = - TIMER_CLASS_BIT_NOT_DORMANT | TIMER_CLASS_BIT_ON_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. + * @brief This timer class indicates that the timer is currently in use as an + * time of day timer which will fire in the context of the clock tick ISR. */ - TIMER_TIME_OF_DAY = - TIMER_CLASS_BIT_NOT_DORMANT | TIMER_CLASS_BIT_TIME_OF_DAY, + 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. + * @brief This timer class indicates that the timer is currently in use as an + * time of day timer which will fire in the context of the Timer Server task. */ - TIMER_TIME_OF_DAY_ON_TASK = - TIMER_CLASS_BIT_NOT_DORMANT | TIMER_CLASS_BIT_TIME_OF_DAY | + 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; +/* Generated from spec:/rtems/timer/if/information */ /** - * 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. + * @ingroup RTEMSAPIClassicTimer + * + * @brief The structure contains information about a timer. */ -typedef rtems_timer_service_routine ( *rtems_timer_service_routine_entry )( - rtems_id, - void * - ); +typedef struct { + /** + * @brief The timer class member indicates how the timer was most recently + * fired. + */ + Timer_Classes the_class; + + /** + * @brief This member indicates the initial requested interval. + */ + Watchdog_Interval initial; + + /** + * @brief This member indicates the time the timer was initially scheduled. + * + * The time is in clock ticks since the clock driver initialization or the last + * clock tick counter overflow. + */ + Watchdog_Interval start_time; + + /** + * @brief This member indicates the time the timer was scheduled to fire. + * + * The time is in clock ticks since the clock driver initialization or the last + * clock tick counter overflow. + */ + Watchdog_Interval stop_time; +} rtems_timer_information; + +/* Generated from spec:/rtems/timer/if/get-information */ /** - * @brief RTEMS Create Timer + * @ingroup RTEMSAPIClassicTimer + * + * @brief Gets information about the timer. + * + * This directive returns information about the timer. + * + * This directive will not cause the running task to be preempted. + * + * @param id is the timer identifier. * - * 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[out] the_info is the pointer to a timer information variable. The + * information about the timer will be stored in this variable, in case of a + * successful operation. * - * @param[in] name is the timer name - * @param[out] id is the pointer to timer id + * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. * - * @retval RTEMS_SUCCESSFUL if successful or error code if unsuccessful + * @retval ::RTEMS_INVALID_ADDRESS The ``the_info`` parameter was NULL. + * + * @retval ::RTEMS_INVALID_ID There was no timer associated with the identifier + * specified by ``id``. */ -rtems_status_code rtems_timer_create( - rtems_name name, - rtems_id *id +rtems_status_code rtems_timer_get_information( + rtems_id id, + rtems_timer_information *the_info ); +/* Generated from spec:/rtems/timer/if/server-default-priority */ + /** - * @brief RTEMS Timer Name to Id + * @ingroup RTEMSAPIClassicTimer + * + * @brief This constant represents the default value for the task priority of + * the Timer Server. * - * 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. + * When given this priority, a special high priority not accessible via the + * Classic API is used. + */ +#define RTEMS_TIMER_SERVER_DEFAULT_PRIORITY ( (rtems_task_priority) -1 ) + +/* Generated from spec:/rtems/timer/if/service-routine */ + +/** + * @ingroup RTEMSAPIClassicTimer * - * @param[in] name is the user defined message queue name - * @param[in] id is the pointer to timer id + * @brief This type defines the return type of routines which can be fired by + * directives of the Timer Manager. * - * @retval RTEMS_SUCCESSFUL if successful or error code if unsuccessful and - * id filled with the message queue id + * This type can be used to document timer service routines in the source code. */ -rtems_status_code rtems_timer_ident( - rtems_name name, - rtems_id *id -); +typedef void rtems_timer_service_routine; + +/* Generated from spec:/rtems/timer/if/service-routine-entry */ /** - * @brief rtems_timer_cancel + * @ingroup RTEMSAPIClassicTimer * - * This routine implements the rtems_timer_cancel directive. It is used - * to stop the timer associated with ID from firing. + * @brief This type defines the prototype of routines which can be fired by + * directives of the Timer Manager. */ -rtems_status_code rtems_timer_cancel( - rtems_id id -); +typedef rtems_timer_service_routine ( *rtems_timer_service_routine_entry )( rtems_id, void * ); + +/* Generated from spec:/rtems/timer/if/create */ /** - * @brief RTEMS Delete Timer + * @ingroup RTEMSAPIClassicTimer + * + * @brief Creates a timer. + * + * This directive creates a timer. The assigned object identifier is returned + * in ``id``. This identifier is used to access the timer with other timer + * related directives. + * + * This directive may cause the calling task to be preempted due to an obtain + * and release of the object allocator mutex. * - * This routine implements the rtems_timer_delete directive. The - * timer indicated by ID is deleted. + * For control and maintenance of the timer, RTEMS allocates a TMCB from the + * local TMCB free pool and initializes it. * - * @param[in] id is the timer id + * In SMP configurations, the processor of the currently executing thread + * determines the processor used for the created timer. During the life-time + * of the timer this processor is used to manage the timer internally. * - * @retval This method returns RTEMS_SUCCESSFUL if there was not an - * error. Otherwise, a status code is returned indicating the - * source of the error. + * @param name is the name of the timer. + * + * @param[out] id is the pointer to an object identifier variable. The + * identifier of the created timer object will be stored in this variable, in + * case of a successful operation. + * + * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. + * + * @retval ::RTEMS_INVALID_NAME The timer name was invalid. + * + * @retval ::RTEMS_INVALID_ADDRESS The ``id`` parameter was NULL. + * + * @retval ::RTEMS_TOO_MANY There was no inactive object available to create a + * new timer. The number of timers available to the application is + * configured through the #CONFIGURE_MAXIMUM_TIMERS configuration option. */ -rtems_status_code rtems_timer_delete( - rtems_id id -); +rtems_status_code rtems_timer_create( rtems_name name, rtems_id *id ); + +/* Generated from spec:/rtems/timer/if/ident */ /** - * @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. + * @ingroup RTEMSAPIClassicTimer + * + * @brief Identifies a timer by the object name. + * + * This directive obtains the timer identifier associated with the timer name + * specified in ``name``. + * + * If the timer name is not unique, then the timer identifier will match the + * first timer with that name in the search order. However, this timer + * identifier is not guaranteed to correspond to the desired timer. The timer + * identifier is used with other timer related directives to access the timer. + * + * The objects are searched from lowest to the highest index. Only the local + * node is searched. + * + * @param name is the object name to look up. + * + * @param[out] id is the pointer to an object identifier variable. The object + * identifier of an object with the specified name will be stored in this + * variable, in case of a successful operation. + * + * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. + * + * @retval ::RTEMS_INVALID_ADDRESS The ``id`` parameter was NULL. + * + * @retval ::RTEMS_INVALID_NAME The ``name`` parameter was 0. + * + * @retval ::RTEMS_INVALID_NAME There was no object with the specified name on + * the local node. */ -rtems_status_code rtems_timer_fire_after( - rtems_id id, - rtems_interval ticks, - rtems_timer_service_routine_entry routine, - void *user_data -); +rtems_status_code rtems_timer_ident( rtems_name name, rtems_id *id ); + +/* Generated from spec:/rtems/timer/if/cancel */ /** - * @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. + * @ingroup RTEMSAPIClassicTimer + * + * @brief Cancels the timer. + * + * This directive cancels the timer specified in the ``id`` parameter. This + * timer will be reinitiated by the next invocation of rtems_timer_reset(), + * rtems_timer_fire_after(), or rtems_timer_fire_when() with the same timer + * identifier. + * + * This directive will not cause the running task to be preempted. + * + * @param id is the timer identifier. + * + * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. + * + * @retval ::RTEMS_INVALID_ID There was no timer associated with the identifier + * specified by ``id``. */ -rtems_status_code rtems_timer_server_fire_after( - rtems_id id, - rtems_interval ticks, - rtems_timer_service_routine_entry routine, - void *user_data -); +rtems_status_code rtems_timer_cancel( rtems_id id ); + +/* Generated from spec:/rtems/timer/if/delete */ /** - * @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. + * @ingroup RTEMSAPIClassicTimer + * + * @brief Deletes the timer. + * + * This directive deletes the timer specified by the ``id`` parameter. If the + * timer is running, it is automatically canceled. + * + * This directive may cause the calling task to be preempted due to an obtain + * and release of the object allocator mutex. + * + * The TMCB for the deleted timer is reclaimed by RTEMS. + * + * A timer can be deleted by a task other than the task which created the + * timer. + * + * @param id is the timer identifier. + * + * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. + * + * @retval ::RTEMS_INVALID_ID There was no timer associated with the identifier + * specified by ``id``. */ -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 -); +rtems_status_code rtems_timer_delete( rtems_id id ); + +/* Generated from spec:/rtems/timer/if/fire-after */ /** - * @brief RTEMS Timer Server Fire When Directive + * @ingroup RTEMSAPIClassicTimer + * + * @brief Fires the timer after the interval. * - * Timer Manager - RTEMS Timer Server Fire When Directive + * This directive initiates the timer specified by ``id``. If the timer is + * running, it is automatically canceled before being initiated. The timer is + * scheduled to fire after an interval of clock ticks has passed specified by + * ``ticks``. When the timer fires, the timer service routine ``routine`` will + * be invoked with the argument ``user_data`` in the context of the clock tick + * ISR. * - * 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. + * This directive will not cause the running task to be preempted. + * + * @param id is the timer identifier. + * + * @param ticks is the interval until the routine is fired in clock ticks. + * + * @param routine is the routine to schedule. + * + * @param user_data is the argument passed to the routine when it is fired. + * + * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. + * + * @retval ::RTEMS_INVALID_NUMBER The ``ticks`` parameter was 0. + * + * @retval ::RTEMS_INVALID_ADDRESS The ``routine`` parameter was NULL. + * + * @retval ::RTEMS_INVALID_ID There was no timer associated with the identifier + * specified by ``id``. */ -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 +rtems_status_code rtems_timer_fire_after( + rtems_id id, + rtems_interval ticks, + rtems_timer_service_routine_entry routine, + void *user_data ); +/* Generated from spec:/rtems/timer/if/fire-when */ + /** - * @brief RTEMS Timer Reset + * @ingroup RTEMSAPIClassicTimer + * + * @brief Fires the timer at the time of day. * - * Timer Manager - RTEMS Timer Reset + * This directive initiates the timer specified by ``id``. If the timer is + * running, it is automatically canceled before being initiated. The timer is + * scheduled to fire at the time of day specified by ``wall_time``. When the + * timer fires, the timer service routine ``routine`` will be invoked with the + * argument ``user_data`` in the context of the clock tick ISR. * - * 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. + * This directive will not cause the running task to be preempted. + * + * @param id is the timer identifier. + * + * @param wall_time is the time of day when the routine is fired. + * + * @param routine is the routine to schedule. + * + * @param user_data is the argument passed to the routine when it is fired. + * + * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. + * + * @retval ::RTEMS_NOT_DEFINED The system date and time was not set. + * + * @retval ::RTEMS_INVALID_ADDRESS The ``routine`` parameter was NULL. + * + * @retval ::RTEMS_INVALID_ADDRESS The ``wall_time`` parameter was NULL. + * + * @retval ::RTEMS_INVALID_CLOCK The time of day was invalid. + * + * @retval ::RTEMS_INVALID_ID There was no timer associated with the identifier + * specified by ``id``. */ -rtems_status_code rtems_timer_reset( - rtems_id id +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 ); +/* Generated from spec:/rtems/timer/if/initiate-server */ + /** - * @brief Initiates the timer server. + * @ingroup RTEMSAPIClassicTimer * - * This directive creates and starts the server for task-based timers. - * It must be invoked before any task-based timers can be initiated. + * @brief Initiates the Timer Server. * - * @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. + * This directive initiates the Timer Server task. This task is responsible + * for executing all timers initiated via the rtems_timer_server_fire_after() + * or rtems_timer_server_fire_when() directives. * - * @return This method returns RTEMS_SUCCESSFUL if successful and an - * error code otherwise. + * This directive may cause the calling task to be preempted due to an obtain + * and release of the object allocator mutex. + * + * The Timer Server task is created using the rtems_task_create() directive and + * must be accounted for when configuring the system. + * + * @param priority is the task priority. + * + * @param stack_size is the task stack size in bytes. + * + * @param attribute_set is the task attribute set. + * + * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. + * + * @retval ::RTEMS_INCORRECT_STATE The Timer Server was already initiated. + * + * @retval ::RTEMS_INVALID_PRIORITY The task priority was invalid. + * + * @retval ::RTEMS_TOO_MANY There was no inactive task object available to + * create the Timer Server task. + * + * @retval ::RTEMS_UNSATISFIED There was not enough memory to allocate the task + * storage area. The task storage area contains the task stack, the + * thread-local storage, and the floating point context. + * + * @retval ::RTEMS_UNSATISFIED One of the task create extensions failed to + * create the Timer Server task. */ rtems_status_code rtems_timer_initiate_server( rtems_task_priority priority, @@ -291,50 +495,129 @@ rtems_status_code rtems_timer_initiate_server( 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 +/* Generated from spec:/rtems/timer/if/server-fire-after */ /** - * This is the structure filled in by the timer get information - * service. + * @ingroup RTEMSAPIClassicTimer + * + * @brief Fires the timer after the interval using the Timer Server. + * + * This directive initiates the timer specified by ``id``. If the timer is + * running, it is automatically canceled before being initiated. The timer is + * scheduled to fire after an interval of clock ticks has passed specified by + * ``ticks``. When the timer fires, the timer service routine ``routine`` will + * be invoked with the argument ``user_data`` in the context of the Timer + * Server task. + * + * This directive will not cause the running task to be preempted. + * + * @param id is the timer identifier. + * + * @param ticks is the interval until the routine is fired in clock ticks. + * + * @param routine is the routine to schedule. + * + * @param user_data is the argument passed to the routine when it is fired. + * + * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. + * + * @retval ::RTEMS_INCORRECT_STATE The Timer Server was not initiated. + * + * @retval ::RTEMS_INVALID_NUMBER The ``ticks`` parameter was 0. + * + * @retval ::RTEMS_INVALID_ADDRESS The ``routine`` parameter was NULL. + * + * @retval ::RTEMS_INVALID_ID There was no timer associated with the identifier + * specified by ``id``. */ -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; +rtems_status_code rtems_timer_server_fire_after( + rtems_id id, + rtems_interval ticks, + rtems_timer_service_routine_entry routine, + void *user_data +); + +/* Generated from spec:/rtems/timer/if/server-fire-when */ /** - * @brief RTEMS Get Timer Information + * @ingroup RTEMSAPIClassicTimer * - * This routine implements the rtems_timer_get_information directive. - * This directive returns information about the timer. + * @brief Fires the timer at the time of day using the Timer Server. + * + * This directive initiates the timer specified by ``id``. If the timer is + * running, it is automatically canceled before being initiated. The timer is + * scheduled to fire at the time of day specified by ``wall_time``. When the + * timer fires, the timer service routine ``routine`` will be invoked with the + * argument ``user_data`` in the context of the Timer Server task. + * + * This directive will not cause the running task to be preempted. + * + * @param id is the timer identifier. + * + * @param wall_time is the time of day when the routine is fired. + * + * @param routine is the routine to schedule. * - * @param[in] id is the timer id - * @param[in] the_info is the pointer to timer information block + * @param user_data is the argument passed to the routine when it is fired. * - * @retval RTEMS_SUCCESSFUL if successful or error code if unsuccessful and - * *the_info region information block filled in + * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. + * + * @retval ::RTEMS_INCORRECT_STATE The Timer Server was not initiated. + * + * @retval ::RTEMS_NOT_DEFINED The system date and time was not set. + * + * @retval ::RTEMS_INVALID_ADDRESS The ``routine`` parameter was NULL. + * + * @retval ::RTEMS_INVALID_ADDRESS The ``wall_time`` parameter was NULL. + * + * @retval ::RTEMS_INVALID_CLOCK The time of day was invalid. + * + * @retval ::RTEMS_INVALID_ID There was no timer associated with the identifier + * specified by ``id``. */ -rtems_status_code rtems_timer_get_information( - rtems_id id, - rtems_timer_information *the_info +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 ); -/**@}*/ +/* Generated from spec:/rtems/timer/if/reset */ + +/** + * @ingroup RTEMSAPIClassicTimer + * + * @brief Resets the timer. + * + * This directive resets the timer specified by ``id``. This timer must have + * been previously initiated with either the rtems_timer_fire_after() or + * rtems_timer_server_fire_after() directive. If active the timer is canceled, + * after which the timer is reinitiated using the same interval and timer + * service routine which the original rtems_timer_fire_after() or + * rtems_timer_server_fire_after() directive used. + * + * This directive will not cause the running task to be preempted. + * + * If the timer has not been used or the last usage of this timer was by a + * rtems_timer_fire_when() or rtems_timer_server_fire_when() directive, then + * the ::RTEMS_NOT_DEFINED error is returned. + * + * Restarting a cancelled after timer results in the timer being reinitiated + * with its previous timer service routine and interval. + * + * @param id is the timer identifier. + * + * @retval ::RTEMS_SUCCESSFUL The requested operation was successful. + * + * @retval ::RTEMS_INVALID_ID There was no timer associated with the identifier + * specified by ``id``. + * + * @retval ::RTEMS_NOT_DEFINED The timer was not of the interval class. + */ +rtems_status_code rtems_timer_reset( rtems_id id ); #ifdef __cplusplus } #endif -#endif -/* end of include file */ +#endif /* _RTEMS_RTEMS_TIMER_H */ -- cgit v1.2.3