[rtems commit] rtems: Generate <rtems/rtems/timer.h>
Sebastian Huber
sebh at rtems.org
Thu Dec 3 06:25:02 UTC 2020
Module: rtems
Branch: master
Commit: 768327d06de3fbcf372ae2fe04199a036bc3234a
Changeset: http://git.rtems.org/rtems/commit/?id=768327d06de3fbcf372ae2fe04199a036bc3234a
Author: Sebastian Huber <sebastian.huber at embedded-brains.de>
Date: Mon Jun 22 13:36:21 2020 +0200
rtems: Generate <rtems/rtems/timer.h>
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 244d560..3d454e3 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 */
More information about the vc
mailing list