Changeset de6e515 in rtems


Ignore:
Timestamp:
Jun 24, 2020, 4:58:53 AM (11 months ago)
Author:
Sebastian Huber <sebastian.huber@…>
Branches:
master
Children:
53bb397
Parents:
73a0175
git-author:
Sebastian Huber <sebastian.huber@…> (06/24/20 04:58:53)
git-committer:
Sebastian Huber <sebastian.huber@…> (04/23/21 06:42:03)
Message:

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.

File:
1 edited

Legend:

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

    r73a0175 rde6e515  
     1/* SPDX-License-Identifier: BSD-2-Clause */
     2
    13/**
    24 * @file
    35 *
    4  * @ingroup ClassicRateMon
    5  *
    6  * This include file contains all the constants, structures, and
    7  * prototypes associated with the Rate Monotonic Manager. This manager
    8  * provides facilities to implement threads which execute in a periodic
    9  * fashion.
    10  *
    11  * Directives provided are:
    12  *
    13  * - create a rate monotonic timer
    14  * - cancel a period
    15  * - delete a rate monotonic timer
    16  * - conclude current and start the next period
    17  * - obtain status information on a period
    18  * - obtain the number of postponed jobs
    19  */
    20 
    21 /* COPYRIGHT (c) 1989-2009, 2016.
    22  * On-Line Applications Research Corporation (OAR).
    23  * COPYRIGHT (c) 2016-2017 Kuan-Hsun Chen.
    24  *
    25  * The license and distribution terms for this file may be
    26  * found in the file LICENSE in this distribution or at
    27  * http://www.rtems.org/license/LICENSE.
    28  */
     6 * @brief This header file defines the Rate-Monotonic Manager API.
     7 */
     8
     9/*
     10 * Copyright (C) 2020, 2021 embedded brains GmbH (http://www.embedded-brains.de)
     11 * Copyright (C) 2017 Kuan-Hsun Chen
     12 * Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
     13 *
     14 * Redistribution and use in source and binary forms, with or without
     15 * modification, are permitted provided that the following conditions
     16 * are met:
     17 * 1. Redistributions of source code must retain the above copyright
     18 *    notice, this list of conditions and the following disclaimer.
     19 * 2. Redistributions in binary form must reproduce the above copyright
     20 *    notice, this list of conditions and the following disclaimer in the
     21 *    documentation and/or other materials provided with the distribution.
     22 *
     23 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
     24 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
     25 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
     26 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
     27 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
     28 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
     29 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
     30 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
     31 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
     32 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
     33 * POSSIBILITY OF SUCH DAMAGE.
     34 */
     35
     36/*
     37 * This file is part of the RTEMS quality process and was automatically
     38 * generated.  If you find something that needs to be fixed or
     39 * worded better please post a report or patch to an RTEMS mailing list
     40 * or raise a bug report:
     41 *
     42 * https://www.rtems.org/bugs.html
     43 *
     44 * For information on updating and regenerating please refer to the How-To
     45 * section in the Software Requirements Engineering chapter of the
     46 * RTEMS Software Engineering manual.  The manual is provided as a part of
     47 * a release.  For development sources please refer to the online
     48 * documentation at:
     49 *
     50 * https://docs.rtems.org
     51 */
     52
     53/* Generated from spec:/rtems/ratemon/if/header */
    2954
    3055#ifndef _RTEMS_RTEMS_RATEMON_H
    3156#define _RTEMS_RTEMS_RATEMON_H
    3257
     58#include <stdint.h>
     59#include <sys/_timespec.h>
     60#include <rtems/rtems/status.h>
    3361#include <rtems/rtems/types.h>
    34 #include <rtems/rtems/status.h>
    35 
    36 struct rtems_printer;
     62#include <rtems/score/watchdogticks.h>
    3763
    3864#ifdef __cplusplus
     
    4066#endif
    4167
    42 /**
    43  *  @defgroup ClassicRateMon Rate Monotonic Scheduler
    44  *
    45  *  @ingroup RTEMSAPIClassic
    46  *
    47  *  This encapsulates functionality related to the Classic API Rate
    48  *  Monotonic Manager.
    49  *
    50  *  Statistics are kept for each period and can be obtained or printed via
    51  *  API calls.  The statistics kept include minimum, maximum and average times
    52  *  for both cpu usage and wall time.  The statistics indicate the execution
    53  *  and wall time used by the owning thread between successive calls to
    54  *  rtems_rate_monotonic_period.
    55  */
    56 /**@{*/
    57 
    58 /**
    59  *  The following enumerated type defines the states in which a
    60  *  period may be.
     68/* Generated from spec:/rtems/ratemon/if/group */
     69
     70/**
     71 * @defgroup RTEMSAPIClassicRatemon Rate-Monotonic Manager
     72 *
     73 * @ingroup RTEMSAPIClassic
     74 *
     75 * @brief The Rate-Monotonic Manager provides facilities to implement tasks
     76 *   which execute in a periodic fashion.  Critically, it also gathers
     77 *   information about the execution of those periods and can provide important
     78 *   statistics to the user which can be used to analyze and tune the
     79 *   application.
     80 */
     81
     82/* Generated from spec:/rtems/ratemon/if/period-states */
     83
     84/**
     85 * @ingroup RTEMSAPIClassicRatemon
     86 *
     87 * @brief This enumeration defines the states in which a period may be.
    6188 */
    6289typedef enum {
    6390  /**
    64    * This value indicates the period is off the watchdog chain,
    65    * and has never been initialized.
     91   * @brief This status indicates the period is off the watchdog chain, and has
     92   *   never been initialized.
    6693   */
    6794  RATE_MONOTONIC_INACTIVE,
    6895
    6996  /**
    70    * This value indicates the period is on the watchdog chain, and
    71    * running.  The owner should be executed or blocked waiting on
    72    * another object.
     97   * @brief This status indicates the period is on the watchdog chain, and
     98   *   running.  The owner may be executing or blocked waiting on another object.
    7399   */
    74100  RATE_MONOTONIC_ACTIVE,
    75101
    76102  /**
    77    * This value indicates the period is off the watchdog chain, and
    78    * has expired.  The owner is still executing and has taken too much
    79    * all time to complete this iteration of the period.
     103   * @brief This status indicates the period is off the watchdog chain, and has
     104   *   expired. The owner may still execute and has taken too much time to
     105   *   complete this iteration of the period.
    80106   */
    81107  RATE_MONOTONIC_EXPIRED
    82 }   rtems_rate_monotonic_period_states;
    83 
    84 /**
    85  *  The following constant is the interval passed to the rate_monontonic_period
    86  *  directive to obtain status information.
    87  */
    88 #define RTEMS_PERIOD_STATUS       WATCHDOG_NO_TIMEOUT
    89 
    90 /**
    91  *  The following defines the PUBLIC data structure that has the
    92  *  statistics kept on each period instance.
    93  *
    94  *  @note The public structure uses struct timespec while the
    95  *        internal one uses Timestamp_Control.
     108} rtems_rate_monotonic_period_states;
     109
     110/* Generated from spec:/rtems/ratemon/if/period-statistics */
     111
     112/**
     113 * @ingroup RTEMSAPIClassicRatemon
     114 *
     115 * @brief This structure provides the statistics of a period.
    96116 */
    97117typedef struct {
    98   /** This field contains the number of periods executed. */
    99   uint32_t     count;
    100   /** This field contains the number of periods missed. */
    101   uint32_t     missed_count;
    102 
    103   /** This field contains the least amount of CPU time used in a period. */
     118  /**
     119   * @brief This member contains the number of periods executed.
     120   */
     121  uint32_t count;
     122
     123  /**
     124   * @brief This member contains the number of periods missed.
     125   */
     126  uint32_t missed_count;
     127
     128  /**
     129   * @brief This member contains the least amount of processor time used in a
     130   *   period.
     131   */
    104132  struct timespec min_cpu_time;
    105   /** This field contains the highest amount of CPU time used in a period. */
     133
     134  /**
     135   * @brief This member contains the highest amount of processor time used in a
     136   *   period.
     137   */
    106138  struct timespec max_cpu_time;
    107   /** This field contains the total amount of wall time used in a period. */
     139
     140  /**
     141   * @brief This member contains the total amount of processor time used in a
     142   *   period.
     143   */
    108144  struct timespec total_cpu_time;
    109145
    110   /** This field contains the least amount of wall time used in a period. */
     146  /**
     147   * @brief This member contains the least amount of CLOCK_MONOTONIC time used in
     148   *   a period.
     149   */
    111150  struct timespec min_wall_time;
    112   /** This field contains the highest amount of wall time used in a period. */
     151
     152  /**
     153   * @brief This member contains the highest amount of CLOCK_MONOTONIC time used
     154   *   in a period.
     155   */
    113156  struct timespec max_wall_time;
    114   /** This field contains the total amount of CPU time used in a period. */
     157
     158  /**
     159   * @brief This member contains the total amount of CLOCK_MONOTONIC time used in
     160   *   a period.
     161   */
    115162  struct timespec total_wall_time;
    116 }  rtems_rate_monotonic_period_statistics;
    117 
    118 /**
    119  *  The following defines the period status structure.
     163} rtems_rate_monotonic_period_statistics;
     164
     165/* Generated from spec:/rtems/ratemon/if/period-status */
     166
     167/**
     168 * @ingroup RTEMSAPIClassicRatemon
     169 *
     170 * @brief This structure provides the detailed status of a period.
    120171 */
    121172typedef struct {
    122   /** This is the Id of the thread using this period. */
    123   rtems_id                             owner;
    124 
    125   /** This is the current state of this period. */
    126   rtems_rate_monotonic_period_states   state;
    127 
    128   /**
    129    *  This is the length of wall time that has passed since this period
    130    *  was last initiated.  If the period is expired or has not been initiated,
    131    *  then this field has no meaning.
    132    */
    133   struct timespec                      since_last_period;
    134 
    135   /**
    136    *  This is the amount of CPU time that has been used since this period
    137    *  was last initiated.  If the period is expired or has not been initiated,
    138    *  then this field has no meaning.
    139    */
    140   struct timespec                      executed_since_last_period;
    141 
    142   /** This is the count of postponed jobs of this period. */
    143   uint32_t                             postponed_jobs_count;
    144 }  rtems_rate_monotonic_period_status;
    145 
    146 /**
    147  *  @brief Create a Period
    148  *
    149  *  Rate Monotonic Manager
    150  *
    151  *  This routine implements the rate_monotonic_create directive.  The
    152  *  period will have the name name.  It returns the id of the
    153  *  created period in ID.
    154  */
    155 rtems_status_code rtems_rate_monotonic_create(
    156   rtems_name    name,
    157   rtems_id     *id
     173  /**
     174   * @brief This member contains the identifier of the owner task of the period.
     175   */
     176  rtems_id owner;
     177
     178  /**
     179   * @brief This member contains the state of the period.
     180   */
     181  rtems_rate_monotonic_period_states state;
     182
     183  /**
     184   * @brief This member contains the time elapsed since the last successful
     185   *   invocation rtems_rate_monotonic_period() using CLOCK_MONOTONIC.
     186   *
     187   * If the period is expired or has not been initiated, then this value has no
     188   * meaning.
     189   */
     190  struct timespec since_last_period;
     191
     192  /**
     193   * @brief This member contains the processor time consumed by the owner task
     194   *   since the last successful invocation rtems_rate_monotonic_period().
     195   *
     196   * If the period is expired or has not been initiated, then this value has no
     197   * meaning.
     198   */
     199  struct timespec executed_since_last_period;
     200
     201  /**
     202   * @brief This member contains the count of jobs which are not released yet.
     203   */
     204  uint32_t postponed_jobs_count;
     205} rtems_rate_monotonic_period_status;
     206
     207/* Generated from spec:/rtems/ratemon/if/period-status-define */
     208
     209/**
     210 * @ingroup RTEMSAPIClassicRatemon
     211 *
     212 * @brief This constant is the interval passed to the
     213 *   rtems_rate_monotonic_period() directive to obtain status information.
     214 */
     215#define RTEMS_PERIOD_STATUS WATCHDOG_NO_TIMEOUT
     216
     217/* Generated from spec:/rtems/ratemon/if/printer */
     218
     219/* Forward declaration */
     220struct rtems_printer;
     221
     222/* Generated from spec:/rtems/ratemon/if/create */
     223
     224/**
     225 * @ingroup RTEMSAPIClassicRatemon
     226 *
     227 * @brief Creates a period.
     228 *
     229 * @param name is the object name of the period.
     230 *
     231 * @param[out] id is the pointer to an object identifier variable.  When the
     232 *   directive call is successful, the identifier of the created period will be
     233 *   stored in this variable.
     234 *
     235 * This directive creates a period which resides on the local node.  The period
     236 * has the user-defined object name specified in ``name`` The assigned object
     237 * identifier is returned in ``id``.  This identifier is used to access the
     238 * period with other rate monotonic related directives.
     239 *
     240 * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
     241 *
     242 * @retval ::RTEMS_INVALID_NAME The ``name`` parameter was invalid.
     243 *
     244 * @retval ::RTEMS_TOO_MANY There was no inactive object available to create a
     245 *   period.  The number of periods available to the application is configured
     246 *   through the #CONFIGURE_MAXIMUM_PERIODS application configuration option.
     247 *
     248 * @par Notes
     249 * @parblock
     250 * The calling task is registered as the owner of the created period.  Some
     251 * directives can be only used by this task for the created period.
     252 *
     253 * For control and maintenance of the period, RTEMS allocates a PCB from the
     254 * local PCB free pool and initializes it.
     255 * @endparblock
     256 *
     257 * @par Constraints
     258 * @parblock
     259 * The following constraints apply to this directive:
     260 *
     261 * * The directive may be called from within device driver initialization
     262 *   context.
     263 *
     264 * * The directive may be called from within task context.
     265 *
     266 * * The directive may obtain and release the object allocator mutex.  This may
     267 *   cause the calling task to be preempted.
     268 *
     269 * * The number of periods available to the application is configured through
     270 *   the #CONFIGURE_MAXIMUM_PERIODS application configuration option.
     271 *
     272 * * Where the object class corresponding to the directive is configured to use
     273 *   unlimited objects, the directive may allocate memory from the RTEMS
     274 *   Workspace.
     275 * @endparblock
     276 */
     277rtems_status_code rtems_rate_monotonic_create( rtems_name name, rtems_id *id );
     278
     279/* Generated from spec:/rtems/ratemon/if/ident */
     280
     281/**
     282 * @ingroup RTEMSAPIClassicRatemon
     283 *
     284 * @brief Identifies a period by the object name.
     285 *
     286 * @param name is the object name to look up.
     287 *
     288 * @param[out] id is the pointer to an object identifier variable.  When the
     289 *   directive call is successful, the object identifier of an object with the
     290 *   specified name will be stored in this variable.
     291 *
     292 * This directive obtains a period identifier associated with the period name
     293 * specified in ``name``.
     294 *
     295 * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
     296 *
     297 * @retval ::RTEMS_INVALID_ADDRESS The ``id`` parameter was NULL.
     298 *
     299 * @retval ::RTEMS_INVALID_NAME The ``name`` parameter was 0.
     300 *
     301 * @retval ::RTEMS_INVALID_NAME There was no object with the specified name on
     302 *   the local node.
     303 *
     304 * @par Notes
     305 * @parblock
     306 * If the period name is not unique, then the period identifier will match the
     307 * first period with that name in the search order.  However, this period
     308 * identifier is not guaranteed to correspond to the desired period.
     309 *
     310 * The objects are searched from lowest to the highest index.  Only the local
     311 * node is searched.
     312 *
     313 * The period identifier is used with other rate monotonic related directives
     314 * to access the period.
     315 * @endparblock
     316 *
     317 * @par Constraints
     318 * @parblock
     319 * The following constraints apply to this directive:
     320 *
     321 * * The directive may be called from within any runtime context.
     322 *
     323 * * The directive will not cause the calling task to be preempted.
     324 * @endparblock
     325 */
     326rtems_status_code rtems_rate_monotonic_ident( rtems_name name, rtems_id *id );
     327
     328/* Generated from spec:/rtems/ratemon/if/cancel */
     329
     330/**
     331 * @ingroup RTEMSAPIClassicRatemon
     332 *
     333 * @brief Cancels the period.
     334 *
     335 * @param id is the rate monotonic period identifier.
     336 *
     337 * This directive cancels the rate monotonic period specified by ``id``.  This
     338 * period may be reinitiated by the next invocation of
     339 * rtems_rate_monotonic_period().
     340 *
     341 * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
     342 *
     343 * @retval ::RTEMS_INVALID_ID There was no rate monotonic period associated
     344 *   with the identifier specified by ``id``.
     345 *
     346 * @retval ::RTEMS_NOT_OWNER_OF_RESOURCE The rate monotonic period was not
     347 *   created by the calling task.
     348 *
     349 * @par Constraints
     350 * @parblock
     351 * The following constraints apply to this directive:
     352 *
     353 * * The directive may be called from within task context.
     354 *
     355 * * The directive will not cause the calling task to be preempted.
     356 *
     357 * * The directive may be used exclusively by the task which created the
     358 *   associated object.
     359 * @endparblock
     360 */
     361rtems_status_code rtems_rate_monotonic_cancel( rtems_id id );
     362
     363/* Generated from spec:/rtems/ratemon/if/delete */
     364
     365/**
     366 * @ingroup RTEMSAPIClassicRatemon
     367 *
     368 * @brief Deletes the period.
     369 *
     370 * @param id is the period identifier.
     371 *
     372 * This directive deletes the period specified by ``id``.  If the period is
     373 * running, it is automatically canceled.
     374 *
     375 * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
     376 *
     377 * @retval ::RTEMS_INVALID_ID There was no period associated with the
     378 *   identifier specified by ``id``.
     379 *
     380 * @par Notes
     381 * The PCB for the deleted period is reclaimed by RTEMS.
     382 *
     383 * @par Constraints
     384 * @parblock
     385 * The following constraints apply to this directive:
     386 *
     387 * * The directive may be called from within device driver initialization
     388 *   context.
     389 *
     390 * * The directive may be called from within task context.
     391 *
     392 * * The directive may obtain and release the object allocator mutex.  This may
     393 *   cause the calling task to be preempted.
     394 *
     395 * * The calling task does not have to be the task that created the object.
     396 *   Any local task that knows the object identifier can delete the object.
     397 *
     398 * * Where the object class corresponding to the directive is configured to use
     399 *   unlimited objects, the directive may free memory to the RTEMS Workspace.
     400 * @endparblock
     401 */
     402rtems_status_code rtems_rate_monotonic_delete( rtems_id id );
     403
     404/* Generated from spec:/rtems/ratemon/if/period */
     405
     406/**
     407 * @ingroup RTEMSAPIClassicRatemon
     408 *
     409 * @brief Concludes the current period and start the next period, or gets the
     410 *   period status.
     411 *
     412 * @param id is the rate monotonic period identifier.
     413 *
     414 * @param length is the period length in clock ticks or #RTEMS_PERIOD_STATUS to
     415 *   get the period status.
     416 *
     417 * This directive initiates the rate monotonic period specified by ``id``  with
     418 * a length of period ticks specified by ``length``.  If the period is running,
     419 * then the calling task will block for the remainder of the period before
     420 * reinitiating the period with the specified period length.  If the period was
     421 * not running (either expired or never initiated), the period is immediately
     422 * initiated and the directive returns immediately.  If the period has expired,
     423 * the postponed job will be released immediately and the following calls of
     424 * this directive will release postponed jobs until there is no more deadline
     425 * miss.
     426 *
     427 * If invoked with a period length of #RTEMS_PERIOD_STATUS ticks, the current
     428 * state of the period will be returned.  The directive status indicates the
     429 * current state of the period.  This does not alter the state or period length
     430 * of the period.
     431 *
     432 * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
     433 *
     434 * @retval ::RTEMS_INVALID_ID There was no rate monotonic period associated
     435 *   with the identifier specified by ``id``.
     436 *
     437 * @retval ::RTEMS_NOT_OWNER_OF_RESOURCE The rate monotonic period was not
     438 *   created by the calling task.
     439 *
     440 * @retval ::RTEMS_NOT_DEFINED The rate monotonic period has never been
     441 *   initiated (only possible when the ``length`` parameter was equal to
     442 *   #RTEMS_PERIOD_STATUS).
     443 *
     444 * @retval ::RTEMS_TIMEOUT The rate monotonic period has expired.
     445 *
     446 * @par Constraints
     447 * @parblock
     448 * The following constraints apply to this directive:
     449 *
     450 * * The directive may be called from within task context.
     451 *
     452 * * The directive may be used exclusively by the task which created the
     453 *   associated object.
     454 * @endparblock
     455 */
     456rtems_status_code rtems_rate_monotonic_period(
     457  rtems_id       id,
     458  rtems_interval length
    158459);
    159460
    160 /**
    161  * @brief RTEMS Rate Monotonic Name to Id
    162  *
    163  * This routine implements the rtems_rate_monotonic_ident directive.
    164  * It returns the period ID associated with name. If more than one period
    165  * is named name, then the period to which the ID belongs is arbitrary.
    166  *
    167  * @param[in] name is the user defined period name
    168  * @param[in] id is the pointer to period id
    169  *
    170  * @retval This method returns RTEMS_SUCCESSFUL if there was not an
    171  *         error. Otherwise, a status code is returned indicating the
    172  *         source of the error. If successful, the id will
    173  *         be filled in with the region id.
    174  */
    175 rtems_status_code rtems_rate_monotonic_ident(
    176   rtems_name    name,
    177   rtems_id     *id
     461/* Generated from spec:/rtems/ratemon/if/get-status */
     462
     463/**
     464 * @ingroup RTEMSAPIClassicRatemon
     465 *
     466 * @brief Gets the detailed status of the period.
     467 *
     468 * @param id is the rate monotonic period identifier.
     469 *
     470 * @param[out] status is the pointer to a rtems_rate_monotonic_period_status
     471 *   variable.  When the directive call is successful, the detailed period
     472 *   status will be stored in this variable.
     473 *
     474 * This directive returns the detailed status of the rate monotonic period
     475 * specified by ``id``.  The detailed status of the period will be returned in
     476 * the members of the period status object referenced by ``status``:
     477 *
     478 * * The ``owner`` member is set to the identifier of the owner task of the
     479 *   period.
     480 *
     481 * * The ``state`` member is set to the current state of the period.
     482 *
     483 * * The ``postponed_jobs_count`` member is set to the count of jobs which are
     484 *   not released yet.
     485 *
     486 * * If the current state of the period is ::RATE_MONOTONIC_INACTIVE, the
     487 *   ``since_last_period`` and ``executed_since_last_period`` members will be
     488 *   set to zero.  Otherwise, both members will contain time information since
     489 *   the last successful invocation of the rtems_rate_monotonic_period()
     490 *   directive by the owner task.  More specifically, the ``since_last_period``
     491 *   member will be set to the time elapsed since the last successful
     492 *   invocation.  The ``executed_since_last_period`` member will be set to the
     493 *   processor time consumed by the owner task since the last successful
     494 *   invocation.
     495 *
     496 * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
     497 *
     498 * @retval ::RTEMS_INVALID_ID There was no rate monotonic period associated
     499 *   with the identifier specified by ``id``.
     500 *
     501 * @retval ::RTEMS_INVALID_ADDRESS The ``status`` parameter was NULL.
     502 *
     503 * @retval ::RTEMS_NOT_DEFINED There was no status available due to a reset of
     504 *   the processor time usage of the owner task of the period.
     505 *
     506 * @par Constraints
     507 * @parblock
     508 * The following constraints apply to this directive:
     509 *
     510 * * The directive may be called from within task context.
     511 *
     512 * * The directive may be called from within interrupt context.
     513 *
     514 * * The directive will not cause the calling task to be preempted.
     515 * @endparblock
     516 */
     517rtems_status_code rtems_rate_monotonic_get_status(
     518  rtems_id                            id,
     519  rtems_rate_monotonic_period_status *status
    178520);
    179521
    180 /**
    181  * @brief RTEMS Rate Monotonic Cancel
    182  *
    183  * This routine implements the rtems_rate_monotonic_cancel directive. This
    184  * directive stops the period associated with ID from continuing to
    185  * run.
    186  *
    187  * @param[in] id is the rate monotonic id
    188  *
    189  * @retval RTEMS_SUCCESSFUL if successful and caller is not the owning thread
    190  * or error code if unsuccessful
    191  *
    192  */
    193 rtems_status_code rtems_rate_monotonic_cancel(
    194   rtems_id   id
    195 );
    196 
    197 /**
    198  * @brief RTEMS Delete Rate Monotonic
    199  *
    200  * This routine implements the rtems_rate_monotonic_delete directive. The
    201  * period indicated by ID is deleted.
    202  *
    203  * @param[in] id is the rate monotonic id
    204  *
    205  * @retval This method returns RTEMS_SUCCESSFUL if there was not an
    206  *         error. Otherwise, a status code is returned indicating the
    207  *         source of the error.
    208  */
    209 rtems_status_code rtems_rate_monotonic_delete(
    210   rtems_id   id
    211 );
    212 
    213 /**
    214  * @brief RTEMS Rate Monotonic Get Status
    215  *
    216  * This routine implements the rtems_rate_monotonic_get_status directive.
    217  * Information about the period indicated by ID is returned.
    218  *
    219  * @param[in] id is the rate monotonic id
    220  * @param[in] status is the pointer to status control block
    221  *
    222  * @retval This method returns RTEMS_SUCCESSFUL if there was not an
    223  *         error. Otherwise, a status code is returned indicating the
    224  *         source of the error.
    225  *
    226  */
    227 rtems_status_code rtems_rate_monotonic_get_status(
    228   rtems_id                             id,
    229   rtems_rate_monotonic_period_status  *status
    230 );
    231 
    232 /**
    233  * @brief RTEMS Rate Monotonic Get Statistics
    234  *
    235  * This routine implements the rtems_rate_monotonic_get_statistics directive.
    236  * Statistics gathered from the use of this period are returned.
    237  *
    238  * @param[in] id is the rate monotonic id
    239  * @param[in] statistics is the pointer to statistics control block
    240  *
    241  * @retval RTEMS_SUCCESSFUL if successful or error code if unsuccessful
     522/* Generated from spec:/rtems/ratemon/if/get-statistics */
     523
     524/**
     525 * @ingroup RTEMSAPIClassicRatemon
     526 *
     527 * @brief Gets the statistics of the period.
     528 *
     529 * @param id is the rate monotonic period identifier.
     530 *
     531 * @param[out] status is the pointer to a
     532 *   rtems_rate_monotonic_period_statistics variable.  When the directive call
     533 *   is successful, the period statistics will be stored in this variable.
     534 *
     535 * This directive returns the statistics of the rate monotonic period specified
     536 * by ``id``.  The statistics of the period will be returned in the members of
     537 * the period statistics object referenced by ``status``:
     538 *
     539 * * The ``count`` member is set to the number of periods executed.
     540 *
     541 * * The ``missed_count`` member is set to the number of periods missed.
     542 *
     543 * * The ``min_cpu_time`` member is set to the least amount of processor time
     544 *   used in the period.
     545 *
     546 * * The ``max_cpu_time`` member is set to the highest amount of processor time
     547 *   used in the period.
     548 *
     549 * * The ``total_cpu_time`` member is set to the total amount of processor time
     550 *   used in the period.
     551 *
     552 * * The ``min_wall_time`` member is set to the least amount of CLOCK_MONOTONIC
     553 *   time used in the period.
     554 *
     555 * * The ``max_wall_time`` member is set to the highest amount of
     556 *   CLOCK_MONOTONIC time used in the period.
     557 *
     558 * * The ``total_wall_time`` member is set to the total amount of
     559 *   CLOCK_MONOTONIC time used in the period.
     560 *
     561 * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
     562 *
     563 * @retval ::RTEMS_INVALID_ID There was no rate monotonic period associated
     564 *   with the identifier specified by ``id``.
     565 *
     566 * @retval ::RTEMS_INVALID_ADDRESS The ``status`` parameter was NULL.
     567 *
     568 * @par Constraints
     569 * @parblock
     570 * The following constraints apply to this directive:
     571 *
     572 * * The directive may be called from within task context.
     573 *
     574 * * The directive may be called from within interrupt context.
     575 *
     576 * * The directive will not cause the calling task to be preempted.
     577 * @endparblock
    242578 */
    243579rtems_status_code rtems_rate_monotonic_get_statistics(
    244580  rtems_id                                id,
    245   rtems_rate_monotonic_period_statistics *statistics
     581  rtems_rate_monotonic_period_statistics *status
    246582);
    247583
    248 /**
    249  *  @brief RTEMS Rate Monotonic Reset Statistics
    250  *
    251  *  Rate Monotonic Manager -- Reset Statistics
    252  *
    253  *  This routine allows a thread to reset the statistics information
    254  *  on a specific period instance.
    255  */
    256 rtems_status_code rtems_rate_monotonic_reset_statistics(
    257   rtems_id                                 id
    258 );
    259 
    260 /**
    261  *  @brief rtems_rate_monotonic_reset_all_statistics
    262  *
    263  *  This routine allows a thread to reset the statistics information
    264  *  on ALL period instances.
     584/* Generated from spec:/rtems/ratemon/if/reset-statistics */
     585
     586/**
     587 * @ingroup RTEMSAPIClassicRatemon
     588 *
     589 * @brief Resets the statistics of the period.
     590 *
     591 * @param id is the rate monotonic period identifier.
     592 *
     593 * This directive resets the statistics of the rate monotonic period specified
     594 * by ``id``.
     595 *
     596 * @retval ::RTEMS_SUCCESSFUL The requested operation was successful.
     597 *
     598 * @retval ::RTEMS_INVALID_ID There was no rate monotonic period associated
     599 *   with the identifier specified by ``id``.
     600 *
     601 * @par Constraints
     602 * @parblock
     603 * The following constraints apply to this directive:
     604 *
     605 * * The directive may be called from within task context.
     606 *
     607 * * The directive may be called from within interrupt context.
     608 *
     609 * * The directive will not cause the calling task to be preempted.
     610 * @endparblock
     611 */
     612rtems_status_code rtems_rate_monotonic_reset_statistics( rtems_id id );
     613
     614/* Generated from spec:/rtems/ratemon/if/reset-all-statistics */
     615
     616/**
     617 * @ingroup RTEMSAPIClassicRatemon
     618 *
     619 * @brief Resets the statistics of all periods.
     620 *
     621 * This directive resets the statistics information associated with all rate
     622 * monotonic period instances.
     623 *
     624 * @par Constraints
     625 * @parblock
     626 * The following constraints apply to this directive:
     627 *
     628 * * The directive may be called from within task context.
     629 *
     630 * * The directive may obtain and release the object allocator mutex.  This may
     631 *   cause the calling task to be preempted.
     632 * @endparblock
    265633 */
    266634void rtems_rate_monotonic_reset_all_statistics( void );
    267635
    268 /**
    269  *  @brief RTEMS Report Rate Monotonic Statistics
    270  *
    271  *  This routine allows a thread to print the statistics information
    272  *  on ALL period instances which have non-zero counts using the RTEMS
    273  *  printer. The implementation of this directive straddles the fence
    274  *  between inside and outside of RTEMS.  It is presented as part of
    275  *  the Manager but actually uses other services of the Manager.
     636/* Generated from spec:/rtems/ratemon/if/report-statistics */
     637
     638/**
     639 * @ingroup RTEMSAPIClassicRatemon
     640 *
     641 * @brief Reports the period statistics using the printk() printer.
     642 *
     643 * This directive prints a report on all active periods which have executed at
     644 * least one period using the printk() printer.
     645 *
     646 * @par Constraints
     647 * @parblock
     648 * The following constraints apply to this directive:
     649 *
     650 * * The directive may be called from within task context.
     651 *
     652 * * The directive may obtain and release the object allocator mutex.  This may
     653 *   cause the calling task to be preempted.
     654 * @endparblock
     655 */
     656void rtems_rate_monotonic_report_statistics( void );
     657
     658/* Generated from spec:/rtems/ratemon/if/report-statistics-with-plugin */
     659
     660/**
     661 * @ingroup RTEMSAPIClassicRatemon
     662 *
     663 * @brief Reports the period statistics using the printer plugin.
     664 *
     665 * @param printer is the printer plugin to output the report.
     666 *
     667 * This directive prints a report on all active periods which have executed at
     668 * least one period using the printer plugin specified by ``printer``.
     669 *
     670 * @par Constraints
     671 * @parblock
     672 * The following constraints apply to this directive:
     673 *
     674 * * The directive may be called from within task context.
     675 *
     676 * * The directive may obtain and release the object allocator mutex.  This may
     677 *   cause the calling task to be preempted.
     678 * @endparblock
    276679 */
    277680void rtems_rate_monotonic_report_statistics_with_plugin(
     
    279682);
    280683
    281 /**
    282  *  @brief RTEMS Report Rate Monotonic Statistics
    283  *
    284  *  This routine allows a thread to print the statistics information
    285  *  on ALL period instances which have non-zero counts using printk.
    286  */
    287 void rtems_rate_monotonic_report_statistics( void );
    288 
    289 /**
    290  * @brief RTEMS Rate Monotonic Period
    291  *
    292  * This routine implements the rtems_rate_monotonic_period directive. When
    293  * length is non-zero, this directive initiates the period associated with
    294  * ID from continuing for a period of length. If length is zero, then
    295  * result is set to indicate the current state of the period.
    296  *
    297  * @param[in] id is the rate monotonic id
    298  * @param[in] length is the length of period (in ticks)
    299  *
    300  * @retval RTEMS_SUCCESSFUL if successful or error code if unsuccessful
    301  */
    302 rtems_status_code rtems_rate_monotonic_period(
    303   rtems_id        id,
    304   rtems_interval  length
    305 );
    306 
    307 /**@}*/
    308 
    309684#ifdef __cplusplus
    310685}
    311686#endif
    312687
    313 #endif
    314 /* end of include file */
     688#endif /* _RTEMS_RTEMS_RATEMON_H */
Note: See TracChangeset for help on using the changeset viewer.