1 | .. comment SPDX-License-Identifier: CC-BY-SA-4.0 |
---|
2 | |
---|
3 | .. COMMENT: COPYRIGHT (c) 1988-2008. |
---|
4 | .. COMMENT: On-Line Applications Research Corporation (OAR). |
---|
5 | .. COMMENT: COPYRIGHT (c) 2017 Kuan-Hsun Chen. |
---|
6 | .. COMMENT: All rights reserved. |
---|
7 | |
---|
8 | .. index:: rate mononitonic tasks |
---|
9 | .. index:: periodic tasks |
---|
10 | |
---|
11 | Rate Monotonic Manager |
---|
12 | ********************** |
---|
13 | |
---|
14 | Introduction |
---|
15 | ============ |
---|
16 | |
---|
17 | The rate monotonic manager provides facilities to implement tasks which execute |
---|
18 | in a periodic fashion. Critically, it also gathers information about the |
---|
19 | execution of those periods and can provide important statistics to the user |
---|
20 | which can be used to analyze and tune the application. The directives provided |
---|
21 | by the rate monotonic manager are: |
---|
22 | |
---|
23 | - rtems_rate_monotonic_create_ - Create a rate monotonic period |
---|
24 | |
---|
25 | - rtems_rate_monotonic_ident_ - Get ID of a period |
---|
26 | |
---|
27 | - rtems_rate_monotonic_cancel_ - Cancel a period |
---|
28 | |
---|
29 | - rtems_rate_monotonic_delete_ - Delete a rate monotonic period |
---|
30 | |
---|
31 | - rtems_rate_monotonic_period_ - Conclude current/Start next period |
---|
32 | |
---|
33 | - rtems_rate_monotonic_get_status_ - Obtain status from a period |
---|
34 | |
---|
35 | - rtems_rate_monotonic_get_statistics_ - Obtain statistics from a period |
---|
36 | |
---|
37 | - rtems_rate_monotonic_reset_statistics_ - Reset statistics for a period |
---|
38 | |
---|
39 | - rtems_rate_monotonic_reset_all_statistics_ - Reset statistics for all periods |
---|
40 | |
---|
41 | - rtems_rate_monotonic_report_statistics_ - Print period statistics report |
---|
42 | |
---|
43 | Background |
---|
44 | ========== |
---|
45 | |
---|
46 | The rate monotonic manager provides facilities to manage the execution of |
---|
47 | periodic tasks. This manager was designed to support application designers who |
---|
48 | utilize the Rate Monotonic Scheduling Algorithm (RMS) to ensure that their |
---|
49 | periodic tasks will meet their deadlines, even under transient overload |
---|
50 | conditions. Although designed for hard real-time systems, the services |
---|
51 | provided by the rate monotonic manager may be used by any application which |
---|
52 | requires periodic tasks. |
---|
53 | |
---|
54 | Rate Monotonic Manager Required Support |
---|
55 | --------------------------------------- |
---|
56 | |
---|
57 | A clock tick is required to support the functionality provided by this manager. |
---|
58 | |
---|
59 | Period Statistics |
---|
60 | ----------------- |
---|
61 | |
---|
62 | This manager maintains a set of statistics on each period object. These |
---|
63 | statistics are reset implictly at period creation time and may be reset or |
---|
64 | obtained at any time by the application. The following is a list of the |
---|
65 | information kept: |
---|
66 | |
---|
67 | ``owner`` |
---|
68 | is the id of the thread that owns this period. |
---|
69 | |
---|
70 | ``count`` |
---|
71 | is the total number of periods executed. |
---|
72 | |
---|
73 | ``missed_count`` |
---|
74 | is the number of periods that were missed. |
---|
75 | |
---|
76 | ``min_cpu_time`` |
---|
77 | is the minimum amount of CPU execution time consumed on any execution of the |
---|
78 | periodic loop. |
---|
79 | |
---|
80 | ``max_cpu_time`` |
---|
81 | is the maximum amount of CPU execution time consumed on any execution of the |
---|
82 | periodic loop. |
---|
83 | |
---|
84 | ``total_cpu_time`` |
---|
85 | is the total amount of CPU execution time consumed by executions of the |
---|
86 | periodic loop. |
---|
87 | |
---|
88 | ``min_wall_time`` |
---|
89 | is the minimum amount of wall time that passed on any execution of the |
---|
90 | periodic loop. |
---|
91 | |
---|
92 | ``max_wall_time`` |
---|
93 | is the maximum amount of wall time that passed on any execution of the |
---|
94 | periodic loop. |
---|
95 | |
---|
96 | ``total_wall_time`` |
---|
97 | is the total amount of wall time that passed during executions of the |
---|
98 | periodic loop. |
---|
99 | |
---|
100 | Each period is divided into two consecutive phases. The period starts with the |
---|
101 | active phase of the task and is followed by the inactive phase of the task. In |
---|
102 | the inactive phase the task is blocked and waits for the start of the next |
---|
103 | period. The inactive phase is skipped in case of a period miss. The wall time |
---|
104 | includes the time during the active phase of the task on which the task is not |
---|
105 | executing on a processor. The task is either blocked (for example it waits for |
---|
106 | a resource) or a higher priority tasks executes, thus preventing it from |
---|
107 | executing. In case the wall time exceeds the period time, then this is a |
---|
108 | period miss. The gap between the wall time and the period time is the margin |
---|
109 | between a period miss or success. |
---|
110 | |
---|
111 | The period statistics information is inexpensive to maintain and can provide |
---|
112 | very useful insights into the execution characteristics of a periodic task |
---|
113 | loop. But it is just information. The period statistics reported must be |
---|
114 | analyzed by the user in terms of what the applications is. For example, in an |
---|
115 | application where priorities are assigned by the Rate Monotonic Algorithm, it |
---|
116 | would be very undesirable for high priority (i.e. frequency) tasks to miss |
---|
117 | their period. Similarly, in nearly any application, if a task were supposed to |
---|
118 | execute its periodic loop every 10 milliseconds and it averaged 11 |
---|
119 | milliseconds, then application requirements are not being met. |
---|
120 | |
---|
121 | The information reported can be used to determine the "hot spots" in the |
---|
122 | application. Given a period's id, the user can determine the length of that |
---|
123 | period. From that information and the CPU usage, the user can calculate the |
---|
124 | percentage of CPU time consumed by that periodic task. For example, a task |
---|
125 | executing for 20 milliseconds every 200 milliseconds is consuming 10 percent of |
---|
126 | the processor's execution time. This is usually enough to make it a good |
---|
127 | candidate for optimization. |
---|
128 | |
---|
129 | However, execution time alone is not enough to gauge the value of optimizing a |
---|
130 | particular task. It is more important to optimize a task executing 2 |
---|
131 | millisecond every 10 milliseconds (20 percent of the CPU) than one executing 10 |
---|
132 | milliseconds every 100 (10 percent of the CPU). As a general rule of thumb, |
---|
133 | the higher frequency at which a task executes, the more important it is to |
---|
134 | optimize that task. |
---|
135 | |
---|
136 | .. index:: periodic task, definition |
---|
137 | |
---|
138 | Periodicity Definitions |
---|
139 | ---------------------------------- |
---|
140 | |
---|
141 | A periodic task is one which must be executed at a regular interval. The |
---|
142 | interval between successive iterations of the task is referred to as its |
---|
143 | period. Periodic tasks can be characterized by the length of their period and |
---|
144 | execution time. The period and execution time of a task can be used to |
---|
145 | determine the processor utilization for that task. Processor utilization is |
---|
146 | the percentage of processor time used and can be calculated on a per-task or |
---|
147 | system-wide basis. Typically, the task's worst-case execution time will be |
---|
148 | less than its period. For example, a periodic task's requirements may state |
---|
149 | that it should execute for 10 milliseconds every 100 milliseconds. Although |
---|
150 | the execution time may be the average, worst, or best case, the worst-case |
---|
151 | execution time is more appropriate for use when analyzing system behavior under |
---|
152 | transient overload conditions... index:: aperiodic task, definition |
---|
153 | |
---|
154 | In contrast, an aperiodic task executes at irregular intervals and has only a |
---|
155 | soft deadline. In other words, the deadlines for aperiodic tasks are not |
---|
156 | rigid, but adequate response times are desirable. For example, an aperiodic |
---|
157 | task may process user input from a terminal. |
---|
158 | |
---|
159 | .. index:: sporadic task, definition |
---|
160 | |
---|
161 | Finally, a sporadic task is an aperiodic task with a hard deadline and minimum |
---|
162 | interarrival time. The minimum interarrival time is the minimum period of time |
---|
163 | which exists between successive iterations of the task. For example, a |
---|
164 | sporadic task could be used to process the pressing of a fire button on a |
---|
165 | joystick. The mechanical action of the fire button ensures a minimum time |
---|
166 | period between successive activations, but the missile must be launched by a |
---|
167 | hard deadline. |
---|
168 | |
---|
169 | .. index:: Rate Monotonic Scheduling Algorithm, definition |
---|
170 | .. index:: RMS Algorithm, definition |
---|
171 | |
---|
172 | Rate Monotonic Scheduling Algorithm |
---|
173 | ----------------------------------- |
---|
174 | |
---|
175 | The Rate Monotonic Scheduling Algorithm (RMS) is important to real-time systems |
---|
176 | designers because it allows one to sufficiently guarantee that a set of tasks |
---|
177 | is schedulable (see :cite:`Liu:1973:Scheduling`, :cite:`Lehoczky:1989:RM`, |
---|
178 | :cite:`Sha:1990:Ada`, :cite:`Burns:1991:Review`). |
---|
179 | |
---|
180 | A set of tasks is said to be schedulable if all of the tasks can meet their |
---|
181 | deadlines. RMS provides a set of rules which can be used to perform |
---|
182 | a guaranteed schedulability analysis for a task set. This analysis determines |
---|
183 | whether a task set is schedulable under worst-case conditions and emphasizes |
---|
184 | the predictability of the system's behavior. It has been proven that: |
---|
185 | |
---|
186 | .. sidebar:: *RMS* |
---|
187 | |
---|
188 | RMS is an optimal fixed-priority algorithm for scheduling independent, |
---|
189 | preemptible, periodic tasks on a single processor. |
---|
190 | |
---|
191 | RMS is optimal in the sense that if a set of tasks can be scheduled by any |
---|
192 | fixed-priority algorithm, then RMS will be able to schedule that task set. |
---|
193 | RMS bases it schedulability analysis on the processor utilization level below |
---|
194 | which all deadlines can be met. |
---|
195 | |
---|
196 | RMS calls for the static assignment of task priorities based upon their period. |
---|
197 | The shorter a task's period, the higher its priority. For example, a task with |
---|
198 | a 1 millisecond period has higher priority than a task with a 100 millisecond |
---|
199 | period. If two tasks have the same period, then RMS does not distinguish |
---|
200 | between the tasks. However, RTEMS specifies that when given tasks of equal |
---|
201 | priority, the task which has been ready longest will execute first. RMS's |
---|
202 | priority assignment scheme does not provide one with exact numeric values for |
---|
203 | task priorities. For example, consider the following task set and priority |
---|
204 | assignments: |
---|
205 | |
---|
206 | +--------------------+---------------------+---------------------+ |
---|
207 | | Task | Period | Priority | |
---|
208 | | | (in milliseconds) | | |
---|
209 | +====================+=====================+=====================+ |
---|
210 | | 1 | 100 | Low | |
---|
211 | +--------------------+---------------------+---------------------+ |
---|
212 | | 2 | 50 | Medium | |
---|
213 | +--------------------+---------------------+---------------------+ |
---|
214 | | 3 | 50 | Medium | |
---|
215 | +--------------------+---------------------+---------------------+ |
---|
216 | | 4 | 25 | High | |
---|
217 | +--------------------+---------------------+---------------------+ |
---|
218 | |
---|
219 | RMS only calls for task 1 to have the lowest priority, task 4 to have the |
---|
220 | highest priority, and tasks 2 and 3 to have an equal priority between that of |
---|
221 | tasks 1 and 4. The actual RTEMS priorities assigned to the tasks must only |
---|
222 | adhere to those guidelines. |
---|
223 | |
---|
224 | Many applications have tasks with both hard and soft deadlines. The tasks with |
---|
225 | hard deadlines are typically referred to as the critical task set, with the |
---|
226 | soft deadline tasks being the non-critical task set. The critical task set can |
---|
227 | be scheduled using RMS, with the non-critical tasks not executing under |
---|
228 | transient overload, by simply assigning priorities such that the lowest |
---|
229 | priority critical task (i.e. longest period) has a higher priority than the |
---|
230 | highest priority non-critical task. Although RMS may be used to assign |
---|
231 | priorities to the non-critical tasks, it is not necessary. In this instance, |
---|
232 | schedulability is only guaranteed for the critical task set. |
---|
233 | |
---|
234 | .. index:: RMS schedulability analysis |
---|
235 | |
---|
236 | Schedulability Analysis |
---|
237 | ----------------------- |
---|
238 | |
---|
239 | RMS allows application designers to ensure that tasks can meet all deadlines under fixed-priority assignment, |
---|
240 | even under transient overload, without knowing exactly when any given task will |
---|
241 | execute by applying proven schedulability analysis rules. |
---|
242 | |
---|
243 | Assumptions |
---|
244 | ^^^^^^^^^^^ |
---|
245 | |
---|
246 | The schedulability analysis rules for RMS were developed based on the following |
---|
247 | assumptions: |
---|
248 | |
---|
249 | - The requests for all tasks for which hard deadlines exist are periodic, with |
---|
250 | a constant interval between requests. |
---|
251 | |
---|
252 | - Each task must complete before the next request for it occurs. |
---|
253 | |
---|
254 | - The tasks are independent in that a task does not depend on the initiation or |
---|
255 | completion of requests for other tasks. |
---|
256 | |
---|
257 | - The execution time for each task without preemption or interruption is |
---|
258 | constant and does not vary. |
---|
259 | |
---|
260 | - Any non-periodic tasks in the system are special. These tasks displace |
---|
261 | periodic tasks while executing and do not have hard, critical deadlines. |
---|
262 | |
---|
263 | Once the basic schedulability analysis is understood, some of the above |
---|
264 | assumptions can be relaxed and the side-effects accounted for. |
---|
265 | |
---|
266 | .. index:: RMS Processor Utilization Rule |
---|
267 | |
---|
268 | Processor Utilization Rule |
---|
269 | ^^^^^^^^^^^^^^^^^^^^^^^^^^ |
---|
270 | |
---|
271 | The Processor Utilization Rule requires that processor utilization be |
---|
272 | calculated based upon the period and execution time of each task. |
---|
273 | The fraction of processor time spent executing task index is ``Time(i) |
---|
274 | / Period(i)``. The processor utilization can be calculated as follows |
---|
275 | where n is the number of tasks in the set being analyzed: |
---|
276 | |
---|
277 | .. math:: |
---|
278 | |
---|
279 | Utilization = \sum_{i=1}^{n} Time_i/Period_i |
---|
280 | |
---|
281 | To ensure schedulability even under transient overload, the processor |
---|
282 | utilization must adhere to the following rule: |
---|
283 | |
---|
284 | .. math:: |
---|
285 | |
---|
286 | maximumUtilization = n * (2^{\frac{1}{n}} - 1) |
---|
287 | |
---|
288 | As the number of tasks increases, the above formula approaches ln(2) for a |
---|
289 | worst-case utilization factor of approximately 0.693. Many tasks sets can be |
---|
290 | scheduled with a greater utilization factor. In fact, the average processor |
---|
291 | utilization threshold for a randomly generated task set is approximately 0.88. |
---|
292 | See more detail in :cite:`Liu:1973:Scheduling`. |
---|
293 | |
---|
294 | Processor Utilization Rule Example |
---|
295 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
---|
296 | |
---|
297 | This example illustrates the application of the Processor Utilization Rule to |
---|
298 | an application with three critical periodic tasks. The following table details |
---|
299 | the RMS priority, period, execution time, and processor utilization for each |
---|
300 | task: |
---|
301 | |
---|
302 | +------------+----------+--------+-----------+-------------+ |
---|
303 | | Task | RMS | Period | Execution | Processor | |
---|
304 | | | Priority | | Time | Utilization | |
---|
305 | +============+==========+========+===========+=============+ |
---|
306 | | 1 | High | 100 | 15 | 0.15 | |
---|
307 | +------------+----------+--------+-----------+-------------+ |
---|
308 | | 2 | Medium | 200 | 50 | 0.25 | |
---|
309 | +------------+----------+--------+-----------+-------------+ |
---|
310 | | 3 | Low | 300 | 100 | 0.33 | |
---|
311 | +------------+----------+--------+-----------+-------------+ |
---|
312 | |
---|
313 | The total processor utilization for this task set is 0.73 which is below the |
---|
314 | upper bound of 3 * (2**(1/3) - 1), or 0.779, imposed by the Processor |
---|
315 | Utilization Rule. Therefore, this task set is guaranteed to be schedulable |
---|
316 | using RMS. |
---|
317 | |
---|
318 | .. index:: RMS First Deadline Rule |
---|
319 | |
---|
320 | First Deadline Rule |
---|
321 | ^^^^^^^^^^^^^^^^^^^ |
---|
322 | |
---|
323 | If a given set of tasks do exceed the processor utilization upper limit imposed |
---|
324 | by the Processor Utilization Rule, they can still be guaranteed to meet all |
---|
325 | their deadlines by application of the First Deadline Rule. This rule can be |
---|
326 | stated as follows: |
---|
327 | |
---|
328 | For a given set of independent periodic tasks, if each task meets its first |
---|
329 | deadline when all tasks are started at the same time, then the deadlines will |
---|
330 | always be met for any combination of start times. |
---|
331 | |
---|
332 | A key point with this rule is that ALL periodic tasks are assumed to start at |
---|
333 | the exact same instant in time. Although this assumption may seem to be |
---|
334 | invalid, RTEMS makes it quite easy to ensure. By having a non-preemptible user |
---|
335 | initialization task, all application tasks, regardless of priority, can be |
---|
336 | created and started before the initialization deletes itself. This technique |
---|
337 | ensures that all tasks begin to compete for execution time at the same instant |
---|
338 | - when the user initialization task deletes itself. |
---|
339 | See more detail in :cite:`Lehoczky:1989:RM`. |
---|
340 | |
---|
341 | First Deadline Rule Example |
---|
342 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
---|
343 | |
---|
344 | The First Deadline Rule can ensure schedulability even when the Processor |
---|
345 | Utilization Rule fails. The example below is a modification of the Processor |
---|
346 | Utilization Rule example where task execution time has been increased from 15 |
---|
347 | to 25 units. The following table details the RMS priority, period, execution |
---|
348 | time, and processor utilization for each task: |
---|
349 | |
---|
350 | +------------+----------+--------+-----------+-------------+ |
---|
351 | | Task | RMS | Period | Execution | Processor | |
---|
352 | | | Priority | | Time | Utilization | |
---|
353 | +============+==========+========+===========+=============+ |
---|
354 | | 1 | High | 100 | 25 | 0.25 | |
---|
355 | +------------+----------+--------+-----------+-------------+ |
---|
356 | | 2 | Medium | 200 | 50 | 0.25 | |
---|
357 | +------------+----------+--------+-----------+-------------+ |
---|
358 | | 3 | Low | 300 | 100 | 0.33 | |
---|
359 | +------------+----------+--------+-----------+-------------+ |
---|
360 | |
---|
361 | The total processor utilization for the modified task set is 0.83 which is |
---|
362 | above the upper bound of 3 * (2**(1/3) - 1), or 0.779, imposed by the Processor |
---|
363 | Utilization Rule. Therefore, this task set is not guaranteed to be schedulable |
---|
364 | using RMS. However, the First Deadline Rule can guarantee the schedulability |
---|
365 | of this task set. This rule calls for one to examine each occurrence of |
---|
366 | deadline until either all tasks have met their deadline or one task failed to |
---|
367 | meet its first deadline. The following table details the time of each deadline |
---|
368 | occurrence, the maximum number of times each task may have run, the total |
---|
369 | execution time, and whether all the deadlines have been met: |
---|
370 | |
---|
371 | +----------+------+------+------+----------------------+---------------+ |
---|
372 | | Deadline | Task | Task | Task | Total | All Deadlines | |
---|
373 | | Time | 1 | 2 | 3 | Execution Time | Met? | |
---|
374 | +==========+======+======+======+======================+===============+ |
---|
375 | | 100 | 1 | 1 | 1 | 25 + 50 + 100 = 175 | NO | |
---|
376 | +----------+------+------+------+----------------------+---------------+ |
---|
377 | | 200 | 2 | 1 | 1 | 50 + 50 + 100 = 200 | YES | |
---|
378 | +----------+------+------+------+----------------------+---------------+ |
---|
379 | |
---|
380 | The key to this analysis is to recognize when each task will execute. For |
---|
381 | example at time 100, task 1 must have met its first deadline, but tasks 2 and 3 |
---|
382 | may also have begun execution. In this example, at time 100 tasks 1 and 2 have |
---|
383 | completed execution and thus have met their first deadline. Tasks 1 and 2 have |
---|
384 | used (25 + 50) = 75 time units, leaving (100 - 75) = 25 time units for task 3 |
---|
385 | to begin. Because task 3 takes 100 ticks to execute, it will not have |
---|
386 | completed execution at time 100. Thus at time 100, all of the tasks except |
---|
387 | task 3 have met their first deadline. |
---|
388 | |
---|
389 | At time 200, task 1 must have met its second deadline and task 2 its first |
---|
390 | deadline. As a result, of the first 200 time units, task 1 uses (2 * 25) = 50 |
---|
391 | and task 2 uses 50, leaving (200 - 100) time units for task 3. Task 3 requires |
---|
392 | 100 time units to execute, thus it will have completed execution at time 200. |
---|
393 | Thus, all of the tasks have met their first deadlines at time 200, and the task |
---|
394 | set is schedulable using the First Deadline Rule. |
---|
395 | |
---|
396 | Relaxation of Assumptions |
---|
397 | ^^^^^^^^^^^^^^^^^^^^^^^^^ |
---|
398 | |
---|
399 | The assumptions used to develop the RMS schedulability rules are uncommon in |
---|
400 | most real-time systems. For example, it was assumed that tasks have constant |
---|
401 | unvarying execution time. It is possible to relax this assumption, simply by |
---|
402 | using the worst-case execution time of each task. |
---|
403 | |
---|
404 | Another assumption is that the tasks are independent. This means that the |
---|
405 | tasks do not wait for one another or contend for resources. This assumption |
---|
406 | can be relaxed by accounting for the amount of time a task spends waiting to |
---|
407 | acquire resources. Similarly, each task's execution time must account for any |
---|
408 | I/O performed and any RTEMS directive calls. |
---|
409 | |
---|
410 | In addition, the assumptions did not account for the time spent executing |
---|
411 | interrupt service routines. This can be accounted for by including all the |
---|
412 | processor utilization by interrupt service routines in the utilization |
---|
413 | calculation. Similarly, one should also account for the impact of delays in |
---|
414 | accessing local memory caused by direct memory access and other processors |
---|
415 | accessing local dual-ported memory. |
---|
416 | |
---|
417 | The assumption that nonperiodic tasks are used only for initialization or |
---|
418 | failure-recovery can be relaxed by placing all periodic tasks in the critical |
---|
419 | task set. This task set can be scheduled and analyzed using RMS. All |
---|
420 | nonperiodic tasks are placed in the non-critical task set. Although the |
---|
421 | critical task set can be guaranteed to execute even under transient overload, |
---|
422 | the non-critical task set is not guaranteed to execute. |
---|
423 | |
---|
424 | In conclusion, the application designer must be fully cognizant of the system |
---|
425 | and its run-time behavior when performing schedulability analysis for a system |
---|
426 | using RMS. Every hardware and software factor which impacts the execution time |
---|
427 | of each task must be accounted for in the schedulability analysis. |
---|
428 | |
---|
429 | Operations |
---|
430 | ========== |
---|
431 | |
---|
432 | Creating a Rate Monotonic Period |
---|
433 | -------------------------------- |
---|
434 | |
---|
435 | The ``rtems_rate_monotonic_create`` directive creates a rate monotonic period |
---|
436 | which is to be used by the calling task to delineate a period. RTEMS allocates |
---|
437 | a Period Control Block (PCB) from the PCB free list. This data structure is |
---|
438 | used by RTEMS to manage the newly created rate monotonic period. RTEMS returns |
---|
439 | a unique period ID to the application which is used by other rate monotonic |
---|
440 | manager directives to access this rate monotonic period. |
---|
441 | |
---|
442 | Manipulating a Period |
---|
443 | --------------------- |
---|
444 | |
---|
445 | The ``rtems_rate_monotonic_period`` directive is used to establish and maintain |
---|
446 | periodic execution utilizing a previously created rate monotonic period. Once |
---|
447 | initiated by the ``rtems_rate_monotonic_period`` directive, the period is said |
---|
448 | to run until it either expires or is reinitiated. The state of the rate |
---|
449 | monotonic period results in one of the following scenarios: |
---|
450 | |
---|
451 | - If the rate monotonic period is running, the calling task will be blocked for |
---|
452 | the remainder of the outstanding period and, upon completion of that period, |
---|
453 | the period will be reinitiated with the specified period. |
---|
454 | |
---|
455 | - If the rate monotonic period is not currently running and has not expired, it |
---|
456 | is initiated with a length of period ticks and the calling task returns |
---|
457 | immediately. |
---|
458 | |
---|
459 | - If the rate monotonic period has expired before the task invokes the |
---|
460 | ``rtems_rate_monotonic_period`` directive, the postponed job will be released |
---|
461 | until there is no more postponed jobs. The calling task returns immediately |
---|
462 | with a timeout error status. In the watchdog routine, the period will still |
---|
463 | be updated periodically and track the count of the postponed jobs :cite:`Chen:2016:Overrun`. |
---|
464 | Please note, the count of the postponed jobs is only saturated until 0xffffffff. |
---|
465 | |
---|
466 | Obtaining the Status of a Period |
---|
467 | -------------------------------- |
---|
468 | |
---|
469 | If the ``rtems_rate_monotonic_period`` directive is invoked with a period of |
---|
470 | ``RTEMS_PERIOD_STATUS`` ticks, the current state of the specified rate |
---|
471 | monotonic period will be returned. The following table details the |
---|
472 | relationship between the period's status and the directive status code returned |
---|
473 | by the ``rtems_rate_monotonic_period`` directive: |
---|
474 | |
---|
475 | .. list-table:: |
---|
476 | :class: rtems-table |
---|
477 | |
---|
478 | * - ``RTEMS_SUCCESSFUL`` |
---|
479 | - period is running |
---|
480 | * - ``RTEMS_TIMEOUT`` |
---|
481 | - period has expired |
---|
482 | * - ``RTEMS_NOT_DEFINED`` |
---|
483 | - period has never been initiated |
---|
484 | |
---|
485 | Obtaining the status of a rate monotonic period does not alter the state or |
---|
486 | length of that period. |
---|
487 | |
---|
488 | Canceling a Period |
---|
489 | ------------------ |
---|
490 | |
---|
491 | The ``rtems_rate_monotonic_cancel`` directive is used to stop the period |
---|
492 | maintained by the specified rate monotonic period. The period is stopped and |
---|
493 | the rate monotonic period can be reinitiated using the |
---|
494 | ``rtems_rate_monotonic_period`` directive. |
---|
495 | |
---|
496 | Deleting a Rate Monotonic Period |
---|
497 | -------------------------------- |
---|
498 | |
---|
499 | The ``rtems_rate_monotonic_delete`` directive is used to delete a rate |
---|
500 | monotonic period. If the period is running and has not expired, the period is |
---|
501 | automatically canceled. The rate monotonic period's control block is returned |
---|
502 | to the PCB free list when it is deleted. A rate monotonic period can be |
---|
503 | deleted by a task other than the task which created the period. |
---|
504 | |
---|
505 | Examples |
---|
506 | -------- |
---|
507 | |
---|
508 | The following sections illustrate common uses of rate monotonic periods to |
---|
509 | construct periodic tasks. |
---|
510 | |
---|
511 | Simple Periodic Task |
---|
512 | -------------------- |
---|
513 | |
---|
514 | This example consists of a single periodic task which, after initialization, |
---|
515 | executes every 100 clock ticks. |
---|
516 | |
---|
517 | .. code-block:: c |
---|
518 | :linenos: |
---|
519 | |
---|
520 | rtems_task Periodic_task(rtems_task_argument arg) |
---|
521 | { |
---|
522 | rtems_name name; |
---|
523 | rtems_id period; |
---|
524 | rtems_status_code status; |
---|
525 | name = rtems_build_name( 'P', 'E', 'R', 'D' ); |
---|
526 | status = rtems_rate_monotonic_create( name, &period ); |
---|
527 | if ( status != RTEMS_STATUS_SUCCESSFUL ) { |
---|
528 | printf( "rtems_monotonic_create failed with status of %d.\n", rc ); |
---|
529 | exit( 1 ); |
---|
530 | } |
---|
531 | while ( 1 ) { |
---|
532 | if ( rtems_rate_monotonic_period( period, 100 ) == RTEMS_TIMEOUT ) |
---|
533 | break; |
---|
534 | /* Perform some periodic actions */ |
---|
535 | } |
---|
536 | /* missed period so delete period and SELF */ |
---|
537 | status = rtems_rate_monotonic_delete( period ); |
---|
538 | if ( status != RTEMS_STATUS_SUCCESSFUL ) { |
---|
539 | printf( "rtems_rate_monotonic_delete failed with status of %d.\n", status ); |
---|
540 | exit( 1 ); |
---|
541 | } |
---|
542 | status = rtems_task_delete( SELF ); /* should not return */ |
---|
543 | printf( "rtems_task_delete returned with status of %d.\n", status ); |
---|
544 | exit( 1 ); |
---|
545 | } |
---|
546 | |
---|
547 | The above task creates a rate monotonic period as part of its initialization. |
---|
548 | The first time the loop is executed, the ``rtems_rate_monotonic_period`` |
---|
549 | directive will initiate the period for 100 ticks and return immediately. |
---|
550 | Subsequent invocations of the ``rtems_rate_monotonic_period`` directive will |
---|
551 | result in the task blocking for the remainder of the 100 tick period. If, for |
---|
552 | any reason, the body of the loop takes more than 100 ticks to execute, the |
---|
553 | ``rtems_rate_monotonic_period`` directive will return the ``RTEMS_TIMEOUT`` |
---|
554 | status. If the above task misses its deadline, it will delete the rate |
---|
555 | monotonic period and itself. |
---|
556 | |
---|
557 | Task with Multiple Periods |
---|
558 | -------------------------- |
---|
559 | |
---|
560 | This example consists of a single periodic task which, after initialization, |
---|
561 | performs two sets of actions every 100 clock ticks. The first set of actions |
---|
562 | is performed in the first forty clock ticks of every 100 clock ticks, while the |
---|
563 | second set of actions is performed between the fortieth and seventieth clock |
---|
564 | ticks. The last thirty clock ticks are not used by this task. |
---|
565 | |
---|
566 | .. code-block:: c |
---|
567 | :linenos: |
---|
568 | |
---|
569 | rtems_task Periodic_task(rtems_task_argument arg) |
---|
570 | { |
---|
571 | rtems_name name_1, name_2; |
---|
572 | rtems_id period_1, period_2; |
---|
573 | rtems_status_code status; |
---|
574 | name_1 = rtems_build_name( 'P', 'E', 'R', '1' ); |
---|
575 | name_2 = rtems_build_name( 'P', 'E', 'R', '2' ); |
---|
576 | (void ) rtems_rate_monotonic_create( name_1, &period_1 ); |
---|
577 | (void ) rtems_rate_monotonic_create( name_2, &period_2 ); |
---|
578 | while ( 1 ) { |
---|
579 | if ( rtems_rate_monotonic_period( period_1, 100 ) == TIMEOUT ) |
---|
580 | break; |
---|
581 | if ( rtems_rate_monotonic_period( period_2, 40 ) == TIMEOUT ) |
---|
582 | break; |
---|
583 | /* |
---|
584 | * Perform first set of actions between clock |
---|
585 | * ticks 0 and 39 of every 100 ticks. |
---|
586 | */ |
---|
587 | if ( rtems_rate_monotonic_period( period_2, 30 ) == TIMEOUT ) |
---|
588 | break; |
---|
589 | /* |
---|
590 | * Perform second set of actions between clock 40 and 69 |
---|
591 | * of every 100 ticks. THEN ... |
---|
592 | * |
---|
593 | * Check to make sure we didn't miss the period_2 period. |
---|
594 | */ |
---|
595 | if ( rtems_rate_monotonic_period( period_2, STATUS ) == TIMEOUT ) |
---|
596 | break; |
---|
597 | (void) rtems_rate_monotonic_cancel( period_2 ); |
---|
598 | } |
---|
599 | /* missed period so delete period and SELF */ |
---|
600 | (void ) rtems_rate_monotonic_delete( period_1 ); |
---|
601 | (void ) rtems_rate_monotonic_delete( period_2 ); |
---|
602 | (void ) task_delete( SELF ); |
---|
603 | } |
---|
604 | |
---|
605 | The above task creates two rate monotonic periods as part of its |
---|
606 | initialization. The first time the loop is executed, the |
---|
607 | ``rtems_rate_monotonic_period`` directive will initiate the period_1 period for |
---|
608 | 100 ticks and return immediately. Subsequent invocations of the |
---|
609 | ``rtems_rate_monotonic_period`` directive for period_1 will result in the task |
---|
610 | blocking for the remainder of the 100 tick period. The period_2 period is used |
---|
611 | to control the execution time of the two sets of actions within each 100 tick |
---|
612 | period established by period_1. The ``rtems_rate_monotonic_cancel( period_2 |
---|
613 | )`` call is performed to ensure that the period_2 period does not expire while |
---|
614 | the task is blocked on the period_1 period. If this cancel operation were not |
---|
615 | performed, every time the ``rtems_rate_monotonic_period( period_2, 40 )`` call |
---|
616 | is executed, except for the initial one, a directive status of |
---|
617 | ``RTEMS_TIMEOUT`` is returned. It is important to note that every time this |
---|
618 | call is made, the period_2 period will be initiated immediately and the task |
---|
619 | will not block. |
---|
620 | |
---|
621 | If, for any reason, the task misses any deadline, the |
---|
622 | ``rtems_rate_monotonic_period`` directive will return the ``RTEMS_TIMEOUT`` |
---|
623 | directive status. If the above task misses its deadline, it will delete the |
---|
624 | rate monotonic periods and itself. |
---|
625 | |
---|
626 | Directives |
---|
627 | ========== |
---|
628 | |
---|
629 | This section details the rate monotonic manager's directives. A subsection is |
---|
630 | dedicated to each of this manager's directives and describes the calling |
---|
631 | sequence, related constants, usage, and status codes. |
---|
632 | |
---|
633 | .. raw:: latex |
---|
634 | |
---|
635 | \clearpage |
---|
636 | |
---|
637 | .. index:: create a period |
---|
638 | .. index:: rtems_rate_monotonic_create |
---|
639 | |
---|
640 | .. _rtems_rate_monotonic_create: |
---|
641 | |
---|
642 | RATE_MONOTONIC_CREATE - Create a rate monotonic period |
---|
643 | ------------------------------------------------------ |
---|
644 | |
---|
645 | CALLING SEQUENCE: |
---|
646 | .. code-block:: c |
---|
647 | |
---|
648 | rtems_status_code rtems_rate_monotonic_create( |
---|
649 | rtems_name name, |
---|
650 | rtems_id *id |
---|
651 | ); |
---|
652 | |
---|
653 | DIRECTIVE STATUS CODES: |
---|
654 | .. list-table:: |
---|
655 | :class: rtems-table |
---|
656 | |
---|
657 | * - ``RTEMS_SUCCESSFUL`` |
---|
658 | - rate monotonic period created successfully |
---|
659 | * - ``RTEMS_INVALID_NAME`` |
---|
660 | - invalid period name |
---|
661 | * - ``RTEMS_TOO_MANY`` |
---|
662 | - too many periods created |
---|
663 | |
---|
664 | DESCRIPTION: |
---|
665 | This directive creates a rate monotonic period. The assigned rate |
---|
666 | monotonic id is returned in id. This id is used to access the period with |
---|
667 | other rate monotonic manager directives. For control and maintenance of |
---|
668 | the rate monotonic period, RTEMS allocates a PCB from the local PCB free |
---|
669 | pool and initializes it. |
---|
670 | |
---|
671 | NOTES: |
---|
672 | This directive will not cause the calling task to be preempted. |
---|
673 | |
---|
674 | .. raw:: latex |
---|
675 | |
---|
676 | \clearpage |
---|
677 | |
---|
678 | .. index:: get ID of a period |
---|
679 | .. index:: obtain ID of a period |
---|
680 | .. index:: rtems_rate_monotonic_ident |
---|
681 | |
---|
682 | .. _rtems_rate_monotonic_ident: |
---|
683 | |
---|
684 | RATE_MONOTONIC_IDENT - Get ID of a period |
---|
685 | ----------------------------------------- |
---|
686 | |
---|
687 | CALLING SEQUENCE: |
---|
688 | .. code-block:: c |
---|
689 | |
---|
690 | rtems_status_code rtems_rate_monotonic_ident( |
---|
691 | rtems_name name, |
---|
692 | rtems_id *id |
---|
693 | ); |
---|
694 | |
---|
695 | DIRECTIVE STATUS CODES: |
---|
696 | .. list-table:: |
---|
697 | :class: rtems-table |
---|
698 | |
---|
699 | * - ``RTEMS_SUCCESSFUL`` |
---|
700 | - period identified successfully |
---|
701 | * - ``RTEMS_INVALID_NAME`` |
---|
702 | - period name not found |
---|
703 | |
---|
704 | DESCRIPTION: |
---|
705 | This directive obtains the period id associated with the period name to be |
---|
706 | acquired. If the period name is not unique, then the period id will match |
---|
707 | one of the periods with that name. However, this period id is not |
---|
708 | guaranteed to correspond to the desired period. The period id is used to |
---|
709 | access this period in other rate monotonic manager directives. |
---|
710 | |
---|
711 | NOTES: |
---|
712 | This directive will not cause the running task to be preempted. |
---|
713 | |
---|
714 | .. raw:: latex |
---|
715 | |
---|
716 | \clearpage |
---|
717 | |
---|
718 | .. index:: cancel a period |
---|
719 | .. index:: rtems_rate_monotonic_cancel |
---|
720 | |
---|
721 | .. _rtems_rate_monotonic_cancel: |
---|
722 | |
---|
723 | RATE_MONOTONIC_CANCEL - Cancel a period |
---|
724 | --------------------------------------- |
---|
725 | |
---|
726 | CALLING SEQUENCE: |
---|
727 | .. code-block:: c |
---|
728 | |
---|
729 | rtems_status_code rtems_rate_monotonic_cancel( |
---|
730 | rtems_id id |
---|
731 | ); |
---|
732 | |
---|
733 | DIRECTIVE STATUS CODES: |
---|
734 | .. list-table:: |
---|
735 | :class: rtems-table |
---|
736 | |
---|
737 | * - ``RTEMS_SUCCESSFUL`` |
---|
738 | - period canceled successfully |
---|
739 | * - ``RTEMS_INVALID_ID`` |
---|
740 | - invalid rate monotonic period id |
---|
741 | * - ``RTEMS_NOT_OWNER_OF_RESOURCE`` |
---|
742 | - rate monotonic period not created by calling task |
---|
743 | |
---|
744 | DESCRIPTION: |
---|
745 | |
---|
746 | This directive cancels the rate monotonic period id. This period will be |
---|
747 | reinitiated by the next invocation of ``rtems_rate_monotonic_period`` |
---|
748 | with id. |
---|
749 | |
---|
750 | NOTES: |
---|
751 | This directive will not cause the running task to be preempted. |
---|
752 | |
---|
753 | The rate monotonic period specified by id must have been created by the |
---|
754 | calling task. |
---|
755 | |
---|
756 | .. raw:: latex |
---|
757 | |
---|
758 | \clearpage |
---|
759 | |
---|
760 | .. index:: rtems_rate_monotonic_delete |
---|
761 | .. index:: delete a period |
---|
762 | |
---|
763 | .. _rtems_rate_monotonic_delete: |
---|
764 | |
---|
765 | RATE_MONOTONIC_DELETE - Delete a rate monotonic period |
---|
766 | ------------------------------------------------------ |
---|
767 | |
---|
768 | CALLING SEQUENCE: |
---|
769 | .. code-block:: c |
---|
770 | |
---|
771 | rtems_status_code rtems_rate_monotonic_delete( |
---|
772 | rtems_id id |
---|
773 | ); |
---|
774 | |
---|
775 | DIRECTIVE STATUS CODES: |
---|
776 | .. list-table:: |
---|
777 | :class: rtems-table |
---|
778 | |
---|
779 | * - ``RTEMS_SUCCESSFUL`` |
---|
780 | - period deleted successfully |
---|
781 | * - ``RTEMS_INVALID_ID`` |
---|
782 | - invalid rate monotonic period id |
---|
783 | |
---|
784 | DESCRIPTION: |
---|
785 | |
---|
786 | This directive deletes the rate monotonic period specified by id. If the |
---|
787 | period is running, it is automatically canceled. The PCB for the deleted |
---|
788 | period is reclaimed by RTEMS. |
---|
789 | |
---|
790 | NOTES: |
---|
791 | This directive will not cause the running task to be preempted. |
---|
792 | |
---|
793 | A rate monotonic period can be deleted by a task other than the task which |
---|
794 | created the period. |
---|
795 | |
---|
796 | .. raw:: latex |
---|
797 | |
---|
798 | \clearpage |
---|
799 | |
---|
800 | .. index:: conclude current period |
---|
801 | .. index:: start current period |
---|
802 | .. index:: period initiation |
---|
803 | .. index:: rtems_rate_monotonic_period |
---|
804 | |
---|
805 | .. _rtems_rate_monotonic_period: |
---|
806 | |
---|
807 | RATE_MONOTONIC_PERIOD - Conclude current/Start next period |
---|
808 | ---------------------------------------------------------- |
---|
809 | |
---|
810 | CALLING SEQUENCE: |
---|
811 | .. code-block:: c |
---|
812 | |
---|
813 | rtems_status_code rtems_rate_monotonic_period( |
---|
814 | rtems_id id, |
---|
815 | rtems_interval length |
---|
816 | ); |
---|
817 | |
---|
818 | DIRECTIVE STATUS CODES: |
---|
819 | .. list-table:: |
---|
820 | :class: rtems-table |
---|
821 | |
---|
822 | * - ``RTEMS_SUCCESSFUL`` |
---|
823 | - period initiated successfully |
---|
824 | * - ``RTEMS_INVALID_ID`` |
---|
825 | - invalid rate monotonic period id |
---|
826 | * - ``RTEMS_NOT_OWNER_OF_RESOURCE`` |
---|
827 | - period not created by calling task |
---|
828 | * - ``RTEMS_NOT_DEFINED`` |
---|
829 | - period has never been initiated (only possible when period is set to PERIOD_STATUS) |
---|
830 | * - ``RTEMS_TIMEOUT`` |
---|
831 | - period has expired |
---|
832 | |
---|
833 | DESCRIPTION: |
---|
834 | This directive initiates the rate monotonic period id with a length of |
---|
835 | period ticks. If id is running, then the calling task will block for the |
---|
836 | remainder of the period before reinitiating the period with the specified |
---|
837 | period. If id was not running (either expired or never initiated), the |
---|
838 | period is immediately initiated and the directive returns immediately. |
---|
839 | If id has expired its period, the postponed job will be released immediately |
---|
840 | and the following calls of this directive will release postponed |
---|
841 | jobs until there is no more deadline miss. |
---|
842 | |
---|
843 | If invoked with a period of ``RTEMS_PERIOD_STATUS`` ticks, the current |
---|
844 | state of id will be returned. The directive status indicates the current |
---|
845 | state of the period. This does not alter the state or period of the |
---|
846 | period. |
---|
847 | |
---|
848 | NOTES: |
---|
849 | This directive will not cause the running task to be preempted. |
---|
850 | |
---|
851 | .. raw:: latex |
---|
852 | |
---|
853 | \clearpage |
---|
854 | |
---|
855 | .. index:: get status of period |
---|
856 | .. index:: obtain status of period |
---|
857 | .. index:: rtems_rate_monotonic_get_status |
---|
858 | |
---|
859 | .. _rtems_rate_monotonic_get_status: |
---|
860 | |
---|
861 | RATE_MONOTONIC_GET_STATUS - Obtain status from a period |
---|
862 | ------------------------------------------------------- |
---|
863 | |
---|
864 | CALLING SEQUENCE: |
---|
865 | .. code-block:: c |
---|
866 | |
---|
867 | rtems_status_code rtems_rate_monotonic_get_status( |
---|
868 | rtems_id id, |
---|
869 | rtems_rate_monotonic_period_status *status |
---|
870 | ); |
---|
871 | |
---|
872 | DIRECTIVE STATUS CODES: |
---|
873 | .. list-table:: |
---|
874 | :class: rtems-table |
---|
875 | |
---|
876 | * - ``RTEMS_SUCCESSFUL`` |
---|
877 | - period initiated successfully |
---|
878 | * - ``RTEMS_INVALID_ID`` |
---|
879 | - invalid rate monotonic period id |
---|
880 | * - ``RTEMS_INVALID_ADDRESS`` |
---|
881 | - invalid address of status |
---|
882 | |
---|
883 | *DESCRIPTION: |
---|
884 | This directive returns status information associated with the rate |
---|
885 | monotonic period id in the following data structure: |
---|
886 | |
---|
887 | .. index:: rtems_rate_monotonic_period_status |
---|
888 | |
---|
889 | .. code-block:: c |
---|
890 | |
---|
891 | typedef struct { |
---|
892 | rtems_id owner; |
---|
893 | rtems_rate_monotonic_period_states state; |
---|
894 | rtems_rate_monotonic_period_time_t since_last_period; |
---|
895 | rtems_thread_cpu_usage_t executed_since_last_period; |
---|
896 | uint32_t postponed_jobs_count; |
---|
897 | } rtems_rate_monotonic_period_status; |
---|
898 | |
---|
899 | .. COMMENT: RATE_MONOTONIC_INACTIVE does not have RTEMS in front of it. |
---|
900 | |
---|
901 | A configure time option can be used to select whether the time information |
---|
902 | is given in ticks or seconds and nanoseconds. The default is seconds and |
---|
903 | nanoseconds. If the period's state is ``RATE_MONOTONIC_INACTIVE``, both |
---|
904 | time values will be set to 0. Otherwise, both time values will contain |
---|
905 | time information since the last invocation of the |
---|
906 | ``rtems_rate_monotonic_period`` directive. More specifically, the |
---|
907 | since_last_period value contains the elapsed time which has occurred since |
---|
908 | the last invocation of the ``rtems_rate_monotonic_period`` directive and |
---|
909 | the ``executed_since_last_period`` contains how much processor time the |
---|
910 | owning task has consumed since the invocation of the |
---|
911 | ``rtems_rate_monotonic_period`` directive. In addition, the |
---|
912 | ``postponed_jobs_count value`` contains the count of jobs which are not |
---|
913 | released yet. |
---|
914 | |
---|
915 | NOTES: |
---|
916 | This directive will not cause the running task to be preempted. |
---|
917 | |
---|
918 | .. raw:: latex |
---|
919 | |
---|
920 | \clearpage |
---|
921 | |
---|
922 | .. index:: get statistics of period |
---|
923 | .. index:: obtain statistics of period |
---|
924 | .. index:: rtems_rate_monotonic_get_statistics |
---|
925 | |
---|
926 | .. _rtems_rate_monotonic_get_statistics: |
---|
927 | |
---|
928 | RATE_MONOTONIC_GET_STATISTICS - Obtain statistics from a period |
---|
929 | --------------------------------------------------------------- |
---|
930 | |
---|
931 | CALLING SEQUENCE: |
---|
932 | .. code-block:: c |
---|
933 | |
---|
934 | rtems_status_code rtems_rate_monotonic_get_statistics( |
---|
935 | rtems_id id, |
---|
936 | rtems_rate_monotonic_period_statistics *statistics |
---|
937 | ); |
---|
938 | |
---|
939 | DIRECTIVE STATUS CODES: |
---|
940 | .. list-table:: |
---|
941 | :class: rtems-table |
---|
942 | |
---|
943 | * - ``RTEMS_SUCCESSFUL`` |
---|
944 | - period initiated successfully |
---|
945 | * - ``RTEMS_INVALID_ID`` |
---|
946 | - invalid rate monotonic period id |
---|
947 | * - ``RTEMS_INVALID_ADDRESS`` |
---|
948 | - invalid address of statistics |
---|
949 | |
---|
950 | DESCRIPTION: |
---|
951 | This directive returns statistics information associated with the rate |
---|
952 | monotonic period id in the following data structure: |
---|
953 | |
---|
954 | .. index:: rtems_rate_monotonic_period_statistics |
---|
955 | |
---|
956 | .. code-block:: c |
---|
957 | |
---|
958 | typedef struct { |
---|
959 | uint32_t count; |
---|
960 | uint32_t missed_count; |
---|
961 | #ifdef RTEMS_ENABLE_NANOSECOND_CPU_USAGE_STATISTICS |
---|
962 | struct timespec min_cpu_time; |
---|
963 | struct timespec max_cpu_time; |
---|
964 | struct timespec total_cpu_time; |
---|
965 | #else |
---|
966 | uint32_t min_cpu_time; |
---|
967 | uint32_t max_cpu_time; |
---|
968 | uint32_t total_cpu_time; |
---|
969 | #endif |
---|
970 | #ifdef RTEMS_ENABLE_NANOSECOND_RATE_MONOTONIC_STATISTICS |
---|
971 | struct timespec min_wall_time; |
---|
972 | struct timespec max_wall_time; |
---|
973 | struct timespec total_wall_time; |
---|
974 | #else |
---|
975 | uint32_t min_wall_time; |
---|
976 | uint32_t max_wall_time; |
---|
977 | uint32_t total_wall_time; |
---|
978 | #endif |
---|
979 | } rtems_rate_monotonic_period_statistics; |
---|
980 | |
---|
981 | This directive returns the current statistics information for the period |
---|
982 | instance assocaited with ``id``. The information returned is indicated by |
---|
983 | the structure above. |
---|
984 | |
---|
985 | NOTES: |
---|
986 | This directive will not cause the running task to be preempted. |
---|
987 | |
---|
988 | .. raw:: latex |
---|
989 | |
---|
990 | \clearpage |
---|
991 | |
---|
992 | .. index:: reset statistics of period |
---|
993 | .. index:: rtems_rate_monotonic_reset_statistics |
---|
994 | |
---|
995 | .. _rtems_rate_monotonic_reset_statistics: |
---|
996 | |
---|
997 | RATE_MONOTONIC_RESET_STATISTICS - Reset statistics for a period |
---|
998 | --------------------------------------------------------------- |
---|
999 | |
---|
1000 | CALLING SEQUENCE: |
---|
1001 | .. code-block:: c |
---|
1002 | |
---|
1003 | rtems_status_code rtems_rate_monotonic_reset_statistics( |
---|
1004 | rtems_id id |
---|
1005 | ); |
---|
1006 | |
---|
1007 | DIRECTIVE STATUS CODES: |
---|
1008 | .. list-table:: |
---|
1009 | :class: rtems-table |
---|
1010 | |
---|
1011 | * - ``RTEMS_SUCCESSFUL`` |
---|
1012 | - period initiated successfully |
---|
1013 | * - ``RTEMS_INVALID_ID`` |
---|
1014 | - invalid rate monotonic period id |
---|
1015 | |
---|
1016 | DESCRIPTION: |
---|
1017 | This directive resets the statistics information associated with this rate |
---|
1018 | monotonic period instance. |
---|
1019 | |
---|
1020 | NOTES: |
---|
1021 | This directive will not cause the running task to be preempted. |
---|
1022 | |
---|
1023 | .. raw:: latex |
---|
1024 | |
---|
1025 | \clearpage |
---|
1026 | |
---|
1027 | .. index:: reset statistics of all periods |
---|
1028 | .. index:: rtems_rate_monotonic_reset_all_statistics |
---|
1029 | |
---|
1030 | .. _rtems_rate_monotonic_reset_all_statistics: |
---|
1031 | |
---|
1032 | RATE_MONOTONIC_RESET_ALL_STATISTICS - Reset statistics for all periods |
---|
1033 | ---------------------------------------------------------------------- |
---|
1034 | |
---|
1035 | CALLING SEQUENCE: |
---|
1036 | .. code-block:: c |
---|
1037 | |
---|
1038 | void rtems_rate_monotonic_reset_all_statistics(void); |
---|
1039 | |
---|
1040 | DIRECTIVE STATUS CODES: |
---|
1041 | NONE |
---|
1042 | |
---|
1043 | DESCRIPTION: |
---|
1044 | This directive resets the statistics information associated with all rate |
---|
1045 | monotonic period instances. |
---|
1046 | |
---|
1047 | NOTES: |
---|
1048 | This directive will not cause the running task to be preempted. |
---|
1049 | |
---|
1050 | .. raw:: latex |
---|
1051 | |
---|
1052 | \clearpage |
---|
1053 | |
---|
1054 | .. index:: print period statistics report |
---|
1055 | .. index:: period statistics report |
---|
1056 | .. index:: rtems_rate_monotonic_report_statistics |
---|
1057 | |
---|
1058 | .. _rtems_rate_monotonic_report_statistics: |
---|
1059 | |
---|
1060 | RATE_MONOTONIC_REPORT_STATISTICS - Print period statistics report |
---|
1061 | ----------------------------------------------------------------- |
---|
1062 | |
---|
1063 | CALLING SEQUENCE: |
---|
1064 | .. code-block:: c |
---|
1065 | |
---|
1066 | void rtems_rate_monotonic_report_statistics(void); |
---|
1067 | |
---|
1068 | DIRECTIVE STATUS CODES: |
---|
1069 | NONE |
---|
1070 | |
---|
1071 | DESCRIPTION: |
---|
1072 | This directive prints a report on all active periods which have executed at |
---|
1073 | least one period. The following is an example of the output generated by |
---|
1074 | this directive. |
---|
1075 | |
---|
1076 | .. index:: rtems_rate_monotonic_period_statistics |
---|
1077 | |
---|
1078 | .. code-block:: c |
---|
1079 | |
---|
1080 | ID OWNER PERIODS MISSED CPU TIME WALL TIME |
---|
1081 | MIN/MAX/AVG MIN/MAX/AVG |
---|
1082 | 0x42010001 TA1 502 0 0/1/0.99 0/0/0.00 |
---|
1083 | 0x42010002 TA2 502 0 0/1/0.99 0/0/0.00 |
---|
1084 | 0x42010003 TA3 501 0 0/1/0.99 0/0/0.00 |
---|
1085 | 0x42010004 TA4 501 0 0/1/0.99 0/0/0.00 |
---|
1086 | 0x42010005 TA5 10 0 0/1/0.90 0/0/0.00 |
---|
1087 | |
---|
1088 | NOTES: |
---|
1089 | This directive will not cause the running task to be preempted. |
---|