Generate <rtems/rtems/ratemon.h>

1 files changed, 199 insertions, 184 deletions

diff --git a/cpukit/include/rtems/rtems/ratemon.h b/cpukit/include/rtems/rtems/ratemon.h
index 16d390d59f..1c6cca1766 100644
--- a/cpukit/include/rtems/rtems/ratemon.h
+++ b/cpukit/include/rtems/rtems/ratemon.h
@@ -1,314 +1,329 @@
+/* SPDX-License-Identifier: BSD-2-Clause */
+
 /**
  * @file
  *
- * @ingroup ClassicRateMon
- *
- * This include file contains all the constants, structures, and
- * prototypes associated with the Rate Monotonic Manager. This manager
- * provides facilities to implement threads which execute in a periodic
- * fashion.
- *
- * Directives provided are:
+ * @ingroup RTEMSAPIClassicRatemon
  *
- * - create a rate monotonic timer
- * - cancel a period
- * - delete a rate monotonic timer
- * - conclude current and start the next period
- * - obtain status information on a period
- * - obtain the number of postponed jobs
+ * @brief This header file defines the Rate-Monotonic 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-2009, 2016.
- * On-Line Applications Research Corporation (OAR).
- * COPYRIGHT (c) 2016-2017 Kuan-Hsun Chen.
+/*
+ * This file was automatically generated.  Do not edit it manually.
+ * Please have a look at
  *
- * 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
+ *
+ * for information how to maintain and re-generate this file.
  */
 
 #ifndef _RTEMS_RTEMS_RATEMON_H
 #define _RTEMS_RTEMS_RATEMON_H
 
-#include <rtems/rtems/types.h>
+#include <stdint.h>
+#include <sys/_timespec.h>
 #include <rtems/rtems/status.h>
-
-struct rtems_printer;
+#include <rtems/rtems/types.h>
+#include <rtems/score/watchdogticks.h>
 
 #ifdef __cplusplus
 extern "C" {
 #endif
 
 /**
- *  @defgroup ClassicRateMon Rate Monotonic Scheduler
+ * @defgroup RTEMSAPIClassicRatemon Rate-Monotonic Manager
  *
- *  @ingroup RTEMSAPIClassic
+ * @ingroup RTEMSAPIClassic
  *
- *  This encapsulates functionality related to the Classic API Rate
- *  Monotonic Manager.
- *
- *  Statistics are kept for each period and can be obtained or printed via
- *  API calls.  The statistics kept include minimum, maximum and average times
- *  for both cpu usage and wall time.  The statistics indicate the execution
- *  and wall time used by the owning thread between successive calls to
- *  rtems_rate_monotonic_period.
+ * @brief The Rate-Monotonic Manager provides facilities to implement tasks
+ *   which execute in a periodic fashion.  Critically, it also gathers
+ *   information about the execution of those periods and can provide important
+ *   statistics to the user which can be used to analyze and tune the
+ *   application.
  */
-/**@{*/
 
 /**
- *  The following enumerated type defines the states in which a
- *  period may be.
+ * @ingroup RTEMSAPIClassicRatemon
+ *
+ * @brief %
  */
 typedef enum {
   /**
-   * This value indicates the period is off the watchdog chain,
-   * and has never been initialized.
+   * @brief %
    */
   RATE_MONOTONIC_INACTIVE,
 
   /**
-   * This value indicates the period is on the watchdog chain, and
-   * running.  The owner should be executed or blocked waiting on
-   * another object.
+   * @brief %
    */
   RATE_MONOTONIC_ACTIVE,
 
   /**
-   * This value indicates the period is off the watchdog chain, and
-   * has expired.  The owner is still executing and has taken too much
-   * all time to complete this iteration of the period.
+   * @brief %
    */
   RATE_MONOTONIC_EXPIRED
-}   rtems_rate_monotonic_period_states;
-
-/**
- *  The following constant is the interval passed to the rate_monontonic_period
- *  directive to obtain status information.
- */
-#define RTEMS_PERIOD_STATUS       WATCHDOG_NO_TIMEOUT
+} rtems_rate_monotonic_period_states;
 
 /**
- *  The following defines the PUBLIC data structure that has the
- *  statistics kept on each period instance.
+ * @ingroup RTEMSAPIClassicRatemon
  *
- *  @note The public structure uses struct timespec while the
- *        internal one uses Timestamp_Control.
+ * @brief %
  */
 typedef struct {
-  /** This field contains the number of periods executed. */
-  uint32_t     count;
-  /** This field contains the number of periods missed. */
-  uint32_t     missed_count;
+  /**
+   * @brief This member is
+   *
+   * %
+   */
+  uint32_t count;
 
-  /** This field contains the least amount of CPU time used in a period. */
+  /**
+   * @brief This member is
+   *
+   * %
+   */
+  uint32_t missed_count;
+
+  /**
+   * @brief This member is
+   *
+   * %
+   */
   struct timespec min_cpu_time;
-  /** This field contains the highest amount of CPU time used in a period. */
+
+  /**
+   * @brief This member is
+   *
+   * %
+   */
   struct timespec max_cpu_time;
-  /** This field contains the total amount of wall time used in a period. */
+
+  /**
+   * @brief This member is
+   *
+   * %
+   */
   struct timespec total_cpu_time;
 
-  /** This field contains the least amount of wall time used in a period. */
+  /**
+   * @brief This member is
+   *
+   * %
+   */
   struct timespec min_wall_time;
-  /** This field contains the highest amount of wall time used in a period. */
+
+  /**
+   * @brief This member is
+   *
+   * %
+   */
   struct timespec max_wall_time;
-  /** This field contains the total amount of CPU time used in a period. */
+
+  /**
+   * @brief This member is
+   *
+   * %
+   */
   struct timespec total_wall_time;
-}  rtems_rate_monotonic_period_statistics;
+} rtems_rate_monotonic_period_statistics;
 
 /**
- *  The following defines the period status structure.
+ * @ingroup RTEMSAPIClassicRatemon
+ *
+ * @brief %
  */
 typedef struct {
-  /** This is the Id of the thread using this period. */
-  rtems_id                             owner;
+  /**
+   * @brief This member is
+   *
+   * %
+   */
+  rtems_id owner;
+
+  /**
+   * @brief This member is
+   *
+   * %
+   */
+  rtems_rate_monotonic_period_states state;
 
-  /** This is the current state of this period. */
-  rtems_rate_monotonic_period_states   state;
+  /**
+   * @brief This member is
+   *
+   * %
+   */
+  struct timespec since_last_period;
 
   /**
-   *  This is the length of wall time that has passed since this period
-   *  was last initiated.  If the period is expired or has not been initiated,
-   *  then this field has no meaning.
+   * @brief This member is
+   *
+   * %
    */
-  struct timespec                      since_last_period;
+  struct timespec executed_since_last_period;
 
   /**
-   *  This is the amount of CPU time that has been used since this period
-   *  was last initiated.  If the period is expired or has not been initiated,
-   *  then this field has no meaning.
+   * @brief This member is
+   *
+   * %
    */
-  struct timespec                      executed_since_last_period;
+  uint32_t postponed_jobs_count;
+} rtems_rate_monotonic_period_status;
 
-  /** This is the count of postponed jobs of this period. */
-  uint32_t                             postponed_jobs_count;
-}  rtems_rate_monotonic_period_status;
+/* Forward declaration */
+struct rtems_printer;
 
 /**
- *  @brief Create a Period
+ * @ingroup RTEMSAPIClassicRatemon
  *
- *  Rate Monotonic Manager
+ * @brief %
  *
- *  This routine implements the rate_monotonic_create directive.  The
- *  period will have the name name.  It returns the id of the
- *  created period in ID.
+ * @param id %
  */
-rtems_status_code rtems_rate_monotonic_create(
-  rtems_name    name,
-  rtems_id     *id
-);
+rtems_status_code rtems_rate_monotonic_cancel( rtems_id id );
 
 /**
- * @brief RTEMS Rate Monotonic Name to Id
+ * @ingroup RTEMSAPIClassicRatemon
  *
- * This routine implements the rtems_rate_monotonic_ident directive.
- * It returns the period ID associated with name. If more than one period
- * is named name, then the period to which the ID belongs is arbitrary.
+ * @brief %
  *
- * @param[in] name is the user defined period name
- * @param[in] id is the pointer to period id
+ * @param name %
  *
- * @retval This method returns RTEMS_SUCCESSFUL if there was not an
- *         error. Otherwise, a status code is returned indicating the
- *         source of the error. If successful, the id will
- *         be filled in with the region id.
+ * @param id %
  */
-rtems_status_code rtems_rate_monotonic_ident(
-  rtems_name    name,
-  rtems_id     *id
-);
+rtems_status_code rtems_rate_monotonic_create( rtems_name name, rtems_id *id );
 
 /**
- * @brief RTEMS Rate Monotonic Cancel
+ * @ingroup RTEMSAPIClassicRatemon
  *
- * This routine implements the rtems_rate_monotonic_cancel directive. This
- * directive stops the period associated with ID from continuing to
- * run.
- *
- * @param[in] id is the rate monotonic id
- *
- * @retval RTEMS_SUCCESSFUL if successful and caller is not the owning thread
- * or error code if unsuccessful
+ * @brief %
  *
+ * @param id %
  */
-rtems_status_code rtems_rate_monotonic_cancel(
-  rtems_id   id
-);
+rtems_status_code rtems_rate_monotonic_delete( rtems_id id );
 
 /**
- * @brief RTEMS Delete Rate Monotonic
+ * @ingroup RTEMSAPIClassicRatemon
  *
- * This routine implements the rtems_rate_monotonic_delete directive. The
- * period indicated by ID is deleted.
+ * @brief %
  *
- * @param[in] id is the rate monotonic 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.
+ * @param statistics %
  */
-rtems_status_code rtems_rate_monotonic_delete(
-  rtems_id   id
+rtems_status_code rtems_rate_monotonic_get_statistics(
+  rtems_id                                id,
+  rtems_rate_monotonic_period_statistics *statistics
 );
 
 /**
- * @brief RTEMS Rate Monotonic Get Status
- *
- * This routine implements the rtems_rate_monotonic_get_status directive.
- * Information about the period indicated by ID is returned.
+ * @ingroup RTEMSAPIClassicRatemon
  *
- * @param[in] id is the rate monotonic id
- * @param[in] status is the pointer to status control block
+ * @brief %
  *
- * @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 id %
  *
+ * @param status %
  */
 rtems_status_code rtems_rate_monotonic_get_status(
-  rtems_id                             id,
-  rtems_rate_monotonic_period_status  *status
+  rtems_id                            id,
+  rtems_rate_monotonic_period_status *status
 );
 
 /**
- * @brief RTEMS Rate Monotonic Get Statistics
+ * @ingroup RTEMSAPIClassicRatemon
  *
- * This routine implements the rtems_rate_monotonic_get_statistics directive.
- * Statistics gathered from the use of this period are returned.
+ * @brief %
  *
- * @param[in] id is the rate monotonic id
- * @param[in] statistics is the pointer to statistics control block
+ * @param name %
  *
- * @retval RTEMS_SUCCESSFUL if successful or error code if unsuccessful
+ * @param id %
  */
-rtems_status_code rtems_rate_monotonic_get_statistics(
-  rtems_id                                id,
-  rtems_rate_monotonic_period_statistics *statistics
-);
+rtems_status_code rtems_rate_monotonic_ident( rtems_name name, rtems_id *id );
 
 /**
- *  @brief RTEMS Rate Monotonic Reset Statistics
+ * @ingroup RTEMSAPIClassicRatemon
+ *
+ * @brief %
  *
- *  Rate Monotonic Manager -- Reset Statistics
+ * @param id %
  *
- *  This routine allows a thread to reset the statistics information
- *  on a specific period instance.
+ * @param length %
  */
-rtems_status_code rtems_rate_monotonic_reset_statistics(
-  rtems_id                                 id
+rtems_status_code rtems_rate_monotonic_period(
+  rtems_id       id,
+  rtems_interval length
 );
 
 /**
- *  @brief rtems_rate_monotonic_reset_all_statistics
+ * @ingroup RTEMSAPIClassicRatemon
  *
- *  This routine allows a thread to reset the statistics information
- *  on ALL period instances.
+ * @brief This constant is the interval passed to the
+ *   rtems_rate_monotonic_period() directive to obtain status information.
  */
-void rtems_rate_monotonic_reset_all_statistics( void );
+#define RTEMS_PERIOD_STATUS WATCHDOG_NO_TIMEOUT
+
+/**
+ * @ingroup RTEMSAPIClassicRatemon
+ *
+ * @brief %
+ */
+void rtems_rate_monotonic_report_statistics( void );
 
 /**
- *  @brief RTEMS Report Rate Monotonic Statistics
+ * @ingroup RTEMSAPIClassicRatemon
+ *
+ * @brief %
  *
- *  This routine allows a thread to print the statistics information
- *  on ALL period instances which have non-zero counts using the RTEMS
- *  printer. The implementation of this directive straddles the fence
- *  between inside and outside of RTEMS.  It is presented as part of
- *  the Manager but actually uses other services of the Manager.
+ * @param printer %
  */
 void rtems_rate_monotonic_report_statistics_with_plugin(
   const struct rtems_printer *printer
 );
 
 /**
- *  @brief RTEMS Report Rate Monotonic Statistics
+ * @ingroup RTEMSAPIClassicRatemon
  *
- *  This routine allows a thread to print the statistics information
- *  on ALL period instances which have non-zero counts using printk.
+ * @brief %
  */
-void rtems_rate_monotonic_report_statistics( void );
+void rtems_rate_monotonic_reset_all_statistics( void );
 
 /**
- * @brief RTEMS Rate Monotonic Period
- *
- * This routine implements the rtems_rate_monotonic_period directive. When
- * length is non-zero, this directive initiates the period associated with
- * ID from continuing for a period of length. If length is zero, then
- * result is set to indicate the current state of the period.
+ * @ingroup RTEMSAPIClassicRatemon
  *
- * @param[in] id is the rate monotonic id
- * @param[in] length is the length of period (in ticks)
+ * @brief %
  *
- * @retval RTEMS_SUCCESSFUL if successful or error code if unsuccessful
+ * @param id %
  */
-rtems_status_code rtems_rate_monotonic_period(
-  rtems_id        id,
-  rtems_interval  length
-);
-
-/**@}*/
+rtems_status_code rtems_rate_monotonic_reset_statistics( rtems_id id );
 
 #ifdef __cplusplus
 }
 #endif
 
-#endif
-/* end of include file */
+#endif /* _RTEMS_RTEMS_RATEMON_H */