source: rtems/cpukit/include/rtems/rtems/ratemon.h @ 1e039fb3

Last change on this file since 1e039fb3 was 1e039fb3, checked in by Sebastian Huber <sebastian.huber@…>, on Nov 8, 2018 at 7:01:13 AM

rtems: Deprecate rtems_rate_monotonic_period_time_t

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

Close #3595.

  • Property mode set to 100644
File size: 13.0 KB
Line 
1/**
2 * @file rtems/rtems/ratemon.h
3 *
4 * @defgroup ClassicRateMon Rate Monotonic Scheduler
5 *
6 * @ingroup ClassicRTEMS
7 * @brief Classic API Rate Monotonic Manager.
8 *
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.
13 *
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
21 * - obtain the number of postponed jobs
22 */
23
24/* COPYRIGHT (c) 1989-2009, 2016.
25 * On-Line Applications Research Corporation (OAR).
26 * COPYRIGHT (c) 2016-2017 Kuan-Hsun Chen.
27 *
28 * The license and distribution terms for this file may be
29 * found in the file LICENSE in this distribution or at
30 * http://www.rtems.org/license/LICENSE.
31 */
32
33#ifndef _RTEMS_RTEMS_RATEMON_H
34#define _RTEMS_RTEMS_RATEMON_H
35
36#include <rtems/rtems/types.h>
37#include <rtems/rtems/status.h>
38#include <rtems/score/thread.h>
39#include <rtems/score/watchdog.h>
40
41struct rtems_printer;
42
43#ifdef __cplusplus
44extern "C" {
45#endif
46
47/**
48 *  @defgroup ClassicRateMon Rate Monotonic Scheduler
49 *
50 *  @ingroup ClassicRTEMS
51 *
52 *  This encapsulates functionality related to the Classic API Rate
53 *  Monotonic Manager.
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
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.
60 */
61/**@{*/
62
63/**
64 *  This is the public type used for the rate monotonic timing
65 *  statistics.
66 */
67#include <rtems/score/timespec.h>
68
69typedef struct timespec rtems_rate_monotonic_period_time_t RTEMS_DEPRECATED;
70
71/**
72 *  This is the internal type used for the rate monotonic timing
73 *  statistics.
74 */
75#include <rtems/score/timestamp.h>
76
77/**
78 *  The following enumerated type defines the states in which a
79 *  period may be.
80 */
81typedef enum {
82  /**
83   * This value indicates the period is off the watchdog chain,
84   * and has never been initialized.
85   */
86  RATE_MONOTONIC_INACTIVE,
87
88  /**
89   * This value indicates the period is on the watchdog chain, and
90   * running.  The owner should be executed or blocked waiting on
91   * another object.
92   */
93  RATE_MONOTONIC_ACTIVE,
94
95  /**
96   * This value indicates the period is off the watchdog chain, and
97   * has expired.  The owner is still executing and has taken too much
98   * all time to complete this iteration of the period.
99   */
100  RATE_MONOTONIC_EXPIRED
101}   rtems_rate_monotonic_period_states;
102
103/**
104 *  The following constant is the interval passed to the rate_monontonic_period
105 *  directive to obtain status information.
106 */
107#define RTEMS_PERIOD_STATUS       WATCHDOG_NO_TIMEOUT
108
109/**
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
114 *        internal one uses Timestamp_Control.
115 */
116typedef struct {
117  /** This field contains the number of periods executed. */
118  uint32_t     count;
119  /** This field contains the number of periods missed. */
120  uint32_t     missed_count;
121
122  /** This field contains the least amount of CPU time used in a period. */
123  struct timespec min_cpu_time;
124  /** This field contains the highest amount of CPU time used in a period. */
125  struct timespec max_cpu_time;
126  /** This field contains the total amount of wall time used in a period. */
127  struct timespec total_cpu_time;
128
129  /** This field contains the least amount of wall time used in a period. */
130  struct timespec min_wall_time;
131  /** This field contains the highest amount of wall time used in a period. */
132  struct timespec max_wall_time;
133  /** This field contains the total amount of CPU time used in a period. */
134  struct timespec total_wall_time;
135}  rtems_rate_monotonic_period_statistics;
136
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. */
148  Timestamp_Control min_cpu_time;
149  /** This field contains the highest amount of CPU time used in a period. */
150  Timestamp_Control max_cpu_time;
151  /** This field contains the total amount of wall time used in a period. */
152  Timestamp_Control total_cpu_time;
153
154  /** This field contains the least amount of wall time used in a period. */
155  Timestamp_Control min_wall_time;
156  /** This field contains the highest amount of wall time used in a period. */
157  Timestamp_Control max_wall_time;
158  /** This field contains the total amount of CPU time used in a period. */
159  Timestamp_Control total_wall_time;
160}  Rate_monotonic_Statistics;
161
162/**
163 *  The following defines the period status structure.
164 */
165typedef struct {
166  /** This is the Id of the thread using this period. */
167  rtems_id                             owner;
168
169  /** This is the current state of this period. */
170  rtems_rate_monotonic_period_states   state;
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   */
177  struct timespec                      since_last_period;
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   */
184  struct timespec                      executed_since_last_period;
185
186  /** This is the count of postponed jobs of this period. */
187  uint32_t                             postponed_jobs_count;
188}  rtems_rate_monotonic_period_status;
189
190/**
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.
197 */
198typedef struct {
199  /** This field is the object management portion of a Period instance. */
200  Objects_Control                         Object;
201
202  /**
203   * @brief Protects the rate monotonic period state.
204   */
205  ISR_LOCK_MEMBER(                        Lock )
206
207  /** This is the timer used to provide the unblocking mechanism. */
208  Watchdog_Control                        Timer;
209
210  /** This field indicates the current state of the period. */
211  rtems_rate_monotonic_period_states      state;
212
213  /**
214   * @brief A priority node for use by the scheduler job release and cancel
215   * operations.
216   */
217  Priority_Node                           Priority;
218
219  /**
220   * This field contains the length of the next period to be
221   * executed.
222   */
223  uint32_t                                next_length;
224
225  /**
226   * This field contains a pointer to the TCB for the thread
227   * which owns and uses this period instance.
228   */
229  Thread_Control                         *owner;
230
231  /**
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   */
236  Timestamp_Control                       cpu_usage_period_initiated;
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   */
242  Timestamp_Control                       time_period_initiated;
243
244  /**
245   * This field contains the statistics maintained for the period.
246   */
247  Rate_monotonic_Statistics               Statistics;
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;
260}   Rate_monotonic_Control;
261
262/**
263 *  @brief Create a Period
264 *
265 *  Rate Monotonic Manager
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(
272  rtems_name    name,
273  rtems_id     *id
274);
275
276/**
277 * @brief RTEMS Rate Monotonic Name to Id
278 *
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.
282 *
283 * @param[in] name is the user defined period name
284 * @param[in] id is the pointer to period id
285 *
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.
290 */
291rtems_status_code rtems_rate_monotonic_ident(
292  rtems_name    name,
293  rtems_id     *id
294);
295
296/**
297 * @brief RTEMS Rate Monotonic Cancel
298 *
299 * This routine implements the rtems_rate_monotonic_cancel directive. This
300 * directive stops the period associated with ID from continuing to
301 * run.
302 *
303 * @param[in] id is the rate monotonic id
304 *
305 * @retval RTEMS_SUCCESSFUL if successful and caller is not the owning thread
306 * or error code if unsuccessful
307 *
308 */
309rtems_status_code rtems_rate_monotonic_cancel(
310  rtems_id   id
311);
312
313/**
314 * @brief RTEMS Delete Rate Monotonic
315 *
316 * This routine implements the rtems_rate_monotonic_delete directive. The
317 * period indicated by ID is deleted.
318 *
319 * @param[in] id is the rate monotonic id
320 *
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.
324 */
325rtems_status_code rtems_rate_monotonic_delete(
326  rtems_id   id
327);
328
329/**
330 * @brief RTEMS Rate Monotonic Get Status
331 *
332 * This routine implements the rtems_rate_monotonic_get_status directive.
333 * Information about the period indicated by ID is returned.
334 *
335 * @param[in] id is the rate monotonic id
336 * @param[in] status is the pointer to status control block
337 *
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.
341 *
342 */
343rtems_status_code rtems_rate_monotonic_get_status(
344  rtems_id                             id,
345  rtems_rate_monotonic_period_status  *status
346);
347
348/**
349 * @brief RTEMS Rate Monotonic Get Statistics
350 *
351 * This routine implements the rtems_rate_monotonic_get_statistics directive.
352 * Statistics gathered from the use of this period are returned.
353 *
354 * @param[in] id is the rate monotonic id
355 * @param[in] statistics is the pointer to statistics control block
356 *
357 * @retval RTEMS_SUCCESSFUL if successful or error code if unsuccessful
358 */
359rtems_status_code rtems_rate_monotonic_get_statistics(
360  rtems_id                                id,
361  rtems_rate_monotonic_period_statistics *statistics
362);
363
364/**
365 *  @brief RTEMS Rate Monotonic Reset Statistics
366 *
367 *  Rate Monotonic Manager -- Reset Statistics
368 *
369 *  This routine allows a thread to reset the statistics information
370 *  on a specific period instance.
371 */
372rtems_status_code rtems_rate_monotonic_reset_statistics(
373  rtems_id                                 id
374);
375
376/**
377 *  @brief rtems_rate_monotonic_reset_all_statistics
378 *
379 *  This routine allows a thread to reset the statistics information
380 *  on ALL period instances.
381 */
382void rtems_rate_monotonic_reset_all_statistics( void );
383
384/**
385 *  @brief RTEMS Report Rate Monotonic Statistics
386 *
387 *  This routine allows a thread to print the statistics information
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.
392 */
393void rtems_rate_monotonic_report_statistics_with_plugin(
394  const struct rtems_printer *printer
395);
396
397/**
398 *  @brief RTEMS Report Rate Monotonic Statistics
399 *
400 *  This routine allows a thread to print the statistics information
401 *  on ALL period instances which have non-zero counts using printk.
402 */
403void rtems_rate_monotonic_report_statistics( void );
404
405/**
406 * @brief RTEMS Rate Monotonic Period
407 *
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.
412 *
413 * @param[in] id is the rate monotonic id
414 * @param[in] length is the length of period (in ticks)
415 *
416 * @retval RTEMS_SUCCESSFUL if successful or error code if unsuccessful
417 */
418rtems_status_code rtems_rate_monotonic_period(
419  rtems_id        id,
420  rtems_interval  length
421);
422
423/**@}*/
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.