source: rtems/cpukit/include/rtems/rtems/ratemon.h @ aacc7a0

Last change on this file since aacc7a0 was aacc7a0, checked in by Sebastian Huber <sebastian.huber@…>, on Nov 8, 2018 at 6:59:04 AM

rtems: Deprecate rtems_thread_cpu_usage_t

The rtems_thread_cpu_usage_t typedef as no corresponding API. It
violates the POSIX namespace. A user can do nothing with it.

Close #3593.

  • Property mode set to 100644
File size: 13.1 KB
RevLine 
[4b487363]1/**
2 * @file rtems/rtems/ratemon.h
[067a96a]3 *
[61b8e9f]4 * @defgroup ClassicRateMon Rate Monotonic Scheduler
[f1eb368d]5 *
[61b8e9f]6 * @ingroup ClassicRTEMS
7 * @brief Classic API Rate Monotonic Manager.
[ac7d5ef0]8 *
[61b8e9f]9 * This include file contains all the constants, structures, and
10 * prototypes associated with the Rate Monotonic Manager. This manager
11 * provides facilities to implement threads which execute in a periodic
12 * fashion.
[ac7d5ef0]13 *
[61b8e9f]14 * Directives provided are:
15 *
16 * - create a rate monotonic timer
17 * - cancel a period
18 * - delete a rate monotonic timer
19 * - conclude current and start the next period
20 * - obtain status information on a period
[3a46b72]21 * - obtain the number of postponed jobs
[067a96a]22 */
23
[815b653]24/* COPYRIGHT (c) 1989-2009, 2016.
[61b8e9f]25 * On-Line Applications Research Corporation (OAR).
[d7feb86]26 * COPYRIGHT (c) 2016-2017 Kuan-Hsun Chen.
[ac7d5ef0]27 *
[61b8e9f]28 * The license and distribution terms for this file may be
29 * found in the file LICENSE in this distribution or at
[c499856]30 * http://www.rtems.org/license/LICENSE.
[ac7d5ef0]31 */
32
[092f142a]33#ifndef _RTEMS_RTEMS_RATEMON_H
34#define _RTEMS_RTEMS_RATEMON_H
[ac7d5ef0]35
[ecdcf01]36#include <rtems/rtems/types.h>
37#include <rtems/rtems/status.h>
38#include <rtems/score/thread.h>
39#include <rtems/score/watchdog.h>
[a33bfb6]40
41struct rtems_printer;
[90a5d194]42
[ecdcf01]43#ifdef __cplusplus
44extern "C" {
45#endif
46
[067a96a]47/**
[c85ab23]48 *  @defgroup ClassicRateMon Rate Monotonic Scheduler
49 *
50 *  @ingroup ClassicRTEMS
[067a96a]51 *
[815b653]52 *  This encapsulates functionality related to the Classic API Rate
53 *  Monotonic Manager.
[eb37f9d]54 *
55 *  Statistics are kept for each period and can be obtained or printed via
56 *  API calls.  The statistics kept include minimum, maximum and average times
[815b653]57 *  for both cpu usage and wall time.  The statistics indicate the execution
58 *  and wall time used by the owning thread between successive calls to
59 *  rtems_rate_monotonic_period.
[067a96a]60 */
61/**@{*/
62
[8c8fd64]63/**
[9dc2c8d]64 *  This is the public type used for the rate monotonic timing
[8c8fd64]65 *  statistics.
66 */
[e6b31b27]67#include <rtems/score/timespec.h>
[c16bcc0]68
[e6b31b27]69typedef struct timespec rtems_rate_monotonic_period_time_t;
[c3330a8]70
[9dc2c8d]71/**
72 *  This is the internal type used for the rate monotonic timing
73 *  statistics.
74 */
[e6b31b27]75#include <rtems/score/timestamp.h>
[9dc2c8d]76
[067a96a]77/**
[ac7d5ef0]78 *  The following enumerated type defines the states in which a
79 *  period may be.
80 */
81typedef enum {
[8c8fd64]82  /**
[33c3b54d]83   * This value indicates the period is off the watchdog chain,
[8c8fd64]84   * and has never been initialized.
85   */
86  RATE_MONOTONIC_INACTIVE,
87
88  /**
[33c3b54d]89   * This value indicates the period is on the watchdog chain, and
[8c8fd64]90   * running.  The owner should be executed or blocked waiting on
91   * another object.
92   */
93  RATE_MONOTONIC_ACTIVE,
94
95  /**
[33c3b54d]96   * This value indicates the period is off the watchdog chain, and
[8c8fd64]97   * has expired.  The owner is still executing and has taken too much
98   * all time to complete this iteration of the period.
99   */
[4daebbd]100  RATE_MONOTONIC_EXPIRED
[113ef9fc]101}   rtems_rate_monotonic_period_states;
[ac7d5ef0]102
[067a96a]103/**
[ac7d5ef0]104 *  The following constant is the interval passed to the rate_monontonic_period
105 *  directive to obtain status information.
106 */
[3a4ae6c]107#define RTEMS_PERIOD_STATUS       WATCHDOG_NO_TIMEOUT
[ac7d5ef0]108
[067a96a]109/**
[9dc2c8d]110 *  The following defines the PUBLIC data structure that has the
111 *  statistics kept on each period instance.
112 *
113 *  @note The public structure uses struct timespec while the
[33c3b54d]114 *        internal one uses Timestamp_Control.
[e1bce86]115 */
116typedef struct {
[8c8fd64]117  /** This field contains the number of periods executed. */
[e1bce86]118  uint32_t     count;
[8c8fd64]119  /** This field contains the number of periods missed. */
[e1bce86]120  uint32_t     missed_count;
[ebfd9ea]121
[8c8fd64]122  /** This field contains the least amount of CPU time used in a period. */
[aacc7a0]123  struct timespec min_cpu_time;
[8c8fd64]124  /** This field contains the highest amount of CPU time used in a period. */
[aacc7a0]125  struct timespec max_cpu_time;
[8c8fd64]126  /** This field contains the total amount of wall time used in a period. */
[aacc7a0]127  struct timespec total_cpu_time;
[5fa5185]128
[8c8fd64]129  /** This field contains the least amount of wall time used in a period. */
[5fa5185]130  rtems_rate_monotonic_period_time_t   min_wall_time;
[8c8fd64]131  /** This field contains the highest amount of wall time used in a period. */
[5fa5185]132  rtems_rate_monotonic_period_time_t   max_wall_time;
[8c8fd64]133  /** This field contains the total amount of CPU time used in a period. */
[5fa5185]134  rtems_rate_monotonic_period_time_t   total_wall_time;
[e1bce86]135}  rtems_rate_monotonic_period_statistics;
136
[9dc2c8d]137/**
138 *  The following defines the INTERNAL data structure that has the
139 *  statistics kept on each period instance.
140 */
141typedef struct {
142  /** This field contains the number of periods executed. */
143  uint32_t     count;
144  /** This field contains the number of periods missed. */
145  uint32_t     missed_count;
146
147  /** This field contains the least amount of CPU time used in a period. */
[300eaad]148  Timestamp_Control min_cpu_time;
[9dc2c8d]149  /** This field contains the highest amount of CPU time used in a period. */
[300eaad]150  Timestamp_Control max_cpu_time;
[9dc2c8d]151  /** This field contains the total amount of wall time used in a period. */
[300eaad]152  Timestamp_Control total_cpu_time;
[9dc2c8d]153
154  /** This field contains the least amount of wall time used in a period. */
[300eaad]155  Timestamp_Control min_wall_time;
[9dc2c8d]156  /** This field contains the highest amount of wall time used in a period. */
[300eaad]157  Timestamp_Control max_wall_time;
[9dc2c8d]158  /** This field contains the total amount of CPU time used in a period. */
[300eaad]159  Timestamp_Control total_wall_time;
[9dc2c8d]160}  Rate_monotonic_Statistics;
161
[067a96a]162/**
[113ef9fc]163 *  The following defines the period status structure.
[50f32b11]164 */
[113ef9fc]165typedef struct {
[8c8fd64]166  /** This is the Id of the thread using this period. */
[d3b72ca3]167  rtems_id                             owner;
[8c8fd64]168
169  /** This is the current state of this period. */
[5fa5185]170  rtems_rate_monotonic_period_states   state;
[8c8fd64]171
172  /**
173   *  This is the length of wall time that has passed since this period
174   *  was last initiated.  If the period is expired or has not been initiated,
175   *  then this field has no meaning.
176   */
[5fa5185]177  rtems_rate_monotonic_period_time_t   since_last_period;
[8c8fd64]178
179  /**
180   *  This is the amount of CPU time that has been used since this period
181   *  was last initiated.  If the period is expired or has not been initiated,
182   *  then this field has no meaning.
183   */
[aacc7a0]184  struct timespec                      executed_since_last_period;
[d7feb86]185
186  /** This is the count of postponed jobs of this period. */
187  uint32_t                             postponed_jobs_count;
[113ef9fc]188}  rtems_rate_monotonic_period_status;
189
[067a96a]190/**
[90960bd]191 * @brief The following structure defines the control block used to manage each
192 * period.
193 *
194 * State changes are protected by the default thread lock of the owner thread.
195 * The owner thread is the thread that created the period object.  The owner
196 * thread field is immutable after object creation.
[ac7d5ef0]197 */
198typedef struct {
[8c8fd64]199  /** This field is the object management portion of a Period instance. */
[e1bce86]200  Objects_Control                         Object;
[8c8fd64]201
[ee0e4135]202  /**
203   * @brief Protects the rate monotonic period state.
204   */
205  ISR_LOCK_MEMBER(                        Lock )
206
[8c8fd64]207  /** This is the timer used to provide the unblocking mechanism. */
[e1bce86]208  Watchdog_Control                        Timer;
[8c8fd64]209
210  /** This field indicates the current state of the period. */
[e1bce86]211  rtems_rate_monotonic_period_states      state;
[8c8fd64]212
[300f6a48]213  /**
214   * @brief A priority node for use by the scheduler job release and cancel
215   * operations.
216   */
217  Priority_Node                           Priority;
218
[8c8fd64]219  /**
220   * This field contains the length of the next period to be
221   * executed.
222   */
[e1bce86]223  uint32_t                                next_length;
[8c8fd64]224
225  /**
226   * This field contains a pointer to the TCB for the thread
227   * which owns and uses this period instance.
228   */
[e1bce86]229  Thread_Control                         *owner;
[8c8fd64]230
231  /**
[eb37f9d]232   * This field contains the cpu usage value of the owning thread when
233   * the period was initiated.  It is used to compute the period's
234   * statistics.
235   */
[d297c81d]236  Timestamp_Control                       cpu_usage_period_initiated;
[eb37f9d]237
238  /**
239   * This field contains the wall time value when the period
240   * was initiated.  It is used to compute the period's statistics.
241   */
[300eaad]242  Timestamp_Control                       time_period_initiated;
[eb37f9d]243
244  /**
245   * This field contains the statistics maintained for the period.
[8c8fd64]246   */
[9dc2c8d]247  Rate_monotonic_Statistics               Statistics;
[3a46b72]248
249  /**
250   * This field contains the number of postponed jobs.
251   * When the watchdog timeout, this variable will be increased immediately.
252   */
253  uint32_t                                postponed_jobs;
254
255  /**
256   *  This field contains the tick of the latest deadline decided by the period
257   *  watchdog.
258  */
259  uint64_t                                latest_deadline;
[ac7d5ef0]260}   Rate_monotonic_Control;
[33c3b54d]261
[067a96a]262/**
[4c90eb4]263 *  @brief Create a Period
264 *
265 *  Rate Monotonic Manager
[ac7d5ef0]266 *
267 *  This routine implements the rate_monotonic_create directive.  The
268 *  period will have the name name.  It returns the id of the
269 *  created period in ID.
270 */
271rtems_status_code rtems_rate_monotonic_create(
[3235ad9]272  rtems_name    name,
[d3b72ca3]273  rtems_id     *id
[ac7d5ef0]274);
275
[067a96a]276/**
[61b8e9f]277 * @brief RTEMS Rate Monotonic Name to Id
[ac7d5ef0]278 *
[61b8e9f]279 * This routine implements the rtems_rate_monotonic_ident directive.
280 * It returns the period ID associated with name. If more than one period
281 * is named name, then the period to which the ID belongs is arbitrary.
[4c90eb4]282 *
[61b8e9f]283 * @param[in] name is the user defined period name
284 * @param[in] id is the pointer to period id
[4c90eb4]285 *
[61b8e9f]286 * @retval This method returns RTEMS_SUCCESSFUL if there was not an
287 *         error. Otherwise, a status code is returned indicating the
288 *         source of the error. If successful, the id will
289 *         be filled in with the region id.
[ac7d5ef0]290 */
291rtems_status_code rtems_rate_monotonic_ident(
[3235ad9]292  rtems_name    name,
[d3b72ca3]293  rtems_id     *id
[ac7d5ef0]294);
295
[067a96a]296/**
[61b8e9f]297 * @brief RTEMS Rate Monotonic Cancel
[ac7d5ef0]298 *
[61b8e9f]299 * This routine implements the rtems_rate_monotonic_cancel directive. This
300 * directive stops the period associated with ID from continuing to
301 * run.
[4efe1955]302 *
[61b8e9f]303 * @param[in] id is the rate monotonic id
[4efe1955]304 *
[61b8e9f]305 * @retval RTEMS_SUCCESSFUL if successful and caller is not the owning thread
306 * or error code if unsuccessful
[4efe1955]307 *
[ac7d5ef0]308 */
309rtems_status_code rtems_rate_monotonic_cancel(
[d3b72ca3]310  rtems_id   id
[ac7d5ef0]311);
312
[067a96a]313/**
[61b8e9f]314 * @brief RTEMS Delete Rate Monotonic
[ac7d5ef0]315 *
[61b8e9f]316 * This routine implements the rtems_rate_monotonic_delete directive. The
317 * period indicated by ID is deleted.
[4c90eb4]318 *
[61b8e9f]319 * @param[in] id is the rate monotonic id
[4c90eb4]320 *
[61b8e9f]321 * @retval This method returns RTEMS_SUCCESSFUL if there was not an
322 *         error. Otherwise, a status code is returned indicating the
323 *         source of the error.
[ac7d5ef0]324 */
325rtems_status_code rtems_rate_monotonic_delete(
[d3b72ca3]326  rtems_id   id
[ac7d5ef0]327);
328
[067a96a]329/**
[61b8e9f]330 * @brief RTEMS Rate Monotonic Get Status
[113ef9fc]331 *
[61b8e9f]332 * This routine implements the rtems_rate_monotonic_get_status directive.
333 * Information about the period indicated by ID is returned.
[4c90eb4]334 *
[61b8e9f]335 * @param[in] id is the rate monotonic id
336 * @param[in] status is the pointer to status control block
[4c90eb4]337 *
[61b8e9f]338 * @retval This method returns RTEMS_SUCCESSFUL if there was not an
339 *         error. Otherwise, a status code is returned indicating the
340 *         source of the error.
[113ef9fc]341 *
342 */
343rtems_status_code rtems_rate_monotonic_get_status(
[d3b72ca3]344  rtems_id                             id,
[113ef9fc]345  rtems_rate_monotonic_period_status  *status
346);
347
[067a96a]348/**
[61b8e9f]349 * @brief RTEMS Rate Monotonic Get Statistics
[e1bce86]350 *
[61b8e9f]351 * This routine implements the rtems_rate_monotonic_get_statistics directive.
352 * Statistics gathered from the use of this period are returned.
[4efe1955]353 *
[61b8e9f]354 * @param[in] id is the rate monotonic id
355 * @param[in] statistics is the pointer to statistics control block
[4efe1955]356 *
[61b8e9f]357 * @retval RTEMS_SUCCESSFUL if successful or error code if unsuccessful
[e1bce86]358 */
359rtems_status_code rtems_rate_monotonic_get_statistics(
[d3b72ca3]360  rtems_id                                id,
[e1bce86]361  rtems_rate_monotonic_period_statistics *statistics
362);
363
[067a96a]364/**
[4c90eb4]365 *  @brief RTEMS Rate Monotonic Reset Statistics
366 *
367 *  Rate Monotonic Manager -- Reset Statistics
[e1bce86]368 *
[eb37f9d]369 *  This routine allows a thread to reset the statistics information
[e1bce86]370 *  on a specific period instance.
371 */
372rtems_status_code rtems_rate_monotonic_reset_statistics(
[d3b72ca3]373  rtems_id                                 id
[e1bce86]374);
375
[067a96a]376/**
377 *  @brief rtems_rate_monotonic_reset_all_statistics
[e1bce86]378 *
[eb37f9d]379 *  This routine allows a thread to reset the statistics information
[e1bce86]380 *  on ALL period instances.
381 */
[c3330a8]382void rtems_rate_monotonic_reset_all_statistics( void );
[e1bce86]383
[067a96a]384/**
[a6500136]385 *  @brief RTEMS Report Rate Monotonic Statistics
[90a5d194]386 *
[eb37f9d]387 *  This routine allows a thread to print the statistics information
[24d0ee57]388 *  on ALL period instances which have non-zero counts using the RTEMS
389 *  printer. The implementation of this directive straddles the fence
390 *  between inside and outside of RTEMS.  It is presented as part of
391 *  the Manager but actually uses other services of the Manager.
[90a5d194]392 */
393void rtems_rate_monotonic_report_statistics_with_plugin(
[a33bfb6]394  const struct rtems_printer *printer
[90a5d194]395);
396
[067a96a]397/**
[a6500136]398 *  @brief RTEMS Report Rate Monotonic Statistics
[e1bce86]399 *
[eb37f9d]400 *  This routine allows a thread to print the statistics information
[e1bce86]401 *  on ALL period instances which have non-zero counts using printk.
402 */
[c3330a8]403void rtems_rate_monotonic_report_statistics( void );
[e1bce86]404
[067a96a]405/**
[61b8e9f]406 * @brief RTEMS Rate Monotonic Period
[ac7d5ef0]407 *
[61b8e9f]408 * This routine implements the rtems_rate_monotonic_period directive. When
409 * length is non-zero, this directive initiates the period associated with
410 * ID from continuing for a period of length. If length is zero, then
411 * result is set to indicate the current state of the period.
[4efe1955]412 *
[61b8e9f]413 * @param[in] id is the rate monotonic id
[e858f70]414 * @param[in] length is the length of period (in ticks)
[4efe1955]415 *
[61b8e9f]416 * @retval RTEMS_SUCCESSFUL if successful or error code if unsuccessful
[ac7d5ef0]417 */
418rtems_status_code rtems_rate_monotonic_period(
[d3b72ca3]419  rtems_id        id,
[3a4ae6c]420  rtems_interval  length
[ac7d5ef0]421);
422
[ecdcf01]423/**@}*/
[ac7d5ef0]424
425#ifdef __cplusplus
426}
427#endif
428
429#endif
430/* end of include file */
Note: See TracBrowser for help on using the repository browser.