Looks good to me. On Wed, Dec 2, 2020 at 1:26 AM Sebastian Huber < sebastian.hu...@embedded-brains.de> wrote:
> 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(-) > > 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 <stddef.h> > #include <rtems/rtems/attr.h> > #include <rtems/rtems/status.h> > #include <rtems/rtems/tasks.h> > #include <rtems/rtems/types.h> > +#include <rtems/score/watchdogticks.h> > > #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 */ > -- > 2.26.2 > > _______________________________________________ > devel mailing list > devel@rtems.org > http://lists.rtems.org/mailman/listinfo/devel >
_______________________________________________ devel mailing list devel@rtems.org http://lists.rtems.org/mailman/listinfo/devel
