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

Last change on this file since de6e515 was de6e515, checked in by Sebastian Huber <sebastian.huber@…>, on Jun 24, 2020 at 4:58:53 AM

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.

  • Property mode set to 100644
File size: 22.1 KB
Line 
1/* SPDX-License-Identifier: BSD-2-Clause */
2
3/**
4 * @file
5 *
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 */
54
55#ifndef _RTEMS_RTEMS_RATEMON_H
56#define _RTEMS_RTEMS_RATEMON_H
57
58#include <stdint.h>
59#include <sys/_timespec.h>
60#include <rtems/rtems/status.h>
61#include <rtems/rtems/types.h>
62#include <rtems/score/watchdogticks.h>
63
64#ifdef __cplusplus
65extern "C" {
66#endif
67
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.
88 */
89typedef enum {
90  /**
91   * @brief This status indicates the period is off the watchdog chain, and has
92   *   never been initialized.
93   */
94  RATE_MONOTONIC_INACTIVE,
95
96  /**
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.
99   */
100  RATE_MONOTONIC_ACTIVE,
101
102  /**
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.
106   */
107  RATE_MONOTONIC_EXPIRED
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.
116 */
117typedef struct {
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   */
132  struct timespec min_cpu_time;
133
134  /**
135   * @brief This member contains the highest amount of processor time used in a
136   *   period.
137   */
138  struct timespec max_cpu_time;
139
140  /**
141   * @brief This member contains the total amount of processor time used in a
142   *   period.
143   */
144  struct timespec total_cpu_time;
145
146  /**
147   * @brief This member contains the least amount of CLOCK_MONOTONIC time used in
148   *   a period.
149   */
150  struct timespec min_wall_time;
151
152  /**
153   * @brief This member contains the highest amount of CLOCK_MONOTONIC time used
154   *   in a period.
155   */
156  struct timespec max_wall_time;
157
158  /**
159   * @brief This member contains the total amount of CLOCK_MONOTONIC time used in
160   *   a period.
161   */
162  struct timespec total_wall_time;
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.
171 */
172typedef struct {
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
459);
460
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
520);
521
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
578 */
579rtems_status_code rtems_rate_monotonic_get_statistics(
580  rtems_id                                id,
581  rtems_rate_monotonic_period_statistics *status
582);
583
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
633 */
634void rtems_rate_monotonic_reset_all_statistics( void );
635
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
679 */
680void rtems_rate_monotonic_report_statistics_with_plugin(
681  const struct rtems_printer *printer
682);
683
684#ifdef __cplusplus
685}
686#endif
687
688#endif /* _RTEMS_RTEMS_RATEMON_H */
Note: See TracBrowser for help on using the repository browser.