Generate <rtems/rtems/timer.h>

1 files changed, 215 insertions, 210 deletions

diff --git a/cpukit/include/rtems/rtems/timer.h b/cpukit/include/rtems/rtems/timer.h
index 244d5603ba..00d1307bb5 100644
--- a/cpukit/include/rtems/rtems/timer.h
+++ b/cpukit/include/rtems/rtems/timer.h
@@ -1,289 +1,280 @@
+/* SPDX-License-Identifier: BSD-2-Clause */
+
 /**
  * @file
  *
- * @ingroup ClassicTimer
+ * @ingroup RTEMSAPIClassicTimer
  *
- * @brief Classic Timer Manager API
+ * @brief This header file defines 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 was automatically generated.  Do not edit it manually.
+ * Please have a look at
  *
- * Copyright (c) 2009, 2016 embedded brains GmbH.
+ * https://docs.rtems.org/branches/master/eng/req/howto.html
  *
- * 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.
+ * for information how to maintain and re-generate this file.
  */
 
 #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
 
 /**
- *  @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.
  */
-/**@{*/
 
+/**
+ * @ingroup RTEMSAPIClassicTimer
+ *
+ * @brief %
+ */
 #define TIMER_CLASS_BIT_TIME_OF_DAY 0x1
 
+/**
+ * @ingroup RTEMSAPIClassicTimer
+ *
+ * @brief %
+ */
 #define TIMER_CLASS_BIT_ON_TASK 0x2
 
+/**
+ * @ingroup RTEMSAPIClassicTimer
+ *
+ * @brief %
+ */
 #define TIMER_CLASS_BIT_NOT_DORMANT 0x4
 
 /**
- *  The following enumerated type details the classes to which a timer
- *  may belong.
+ * @ingroup RTEMSAPIClassicTimer
+ *
+ * @brief %
+ */
+typedef void rtems_timer_service_routine;
+
+/**
+ * @ingroup RTEMSAPIClassicTimer
+ *
+ * @brief %
  */
 typedef enum {
   /**
-   * This value indicates the timer is currently not in use.
+   * @brief %
    */
   TIMER_DORMANT,
 
   /**
-   * This value indicates the timer is currently in use as an interval
-   * timer which will fire in the clock tick ISR.
+   * @brief %
    */
   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 %
    */
-  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 %
    */
-  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 %
    */
-  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.
+ * @ingroup RTEMSAPIClassicTimer
+ *
+ * @brief %
  */
-typedef void rtems_timer_service_routine;
+typedef rtems_timer_service_routine ( *rtems_timer_service_routine_entry )( rtems_id, void * );
 
 /**
- *  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 %
  */
-typedef rtems_timer_service_routine ( *rtems_timer_service_routine_entry )(
-                 rtems_id,
-                 void *
-             );
+typedef struct {
+  /**
+   * @brief This member is
+   *
+   * %
+   */
+  Timer_Classes the_class;
+
+  /**
+   * @brief This member is
+   *
+   * %
+   */
+  Watchdog_Interval initial;
+
+  /**
+   * @brief This member is
+   *
+   * %
+   */
+  Watchdog_Interval start_time;
+
+  /**
+   * @brief This member is
+   *
+   * %
+   */
+  Watchdog_Interval stop_time;
+} rtems_timer_information;
 
 /**
- * @brief RTEMS Create Timer
- *
- * This routine implements the rtems_timer_create directive. The
- * timer will have the name name. It returns the id of the
- * created timer in ID.
+ * @ingroup RTEMSAPIClassicTimer
  *
- * @param[in] name is the timer name
- * @param[out] id is the pointer to timer id
+ * @brief %
  *
- * @retval RTEMS_SUCCESSFUL if successful or error code if unsuccessful
+ * @param id %
  */
-rtems_status_code rtems_timer_create(
-  rtems_name    name,
-  rtems_id     *id
-);
+rtems_status_code rtems_timer_cancel( rtems_id id );
 
 /**
- * @brief RTEMS Timer Name to Id
+ * @ingroup RTEMSAPIClassicTimer
  *
- * 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.
+ * @brief %
  *
- * @param[in] name is the user defined message queue name
- * @param[in] id is the pointer to timer id
+ * @param name %
  *
- * @retval RTEMS_SUCCESSFUL if successful or error code if unsuccessful and
- * id filled with the message queue id
+ * @param id %
  */
-rtems_status_code rtems_timer_ident(
-  rtems_name    name,
-  rtems_id     *id
-);
+rtems_status_code rtems_timer_create( rtems_name name, rtems_id *id );
 
 /**
- *  @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 %
+ *
+ * @param id %
  */
-rtems_status_code rtems_timer_cancel(
-  rtems_id   id
-);
+rtems_status_code rtems_timer_delete( rtems_id id );
 
 /**
- * @brief RTEMS Delete Timer
+ * @ingroup RTEMSAPIClassicTimer
  *
- * This routine implements the rtems_timer_delete directive. The
- * timer indicated by ID is deleted.
+ * @brief %
  *
- * @param[in] id is the timer id
+ * @param id %
  *
- * @retval This method returns RTEMS_SUCCESSFUL if there was not an
- *         error. Otherwise, a status code is returned indicating the
- *         source of the error.
- */
-rtems_status_code rtems_timer_delete(
-  rtems_id   id
-);
-
-/**
- * @brief RTEMS Timer Fire After
- *
- * This routine implements the rtems_timer_fire_after directive. It
- * initiates the timer associated with ID to fire in ticks clock ticks.
- * When the timer fires, the routine will be invoked in the context
- * of the rtems_clock_tick directive which is normally invoked as
- * part of servicing a periodic interupt.
- *
- * @param[in] id is the timer id
- * @param[in] ticks is the interval until routine is fired
- * @param[in] routine is the routine to schedule
- * @param[in] user_data is the passed as argument to routine when it is fired
- *
- * @retval This method returns RTEMS_SUCCESSFUL if there was not an
- *         error. Otherwise, a status code is returned indicating the
- *         source of the error.
+ * @param ticks %
+ *
+ * @param routine %
+ *
+ * @param user_data %
  */
 rtems_status_code rtems_timer_fire_after(
-  rtems_id                           id,
-  rtems_interval                     ticks,
-  rtems_timer_service_routine_entry  routine,
-  void                              *user_data
+  rtems_id                          id,
+  rtems_interval                    ticks,
+  rtems_timer_service_routine_entry routine,
+  void                             *user_data
 );
 
 /**
- * @brief RTEMS Timer Server Fire After
- *
- * This routine implements the rtems_timer_server_fire_after directive. It
- * initiates the timer associated with ID to fire in ticks clock
- * ticks. When the timer fires, the routine will be invoked by the
- * Timer Server in the context of a task NOT IN THE CONTEXT of the
- * clock tick interrupt.
- *
- * @param[in] id is the timer id
- * @param[in] ticks is the interval until routine is fired
- * @param[in] routine is the routine to schedule
- * @param[in] user_data is the passed as argument to routine when it is fired
- *
- * @retval This method returns RTEMS_SUCCESSFUL if there was not an
- *         error. Otherwise, a status code is returned indicating the
- *         source of the error.
- */
-rtems_status_code rtems_timer_server_fire_after(
-  rtems_id                           id,
-  rtems_interval                     ticks,
-  rtems_timer_service_routine_entry  routine,
-  void                              *user_data
-);
-
-/**
- * @brief RTEMS Timer Fire When
- *
- * This routine implements the rtems_timer_fire_when directive. It
- * initiates the timer associated with ID to fire at wall_time
- * When the timer fires, the routine will be invoked in the context
- * of the rtems_clock_tick directive which is normally invoked as
- * part of servicing a periodic interupt.
- *
- * @param[in] id is the timer id
- * @param[in] wall_time is the time of day to fire timer
- * @param[in] routine is the routine to schedule
- * @param[in] user_data is the passed as argument to routine when it is fired
- *
- * @retval This method returns RTEMS_SUCCESSFUL if there was not an
- *         error. Otherwise, a status code is returned indicating the
- *         source of the error.
+ * @ingroup RTEMSAPIClassicTimer
+ *
+ * @brief %
+ *
+ * @param id %
+ *
+ * @param wall_time %
+ *
+ * @param routine %
+ *
+ * @param user_data %
  */
 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_id                          id,
+  rtems_time_of_day                *wall_time,
+  rtems_timer_service_routine_entry routine,
+  void                             *user_data
 );
 
 /**
- *  @brief RTEMS Timer Server Fire When Directive
+ * @ingroup RTEMSAPIClassicTimer
+ *
+ * @brief %
  *
- *  Timer Manager - RTEMS Timer Server Fire When Directive
+ * @param id %
  *
- *  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.
+ * @param 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
+rtems_status_code rtems_timer_get_information(
+  rtems_id                 id,
+  rtems_timer_information *the_info
 );
 
 /**
- *  @brief RTEMS Timer Reset
+ * @ingroup RTEMSAPIClassicTimer
+ *
+ * @brief %
  *
- *  Timer Manager - RTEMS Timer Reset
+ * @param name %
  *
- *  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.
+ * @param id %
  */
-rtems_status_code rtems_timer_reset(
-  rtems_id   id
-);
+rtems_status_code rtems_timer_ident( rtems_name name, rtems_id *id );
 
 /**
- *  @brief Initiates the timer server.
+ * @ingroup RTEMSAPIClassicTimer
+ *
+ * @brief %
  *
- *  This directive creates and starts the server for task-based timers.
- *  It must be invoked before any task-based timers can be initiated.
+ * @param priority %
  *
- *  @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.
+ * @param stack_size %
  *
- *  @return This method returns RTEMS_SUCCESSFUL if successful and an
- *          error code otherwise.
+ * @param attribute_set %
  */
 rtems_status_code rtems_timer_initiate_server(
   rtems_task_priority priority,
@@ -292,49 +283,63 @@ rtems_status_code rtems_timer_initiate_server(
 );
 
 /**
- *  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.
+ * @ingroup RTEMSAPIClassicTimer
+ *
+ * @brief %
+ *
+ * @param id %
  */
-#define RTEMS_TIMER_SERVER_DEFAULT_PRIORITY (uint32_t) -1
+rtems_status_code rtems_timer_reset( rtems_id id );
 
 /**
- *  This is the structure filled in by the timer get information
- *  service.
+ * @ingroup RTEMSAPIClassicTimer
+ *
+ * @brief %
  */
-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;
+#define RTEMS_TIMER_SERVER_DEFAULT_PRIORITY ( (rtems_task_priority) -1 )
 
 /**
- * @brief RTEMS Get Timer Information
+ * @ingroup RTEMSAPIClassicTimer
+ *
+ * @brief %
  *
- * This routine implements the rtems_timer_get_information directive.
- * This directive returns information about the timer.
+ * @param id %
  *
- * @param[in] id is the timer id
- * @param[in] the_info is the pointer to timer information block
+ * @param ticks %
  *
- * @retval RTEMS_SUCCESSFUL if successful or error code if unsuccessful and
- * 		*the_info region information block filled in
+ * @param routine %
+ *
+ * @param user_data %
  */
-rtems_status_code rtems_timer_get_information(
-  rtems_id                 id,
-  rtems_timer_information *the_info
+rtems_status_code rtems_timer_server_fire_after(
+  rtems_id                          id,
+  rtems_interval                    ticks,
+  rtems_timer_service_routine_entry routine,
+  void                             *user_data
 );
 
-/**@}*/
+/**
+ * @ingroup RTEMSAPIClassicTimer
+ *
+ * @brief %
+ *
+ * @param id %
+ *
+ * @param wall_time %
+ *
+ * @param routine %
+ *
+ * @param user_data %
+ */
+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
+);
 
 #ifdef __cplusplus
 }
 #endif
 
-#endif
-/* end of include file */
+#endif /* _RTEMS_RTEMS_TIMER_H */