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

4.104.115
Last change on this file since eb37f9d was eb37f9d, checked in by Glenn Humphrey <glenn.humphrey@…>, on 12/08/09 at 23:05:30

2009-12-08 Glenn Humphrey <glenn.humphrey@…>

  • rtems/include/rtems/rtems/ratemon.h, rtems/src/ratemongetstatus.c, rtems/src/ratemonperiod.c: Factored out common code to ensure consistent behavior between rtems_rate_monotonic_get_status and rtems_rate_monotonic_report_statistics.
  • Property mode set to 100644
File size: 15.5 KB
Line 
1/**
2 * @file rtems/rtems/ratemon.h
3 *
4 *  This include file contains all the constants, structures, and
5 *  prototypes associated with the Rate Monotonic Manager.  This manager
6 *  provides facilities to implement threads which execute in a periodic
7 *  fashion.
8 *
9 *  Directives provided are:
10 *
11 *     - create a rate monotonic timer
12 *     - cancel a period
13 *     - delete a rate monotonic timer
14 *     - conclude current and start the next period
15 *     - obtain status information on a period
16 */
17
18/*  COPYRIGHT (c) 1989-2009.
19 *  On-Line Applications Research Corporation (OAR).
20 *
21 *  The license and distribution terms for this file may be
22 *  found in the file LICENSE in this distribution or at
23 *  http://www.rtems.com/license/LICENSE.
24 *
25 *  $Id$
26 */
27
28#ifndef _RTEMS_RTEMS_RATEMON_H
29#define _RTEMS_RTEMS_RATEMON_H
30
31/**
32 *  This constant is defined to extern most of the time when using
33 *  this header file.  However by defining it to nothing, the data
34 *  declared in this header file can be instantiated.  This is done
35 *  in a single per manager file.
36 */
37#ifndef RTEMS_RATEMON_EXTERN
38#define RTEMS_RATEMON_EXTERN extern
39#endif
40
41#include <rtems/bspIo.h>
42
43/**
44 *  @defgroup ClassicRateMon Rate Monotonic Scheduler
45 *
46 *  @ingroup ClassicRTEMS
47 *
48 *  This encapsulates functionality related to the
49 *  Classic API Rate Monotonic Manager.
50 *
51 *  Statistics are kept for each period and can be obtained or printed via
52 *  API calls.  The statistics kept include minimum, maximum and average times
53 *  for both cpu usage and wall time.  The statistics indicate the execution time
54 *  used by the owning thread between successive calls to rtems_rate_monotonic_period.
55 */
56/**@{*/
57
58#ifdef __cplusplus
59extern "C" {
60#endif
61
62/**
63 *  This is the public type used for the rate monotonic timing
64 *  statistics.
65 */
66#ifndef __RTEMS_USE_TICKS_FOR_STATISTICS__
67  #include <rtems/score/timespec.h>
68
69  typedef struct timespec rtems_rate_monotonic_period_time_t;
70#else
71  typedef uint32_t rtems_rate_monotonic_period_time_t;
72#endif
73
74/**
75 *  This is the internal type used for the rate monotonic timing
76 *  statistics.
77 */
78#ifndef __RTEMS_USE_TICKS_FOR_STATISTICS__
79  #include <rtems/score/timestamp.h>
80
81  typedef Timestamp_Control Rate_monotonic_Period_time_t;
82#else
83  typedef uint32_t Rate_monotonic_Period_time_t;
84#endif
85
86#include <rtems/score/object.h>
87#include <rtems/score/thread.h>
88#include <rtems/score/watchdog.h>
89#include <rtems/rtems/status.h>
90#include <rtems/rtems/support.h>
91
92#include <string.h>
93
94
95/**
96 *  The following enumerated type defines the states in which a
97 *  period may be.
98 */
99typedef enum {
100  /**
101   * This value indicates the period is off the watchdog chain,
102   * and has never been initialized.
103   */
104  RATE_MONOTONIC_INACTIVE,
105
106  /**
107   * This value indicates the period is on the watchdog chain, and
108   * the owner is blocked waiting on it.
109   */
110  RATE_MONOTONIC_OWNER_IS_BLOCKING,
111
112  /**
113   * This value indicates the period is on the watchdog chain, and
114   * running.  The owner should be executed or blocked waiting on
115   * another object.
116   */
117  RATE_MONOTONIC_ACTIVE,
118
119  /**
120   * This value indicates the period is on the watchdog chain, and
121   * has expired.  The owner should be blocked waiting for the next period.
122   */
123  RATE_MONOTONIC_EXPIRED_WHILE_BLOCKING,
124
125  /**
126   * This value indicates the period is off the watchdog chain, and
127   * has expired.  The owner is still executing and has taken too much
128   * all time to complete this iteration of the period.
129   */
130  RATE_MONOTONIC_EXPIRED
131}   rtems_rate_monotonic_period_states;
132
133/**
134 *  The following constant is the interval passed to the rate_monontonic_period
135 *  directive to obtain status information.
136 */
137#define RTEMS_PERIOD_STATUS       WATCHDOG_NO_TIMEOUT
138
139/**
140 *  The following defines the PUBLIC data structure that has the
141 *  statistics kept on each period instance.
142 *
143 *  @note The public structure uses struct timespec while the
144 *        internal one uses Timestamp_Control.
145 */
146typedef struct {
147  /** This field contains the number of periods executed. */
148  uint32_t     count;
149  /** This field contains the number of periods missed. */
150  uint32_t     missed_count;
151
152  /** This field contains the least amount of CPU time used in a period. */
153  rtems_thread_cpu_usage_t             min_cpu_time;
154  /** This field contains the highest amount of CPU time used in a period. */
155  rtems_thread_cpu_usage_t             max_cpu_time;
156  /** This field contains the total amount of wall time used in a period. */
157  rtems_thread_cpu_usage_t             total_cpu_time;
158
159  /** This field contains the least amount of wall time used in a period. */
160  rtems_rate_monotonic_period_time_t   min_wall_time;
161  /** This field contains the highest amount of wall time used in a period. */
162  rtems_rate_monotonic_period_time_t   max_wall_time;
163  /** This field contains the total amount of CPU time used in a period. */
164  rtems_rate_monotonic_period_time_t   total_wall_time;
165}  rtems_rate_monotonic_period_statistics;
166
167/**
168 *  The following defines the INTERNAL data structure that has the
169 *  statistics kept on each period instance.
170 */
171typedef struct {
172  /** This field contains the number of periods executed. */
173  uint32_t     count;
174  /** This field contains the number of periods missed. */
175  uint32_t     missed_count;
176
177  /** This field contains the least amount of CPU time used in a period. */
178  Thread_CPU_usage_t                   min_cpu_time;
179  /** This field contains the highest amount of CPU time used in a period. */
180  Thread_CPU_usage_t                   max_cpu_time;
181  /** This field contains the total amount of wall time used in a period. */
182  Thread_CPU_usage_t                   total_cpu_time;
183
184  /** This field contains the least amount of wall time used in a period. */
185  Rate_monotonic_Period_time_t         min_wall_time;
186  /** This field contains the highest amount of wall time used in a period. */
187  Rate_monotonic_Period_time_t         max_wall_time;
188  /** This field contains the total amount of CPU time used in a period. */
189  Rate_monotonic_Period_time_t         total_wall_time;
190}  Rate_monotonic_Statistics;
191
192/**
193 *  The following defines the period status structure.
194 */
195typedef struct {
196  /** This is the Id of the thread using this period. */
197  Objects_Id                           owner;
198
199  /** This is the current state of this period. */
200  rtems_rate_monotonic_period_states   state;
201
202  /**
203   *  This is the length of wall time that has passed since this period
204   *  was last initiated.  If the period is expired or has not been initiated,
205   *  then this field has no meaning.
206   */
207  rtems_rate_monotonic_period_time_t   since_last_period;
208
209  /**
210   *  This is the amount of CPU time that has been used since this period
211   *  was last initiated.  If the period is expired or has not been initiated,
212   *  then this field has no meaning.
213   */
214  rtems_thread_cpu_usage_t             executed_since_last_period;
215}  rtems_rate_monotonic_period_status;
216
217/**
218 *  The following structure defines the control block used to manage
219 *  each period.
220 */
221typedef struct {
222  /** This field is the object management portion of a Period instance. */
223  Objects_Control                         Object;
224
225  /** This is the timer used to provide the unblocking mechanism. */
226  Watchdog_Control                        Timer;
227
228  /** This field indicates the current state of the period. */
229  rtems_rate_monotonic_period_states      state;
230
231  /**
232   * This field contains the length of the next period to be
233   * executed.
234   */
235  uint32_t                                next_length;
236
237  /**
238   * This field contains a pointer to the TCB for the thread
239   * which owns and uses this period instance.
240   */
241  Thread_Control                         *owner;
242
243  /**
244   * This field contains the cpu usage value of the owning thread when
245   * the period was initiated.  It is used to compute the period's
246   * statistics.
247   */
248  Thread_CPU_usage_t                      cpu_usage_period_initiated;
249
250  /**
251   * This field contains the wall time value when the period
252   * was initiated.  It is used to compute the period's statistics.
253   */
254  Rate_monotonic_Period_time_t            time_period_initiated;
255
256  /**
257   * This field contains the statistics maintained for the period.
258   */
259  Rate_monotonic_Statistics               Statistics;
260}   Rate_monotonic_Control;
261
262/**
263 *  @brief Rate Monotonic Period Class Management Structure
264 *
265 *  This instance of Objects_Information is used to manage the
266 *  set of rate monotonic period instances.
267 */
268RTEMS_RATEMON_EXTERN Objects_Information _Rate_monotonic_Information;
269
270/**
271 *  @brief Rate Monotonic Manager Initialization
272 *
273 *  This routine performs the initialization necessary for this manager.
274 */
275void _Rate_monotonic_Manager_initialization(void);
276
277/**
278 *  @brief rtems_rate_monotonic_create
279 *
280 *  This routine implements the rate_monotonic_create directive.  The
281 *  period will have the name name.  It returns the id of the
282 *  created period in ID.
283 */
284rtems_status_code rtems_rate_monotonic_create(
285  rtems_name    name,
286  Objects_Id   *id
287);
288
289/**
290 *  @brief rtems_rate_monotonic_ident
291 *
292 *  This routine implements the rtems_rate_monotonic_ident directive.
293 *  It returns the period ID associated with name.  If more than one period
294 *  is named name, then the period to which the ID belongs is arbitrary.
295 */
296rtems_status_code rtems_rate_monotonic_ident(
297  rtems_name    name,
298  Objects_Id   *id
299);
300
301/**
302 *  @brief rtems_rate_monotonic_cancel
303 *
304 *  This routine implements the rtems_rate_monotonic_cancel directive.  This
305 *  directive stops the period associated with ID from continuing to
306 *  run.
307 */
308rtems_status_code rtems_rate_monotonic_cancel(
309  Objects_Id id
310);
311
312/**
313 *  @brief rtems_rate_monotonic_delete
314 *
315 *  This routine implements the rtems_rate_monotonic_delete directive.  The
316 *  period indicated by ID is deleted.
317 */
318rtems_status_code rtems_rate_monotonic_delete(
319  Objects_Id id
320);
321
322/**
323 *  @brief rtems_rate_monotonic_get_status
324 *
325 *  This routine implements the rtems_rate_monotonic_get_status directive.
326 *  Information about the period indicated by ID is returned.
327 *
328 */
329rtems_status_code rtems_rate_monotonic_get_status(
330  Objects_Id                           id,
331  rtems_rate_monotonic_period_status  *status
332);
333
334/**
335 *  @brief rtems_rate_monotonic_get_statistics
336 *
337 *  This routine implements the rtems_rate_monotonic_get_statistics directive.
338 *  Statistics gathered from the use of this period are returned.
339 */
340rtems_status_code rtems_rate_monotonic_get_statistics(
341  Objects_Id                              id,
342  rtems_rate_monotonic_period_statistics *statistics
343);
344
345/**
346 *  @brief rtems_rate_monotonic_reset_statistics
347 *
348 *  This routine allows a thread to reset the statistics information
349 *  on a specific period instance.
350 */
351rtems_status_code rtems_rate_monotonic_reset_statistics(
352  Objects_Id                               id
353);
354
355/**
356 *  @brief rtems_rate_monotonic_reset_all_statistics
357 *
358 *  This routine allows a thread to reset the statistics information
359 *  on ALL period instances.
360 */
361void rtems_rate_monotonic_reset_all_statistics( void );
362
363/**
364 *  @brief rtems_rate_monotonic_report_statistics
365 *
366 *  This routine allows a thread to print the statistics information
367 *  on ALL period instances which have non-zero counts using printk.
368 */
369void rtems_rate_monotonic_report_statistics_with_plugin(
370  void                  *context,
371  rtems_printk_plugin_t  print
372);
373
374/**
375 *  @brief rtems_rate_monotonic_report_statistics
376 *
377 *  This routine allows a thread to print the statistics information
378 *  on ALL period instances which have non-zero counts using printk.
379 */
380void rtems_rate_monotonic_report_statistics( void );
381
382/**
383 *  @brief rtems_rate_monotonic_period
384 *
385 *  This routine implements the rtems_rate_monotonic_period directive.  When
386 *  length is non-zero, this directive initiates the period associated with
387 *  ID from continuing for a period of length.  If length is zero, then
388 *  result is set to indicate the current state of the period.
389 */
390rtems_status_code rtems_rate_monotonic_period(
391  Objects_Id      id,
392  rtems_interval  length
393);
394
395/**
396 *  @brief _Rate_monotonic_Timeout
397 *
398 *  This routine is invoked when the period represented
399 *  by ID expires.  If the thread which owns this period is blocked
400 *  waiting for the period to expire, then it is readied and the
401 *  period is restarted.  If the owning thread is not waiting for the
402 *  period to expire, then the period is placed in the EXPIRED
403 *  state and not restarted.
404 */
405void _Rate_monotonic_Timeout(
406  Objects_Id  id,
407  void       *ignored
408);
409
410/**
411 *  @brief _Rate_monotonic_Get_status(
412 *
413 *  This routine is invoked to compute the elapsed wall time and cpu
414 *  time for a period.
415 *
416 *  @param[in] the_period points to the period being operated upon.
417 *  @param[out] wall_since_last_period is set to the wall time elapsed
418 *              since the period was initiated.
419 *  @param[out] cpu_since_last_period is set to the cpu time used by the
420 *              owning thread since the period was initiated.
421 *
422 *  @return This routine returns true if the status can be determined
423 *          and false otherwise.
424 */
425bool _Rate_monotonic_Get_status(
426  Rate_monotonic_Control        *the_period,
427  Rate_monotonic_Period_time_t  *wall_since_last_period,
428  Thread_CPU_usage_t            *cpu_since_last_period
429);
430
431/**
432 *  @brief _Rate_monotonic_Initiate_statistics(
433 *
434 *  This routine is invoked when a period is initiated via an explicit
435 *  call to rtems_rate_monotonic_period for the period's first iteration
436 *  or from _Rate_monotonic_Timeout for period iterations 2-n.
437 *
438 *  @param[in] the_period points to the period being operated upon.
439 */
440void _Rate_monotonic_Initiate_statistics(
441  Rate_monotonic_Control *the_period
442);
443
444/**
445 *  @brief _Rate_monotonic_Reset_wall_time_statistics
446 *
447 *  This method resets the statistics information for a period instance.
448 */
449#ifndef __RTEMS_USE_TICKS_FOR_STATISTICS__
450  #define _Rate_monotonic_Reset_wall_time_statistics( _the_period ) \
451     do { \
452        /* set the minimums to a large value */ \
453        _Timestamp_Set( \
454          &(_the_period)->Statistics.min_wall_time, \
455          0x7fffffff, \
456          0x7fffffff \
457        ); \
458     } while (0)
459#else
460  #define _Rate_monotonic_Reset_wall_time_statistics( _the_period ) \
461     do { \
462        /* set the minimum to a large value */ \
463        (_the_period)->Statistics.min_wall_time = 0xffffffff; \
464     } while (0)
465#endif
466
467/**
468 *  @brief Rate_monotonic_Reset_cpu_use_statistics
469 *
470 *  This helper method resets the period CPU usage statistics structure.
471 */
472#ifndef __RTEMS_USE_TICKS_FOR_STATISTICS__
473  #define _Rate_monotonic_Reset_cpu_use_statistics( _the_period ) \
474     do { \
475        /* set the minimums to a large value */ \
476        _Timestamp_Set( \
477          &(_the_period)->Statistics.min_cpu_time, \
478          0x7fffffff, \
479          0x7fffffff \
480        ); \
481     } while (0)
482#else
483  #define _Rate_monotonic_Reset_cpu_use_statistics( _the_period ) \
484     do { \
485        /* set the minimum to a large value */ \
486        (_the_period)->Statistics.min_cpu_time = 0xffffffff; \
487     } while (0)
488#endif
489
490/**
491 *  @brief Rate_monotonic_Reset_statistics
492 *
493 *  This helper method resets the period wall time statistics structure.
494 */
495#define _Rate_monotonic_Reset_statistics( _the_period ) \
496  do { \
497    memset( \
498      &(_the_period)->Statistics, \
499      0, \
500      sizeof( rtems_rate_monotonic_period_statistics ) \
501    ); \
502    _Rate_monotonic_Reset_cpu_use_statistics( _the_period ); \
503    _Rate_monotonic_Reset_wall_time_statistics( _the_period ); \
504  } while (0)
505
506#ifndef __RTEMS_APPLICATION__
507#include <rtems/rtems/ratemon.inl>
508#endif
509
510#ifdef __cplusplus
511}
512#endif
513
514/**@}*/
515
516#endif
517/* end of include file */
Note: See TracBrowser for help on using the repository browser.