Changeset 768327d0 in rtems


Ignore:
Timestamp:
Jun 22, 2020, 11:36:21 AM (7 months ago)
Author:
Sebastian Huber <sebastian.huber@…>
Branches:
master
Children:
7930fbdd
Parents:
e2f888d1
git-author:
Sebastian Huber <sebastian.huber@…> (06/22/20 11:36:21)
git-committer:
Sebastian Huber <sebastian.huber@…> (12/03/20 06:12:12)
Message:

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.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • cpukit/include/rtems/rtems/timer.h

    re2f888d1 r768327d0  
     1/* SPDX-License-Identifier: BSD-2-Clause */
     2
    13/**
    24 * @file
    35 *
    4  * @ingroup ClassicTimer
    5  *
    6  * @brief Classic Timer Manager API
     6 * @ingroup RTEMSImplClassicTimer
     7 *
     8 * @brief This header file provides the Timer Manager API.
    79 */
    810
    911/*
    10  * COPYRIGHT (c) 1989-2011.
    11  * On-Line Applications Research Corporation (OAR).
    12  *
    13  * Copyright (c) 2009, 2016 embedded brains GmbH.
    14  *
    15  * The license and distribution terms for this file may be
    16  * found in the file LICENSE in this distribution or at
    17  * http://www.rtems.org/license/LICENSE.
    18  */
     12 * Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
     13 * Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
     14 *
     15 * Redistribution and use in source and binary forms, with or without
     16 * modification, are permitted provided that the following conditions
     17 * are met:
     18 * 1. Redistributions of source code must retain the above copyright
     19 *    notice, this list of conditions and the following disclaimer.
     20 * 2. Redistributions in binary form must reproduce the above copyright
     21 *    notice, this list of conditions and the following disclaimer in the
     22 *    documentation and/or other materials provided with the distribution.
     23 *
     24 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
     25 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
     26 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
     27 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
     28 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
     29 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
     30 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
     31 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
     32 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
     33 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
     34 * POSSIBILITY OF SUCH DAMAGE.
     35 */
     36
     37/*
     38 * This file is part of the RTEMS quality process and was automatically
     39 * generated.  If you find something that needs to be fixed or
     40 * worded better please post a report or patch to an RTEMS mailing list
     41 * or raise a bug report:
     42 *
     43 * https://docs.rtems.org/branches/master/user/support/bugs.html
     44 *
     45 * For information on updating and regenerating please refer to:
     46 *
     47 * https://docs.rtems.org/branches/master/eng/req/howto.html
     48 */
     49
     50/* Generated from spec:/rtems/timer/if/header */
    1951
    2052#ifndef _RTEMS_RTEMS_TIMER_H
    2153#define _RTEMS_RTEMS_TIMER_H
    2254
     55#include <stddef.h>
    2356#include <rtems/rtems/attr.h>
    2457#include <rtems/rtems/status.h>
    2558#include <rtems/rtems/tasks.h>
    2659#include <rtems/rtems/types.h>
     60#include <rtems/score/watchdogticks.h>
    2761
    2862#ifdef __cplusplus
     
    3064#endif
    3165
    32 /**
    33  *  @defgroup ClassicTimer Timers
    34  *
    35  *  @ingroup RTEMSAPIClassic
    36  *
    37  *  This encapsulates functionality related to the Classic API Timer
    38  *  Manager.  This manager provides functionality which allows the
    39  *  application to schedule the execution of methods at a specified
    40  *  time in the future.  These methods may be scheduled based upon
    41  *  interval or wall time and may be executed in either the clock tick
    42  *  ISR or in a special dedicated timer server task.
    43  */
    44 /**@{*/
    45 
     66/* Generated from spec:/rtems/timer/if/group */
     67
     68/**
     69 * @defgroup RTEMSAPIClassicTimer Timer Manager
     70 *
     71 * @ingroup RTEMSAPIClassic
     72 *
     73 * @brief The Timer Manager provides support for timer facilities.
     74 */
     75
     76/* Generated from spec:/rtems/timer/if/class-bit-not-dormant */
     77
     78/**
     79 * @ingroup RTEMSAPIClassicTimer
     80 *
     81 * @brief This timer class bit indicates that the timer is not dormant.
     82 */
     83#define TIMER_CLASS_BIT_NOT_DORMANT 0x4
     84
     85/* Generated from spec:/rtems/timer/if/class-bit-on-task */
     86
     87/**
     88 * @ingroup RTEMSAPIClassicTimer
     89 *
     90 * @brief This timer class bit indicates that the timer routine executes in a
     91 *   task context.
     92 */
     93#define TIMER_CLASS_BIT_ON_TASK 0x2
     94
     95/* Generated from spec:/rtems/timer/if/class-bit-time-of-day */
     96
     97/**
     98 * @ingroup RTEMSAPIClassicTimer
     99 *
     100 * @brief This timer class bit indicates that the timer uses a time of day.
     101 */
    46102#define TIMER_CLASS_BIT_TIME_OF_DAY 0x1
    47103
    48 #define TIMER_CLASS_BIT_ON_TASK 0x2
    49 
    50 #define TIMER_CLASS_BIT_NOT_DORMANT 0x4
    51 
    52 /**
    53  *  The following enumerated type details the classes to which a timer
    54  *  may belong.
     104/* Generated from spec:/rtems/timer/if/classes */
     105
     106/**
     107 * @ingroup RTEMSAPIClassicTimer
     108 *
     109 * @brief The timer class indicates how the timer was most recently fired.
    55110 */
    56111typedef enum {
    57112  /**
    58    * This value indicates the timer is currently not in use.
     113   * @brief This timer class indicates that the timer was never in use.
    59114   */
    60115  TIMER_DORMANT,
    61116
    62117  /**
    63    * This value indicates the timer is currently in use as an interval
    64    * timer which will fire in the clock tick ISR.
     118   * @brief This timer class indicates that the timer is currently in use as an
     119   *   interval timer which will fire in the context of the clock tick ISR.
    65120   */
    66121  TIMER_INTERVAL = TIMER_CLASS_BIT_NOT_DORMANT,
    67122
    68123  /**
    69    * This value indicates the timer is currently in use as an interval
    70    * timer which will fire in the timer server task.
    71    */
    72   TIMER_INTERVAL_ON_TASK =
    73     TIMER_CLASS_BIT_NOT_DORMANT | TIMER_CLASS_BIT_ON_TASK,
    74 
    75   /**
    76    * This value indicates the timer is currently in use as an time of day
    77    * timer which will fire in the clock tick ISR.
    78    */
    79   TIMER_TIME_OF_DAY =
    80     TIMER_CLASS_BIT_NOT_DORMANT | TIMER_CLASS_BIT_TIME_OF_DAY,
    81 
    82   /**
    83    * This value indicates the timer is currently in use as an time of day
    84    * timer which will fire in the timer server task.
    85    */
    86   TIMER_TIME_OF_DAY_ON_TASK =
    87     TIMER_CLASS_BIT_NOT_DORMANT | TIMER_CLASS_BIT_TIME_OF_DAY |
     124   * @brief This timer class indicates that the timer is currently in use as an
     125   *   interval timer which will fire in the context of the Timer Server task.
     126   */
     127  TIMER_INTERVAL_ON_TASK = TIMER_CLASS_BIT_NOT_DORMANT |
     128    TIMER_CLASS_BIT_ON_TASK,
     129
     130  /**
     131   * @brief This timer class indicates that the timer is currently in use as an
     132   *   time of day timer which will fire in the context of the clock tick ISR.
     133   */
     134  TIMER_TIME_OF_DAY = TIMER_CLASS_BIT_NOT_DORMANT |
     135    TIMER_CLASS_BIT_TIME_OF_DAY,
     136
     137  /**
     138   * @brief This timer class indicates that the timer is currently in use as an
     139   *   time of day timer which will fire in the context of the Timer Server task.
     140   */
     141  TIMER_TIME_OF_DAY_ON_TASK = TIMER_CLASS_BIT_NOT_DORMANT |
     142    TIMER_CLASS_BIT_TIME_OF_DAY |
    88143    TIMER_CLASS_BIT_ON_TASK
    89144} Timer_Classes;
    90145
    91 /**
    92  *  The following types define a pointer to a timer service routine.
     146/* Generated from spec:/rtems/timer/if/information */
     147
     148/**
     149 * @ingroup RTEMSAPIClassicTimer
     150 *
     151 * @brief The structure contains information about a timer.
     152 */
     153typedef struct {
     154  /**
     155   * @brief The timer class member indicates how the timer was most recently
     156   *   fired.
     157   */
     158  Timer_Classes the_class;
     159
     160  /**
     161   * @brief This member indicates the initial requested interval.
     162   */
     163  Watchdog_Interval initial;
     164
     165  /**
     166   * @brief This member indicates the time the timer was initially scheduled.
     167   *
     168   * The time is in clock ticks since the clock driver initialization or the last
     169   * clock tick counter overflow.
     170   */
     171  Watchdog_Interval start_time;
     172
     173  /**
     174   * @brief This member indicates the time the timer was scheduled to fire.
     175   *
     176   * The time is in clock ticks since the clock driver initialization or the last
     177   * clock tick counter overflow.
     178   */
     179  Watchdog_Interval stop_time;
     180} rtems_timer_information;
     181
     182/* Generated from spec:/rtems/timer/if/get-information */
     183
     184/**
     185 * @ingroup RTEMSAPIClassicTimer
     186 *
     187 * @brief Gets information about the timer.
     188 *
     189 * This directive returns information about the timer.
     190 *
     191 * This directive will not cause the running task to be preempted.
     192 *
     193 * @param id is the timer identifier.
     194 *
     195 * @param[out] the_info is the pointer to a timer information variable.  The
     196 *   information about the timer will be stored in this variable, in case of a
     197 *   successful operation.
     198 *
     199 * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
     200 *
     201 * @retval ::RTEMS_INVALID_ADDRESS The ``the_info`` parameter was NULL.
     202 *
     203 * @retval ::RTEMS_INVALID_ID There was no timer associated with the identifier
     204 *   specified by ``id``.
     205 */
     206rtems_status_code rtems_timer_get_information(
     207  rtems_id                 id,
     208  rtems_timer_information *the_info
     209);
     210
     211/* Generated from spec:/rtems/timer/if/server-default-priority */
     212
     213/**
     214 * @ingroup RTEMSAPIClassicTimer
     215 *
     216 * @brief This constant represents the default value for the task priority of
     217 *   the Timer Server.
     218 *
     219 * When given this priority, a special high priority not accessible via the
     220 * Classic API is used.
     221 */
     222#define RTEMS_TIMER_SERVER_DEFAULT_PRIORITY ( (rtems_task_priority) -1 )
     223
     224/* Generated from spec:/rtems/timer/if/service-routine */
     225
     226/**
     227 * @ingroup RTEMSAPIClassicTimer
     228 *
     229 * @brief This type defines the return type of routines which can be fired by
     230 *   directives of the Timer Manager.
     231 *
     232 * This type can be used to document timer service routines in the source code.
    93233 */
    94234typedef void rtems_timer_service_routine;
    95235
    96 /**
    97  *  This type defines the type used to manage and indirectly invoke
    98  *  Timer Service Routines (TSRs).  This defines the prototype and interface
    99  *  for a function which is to be used as a TSR.
    100  */
    101 typedef rtems_timer_service_routine ( *rtems_timer_service_routine_entry )(
    102                  rtems_id,
    103                  void *
    104              );
    105 
    106 /**
    107  * @brief RTEMS Create Timer
    108  *
    109  * This routine implements the rtems_timer_create directive. The
    110  * timer will have the name name. It returns the id of the
    111  * created timer in ID.
    112  *
    113  * @param[in] name is the timer name
    114  * @param[out] id is the pointer to timer id
    115  *
    116  * @retval RTEMS_SUCCESSFUL if successful or error code if unsuccessful
    117  */
    118 rtems_status_code rtems_timer_create(
    119   rtems_name    name,
    120   rtems_id     *id
     236/* Generated from spec:/rtems/timer/if/service-routine-entry */
     237
     238/**
     239 * @ingroup RTEMSAPIClassicTimer
     240 *
     241 * @brief This type defines the prototype of routines which can be fired by
     242 *   directives of the Timer Manager.
     243 */
     244typedef rtems_timer_service_routine ( *rtems_timer_service_routine_entry )( rtems_id, void * );
     245
     246/* Generated from spec:/rtems/timer/if/create */
     247
     248/**
     249 * @ingroup RTEMSAPIClassicTimer
     250 *
     251 * @brief Creates a timer.
     252 *
     253 * This directive creates a timer.  The assigned object identifier is returned
     254 * in ``id``.  This identifier is used to access the timer with other timer
     255 * related directives.
     256 *
     257 * This directive may cause the calling task to be preempted due to an obtain
     258 * and release of the object allocator mutex.
     259 *
     260 * For control and maintenance of the timer, RTEMS allocates a TMCB from the
     261 * local TMCB free pool and initializes it.
     262 *
     263 * In SMP configurations, the processor of the currently executing thread
     264 * determines the processor used for the created timer.  During the life-time
     265 * of the timer this processor is used to manage the timer internally.
     266 *
     267 * @param name is the name of the timer.
     268 *
     269 * @param[out] id is the pointer to an object identifier variable.  The
     270 *   identifier of the created timer object will be stored in this variable, in
     271 *   case of a successful operation.
     272 *
     273 * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
     274 *
     275 * @retval ::RTEMS_INVALID_NAME The timer name was invalid.
     276 *
     277 * @retval ::RTEMS_INVALID_ADDRESS The ``id`` parameter was NULL.
     278 *
     279 * @retval ::RTEMS_TOO_MANY There was no inactive object available to create a
     280 *   new timer.  The number of timers available to the application is
     281 *   configured through the #CONFIGURE_MAXIMUM_TIMERS configuration option.
     282 */
     283rtems_status_code rtems_timer_create( rtems_name name, rtems_id *id );
     284
     285/* Generated from spec:/rtems/timer/if/ident */
     286
     287/**
     288 * @ingroup RTEMSAPIClassicTimer
     289 *
     290 * @brief Identifies a timer by the object name.
     291 *
     292 * This directive obtains the timer identifier associated with the timer name
     293 * specified in ``name``.
     294 *
     295 * If the timer name is not unique, then the timer identifier will match the
     296 * first timer with that name in the search order.  However, this timer
     297 * identifier is not guaranteed to correspond to the desired timer.  The timer
     298 * identifier is used with other timer related directives to access the timer.
     299 *
     300 * The objects are searched from lowest to the highest index.  Only the local
     301 * node is searched.
     302 *
     303 * @param name is the object name to look up.
     304 *
     305 * @param[out] id is the pointer to an object identifier variable.  The object
     306 *   identifier of an object with the specified name will be stored in this
     307 *   variable, in case of a successful operation.
     308 *
     309 * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
     310 *
     311 * @retval ::RTEMS_INVALID_ADDRESS The ``id`` parameter was NULL.
     312 *
     313 * @retval ::RTEMS_INVALID_NAME The ``name`` parameter was 0.
     314 *
     315 * @retval ::RTEMS_INVALID_NAME There was no object with the specified name on
     316 *   the local node.
     317 */
     318rtems_status_code rtems_timer_ident( rtems_name name, rtems_id *id );
     319
     320/* Generated from spec:/rtems/timer/if/cancel */
     321
     322/**
     323 * @ingroup RTEMSAPIClassicTimer
     324 *
     325 * @brief Cancels the timer.
     326 *
     327 * This directive cancels the timer specified in the ``id`` parameter.  This
     328 * timer will be reinitiated by the next invocation of rtems_timer_reset(),
     329 * rtems_timer_fire_after(), or rtems_timer_fire_when() with the same timer
     330 * identifier.
     331 *
     332 * This directive will not cause the running task to be preempted.
     333 *
     334 * @param id is the timer identifier.
     335 *
     336 * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
     337 *
     338 * @retval ::RTEMS_INVALID_ID There was no timer associated with the identifier
     339 *   specified by ``id``.
     340 */
     341rtems_status_code rtems_timer_cancel( rtems_id id );
     342
     343/* Generated from spec:/rtems/timer/if/delete */
     344
     345/**
     346 * @ingroup RTEMSAPIClassicTimer
     347 *
     348 * @brief Deletes the timer.
     349 *
     350 * This directive deletes the timer specified by the ``id`` parameter.  If the
     351 * timer is running, it is automatically canceled.
     352 *
     353 * This directive may cause the calling task to be preempted due to an obtain
     354 * and release of the object allocator mutex.
     355 *
     356 * The TMCB for the deleted timer is reclaimed by RTEMS.
     357 *
     358 * A timer can be deleted by a task other than the task which created the
     359 * timer.
     360 *
     361 * @param id is the timer identifier.
     362 *
     363 * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
     364 *
     365 * @retval ::RTEMS_INVALID_ID There was no timer associated with the identifier
     366 *   specified by ``id``.
     367 */
     368rtems_status_code rtems_timer_delete( rtems_id id );
     369
     370/* Generated from spec:/rtems/timer/if/fire-after */
     371
     372/**
     373 * @ingroup RTEMSAPIClassicTimer
     374 *
     375 * @brief Fires the timer after the interval.
     376 *
     377 * This directive initiates the timer specified by ``id``.  If the timer is
     378 * running, it is automatically canceled before being initiated.  The timer is
     379 * scheduled to fire after an interval of clock ticks has passed specified by
     380 * ``ticks``.  When the timer fires, the timer service routine ``routine`` will
     381 * be invoked with the argument ``user_data`` in the context of the clock tick
     382 * ISR.
     383 *
     384 * This directive will not cause the running task to be preempted.
     385 *
     386 * @param id is the timer identifier.
     387 *
     388 * @param ticks is the interval until the routine is fired in clock ticks.
     389 *
     390 * @param routine is the routine to schedule.
     391 *
     392 * @param user_data is the argument passed to the routine when it is fired.
     393 *
     394 * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
     395 *
     396 * @retval ::RTEMS_INVALID_NUMBER The ``ticks`` parameter was 0.
     397 *
     398 * @retval ::RTEMS_INVALID_ADDRESS The ``routine`` parameter was NULL.
     399 *
     400 * @retval ::RTEMS_INVALID_ID There was no timer associated with the identifier
     401 *   specified by ``id``.
     402 */
     403rtems_status_code rtems_timer_fire_after(
     404  rtems_id                          id,
     405  rtems_interval                    ticks,
     406  rtems_timer_service_routine_entry routine,
     407  void                             *user_data
    121408);
    122409
    123 /**
    124  * @brief RTEMS Timer Name to Id
    125  *
    126  * This routine implements the rtems_timer_ident directive.
    127  * This directive returns the timer ID associated with name.
    128  * If more than one timer is named name, then the timer
    129  * to which the ID belongs is arbitrary.
    130  *
    131  * @param[in] name is the user defined message queue name
    132  * @param[in] id is the pointer to timer id
    133  *
    134  * @retval RTEMS_SUCCESSFUL if successful or error code if unsuccessful and
    135  * id filled with the message queue id
    136  */
    137 rtems_status_code rtems_timer_ident(
    138   rtems_name    name,
    139   rtems_id     *id
     410/* Generated from spec:/rtems/timer/if/fire-when */
     411
     412/**
     413 * @ingroup RTEMSAPIClassicTimer
     414 *
     415 * @brief Fires the timer at the time of day.
     416 *
     417 * This directive initiates the timer specified by ``id``.  If the timer is
     418 * running, it is automatically canceled before being initiated.  The timer is
     419 * scheduled to fire at the time of day specified by ``wall_time``.  When the
     420 * timer fires, the timer service routine ``routine`` will be invoked with the
     421 * argument ``user_data`` in the context of the clock tick ISR.
     422 *
     423 * This directive will not cause the running task to be preempted.
     424 *
     425 * @param id is the timer identifier.
     426 *
     427 * @param wall_time is the time of day when the routine is fired.
     428 *
     429 * @param routine is the routine to schedule.
     430 *
     431 * @param user_data is the argument passed to the routine when it is fired.
     432 *
     433 * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
     434 *
     435 * @retval ::RTEMS_NOT_DEFINED The system date and time was not set.
     436 *
     437 * @retval ::RTEMS_INVALID_ADDRESS The ``routine`` parameter was NULL.
     438 *
     439 * @retval ::RTEMS_INVALID_ADDRESS The ``wall_time`` parameter was NULL.
     440 *
     441 * @retval ::RTEMS_INVALID_CLOCK The time of day was invalid.
     442 *
     443 * @retval ::RTEMS_INVALID_ID There was no timer associated with the identifier
     444 *   specified by ``id``.
     445 */
     446rtems_status_code rtems_timer_fire_when(
     447  rtems_id                          id,
     448  rtems_time_of_day                *wall_time,
     449  rtems_timer_service_routine_entry routine,
     450  void                             *user_data
    140451);
    141452
    142 /**
    143  *  @brief rtems_timer_cancel
    144  *
    145  *  This routine implements the rtems_timer_cancel directive.  It is used
    146  *  to stop the timer associated with ID from firing.
    147  */
    148 rtems_status_code rtems_timer_cancel(
    149   rtems_id   id
    150 );
    151 
    152 /**
    153  * @brief RTEMS Delete Timer
    154  *
    155  * This routine implements the rtems_timer_delete directive. The
    156  * timer indicated by ID is deleted.
    157  *
    158  * @param[in] id is the timer id
    159  *
    160  * @retval This method returns RTEMS_SUCCESSFUL if there was not an
    161  *         error. Otherwise, a status code is returned indicating the
    162  *         source of the error.
    163  */
    164 rtems_status_code rtems_timer_delete(
    165   rtems_id   id
    166 );
    167 
    168 /**
    169  * @brief RTEMS Timer Fire After
    170  *
    171  * This routine implements the rtems_timer_fire_after directive. It
    172  * initiates the timer associated with ID to fire in ticks clock ticks.
    173  * When the timer fires, the routine will be invoked in the context
    174  * of the rtems_clock_tick directive which is normally invoked as
    175  * part of servicing a periodic interupt.
    176  *
    177  * @param[in] id is the timer id
    178  * @param[in] ticks is the interval until routine is fired
    179  * @param[in] routine is the routine to schedule
    180  * @param[in] user_data is the passed as argument to routine when it is fired
    181  *
    182  * @retval This method returns RTEMS_SUCCESSFUL if there was not an
    183  *         error. Otherwise, a status code is returned indicating the
    184  *         source of the error.
    185  */
    186 rtems_status_code rtems_timer_fire_after(
    187   rtems_id                           id,
    188   rtems_interval                     ticks,
    189   rtems_timer_service_routine_entry  routine,
    190   void                              *user_data
    191 );
    192 
    193 /**
    194  * @brief RTEMS Timer Server Fire After
    195  *
    196  * This routine implements the rtems_timer_server_fire_after directive. It
    197  * initiates the timer associated with ID to fire in ticks clock
    198  * ticks. When the timer fires, the routine will be invoked by the
    199  * Timer Server in the context of a task NOT IN THE CONTEXT of the
    200  * clock tick interrupt.
    201  *
    202  * @param[in] id is the timer id
    203  * @param[in] ticks is the interval until routine is fired
    204  * @param[in] routine is the routine to schedule
    205  * @param[in] user_data is the passed as argument to routine when it is fired
    206  *
    207  * @retval This method returns RTEMS_SUCCESSFUL if there was not an
    208  *         error. Otherwise, a status code is returned indicating the
    209  *         source of the error.
    210  */
    211 rtems_status_code rtems_timer_server_fire_after(
    212   rtems_id                           id,
    213   rtems_interval                     ticks,
    214   rtems_timer_service_routine_entry  routine,
    215   void                              *user_data
    216 );
    217 
    218 /**
    219  * @brief RTEMS Timer Fire When
    220  *
    221  * This routine implements the rtems_timer_fire_when directive. It
    222  * initiates the timer associated with ID to fire at wall_time
    223  * When the timer fires, the routine will be invoked in the context
    224  * of the rtems_clock_tick directive which is normally invoked as
    225  * part of servicing a periodic interupt.
    226  *
    227  * @param[in] id is the timer id
    228  * @param[in] wall_time is the time of day to fire timer
    229  * @param[in] routine is the routine to schedule
    230  * @param[in] user_data is the passed as argument to routine when it is fired
    231  *
    232  * @retval This method returns RTEMS_SUCCESSFUL if there was not an
    233  *         error. Otherwise, a status code is returned indicating the
    234  *         source of the error.
    235  */
    236 rtems_status_code rtems_timer_fire_when(
    237   rtems_id                            id,
    238   rtems_time_of_day                  *wall_time,
    239   rtems_timer_service_routine_entry   routine,
    240   void                               *user_data
    241 );
    242 
    243 /**
    244  *  @brief RTEMS Timer Server Fire When Directive
    245  *
    246  *  Timer Manager - RTEMS Timer Server Fire When Directive
    247  *
    248  *  This routine implements the rtems_timer_server_fire_when directive.  It
    249  *  initiates the timer associated with ID to fire at wall_time
    250  *  When the timer fires, the routine will be invoked by the
    251  *  Timer Server in the context of a task NOT IN THE CONTEXT of the
    252  *  clock tick interrupt.
    253  */
    254 rtems_status_code rtems_timer_server_fire_when(
    255   rtems_id                            id,
    256   rtems_time_of_day                  *wall_time,
    257   rtems_timer_service_routine_entry   routine,
    258   void                               *user_data
    259 );
    260 
    261 /**
    262  *  @brief RTEMS Timer Reset
    263  *
    264  *  Timer Manager - RTEMS Timer Reset
    265  *
    266  *  This routine implements the rtems_timer_reset directive.  It is used
    267  *  to reinitialize the interval timer associated with ID just as if
    268  *  rtems_timer_fire_after were re-invoked with the same arguments that
    269  *  were used to initiate this timer.
    270  */
    271 rtems_status_code rtems_timer_reset(
    272   rtems_id   id
    273 );
    274 
    275 /**
    276  *  @brief Initiates the timer server.
    277  *
    278  *  This directive creates and starts the server for task-based timers.
    279  *  It must be invoked before any task-based timers can be initiated.
    280  *
    281  *  @param priority The timer server task priority.
    282  *  @param stack_size The stack size in bytes for the timer server task.
    283  *  @param attribute_set The timer server task attributes.
    284  *
    285  *  @return This method returns RTEMS_SUCCESSFUL if successful and an
    286  *          error code otherwise.
     453/* Generated from spec:/rtems/timer/if/initiate-server */
     454
     455/**
     456 * @ingroup RTEMSAPIClassicTimer
     457 *
     458 * @brief Initiates the Timer Server.
     459 *
     460 * This directive initiates the Timer Server task.  This task is responsible
     461 * for executing all timers initiated via the rtems_timer_server_fire_after()
     462 * or rtems_timer_server_fire_when() directives.
     463 *
     464 * This directive may cause the calling task to be preempted due to an obtain
     465 * and release of the object allocator mutex.
     466 *
     467 * The Timer Server task is created using the rtems_task_create() directive and
     468 * must be accounted for when configuring the system.
     469 *
     470 * @param priority is the task priority.
     471 *
     472 * @param stack_size is the task stack size in bytes.
     473 *
     474 * @param attribute_set is the task attribute set.
     475 *
     476 * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
     477 *
     478 * @retval ::RTEMS_INCORRECT_STATE The Timer Server was already initiated.
     479 *
     480 * @retval ::RTEMS_INVALID_PRIORITY The task priority was invalid.
     481 *
     482 * @retval ::RTEMS_TOO_MANY There was no inactive task object available to
     483 *   create the Timer Server task.
     484 *
     485 * @retval ::RTEMS_UNSATISFIED There was not enough memory to allocate the task
     486 *   storage area.  The task storage area contains the task stack, the
     487 *   thread-local storage, and the floating point context.
     488 *
     489 * @retval ::RTEMS_UNSATISFIED One of the task create extensions failed to
     490 *   create the Timer Server task.
    287491 */
    288492rtems_status_code rtems_timer_initiate_server(
     
    292496);
    293497
    294 /**
    295  *  This is the default value for the priority of the Timer Server.
    296  *  When given this priority, a special high priority not accessible
    297  *  via the Classic API is used.
    298  */
    299 #define RTEMS_TIMER_SERVER_DEFAULT_PRIORITY (uint32_t) -1
    300 
    301 /**
    302  *  This is the structure filled in by the timer get information
    303  *  service.
    304  */
    305 typedef struct {
    306   /** This indicates the current type of the timer. */
    307   Timer_Classes      the_class;
    308   /** This indicates the initial requested interval. */
    309   Watchdog_Interval  initial;
    310   /** This indicates the time the timer was initially scheduled. */
    311   Watchdog_Interval  start_time;
    312   /** This indicates the time the timer is scheduled to fire. */
    313   Watchdog_Interval  stop_time;
    314 } rtems_timer_information;
    315 
    316 /**
    317  * @brief RTEMS Get Timer Information
    318  *
    319  * This routine implements the rtems_timer_get_information directive.
    320  * This directive returns information about the timer.
    321  *
    322  * @param[in] id is the timer id
    323  * @param[in] the_info is the pointer to timer information block
    324  *
    325  * @retval RTEMS_SUCCESSFUL if successful or error code if unsuccessful and
    326  *              *the_info region information block filled in
    327  */
    328 rtems_status_code rtems_timer_get_information(
    329   rtems_id                 id,
    330   rtems_timer_information *the_info
     498/* Generated from spec:/rtems/timer/if/server-fire-after */
     499
     500/**
     501 * @ingroup RTEMSAPIClassicTimer
     502 *
     503 * @brief Fires the timer after the interval using the Timer Server.
     504 *
     505 * This directive initiates the timer specified by ``id``.  If the timer is
     506 * running, it is automatically canceled before being initiated.  The timer is
     507 * scheduled to fire after an interval of clock ticks has passed specified by
     508 * ``ticks``.  When the timer fires, the timer service routine ``routine`` will
     509 * be invoked with the argument ``user_data`` in the context of the Timer
     510 * Server task.
     511 *
     512 * This directive will not cause the running task to be preempted.
     513 *
     514 * @param id is the timer identifier.
     515 *
     516 * @param ticks is the interval until the routine is fired in clock ticks.
     517 *
     518 * @param routine is the routine to schedule.
     519 *
     520 * @param user_data is the argument passed to the routine when it is fired.
     521 *
     522 * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
     523 *
     524 * @retval ::RTEMS_INCORRECT_STATE The Timer Server was not initiated.
     525 *
     526 * @retval ::RTEMS_INVALID_NUMBER The ``ticks`` parameter was 0.
     527 *
     528 * @retval ::RTEMS_INVALID_ADDRESS The ``routine`` parameter was NULL.
     529 *
     530 * @retval ::RTEMS_INVALID_ID There was no timer associated with the identifier
     531 *   specified by ``id``.
     532 */
     533rtems_status_code rtems_timer_server_fire_after(
     534  rtems_id                          id,
     535  rtems_interval                    ticks,
     536  rtems_timer_service_routine_entry routine,
     537  void                             *user_data
    331538);
    332539
    333 /**@}*/
     540/* Generated from spec:/rtems/timer/if/server-fire-when */
     541
     542/**
     543 * @ingroup RTEMSAPIClassicTimer
     544 *
     545 * @brief Fires the timer at the time of day using the Timer Server.
     546 *
     547 * This directive initiates the timer specified by ``id``.  If the timer is
     548 * running, it is automatically canceled before being initiated.  The timer is
     549 * scheduled to fire at the time of day specified by ``wall_time``.  When the
     550 * timer fires, the timer service routine ``routine`` will be invoked with the
     551 * argument ``user_data`` in the context of the Timer Server task.
     552 *
     553 * This directive will not cause the running task to be preempted.
     554 *
     555 * @param id is the timer identifier.
     556 *
     557 * @param wall_time is the time of day when the routine is fired.
     558 *
     559 * @param routine is the routine to schedule.
     560 *
     561 * @param user_data is the argument passed to the routine when it is fired.
     562 *
     563 * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
     564 *
     565 * @retval ::RTEMS_INCORRECT_STATE The Timer Server was not initiated.
     566 *
     567 * @retval ::RTEMS_NOT_DEFINED The system date and time was not set.
     568 *
     569 * @retval ::RTEMS_INVALID_ADDRESS The ``routine`` parameter was NULL.
     570 *
     571 * @retval ::RTEMS_INVALID_ADDRESS The ``wall_time`` parameter was NULL.
     572 *
     573 * @retval ::RTEMS_INVALID_CLOCK The time of day was invalid.
     574 *
     575 * @retval ::RTEMS_INVALID_ID There was no timer associated with the identifier
     576 *   specified by ``id``.
     577 */
     578rtems_status_code rtems_timer_server_fire_when(
     579  rtems_id                          id,
     580  rtems_time_of_day                *wall_time,
     581  rtems_timer_service_routine_entry routine,
     582  void                             *user_data
     583);
     584
     585/* Generated from spec:/rtems/timer/if/reset */
     586
     587/**
     588 * @ingroup RTEMSAPIClassicTimer
     589 *
     590 * @brief Resets the timer.
     591 *
     592 * This directive resets the timer specified by ``id``.  This timer must have
     593 * been previously initiated with either the rtems_timer_fire_after() or
     594 * rtems_timer_server_fire_after() directive.  If active the timer is canceled,
     595 * after which the timer is reinitiated using the same interval and timer
     596 * service routine which the original rtems_timer_fire_after() or
     597 * rtems_timer_server_fire_after() directive used.
     598 *
     599 * This directive will not cause the running task to be preempted.
     600 *
     601 * If the timer has not been used or the last usage of this timer was by a
     602 * rtems_timer_fire_when() or rtems_timer_server_fire_when() directive, then
     603 * the ::RTEMS_NOT_DEFINED error is returned.
     604 *
     605 * Restarting a cancelled after timer results in the timer being reinitiated
     606 * with its previous timer service routine and interval.
     607 *
     608 * @param id is the timer identifier.
     609 *
     610 * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
     611 *
     612 * @retval ::RTEMS_INVALID_ID There was no timer associated with the identifier
     613 *   specified by ``id``.
     614 *
     615 * @retval ::RTEMS_NOT_DEFINED The timer was not of the interval class.
     616 */
     617rtems_status_code rtems_timer_reset( rtems_id id );
    334618
    335619#ifdef __cplusplus
     
    337621#endif
    338622
    339 #endif
    340 /* end of include file */
     623#endif /* _RTEMS_RTEMS_TIMER_H */
Note: See TracChangeset for help on using the changeset viewer.