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

Last change on this file since ccc6695 was ccc6695, checked in by Sebastian Huber <sebastian.huber@…>, on Nov 8, 2018 at 10:50:24 AM

score: Introduce <rtems/score/watchdogticks.h>

Separate the definitions related to watchdog ticks from the watchdog
structures.

Update #3598.

  • Property mode set to 100644
File size: 9.5 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
39struct rtems_printer;
40
41#ifdef __cplusplus
42extern "C" {
43#endif
44
45/**
46 *  @defgroup ClassicRateMon Rate Monotonic Scheduler
47 *
48 *  @ingroup ClassicRTEMS
49 *
50 *  This encapsulates functionality related to the Classic API Rate
51 *  Monotonic Manager.
52 *
53 *  Statistics are kept for each period and can be obtained or printed via
54 *  API calls.  The statistics kept include minimum, maximum and average times
55 *  for both cpu usage and wall time.  The statistics indicate the execution
56 *  and wall time used by the owning thread between successive calls to
57 *  rtems_rate_monotonic_period.
58 */
59/**@{*/
60
61typedef struct timespec rtems_rate_monotonic_period_time_t RTEMS_DEPRECATED;
62
63/**
64 *  The following enumerated type defines the states in which a
65 *  period may be.
66 */
67typedef enum {
68  /**
69   * This value indicates the period is off the watchdog chain,
70   * and has never been initialized.
71   */
72  RATE_MONOTONIC_INACTIVE,
73
74  /**
75   * This value indicates the period is on the watchdog chain, and
76   * running.  The owner should be executed or blocked waiting on
77   * another object.
78   */
79  RATE_MONOTONIC_ACTIVE,
80
81  /**
82   * This value indicates the period is off the watchdog chain, and
83   * has expired.  The owner is still executing and has taken too much
84   * all time to complete this iteration of the period.
85   */
86  RATE_MONOTONIC_EXPIRED
87}   rtems_rate_monotonic_period_states;
88
89/**
90 *  The following constant is the interval passed to the rate_monontonic_period
91 *  directive to obtain status information.
92 */
93#define RTEMS_PERIOD_STATUS       WATCHDOG_NO_TIMEOUT
94
95/**
96 *  The following defines the PUBLIC data structure that has the
97 *  statistics kept on each period instance.
98 *
99 *  @note The public structure uses struct timespec while the
100 *        internal one uses Timestamp_Control.
101 */
102typedef struct {
103  /** This field contains the number of periods executed. */
104  uint32_t     count;
105  /** This field contains the number of periods missed. */
106  uint32_t     missed_count;
107
108  /** This field contains the least amount of CPU time used in a period. */
109  struct timespec min_cpu_time;
110  /** This field contains the highest amount of CPU time used in a period. */
111  struct timespec max_cpu_time;
112  /** This field contains the total amount of wall time used in a period. */
113  struct timespec total_cpu_time;
114
115  /** This field contains the least amount of wall time used in a period. */
116  struct timespec min_wall_time;
117  /** This field contains the highest amount of wall time used in a period. */
118  struct timespec max_wall_time;
119  /** This field contains the total amount of CPU time used in a period. */
120  struct timespec total_wall_time;
121}  rtems_rate_monotonic_period_statistics;
122
123/**
124 *  The following defines the period status structure.
125 */
126typedef struct {
127  /** This is the Id of the thread using this period. */
128  rtems_id                             owner;
129
130  /** This is the current state of this period. */
131  rtems_rate_monotonic_period_states   state;
132
133  /**
134   *  This is the length of wall time that has passed since this period
135   *  was last initiated.  If the period is expired or has not been initiated,
136   *  then this field has no meaning.
137   */
138  struct timespec                      since_last_period;
139
140  /**
141   *  This is the amount of CPU time that has been used since this period
142   *  was last initiated.  If the period is expired or has not been initiated,
143   *  then this field has no meaning.
144   */
145  struct timespec                      executed_since_last_period;
146
147  /** This is the count of postponed jobs of this period. */
148  uint32_t                             postponed_jobs_count;
149}  rtems_rate_monotonic_period_status;
150
151/**
152 *  @brief Create a Period
153 *
154 *  Rate Monotonic Manager
155 *
156 *  This routine implements the rate_monotonic_create directive.  The
157 *  period will have the name name.  It returns the id of the
158 *  created period in ID.
159 */
160rtems_status_code rtems_rate_monotonic_create(
161  rtems_name    name,
162  rtems_id     *id
163);
164
165/**
166 * @brief RTEMS Rate Monotonic Name to Id
167 *
168 * This routine implements the rtems_rate_monotonic_ident directive.
169 * It returns the period ID associated with name. If more than one period
170 * is named name, then the period to which the ID belongs is arbitrary.
171 *
172 * @param[in] name is the user defined period name
173 * @param[in] id is the pointer to period id
174 *
175 * @retval This method returns RTEMS_SUCCESSFUL if there was not an
176 *         error. Otherwise, a status code is returned indicating the
177 *         source of the error. If successful, the id will
178 *         be filled in with the region id.
179 */
180rtems_status_code rtems_rate_monotonic_ident(
181  rtems_name    name,
182  rtems_id     *id
183);
184
185/**
186 * @brief RTEMS Rate Monotonic Cancel
187 *
188 * This routine implements the rtems_rate_monotonic_cancel directive. This
189 * directive stops the period associated with ID from continuing to
190 * run.
191 *
192 * @param[in] id is the rate monotonic id
193 *
194 * @retval RTEMS_SUCCESSFUL if successful and caller is not the owning thread
195 * or error code if unsuccessful
196 *
197 */
198rtems_status_code rtems_rate_monotonic_cancel(
199  rtems_id   id
200);
201
202/**
203 * @brief RTEMS Delete Rate Monotonic
204 *
205 * This routine implements the rtems_rate_monotonic_delete directive. The
206 * period indicated by ID is deleted.
207 *
208 * @param[in] id is the rate monotonic id
209 *
210 * @retval This method returns RTEMS_SUCCESSFUL if there was not an
211 *         error. Otherwise, a status code is returned indicating the
212 *         source of the error.
213 */
214rtems_status_code rtems_rate_monotonic_delete(
215  rtems_id   id
216);
217
218/**
219 * @brief RTEMS Rate Monotonic Get Status
220 *
221 * This routine implements the rtems_rate_monotonic_get_status directive.
222 * Information about the period indicated by ID is returned.
223 *
224 * @param[in] id is the rate monotonic id
225 * @param[in] status is the pointer to status control block
226 *
227 * @retval This method returns RTEMS_SUCCESSFUL if there was not an
228 *         error. Otherwise, a status code is returned indicating the
229 *         source of the error.
230 *
231 */
232rtems_status_code rtems_rate_monotonic_get_status(
233  rtems_id                             id,
234  rtems_rate_monotonic_period_status  *status
235);
236
237/**
238 * @brief RTEMS Rate Monotonic Get Statistics
239 *
240 * This routine implements the rtems_rate_monotonic_get_statistics directive.
241 * Statistics gathered from the use of this period are returned.
242 *
243 * @param[in] id is the rate monotonic id
244 * @param[in] statistics is the pointer to statistics control block
245 *
246 * @retval RTEMS_SUCCESSFUL if successful or error code if unsuccessful
247 */
248rtems_status_code rtems_rate_monotonic_get_statistics(
249  rtems_id                                id,
250  rtems_rate_monotonic_period_statistics *statistics
251);
252
253/**
254 *  @brief RTEMS Rate Monotonic Reset Statistics
255 *
256 *  Rate Monotonic Manager -- Reset Statistics
257 *
258 *  This routine allows a thread to reset the statistics information
259 *  on a specific period instance.
260 */
261rtems_status_code rtems_rate_monotonic_reset_statistics(
262  rtems_id                                 id
263);
264
265/**
266 *  @brief rtems_rate_monotonic_reset_all_statistics
267 *
268 *  This routine allows a thread to reset the statistics information
269 *  on ALL period instances.
270 */
271void rtems_rate_monotonic_reset_all_statistics( void );
272
273/**
274 *  @brief RTEMS Report Rate Monotonic Statistics
275 *
276 *  This routine allows a thread to print the statistics information
277 *  on ALL period instances which have non-zero counts using the RTEMS
278 *  printer. The implementation of this directive straddles the fence
279 *  between inside and outside of RTEMS.  It is presented as part of
280 *  the Manager but actually uses other services of the Manager.
281 */
282void rtems_rate_monotonic_report_statistics_with_plugin(
283  const struct rtems_printer *printer
284);
285
286/**
287 *  @brief RTEMS Report Rate Monotonic Statistics
288 *
289 *  This routine allows a thread to print the statistics information
290 *  on ALL period instances which have non-zero counts using printk.
291 */
292void rtems_rate_monotonic_report_statistics( void );
293
294/**
295 * @brief RTEMS Rate Monotonic Period
296 *
297 * This routine implements the rtems_rate_monotonic_period directive. When
298 * length is non-zero, this directive initiates the period associated with
299 * ID from continuing for a period of length. If length is zero, then
300 * result is set to indicate the current state of the period.
301 *
302 * @param[in] id is the rate monotonic id
303 * @param[in] length is the length of period (in ticks)
304 *
305 * @retval RTEMS_SUCCESSFUL if successful or error code if unsuccessful
306 */
307rtems_status_code rtems_rate_monotonic_period(
308  rtems_id        id,
309  rtems_interval  length
310);
311
312/**@}*/
313
314#ifdef __cplusplus
315}
316#endif
317
318#endif
319/* end of include file */
Note: See TracBrowser for help on using the repository browser.