[rtems commit] rtems: Generate <rtems/rtems/ratemon.h>
Sebastian Huber
sebh at rtems.org
Fri Apr 23 06:44:32 UTC 2021
Module: rtems
Branch: master
Commit: de6e5153c51e6e6c990c58f474471c236f6926b7
Changeset: http://git.rtems.org/rtems/commit/?id=de6e5153c51e6e6c990c58f474471c236f6926b7
Author: Sebastian Huber <sebastian.huber at embedded-brains.de>
Date: Wed Jun 24 06:58:53 2020 +0200
rtems: Generate <rtems/rtems/ratemon.h>
Change license to BSD-2-Clause according to file histories and
documentation re-licensing agreement.
Update #3899.
Update #3993.
---
cpukit/include/rtems/rtems/ratemon.h | 734 ++++++++++++++++++++++++++---------
1 file changed, 554 insertions(+), 180 deletions(-)
diff --git a/cpukit/include/rtems/rtems/ratemon.h b/cpukit/include/rtems/rtems/ratemon.h
index 16d390d..eee4a37 100644
--- a/cpukit/include/rtems/rtems/ratemon.h
+++ b/cpukit/include/rtems/rtems/ratemon.h
@@ -1,314 +1,688 @@
+/* SPDX-License-Identifier: BSD-2-Clause */
+
/**
* @file
*
- * @ingroup ClassicRateMon
+ * @brief This header file defines the Rate-Monotonic Manager API.
+ */
+
+/*
+ * Copyright (C) 2020, 2021 embedded brains GmbH (http://www.embedded-brains.de)
+ * Copyright (C) 2017 Kuan-Hsun Chen
+ * 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.
+ */
+
+/*
+ * 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:
*
- * 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.
+ * https://www.rtems.org/bugs.html
*
- * Directives provided are:
+ * For information on updating and regenerating please refer to the How-To
+ * section in the Software Requirements Engineering chapter of the
+ * RTEMS Software Engineering manual. The manual is provided as a part of
+ * a release. For development sources please refer to the online
+ * documentation at:
*
- * - 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
+ * https://docs.rtems.org
*/
-/* COPYRIGHT (c) 1989-2009, 2016.
- * On-Line Applications Research Corporation (OAR).
- * COPYRIGHT (c) 2016-2017 Kuan-Hsun Chen.
- *
- * 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.
- */
+/* Generated from spec:/rtems/ratemon/if/header */
#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
+/* Generated from spec:/rtems/ratemon/if/group */
+
/**
- * @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.
*/
-/**@{*/
+
+/* Generated from spec:/rtems/ratemon/if/period-states */
/**
- * The following enumerated type defines the states in which a
- * period may be.
+ * @ingroup RTEMSAPIClassicRatemon
+ *
+ * @brief This enumeration defines the states in which a period may be.
*/
typedef enum {
/**
- * This value indicates the period is off the watchdog chain,
- * and has never been initialized.
+ * @brief This status indicates the period is off the watchdog chain, and has
+ * never been initialized.
*/
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 This status indicates the period is on the watchdog chain, and
+ * running. The owner may be executing or blocked waiting on another object.
*/
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 This status indicates the period is off the watchdog chain, and has
+ * expired. The owner may still execute and has taken too much time to
+ * complete this iteration of the period.
*/
RATE_MONOTONIC_EXPIRED
-} rtems_rate_monotonic_period_states;
+} 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
+/* Generated from spec:/rtems/ratemon/if/period-statistics */
/**
- * 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 This structure provides the statistics of a period.
*/
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 contains the number of periods executed.
+ */
+ uint32_t count;
- /** This field contains the least amount of CPU time used in a period. */
+ /**
+ * @brief This member contains the number of periods missed.
+ */
+ uint32_t missed_count;
+
+ /**
+ * @brief This member contains the least amount of processor time used in a
+ * period.
+ */
struct timespec min_cpu_time;
- /** This field contains the highest amount of CPU time used in a period. */
+
+ /**
+ * @brief This member contains the highest amount of processor time used in a
+ * period.
+ */
struct timespec max_cpu_time;
- /** This field contains the total amount of wall time used in a period. */
+
+ /**
+ * @brief This member contains the total amount of processor time used in a
+ * period.
+ */
struct timespec total_cpu_time;
- /** This field contains the least amount of wall time used in a period. */
+ /**
+ * @brief This member contains the least amount of CLOCK_MONOTONIC time used in
+ * a period.
+ */
struct timespec min_wall_time;
- /** This field contains the highest amount of wall time used in a period. */
+
+ /**
+ * @brief This member contains the highest amount of CLOCK_MONOTONIC time used
+ * in a period.
+ */
struct timespec max_wall_time;
- /** This field contains the total amount of CPU time used in a period. */
+
+ /**
+ * @brief This member contains the total amount of CLOCK_MONOTONIC time used in
+ * a period.
+ */
struct timespec total_wall_time;
-} rtems_rate_monotonic_period_statistics;
+} rtems_rate_monotonic_period_statistics;
+
+/* Generated from spec:/rtems/ratemon/if/period-status */
/**
- * The following defines the period status structure.
+ * @ingroup RTEMSAPIClassicRatemon
+ *
+ * @brief This structure provides the detailed status of a period.
*/
typedef struct {
- /** This is the Id of the thread using this period. */
- rtems_id owner;
+ /**
+ * @brief This member contains the identifier of the owner task of the period.
+ */
+ rtems_id owner;
- /** This is the current state of this period. */
- rtems_rate_monotonic_period_states state;
+ /**
+ * @brief This member contains the state of the period.
+ */
+ rtems_rate_monotonic_period_states state;
/**
- * 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 contains the time elapsed since the last successful
+ * invocation rtems_rate_monotonic_period() using CLOCK_MONOTONIC.
+ *
+ * If the period is expired or has not been initiated, then this value has no
+ * meaning.
*/
- struct timespec since_last_period;
+ struct timespec 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 contains the processor time consumed by the owner task
+ * since the last successful invocation rtems_rate_monotonic_period().
+ *
+ * If the period is expired or has not been initiated, then this value has no
+ * meaning.
*/
- struct timespec executed_since_last_period;
+ struct timespec executed_since_last_period;
- /** This is the count of postponed jobs of this period. */
- uint32_t postponed_jobs_count;
-} rtems_rate_monotonic_period_status;
+ /**
+ * @brief This member contains the count of jobs which are not released yet.
+ */
+ uint32_t postponed_jobs_count;
+} rtems_rate_monotonic_period_status;
+
+/* Generated from spec:/rtems/ratemon/if/period-status-define */
+
+/**
+ * @ingroup RTEMSAPIClassicRatemon
+ *
+ * @brief This constant is the interval passed to the
+ * rtems_rate_monotonic_period() directive to obtain status information.
+ */
+#define RTEMS_PERIOD_STATUS WATCHDOG_NO_TIMEOUT
+
+/* Generated from spec:/rtems/ratemon/if/printer */
+
+/* Forward declaration */
+struct rtems_printer;
+
+/* Generated from spec:/rtems/ratemon/if/create */
/**
- * @brief Create a Period
+ * @ingroup RTEMSAPIClassicRatemon
+ *
+ * @brief Creates a period.
+ *
+ * @param name is the object name of the period.
+ *
+ * @param[out] id is the pointer to an object identifier variable. When the
+ * directive call is successful, the identifier of the created period will be
+ * stored in this variable.
*
- * Rate Monotonic Manager
+ * This directive creates a period which resides on the local node. The period
+ * has the user-defined object name specified in ``name`` The assigned object
+ * identifier is returned in ``id``. This identifier is used to access the
+ * period with other rate monotonic related directives.
*
- * 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.
+ * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
+ *
+ * @retval ::RTEMS_INVALID_NAME The ``name`` parameter was invalid.
+ *
+ * @retval ::RTEMS_TOO_MANY There was no inactive object available to create a
+ * period. The number of periods available to the application is configured
+ * through the #CONFIGURE_MAXIMUM_PERIODS application configuration option.
+ *
+ * @par Notes
+ * @parblock
+ * The calling task is registered as the owner of the created period. Some
+ * directives can be only used by this task for the created period.
+ *
+ * For control and maintenance of the period, RTEMS allocates a PCB from the
+ * local PCB free pool and initializes it.
+ * @endparblock
+ *
+ * @par Constraints
+ * @parblock
+ * The following constraints apply to this directive:
+ *
+ * * The directive may be called from within device driver initialization
+ * context.
+ *
+ * * The directive may be called from within task context.
+ *
+ * * The directive may obtain and release the object allocator mutex. This may
+ * cause the calling task to be preempted.
+ *
+ * * The number of periods available to the application is configured through
+ * the #CONFIGURE_MAXIMUM_PERIODS application configuration option.
+ *
+ * * Where the object class corresponding to the directive is configured to use
+ * unlimited objects, the directive may allocate memory from the RTEMS
+ * Workspace.
+ * @endparblock
*/
-rtems_status_code rtems_rate_monotonic_create(
- rtems_name name,
- rtems_id *id
-);
+rtems_status_code rtems_rate_monotonic_create( rtems_name name, rtems_id *id );
+
+/* Generated from spec:/rtems/ratemon/if/ident */
/**
- * @brief RTEMS Rate Monotonic Name to Id
+ * @ingroup RTEMSAPIClassicRatemon
+ *
+ * @brief Identifies a period by the object name.
+ *
+ * @param name is the object name to look up.
+ *
+ * @param[out] id is the pointer to an object identifier variable. When the
+ * directive call is successful, the object identifier of an object with the
+ * specified name will be stored in this variable.
+ *
+ * This directive obtains a period identifier associated with the period name
+ * specified in ``name``.
+ *
+ * @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.
+ *
+ * @par Notes
+ * @parblock
+ * If the period name is not unique, then the period identifier will match the
+ * first period with that name in the search order. However, this period
+ * identifier is not guaranteed to correspond to the desired period.
+ *
+ * The objects are searched from lowest to the highest index. Only the local
+ * node is searched.
*
- * 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.
+ * The period identifier is used with other rate monotonic related directives
+ * to access the period.
+ * @endparblock
*
- * @param[in] name is the user defined period name
- * @param[in] id is the pointer to period id
+ * @par Constraints
+ * @parblock
+ * The following constraints apply to this directive:
*
- * @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.
+ * * The directive may be called from within any runtime context.
+ *
+ * * The directive will not cause the calling task to be preempted.
+ * @endparblock
*/
-rtems_status_code rtems_rate_monotonic_ident(
- rtems_name name,
- rtems_id *id
-);
+rtems_status_code rtems_rate_monotonic_ident( rtems_name name, rtems_id *id );
+
+/* Generated from spec:/rtems/ratemon/if/cancel */
/**
- * @brief RTEMS Rate Monotonic Cancel
+ * @ingroup RTEMSAPIClassicRatemon
+ *
+ * @brief Cancels the period.
+ *
+ * @param id is the rate monotonic period identifier.
+ *
+ * This directive cancels the rate monotonic period specified by ``id``. This
+ * period may be reinitiated by the next invocation of
+ * rtems_rate_monotonic_period().
*
- * This routine implements the rtems_rate_monotonic_cancel directive. This
- * directive stops the period associated with ID from continuing to
- * run.
+ * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
*
- * @param[in] id is the rate monotonic id
+ * @retval ::RTEMS_INVALID_ID There was no rate monotonic period associated
+ * with the identifier specified by ``id``.
*
- * @retval RTEMS_SUCCESSFUL if successful and caller is not the owning thread
- * or error code if unsuccessful
+ * @retval ::RTEMS_NOT_OWNER_OF_RESOURCE The rate monotonic period was not
+ * created by the calling task.
*
+ * @par Constraints
+ * @parblock
+ * The following constraints apply to this directive:
+ *
+ * * The directive may be called from within task context.
+ *
+ * * The directive will not cause the calling task to be preempted.
+ *
+ * * The directive may be used exclusively by the task which created the
+ * associated object.
+ * @endparblock
*/
-rtems_status_code rtems_rate_monotonic_cancel(
- rtems_id id
-);
+rtems_status_code rtems_rate_monotonic_cancel( rtems_id id );
+
+/* Generated from spec:/rtems/ratemon/if/delete */
/**
- * @brief RTEMS Delete Rate Monotonic
+ * @ingroup RTEMSAPIClassicRatemon
*
- * This routine implements the rtems_rate_monotonic_delete directive. The
- * period indicated by ID is deleted.
+ * @brief Deletes the period.
*
- * @param[in] id is the rate monotonic id
+ * @param id is the period identifier.
*
- * @retval This method returns RTEMS_SUCCESSFUL if there was not an
- * error. Otherwise, a status code is returned indicating the
- * source of the error.
+ * This directive deletes the period specified by ``id``. If the period is
+ * running, it is automatically canceled.
+ *
+ * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
+ *
+ * @retval ::RTEMS_INVALID_ID There was no period associated with the
+ * identifier specified by ``id``.
+ *
+ * @par Notes
+ * The PCB for the deleted period is reclaimed by RTEMS.
+ *
+ * @par Constraints
+ * @parblock
+ * The following constraints apply to this directive:
+ *
+ * * The directive may be called from within device driver initialization
+ * context.
+ *
+ * * The directive may be called from within task context.
+ *
+ * * The directive may obtain and release the object allocator mutex. This may
+ * cause the calling task to be preempted.
+ *
+ * * The calling task does not have to be the task that created the object.
+ * Any local task that knows the object identifier can delete the object.
+ *
+ * * Where the object class corresponding to the directive is configured to use
+ * unlimited objects, the directive may free memory to the RTEMS Workspace.
+ * @endparblock
*/
-rtems_status_code rtems_rate_monotonic_delete(
- rtems_id id
+rtems_status_code rtems_rate_monotonic_delete( rtems_id id );
+
+/* Generated from spec:/rtems/ratemon/if/period */
+
+/**
+ * @ingroup RTEMSAPIClassicRatemon
+ *
+ * @brief Concludes the current period and start the next period, or gets the
+ * period status.
+ *
+ * @param id is the rate monotonic period identifier.
+ *
+ * @param length is the period length in clock ticks or #RTEMS_PERIOD_STATUS to
+ * get the period status.
+ *
+ * This directive initiates the rate monotonic period specified by ``id`` with
+ * a length of period ticks specified by ``length``. If the period is running,
+ * then the calling task will block for the remainder of the period before
+ * reinitiating the period with the specified period length. If the period was
+ * not running (either expired or never initiated), the period is immediately
+ * initiated and the directive returns immediately. If the period has expired,
+ * the postponed job will be released immediately and the following calls of
+ * this directive will release postponed jobs until there is no more deadline
+ * miss.
+ *
+ * If invoked with a period length of #RTEMS_PERIOD_STATUS ticks, the current
+ * state of the period will be returned. The directive status indicates the
+ * current state of the period. This does not alter the state or period length
+ * of the period.
+ *
+ * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
+ *
+ * @retval ::RTEMS_INVALID_ID There was no rate monotonic period associated
+ * with the identifier specified by ``id``.
+ *
+ * @retval ::RTEMS_NOT_OWNER_OF_RESOURCE The rate monotonic period was not
+ * created by the calling task.
+ *
+ * @retval ::RTEMS_NOT_DEFINED The rate monotonic period has never been
+ * initiated (only possible when the ``length`` parameter was equal to
+ * #RTEMS_PERIOD_STATUS).
+ *
+ * @retval ::RTEMS_TIMEOUT The rate monotonic period has expired.
+ *
+ * @par Constraints
+ * @parblock
+ * The following constraints apply to this directive:
+ *
+ * * The directive may be called from within task context.
+ *
+ * * The directive may be used exclusively by the task which created the
+ * associated object.
+ * @endparblock
+ */
+rtems_status_code rtems_rate_monotonic_period(
+ rtems_id id,
+ rtems_interval length
);
+/* Generated from spec:/rtems/ratemon/if/get-status */
+
/**
- * @brief RTEMS Rate Monotonic Get Status
+ * @ingroup RTEMSAPIClassicRatemon
+ *
+ * @brief Gets the detailed status of the period.
+ *
+ * @param id is the rate monotonic period identifier.
+ *
+ * @param[out] status is the pointer to a rtems_rate_monotonic_period_status
+ * variable. When the directive call is successful, the detailed period
+ * status will be stored in this variable.
+ *
+ * This directive returns the detailed status of the rate monotonic period
+ * specified by ``id``. The detailed status of the period will be returned in
+ * the members of the period status object referenced by ``status``:
+ *
+ * * The ``owner`` member is set to the identifier of the owner task of the
+ * period.
+ *
+ * * The ``state`` member is set to the current state of the period.
*
- * This routine implements the rtems_rate_monotonic_get_status directive.
- * Information about the period indicated by ID is returned.
+ * * The ``postponed_jobs_count`` member is set to the count of jobs which are
+ * not released yet.
*
- * @param[in] id is the rate monotonic id
- * @param[in] status is the pointer to status control block
+ * * If the current state of the period is ::RATE_MONOTONIC_INACTIVE, the
+ * ``since_last_period`` and ``executed_since_last_period`` members will be
+ * set to zero. Otherwise, both members will contain time information since
+ * the last successful invocation of the rtems_rate_monotonic_period()
+ * directive by the owner task. More specifically, the ``since_last_period``
+ * member will be set to the time elapsed since the last successful
+ * invocation. The ``executed_since_last_period`` member will be set to the
+ * processor time consumed by the owner task since the last successful
+ * invocation.
*
- * @retval This method returns RTEMS_SUCCESSFUL if there was not an
- * error. Otherwise, a status code is returned indicating the
- * source of the error.
+ * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
*
+ * @retval ::RTEMS_INVALID_ID There was no rate monotonic period associated
+ * with the identifier specified by ``id``.
+ *
+ * @retval ::RTEMS_INVALID_ADDRESS The ``status`` parameter was NULL.
+ *
+ * @retval ::RTEMS_NOT_DEFINED There was no status available due to a reset of
+ * the processor time usage of the owner task of the period.
+ *
+ * @par Constraints
+ * @parblock
+ * The following constraints apply to this directive:
+ *
+ * * The directive may be called from within task context.
+ *
+ * * The directive may be called from within interrupt context.
+ *
+ * * The directive will not cause the calling task to be preempted.
+ * @endparblock
*/
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
);
+/* Generated from spec:/rtems/ratemon/if/get-statistics */
+
/**
- * @brief RTEMS Rate Monotonic Get Statistics
+ * @ingroup RTEMSAPIClassicRatemon
+ *
+ * @brief Gets the statistics of the period.
+ *
+ * @param id is the rate monotonic period identifier.
+ *
+ * @param[out] status is the pointer to a
+ * rtems_rate_monotonic_period_statistics variable. When the directive call
+ * is successful, the period statistics will be stored in this variable.
+ *
+ * This directive returns the statistics of the rate monotonic period specified
+ * by ``id``. The statistics of the period will be returned in the members of
+ * the period statistics object referenced by ``status``:
*
- * This routine implements the rtems_rate_monotonic_get_statistics directive.
- * Statistics gathered from the use of this period are returned.
+ * * The ``count`` member is set to the number of periods executed.
*
- * @param[in] id is the rate monotonic id
- * @param[in] statistics is the pointer to statistics control block
+ * * The ``missed_count`` member is set to the number of periods missed.
*
- * @retval RTEMS_SUCCESSFUL if successful or error code if unsuccessful
+ * * The ``min_cpu_time`` member is set to the least amount of processor time
+ * used in the period.
+ *
+ * * The ``max_cpu_time`` member is set to the highest amount of processor time
+ * used in the period.
+ *
+ * * The ``total_cpu_time`` member is set to the total amount of processor time
+ * used in the period.
+ *
+ * * The ``min_wall_time`` member is set to the least amount of CLOCK_MONOTONIC
+ * time used in the period.
+ *
+ * * The ``max_wall_time`` member is set to the highest amount of
+ * CLOCK_MONOTONIC time used in the period.
+ *
+ * * The ``total_wall_time`` member is set to the total amount of
+ * CLOCK_MONOTONIC time used in the period.
+ *
+ * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
+ *
+ * @retval ::RTEMS_INVALID_ID There was no rate monotonic period associated
+ * with the identifier specified by ``id``.
+ *
+ * @retval ::RTEMS_INVALID_ADDRESS The ``status`` parameter was NULL.
+ *
+ * @par Constraints
+ * @parblock
+ * The following constraints apply to this directive:
+ *
+ * * The directive may be called from within task context.
+ *
+ * * The directive may be called from within interrupt context.
+ *
+ * * The directive will not cause the calling task to be preempted.
+ * @endparblock
*/
rtems_status_code rtems_rate_monotonic_get_statistics(
rtems_id id,
- rtems_rate_monotonic_period_statistics *statistics
+ rtems_rate_monotonic_period_statistics *status
);
+/* Generated from spec:/rtems/ratemon/if/reset-statistics */
+
/**
- * @brief RTEMS Rate Monotonic Reset Statistics
+ * @ingroup RTEMSAPIClassicRatemon
+ *
+ * @brief Resets the statistics of the period.
+ *
+ * @param id is the rate monotonic period identifier.
+ *
+ * This directive resets the statistics of the rate monotonic period specified
+ * by ``id``.
+ *
+ * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
+ *
+ * @retval ::RTEMS_INVALID_ID There was no rate monotonic period associated
+ * with the identifier specified by ``id``.
*
- * Rate Monotonic Manager -- Reset Statistics
+ * @par Constraints
+ * @parblock
+ * The following constraints apply to this directive:
*
- * This routine allows a thread to reset the statistics information
- * on a specific period instance.
+ * * The directive may be called from within task context.
+ *
+ * * The directive may be called from within interrupt context.
+ *
+ * * The directive will not cause the calling task to be preempted.
+ * @endparblock
*/
-rtems_status_code rtems_rate_monotonic_reset_statistics(
- rtems_id id
-);
+rtems_status_code rtems_rate_monotonic_reset_statistics( rtems_id id );
+
+/* Generated from spec:/rtems/ratemon/if/reset-all-statistics */
/**
- * @brief rtems_rate_monotonic_reset_all_statistics
+ * @ingroup RTEMSAPIClassicRatemon
+ *
+ * @brief Resets the statistics of all periods.
*
- * This routine allows a thread to reset the statistics information
- * on ALL period instances.
+ * This directive resets the statistics information associated with all rate
+ * monotonic period instances.
+ *
+ * @par Constraints
+ * @parblock
+ * The following constraints apply to this directive:
+ *
+ * * The directive may be called from within task context.
+ *
+ * * The directive may obtain and release the object allocator mutex. This may
+ * cause the calling task to be preempted.
+ * @endparblock
*/
void rtems_rate_monotonic_reset_all_statistics( void );
-/**
- * @brief RTEMS Report Rate Monotonic Statistics
- *
- * 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.
- */
-void rtems_rate_monotonic_report_statistics_with_plugin(
- const struct rtems_printer *printer
-);
+/* Generated from spec:/rtems/ratemon/if/report-statistics */
/**
- * @brief RTEMS Report Rate Monotonic Statistics
+ * @ingroup RTEMSAPIClassicRatemon
+ *
+ * @brief Reports the period statistics using the printk() printer.
+ *
+ * This directive prints a report on all active periods which have executed at
+ * least one period using the printk() printer.
*
- * This routine allows a thread to print the statistics information
- * on ALL period instances which have non-zero counts using printk.
+ * @par Constraints
+ * @parblock
+ * The following constraints apply to this directive:
+ *
+ * * The directive may be called from within task context.
+ *
+ * * The directive may obtain and release the object allocator mutex. This may
+ * cause the calling task to be preempted.
+ * @endparblock
*/
void rtems_rate_monotonic_report_statistics( void );
+/* Generated from spec:/rtems/ratemon/if/report-statistics-with-plugin */
+
/**
- * @brief RTEMS Rate Monotonic Period
+ * @ingroup RTEMSAPIClassicRatemon
+ *
+ * @brief Reports the period statistics using the printer plugin.
+ *
+ * @param printer is the printer plugin to output the report.
+ *
+ * This directive prints a report on all active periods which have executed at
+ * least one period using the printer plugin specified by ``printer``.
*
- * 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.
+ * @par Constraints
+ * @parblock
+ * The following constraints apply to this directive:
*
- * @param[in] id is the rate monotonic id
- * @param[in] length is the length of period (in ticks)
+ * * The directive may be called from within task context.
*
- * @retval RTEMS_SUCCESSFUL if successful or error code if unsuccessful
+ * * The directive may obtain and release the object allocator mutex. This may
+ * cause the calling task to be preempted.
+ * @endparblock
*/
-rtems_status_code rtems_rate_monotonic_period(
- rtems_id id,
- rtems_interval length
+void rtems_rate_monotonic_report_statistics_with_plugin(
+ const struct rtems_printer *printer
);
-/**@}*/
-
#ifdef __cplusplus
}
#endif
-#endif
-/* end of include file */
+#endif /* _RTEMS_RTEMS_RATEMON_H */
More information about the vc
mailing list