1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
|
.. SPDX-License-Identifier: CC-BY-SA-4.0
.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
.. Copyright (C) 2017 Kuan-Hsun Chen.
Directives
==========
This section details the rate monotonic manager's directives. A subsection is
dedicated to each of this manager's directives and describes the calling
sequence, related constants, usage, and status codes.
.. raw:: latex
\clearpage
.. index:: create a period
.. index:: rtems_rate_monotonic_create
.. _rtems_rate_monotonic_create:
RATE_MONOTONIC_CREATE - Create a rate monotonic period
------------------------------------------------------
CALLING SEQUENCE:
.. code-block:: c
rtems_status_code rtems_rate_monotonic_create(
rtems_name name,
rtems_id *id
);
DIRECTIVE STATUS CODES:
.. list-table::
:class: rtems-table
* - ``RTEMS_SUCCESSFUL``
- rate monotonic period created successfully
* - ``RTEMS_INVALID_NAME``
- invalid period name
* - ``RTEMS_TOO_MANY``
- too many periods created
DESCRIPTION:
This directive creates a rate monotonic period. The assigned rate
monotonic id is returned in id. This id is used to access the period with
other rate monotonic manager directives. For control and maintenance of
the rate monotonic period, RTEMS allocates a PCB from the local PCB free
pool and initializes it.
NOTES:
This directive may cause the calling task to be preempted due to an
obtain and release of the object allocator mutex.
.. raw:: latex
\clearpage
.. index:: get ID of a period
.. index:: obtain ID of a period
.. index:: rtems_rate_monotonic_ident
.. _rtems_rate_monotonic_ident:
RATE_MONOTONIC_IDENT - Get ID of a period
-----------------------------------------
CALLING SEQUENCE:
.. code-block:: c
rtems_status_code rtems_rate_monotonic_ident(
rtems_name name,
rtems_id *id
);
DIRECTIVE STATUS CODES:
.. list-table::
:class: rtems-table
* - ``RTEMS_SUCCESSFUL``
- period identified successfully
* - ``RTEMS_INVALID_NAME``
- period name not found
DESCRIPTION:
This directive obtains the period id associated with the period name to be
acquired. If the period name is not unique, then the period id will match
one of the periods with that name. However, this period id is not
guaranteed to correspond to the desired period. The period id is used to
access this period in other rate monotonic manager directives.
NOTES:
This directive will not cause the running task to be preempted.
.. raw:: latex
\clearpage
.. index:: cancel a period
.. index:: rtems_rate_monotonic_cancel
.. _rtems_rate_monotonic_cancel:
RATE_MONOTONIC_CANCEL - Cancel a period
---------------------------------------
CALLING SEQUENCE:
.. code-block:: c
rtems_status_code rtems_rate_monotonic_cancel(
rtems_id id
);
DIRECTIVE STATUS CODES:
.. list-table::
:class: rtems-table
* - ``RTEMS_SUCCESSFUL``
- period canceled successfully
* - ``RTEMS_INVALID_ID``
- invalid rate monotonic period id
* - ``RTEMS_NOT_OWNER_OF_RESOURCE``
- rate monotonic period not created by calling task
DESCRIPTION:
This directive cancels the rate monotonic period id. This period will be
reinitiated by the next invocation of ``rtems_rate_monotonic_period``
with id.
NOTES:
This directive will not cause the running task to be preempted.
The rate monotonic period specified by id must have been created by the
calling task.
.. raw:: latex
\clearpage
.. index:: rtems_rate_monotonic_delete
.. index:: delete a period
.. _rtems_rate_monotonic_delete:
RATE_MONOTONIC_DELETE - Delete a rate monotonic period
------------------------------------------------------
CALLING SEQUENCE:
.. code-block:: c
rtems_status_code rtems_rate_monotonic_delete(
rtems_id id
);
DIRECTIVE STATUS CODES:
.. list-table::
:class: rtems-table
* - ``RTEMS_SUCCESSFUL``
- period deleted successfully
* - ``RTEMS_INVALID_ID``
- invalid rate monotonic period id
DESCRIPTION:
This directive deletes the rate monotonic period specified by id. If the
period is running, it is automatically canceled. The PCB for the deleted
period is reclaimed by RTEMS.
NOTES:
This directive may cause the calling task to be preempted due to an
obtain and release of the object allocator mutex.
A rate monotonic period can be deleted by a task other than the task which
created the period.
.. raw:: latex
\clearpage
.. index:: conclude current period
.. index:: start current period
.. index:: period initiation
.. index:: rtems_rate_monotonic_period
.. _rtems_rate_monotonic_period:
RATE_MONOTONIC_PERIOD - Conclude current/Start next period
----------------------------------------------------------
CALLING SEQUENCE:
.. code-block:: c
rtems_status_code rtems_rate_monotonic_period(
rtems_id id,
rtems_interval length
);
DIRECTIVE STATUS CODES:
.. list-table::
:class: rtems-table
* - ``RTEMS_SUCCESSFUL``
- period initiated successfully
* - ``RTEMS_INVALID_ID``
- invalid rate monotonic period id
* - ``RTEMS_NOT_OWNER_OF_RESOURCE``
- period not created by calling task
* - ``RTEMS_NOT_DEFINED``
- period has never been initiated (only possible when period is set to PERIOD_STATUS)
* - ``RTEMS_TIMEOUT``
- period has expired
DESCRIPTION:
This directive initiates the rate monotonic period id with a length of
period ticks. If id is running, then the calling task will block for the
remainder of the period before reinitiating the period with the specified
period. If id was not running (either expired or never initiated), the
period is immediately initiated and the directive returns immediately.
If id has expired its period, the postponed job will be released immediately
and the following calls of this directive will release postponed
jobs until there is no more deadline miss.
If invoked with a period of ``RTEMS_PERIOD_STATUS`` ticks, the current
state of id will be returned. The directive status indicates the current
state of the period. This does not alter the state or period of the
period.
NOTES:
This directive will not cause the running task to be preempted.
.. raw:: latex
\clearpage
.. index:: get status of period
.. index:: obtain status of period
.. index:: rtems_rate_monotonic_get_status
.. _rtems_rate_monotonic_get_status:
RATE_MONOTONIC_GET_STATUS - Obtain status from a period
-------------------------------------------------------
CALLING SEQUENCE:
.. code-block:: c
rtems_status_code rtems_rate_monotonic_get_status(
rtems_id id,
rtems_rate_monotonic_period_status *status
);
DIRECTIVE STATUS CODES:
.. list-table::
:class: rtems-table
* - ``RTEMS_SUCCESSFUL``
- period status retrieved successfully
* - ``RTEMS_INVALID_ID``
- invalid rate monotonic period id
* - ``RTEMS_INVALID_ADDRESS``
- invalid address of status
* - ``RTEMS_NOT_DEFINED``
- no status is available due to the cpu usage of the task having been
reset since the period initiated
*DESCRIPTION:
This directive returns status information associated with the rate
monotonic period id in the following data structure:
.. index:: rtems_rate_monotonic_period_status
.. code-block:: c
typedef struct {
rtems_id owner;
rtems_rate_monotonic_period_states state;
rtems_rate_monotonic_period_time_t since_last_period;
rtems_thread_cpu_usage_t executed_since_last_period;
uint32_t postponed_jobs_count;
} rtems_rate_monotonic_period_status;
.. COMMENT: RATE_MONOTONIC_INACTIVE does not have RTEMS in front of it.
A configure time option can be used to select whether the time information
is given in ticks or seconds and nanoseconds. The default is seconds and
nanoseconds. If the period's state is ``RATE_MONOTONIC_INACTIVE``, both
time values will be set to 0. Otherwise, both time values will contain
time information since the last invocation of the
``rtems_rate_monotonic_period`` directive. More specifically, the
since_last_period value contains the elapsed time which has occurred since
the last invocation of the ``rtems_rate_monotonic_period`` directive and
the ``executed_since_last_period`` contains how much processor time the
owning task has consumed since the invocation of the
``rtems_rate_monotonic_period`` directive. In addition, the
``postponed_jobs_count value`` contains the count of jobs which are not
released yet.
NOTES:
This directive will not cause the running task to be preempted.
.. raw:: latex
\clearpage
.. index:: get statistics of period
.. index:: obtain statistics of period
.. index:: rtems_rate_monotonic_get_statistics
.. _rtems_rate_monotonic_get_statistics:
RATE_MONOTONIC_GET_STATISTICS - Obtain statistics from a period
---------------------------------------------------------------
CALLING SEQUENCE:
.. code-block:: c
rtems_status_code rtems_rate_monotonic_get_statistics(
rtems_id id,
rtems_rate_monotonic_period_statistics *statistics
);
DIRECTIVE STATUS CODES:
.. list-table::
:class: rtems-table
* - ``RTEMS_SUCCESSFUL``
- period statistics retrieved successfully
* - ``RTEMS_INVALID_ID``
- invalid rate monotonic period id
* - ``RTEMS_INVALID_ADDRESS``
- invalid address of statistics
DESCRIPTION:
This directive returns statistics information associated with the rate
monotonic period id in the following data structure:
.. index:: rtems_rate_monotonic_period_statistics
.. code-block:: c
typedef struct {
uint32_t count;
uint32_t missed_count;
#ifdef RTEMS_ENABLE_NANOSECOND_CPU_USAGE_STATISTICS
struct timespec min_cpu_time;
struct timespec max_cpu_time;
struct timespec total_cpu_time;
#else
uint32_t min_cpu_time;
uint32_t max_cpu_time;
uint32_t total_cpu_time;
#endif
#ifdef RTEMS_ENABLE_NANOSECOND_RATE_MONOTONIC_STATISTICS
struct timespec min_wall_time;
struct timespec max_wall_time;
struct timespec total_wall_time;
#else
uint32_t min_wall_time;
uint32_t max_wall_time;
uint32_t total_wall_time;
#endif
} rtems_rate_monotonic_period_statistics;
This directive returns the current statistics information for the period
instance assocaited with ``id``. The information returned is indicated by
the structure above.
NOTES:
This directive will not cause the running task to be preempted.
.. raw:: latex
\clearpage
.. index:: reset statistics of period
.. index:: rtems_rate_monotonic_reset_statistics
.. _rtems_rate_monotonic_reset_statistics:
RATE_MONOTONIC_RESET_STATISTICS - Reset statistics for a period
---------------------------------------------------------------
CALLING SEQUENCE:
.. code-block:: c
rtems_status_code rtems_rate_monotonic_reset_statistics(
rtems_id id
);
DIRECTIVE STATUS CODES:
.. list-table::
:class: rtems-table
* - ``RTEMS_SUCCESSFUL``
- period initiated successfully
* - ``RTEMS_INVALID_ID``
- invalid rate monotonic period id
DESCRIPTION:
This directive resets the statistics information associated with this rate
monotonic period instance.
NOTES:
This directive will not cause the running task to be preempted.
.. raw:: latex
\clearpage
.. index:: reset statistics of all periods
.. index:: rtems_rate_monotonic_reset_all_statistics
.. _rtems_rate_monotonic_reset_all_statistics:
RATE_MONOTONIC_RESET_ALL_STATISTICS - Reset statistics for all periods
----------------------------------------------------------------------
CALLING SEQUENCE:
.. code-block:: c
void rtems_rate_monotonic_reset_all_statistics(void);
DIRECTIVE STATUS CODES:
NONE
DESCRIPTION:
This directive resets the statistics information associated with all rate
monotonic period instances.
NOTES:
This directive will not cause the running task to be preempted.
.. raw:: latex
\clearpage
.. index:: print period statistics report
.. index:: period statistics report
.. index:: rtems_rate_monotonic_report_statistics
.. _rtems_rate_monotonic_report_statistics:
RATE_MONOTONIC_REPORT_STATISTICS - Print period statistics report
-----------------------------------------------------------------
CALLING SEQUENCE:
.. code-block:: c
void rtems_rate_monotonic_report_statistics(void);
DIRECTIVE STATUS CODES:
NONE
DESCRIPTION:
This directive prints a report on all active periods which have executed at
least one period. The following is an example of the output generated by
this directive.
.. index:: rtems_rate_monotonic_period_statistics
.. code-block:: c
ID OWNER PERIODS MISSED CPU TIME WALL TIME
MIN/MAX/AVG MIN/MAX/AVG
0x42010001 TA1 502 0 0/1/0.99 0/0/0.00
0x42010002 TA2 502 0 0/1/0.99 0/0/0.00
0x42010003 TA3 501 0 0/1/0.99 0/0/0.00
0x42010004 TA4 501 0 0/1/0.99 0/0/0.00
0x42010005 TA5 10 0 0/1/0.90 0/0/0.00
NOTES:
This directive will not cause the running task to be preempted.
|