source: rtems/cpukit/include/rtems/rtems/ratemon.h @ 78bbe59

Last change on this file since 78bbe59 was 78bbe59, checked in by Sebastian Huber <sebastian.huber@…>, on Nov 7, 2018 at 1:12:52 PM

rtems: Move internal structures to ratemondata.h

Update #3598.

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