[489740f] | 1 | .. comment SPDX-License-Identifier: CC-BY-SA-4.0 |
---|
| 2 | |
---|
[b8d3f6b] | 3 | .. COMMENT: COPYRIGHT (c) 1988-2008. |
---|
| 4 | .. COMMENT: On-Line Applications Research Corporation (OAR). |
---|
[c660173] | 5 | .. COMMENT: COPYRIGHT (c) 2017 Kuan-Hsun Chen. |
---|
[b8d3f6b] | 6 | .. COMMENT: All rights reserved. |
---|
| 7 | |
---|
[fd6dc8c8] | 8 | .. index:: rate mononitonic tasks |
---|
| 9 | .. index:: periodic tasks |
---|
| 10 | |
---|
[6c56401] | 11 | Rate Monotonic Manager |
---|
| 12 | ********************** |
---|
| 13 | |
---|
[fd6dc8c8] | 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 |
---|
[b8d3f6b] | 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: |
---|
[fd6dc8c8] | 22 | |
---|
[b8d3f6b] | 23 | - rtems_rate_monotonic_create_ - Create a rate monotonic period |
---|
[fd6dc8c8] | 24 | |
---|
[b8d3f6b] | 25 | - rtems_rate_monotonic_ident_ - Get ID of a period |
---|
[fd6dc8c8] | 26 | |
---|
[b8d3f6b] | 27 | - rtems_rate_monotonic_cancel_ - Cancel a period |
---|
[fd6dc8c8] | 28 | |
---|
[b8d3f6b] | 29 | - rtems_rate_monotonic_delete_ - Delete a rate monotonic period |
---|
[fd6dc8c8] | 30 | |
---|
[b8d3f6b] | 31 | - rtems_rate_monotonic_period_ - Conclude current/Start next period |
---|
[fd6dc8c8] | 32 | |
---|
[b8d3f6b] | 33 | - rtems_rate_monotonic_get_status_ - Obtain status from a period |
---|
[fd6dc8c8] | 34 | |
---|
[b8d3f6b] | 35 | - rtems_rate_monotonic_get_statistics_ - Obtain statistics from a period |
---|
[fd6dc8c8] | 36 | |
---|
[b8d3f6b] | 37 | - rtems_rate_monotonic_reset_statistics_ - Reset statistics for a period |
---|
[fd6dc8c8] | 38 | |
---|
[b8d3f6b] | 39 | - rtems_rate_monotonic_reset_all_statistics_ - Reset statistics for all periods |
---|
[fd6dc8c8] | 40 | |
---|
[b8d3f6b] | 41 | - rtems_rate_monotonic_report_statistics_ - Print period statistics report |
---|
[fd6dc8c8] | 42 | |
---|
| 43 | Background |
---|
| 44 | ========== |
---|
| 45 | |
---|
[b8d3f6b] | 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. |
---|
[fd6dc8c8] | 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 | |
---|
[b8d3f6b] | 67 | ``owner`` |
---|
[fd6dc8c8] | 68 | is the id of the thread that owns this period. |
---|
| 69 | |
---|
[b8d3f6b] | 70 | ``count`` |
---|
[fd6dc8c8] | 71 | is the total number of periods executed. |
---|
| 72 | |
---|
[b8d3f6b] | 73 | ``missed_count`` |
---|
[fd6dc8c8] | 74 | is the number of periods that were missed. |
---|
| 75 | |
---|
[b8d3f6b] | 76 | ``min_cpu_time`` |
---|
| 77 | is the minimum amount of CPU execution time consumed on any execution of the |
---|
| 78 | periodic loop. |
---|
[fd6dc8c8] | 79 | |
---|
[b8d3f6b] | 80 | ``max_cpu_time`` |
---|
| 81 | is the maximum amount of CPU execution time consumed on any execution of the |
---|
| 82 | periodic loop. |
---|
[fd6dc8c8] | 83 | |
---|
[b8d3f6b] | 84 | ``total_cpu_time`` |
---|
| 85 | is the total amount of CPU execution time consumed by executions of the |
---|
| 86 | periodic loop. |
---|
[fd6dc8c8] | 87 | |
---|
[b8d3f6b] | 88 | ``min_wall_time`` |
---|
| 89 | is the minimum amount of wall time that passed on any execution of the |
---|
| 90 | periodic loop. |
---|
[fd6dc8c8] | 91 | |
---|
[b8d3f6b] | 92 | ``max_wall_time`` |
---|
| 93 | is the maximum amount of wall time that passed on any execution of the |
---|
| 94 | periodic loop. |
---|
[fd6dc8c8] | 95 | |
---|
[b8d3f6b] | 96 | ``total_wall_time`` |
---|
| 97 | is the total amount of wall time that passed during executions of the |
---|
| 98 | periodic loop. |
---|
[fd6dc8c8] | 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 | |
---|
[b8d3f6b] | 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. |
---|
[fd6dc8c8] | 135 | |
---|
[6c56401] | 136 | .. index:: periodic task, definition |
---|
| 137 | |
---|
[69d6622] | 138 | Periodicity Definitions |
---|
[fd6dc8c8] | 139 | ---------------------------------- |
---|
| 140 | |
---|
[b8d3f6b] | 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. |
---|
[fd6dc8c8] | 168 | |
---|
| 169 | .. index:: Rate Monotonic Scheduling Algorithm, definition |
---|
| 170 | .. index:: RMS Algorithm, definition |
---|
| 171 | |
---|
[6c56401] | 172 | Rate Monotonic Scheduling Algorithm |
---|
| 173 | ----------------------------------- |
---|
| 174 | |
---|
[b8d3f6b] | 175 | The Rate Monotonic Scheduling Algorithm (RMS) is important to real-time systems |
---|
[c660173] | 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`, |
---|
[938c49e] | 178 | :cite:`Sha:1990:Ada`, :cite:`Burns:1991:Review`). |
---|
[c660173] | 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 |
---|
[b8d3f6b] | 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 | |
---|
[69d6622] | 188 | RMS is an optimal fixed-priority algorithm for scheduling independent, |
---|
[b8d3f6b] | 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 |
---|
[69d6622] | 192 | fixed-priority algorithm, then RMS will be able to schedule that task set. |
---|
[b8d3f6b] | 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: |
---|
[fd6dc8c8] | 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 | |
---|
[b8d3f6b] | 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, |
---|
[fd6dc8c8] | 232 | schedulability is only guaranteed for the critical task set. |
---|
| 233 | |
---|
[6c56401] | 234 | .. index:: RMS schedulability analysis |
---|
| 235 | |
---|
[fd6dc8c8] | 236 | Schedulability Analysis |
---|
| 237 | ----------------------- |
---|
| 238 | |
---|
[69d6622] | 239 | RMS allows application designers to ensure that tasks can meet all deadlines under fixed-priority assignment, |
---|
[b8d3f6b] | 240 | even under transient overload, without knowing exactly when any given task will |
---|
| 241 | execute by applying proven schedulability analysis rules. |
---|
[fd6dc8c8] | 242 | |
---|
| 243 | Assumptions |
---|
[4da4a15] | 244 | ^^^^^^^^^^^ |
---|
[fd6dc8c8] | 245 | |
---|
[b8d3f6b] | 246 | The schedulability analysis rules for RMS were developed based on the following |
---|
| 247 | assumptions: |
---|
[fd6dc8c8] | 248 | |
---|
[b8d3f6b] | 249 | - The requests for all tasks for which hard deadlines exist are periodic, with |
---|
| 250 | a constant interval between requests. |
---|
[fd6dc8c8] | 251 | |
---|
[b8d3f6b] | 252 | - Each task must complete before the next request for it occurs. |
---|
[fd6dc8c8] | 253 | |
---|
[b8d3f6b] | 254 | - The tasks are independent in that a task does not depend on the initiation or |
---|
| 255 | completion of requests for other tasks. |
---|
[fd6dc8c8] | 256 | |
---|
[b8d3f6b] | 257 | - The execution time for each task without preemption or interruption is |
---|
| 258 | constant and does not vary. |
---|
[fd6dc8c8] | 259 | |
---|
[b8d3f6b] | 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. |
---|
[fd6dc8c8] | 262 | |
---|
[b8d3f6b] | 263 | Once the basic schedulability analysis is understood, some of the above |
---|
| 264 | assumptions can be relaxed and the side-effects accounted for. |
---|
[fd6dc8c8] | 265 | |
---|
[6c56401] | 266 | .. index:: RMS Processor Utilization Rule |
---|
| 267 | |
---|
[fd6dc8c8] | 268 | Processor Utilization Rule |
---|
[4da4a15] | 269 | ^^^^^^^^^^^^^^^^^^^^^^^^^^ |
---|
[fd6dc8c8] | 270 | |
---|
[b8d3f6b] | 271 | The Processor Utilization Rule requires that processor utilization be |
---|
[c8b6745] | 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: |
---|
[b8d3f6b] | 276 | |
---|
[c8b6745] | 277 | .. math:: |
---|
[fd6dc8c8] | 278 | |
---|
[c8b6745] | 279 | Utilization = \sum_{i=1}^{n} Time_i/Period_i |
---|
[fd6dc8c8] | 280 | |
---|
[b8d3f6b] | 281 | To ensure schedulability even under transient overload, the processor |
---|
| 282 | utilization must adhere to the following rule: |
---|
| 283 | |
---|
[c8b6745] | 284 | .. math:: |
---|
[fd6dc8c8] | 285 | |
---|
[c8b6745] | 286 | maximumUtilization = n * (2^{\frac{1}{n}} - 1) |
---|
[fd6dc8c8] | 287 | |
---|
[b8d3f6b] | 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. |
---|
[c660173] | 292 | See more detail in :cite:`Liu:1973:Scheduling`. |
---|
[fd6dc8c8] | 293 | |
---|
| 294 | Processor Utilization Rule Example |
---|
[4da4a15] | 295 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
---|
[fd6dc8c8] | 296 | |
---|
[b8d3f6b] | 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: |
---|
[fd6dc8c8] | 301 | |
---|
| 302 | +------------+----------+--------+-----------+-------------+ |
---|
[e6fe68d] | 303 | | Task | RMS | Period | Execution | Processor | |
---|
[fd6dc8c8] | 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 | |
---|
[b8d3f6b] | 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. |
---|
[fd6dc8c8] | 317 | |
---|
[6c56401] | 318 | .. index:: RMS First Deadline Rule |
---|
| 319 | |
---|
[fd6dc8c8] | 320 | First Deadline Rule |
---|
[4da4a15] | 321 | ^^^^^^^^^^^^^^^^^^^ |
---|
[fd6dc8c8] | 322 | |
---|
[b8d3f6b] | 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 |
---|
[fd6dc8c8] | 326 | stated as follows: |
---|
| 327 | |
---|
[b8d3f6b] | 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. |
---|
[c660173] | 339 | See more detail in :cite:`Lehoczky:1989:RM`. |
---|
[fd6dc8c8] | 340 | |
---|
| 341 | First Deadline Rule Example |
---|
[4da4a15] | 342 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
---|
[fd6dc8c8] | 343 | |
---|
[b8d3f6b] | 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: |
---|
[fd6dc8c8] | 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 | |
---|
[b8d3f6b] | 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: |
---|
[fd6dc8c8] | 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 | |
---|
[b8d3f6b] | 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. |
---|
[fd6dc8c8] | 395 | |
---|
| 396 | Relaxation of Assumptions |
---|
[4da4a15] | 397 | ^^^^^^^^^^^^^^^^^^^^^^^^^ |
---|
[fd6dc8c8] | 398 | |
---|
[b8d3f6b] | 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, |
---|
[fd6dc8c8] | 422 | the non-critical task set is not guaranteed to execute. |
---|
| 423 | |
---|
[b8d3f6b] | 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. |
---|
[fd6dc8c8] | 428 | |
---|
| 429 | Operations |
---|
| 430 | ========== |
---|
| 431 | |
---|
| 432 | Creating a Rate Monotonic Period |
---|
| 433 | -------------------------------- |
---|
| 434 | |
---|
[b8d3f6b] | 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. |
---|
[fd6dc8c8] | 441 | |
---|
| 442 | Manipulating a Period |
---|
| 443 | --------------------- |
---|
| 444 | |
---|
[b8d3f6b] | 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 |
---|
[fd6dc8c8] | 449 | monotonic period results in one of the following scenarios: |
---|
| 450 | |
---|
[b8d3f6b] | 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. |
---|
[fd6dc8c8] | 454 | |
---|
[b8d3f6b] | 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. |
---|
[fd6dc8c8] | 458 | |
---|
[b8d3f6b] | 459 | - If the rate monotonic period has expired before the task invokes the |
---|
[69d6622] | 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 |
---|
[c660173] | 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. |
---|
[fd6dc8c8] | 465 | |
---|
| 466 | Obtaining the Status of a Period |
---|
| 467 | -------------------------------- |
---|
| 468 | |
---|
[b8d3f6b] | 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: |
---|
[fd6dc8c8] | 474 | |
---|
[1a72a98] | 475 | .. list-table:: |
---|
[859f0b7] | 476 | :class: rtems-table |
---|
[fd6dc8c8] | 477 | |
---|
[1a72a98] | 478 | * - ``RTEMS_SUCCESSFUL`` |
---|
| 479 | - period is running |
---|
| 480 | * - ``RTEMS_TIMEOUT`` |
---|
| 481 | - period has expired |
---|
| 482 | * - ``RTEMS_NOT_DEFINED`` |
---|
| 483 | - period has never been initiated |
---|
[fd6dc8c8] | 484 | |
---|
[b8d3f6b] | 485 | Obtaining the status of a rate monotonic period does not alter the state or |
---|
| 486 | length of that period. |
---|
[fd6dc8c8] | 487 | |
---|
| 488 | Canceling a Period |
---|
| 489 | ------------------ |
---|
| 490 | |
---|
[b8d3f6b] | 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. |
---|
[fd6dc8c8] | 495 | |
---|
| 496 | Deleting a Rate Monotonic Period |
---|
| 497 | -------------------------------- |
---|
| 498 | |
---|
[b8d3f6b] | 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. |
---|
[fd6dc8c8] | 504 | |
---|
| 505 | Examples |
---|
| 506 | -------- |
---|
| 507 | |
---|
[b8d3f6b] | 508 | The following sections illustrate common uses of rate monotonic periods to |
---|
| 509 | construct periodic tasks. |
---|
[fd6dc8c8] | 510 | |
---|
| 511 | Simple Periodic Task |
---|
| 512 | -------------------- |
---|
| 513 | |
---|
[b8d3f6b] | 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: |
---|
[fd6dc8c8] | 519 | |
---|
| 520 | rtems_task Periodic_task(rtems_task_argument arg) |
---|
| 521 | { |
---|
[b8d3f6b] | 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 ); |
---|
[fd6dc8c8] | 545 | } |
---|
| 546 | |
---|
[b8d3f6b] | 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`` |
---|
[c660173] | 554 | status. If the above task misses its deadline, it will delete the rate |
---|
| 555 | monotonic period and itself. |
---|
[fd6dc8c8] | 556 | |
---|
| 557 | Task with Multiple Periods |
---|
| 558 | -------------------------- |
---|
| 559 | |
---|
[b8d3f6b] | 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: |
---|
[fd6dc8c8] | 568 | |
---|
| 569 | rtems_task Periodic_task(rtems_task_argument arg) |
---|
| 570 | { |
---|
[b8d3f6b] | 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 ); |
---|
[fd6dc8c8] | 603 | } |
---|
| 604 | |
---|
[b8d3f6b] | 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`` |
---|
[c660173] | 623 | directive status. If the above task misses its deadline, it will delete the |
---|
| 624 | rate monotonic periods and itself. |
---|
[fd6dc8c8] | 625 | |
---|
| 626 | Directives |
---|
| 627 | ========== |
---|
| 628 | |
---|
[b8d3f6b] | 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 | |
---|
[53bb72e] | 633 | .. raw:: latex |
---|
| 634 | |
---|
| 635 | \clearpage |
---|
| 636 | |
---|
[6c56401] | 637 | .. index:: create a period |
---|
| 638 | .. index:: rtems_rate_monotonic_create |
---|
[fd6dc8c8] | 639 | |
---|
[3384994] | 640 | .. _rtems_rate_monotonic_create: |
---|
| 641 | |
---|
[fd6dc8c8] | 642 | RATE_MONOTONIC_CREATE - Create a rate monotonic period |
---|
| 643 | ------------------------------------------------------ |
---|
| 644 | |
---|
[53bb72e] | 645 | CALLING SEQUENCE: |
---|
| 646 | .. code-block:: c |
---|
[fd6dc8c8] | 647 | |
---|
[53bb72e] | 648 | rtems_status_code rtems_rate_monotonic_create( |
---|
| 649 | rtems_name name, |
---|
| 650 | rtems_id *id |
---|
| 651 | ); |
---|
[fd6dc8c8] | 652 | |
---|
[53bb72e] | 653 | DIRECTIVE STATUS CODES: |
---|
| 654 | .. list-table:: |
---|
| 655 | :class: rtems-table |
---|
[fd6dc8c8] | 656 | |
---|
[53bb72e] | 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 |
---|
[fd6dc8c8] | 663 | |
---|
[53bb72e] | 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. |
---|
[fd6dc8c8] | 670 | |
---|
[53bb72e] | 671 | NOTES: |
---|
| 672 | This directive will not cause the calling task to be preempted. |
---|
[fd6dc8c8] | 673 | |
---|
[53bb72e] | 674 | .. raw:: latex |
---|
[fd6dc8c8] | 675 | |
---|
[53bb72e] | 676 | \clearpage |
---|
[b8d3f6b] | 677 | |
---|
[fd6dc8c8] | 678 | .. index:: get ID of a period |
---|
| 679 | .. index:: obtain ID of a period |
---|
| 680 | .. index:: rtems_rate_monotonic_ident |
---|
| 681 | |
---|
[3384994] | 682 | .. _rtems_rate_monotonic_ident: |
---|
| 683 | |
---|
[6c56401] | 684 | RATE_MONOTONIC_IDENT - Get ID of a period |
---|
| 685 | ----------------------------------------- |
---|
| 686 | |
---|
[53bb72e] | 687 | CALLING SEQUENCE: |
---|
| 688 | .. code-block:: c |
---|
[fd6dc8c8] | 689 | |
---|
[53bb72e] | 690 | rtems_status_code rtems_rate_monotonic_ident( |
---|
| 691 | rtems_name name, |
---|
| 692 | rtems_id *id |
---|
| 693 | ); |
---|
[fd6dc8c8] | 694 | |
---|
[53bb72e] | 695 | DIRECTIVE STATUS CODES: |
---|
| 696 | .. list-table:: |
---|
| 697 | :class: rtems-table |
---|
[fd6dc8c8] | 698 | |
---|
[53bb72e] | 699 | * - ``RTEMS_SUCCESSFUL`` |
---|
| 700 | - period identified successfully |
---|
| 701 | * - ``RTEMS_INVALID_NAME`` |
---|
| 702 | - period name not found |
---|
[fd6dc8c8] | 703 | |
---|
[53bb72e] | 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. |
---|
[fd6dc8c8] | 710 | |
---|
[53bb72e] | 711 | NOTES: |
---|
| 712 | This directive will not cause the running task to be preempted. |
---|
[fd6dc8c8] | 713 | |
---|
[53bb72e] | 714 | .. raw:: latex |
---|
[fd6dc8c8] | 715 | |
---|
[53bb72e] | 716 | \clearpage |
---|
[b8d3f6b] | 717 | |
---|
[6c56401] | 718 | .. index:: cancel a period |
---|
| 719 | .. index:: rtems_rate_monotonic_cancel |
---|
[fd6dc8c8] | 720 | |
---|
[3384994] | 721 | .. _rtems_rate_monotonic_cancel: |
---|
| 722 | |
---|
[fd6dc8c8] | 723 | RATE_MONOTONIC_CANCEL - Cancel a period |
---|
| 724 | --------------------------------------- |
---|
| 725 | |
---|
[53bb72e] | 726 | CALLING SEQUENCE: |
---|
| 727 | .. code-block:: c |
---|
[fd6dc8c8] | 728 | |
---|
[53bb72e] | 729 | rtems_status_code rtems_rate_monotonic_cancel( |
---|
| 730 | rtems_id id |
---|
| 731 | ); |
---|
[fd6dc8c8] | 732 | |
---|
[53bb72e] | 733 | DIRECTIVE STATUS CODES: |
---|
| 734 | .. list-table:: |
---|
| 735 | :class: rtems-table |
---|
[fd6dc8c8] | 736 | |
---|
[53bb72e] | 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 |
---|
[b8d3f6b] | 743 | |
---|
[53bb72e] | 744 | DESCRIPTION: |
---|
[fd6dc8c8] | 745 | |
---|
[53bb72e] | 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. |
---|
[fd6dc8c8] | 749 | |
---|
[53bb72e] | 750 | NOTES: |
---|
| 751 | This directive will not cause the running task to be preempted. |
---|
[fd6dc8c8] | 752 | |
---|
[53bb72e] | 753 | The rate monotonic period specified by id must have been created by the |
---|
| 754 | calling task. |
---|
[fd6dc8c8] | 755 | |
---|
[53bb72e] | 756 | .. raw:: latex |
---|
[b8d3f6b] | 757 | |
---|
[53bb72e] | 758 | \clearpage |
---|
[fd6dc8c8] | 759 | |
---|
[53bb72e] | 760 | .. index:: rtems_rate_monotonic_delete |
---|
[6c56401] | 761 | .. index:: delete a period |
---|
[fd6dc8c8] | 762 | |
---|
[3384994] | 763 | .. _rtems_rate_monotonic_delete: |
---|
| 764 | |
---|
[fd6dc8c8] | 765 | RATE_MONOTONIC_DELETE - Delete a rate monotonic period |
---|
| 766 | ------------------------------------------------------ |
---|
| 767 | |
---|
[53bb72e] | 768 | CALLING SEQUENCE: |
---|
| 769 | .. code-block:: c |
---|
[fd6dc8c8] | 770 | |
---|
[53bb72e] | 771 | rtems_status_code rtems_rate_monotonic_delete( |
---|
| 772 | rtems_id id |
---|
| 773 | ); |
---|
[fd6dc8c8] | 774 | |
---|
[53bb72e] | 775 | DIRECTIVE STATUS CODES: |
---|
| 776 | .. list-table:: |
---|
| 777 | :class: rtems-table |
---|
[fd6dc8c8] | 778 | |
---|
[53bb72e] | 779 | * - ``RTEMS_SUCCESSFUL`` |
---|
| 780 | - period deleted successfully |
---|
| 781 | * - ``RTEMS_INVALID_ID`` |
---|
| 782 | - invalid rate monotonic period id |
---|
[fd6dc8c8] | 783 | |
---|
[53bb72e] | 784 | DESCRIPTION: |
---|
[fd6dc8c8] | 785 | |
---|
[53bb72e] | 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. |
---|
[b8d3f6b] | 789 | |
---|
[53bb72e] | 790 | NOTES: |
---|
| 791 | This directive will not cause the running task to be preempted. |
---|
[fd6dc8c8] | 792 | |
---|
[53bb72e] | 793 | A rate monotonic period can be deleted by a task other than the task which |
---|
| 794 | created the period. |
---|
[fd6dc8c8] | 795 | |
---|
[53bb72e] | 796 | .. raw:: latex |
---|
[fd6dc8c8] | 797 | |
---|
[53bb72e] | 798 | \clearpage |
---|
[b8d3f6b] | 799 | |
---|
[fd6dc8c8] | 800 | .. index:: conclude current period |
---|
| 801 | .. index:: start current period |
---|
| 802 | .. index:: period initiation |
---|
| 803 | .. index:: rtems_rate_monotonic_period |
---|
| 804 | |
---|
[3384994] | 805 | .. _rtems_rate_monotonic_period: |
---|
| 806 | |
---|
[6c56401] | 807 | RATE_MONOTONIC_PERIOD - Conclude current/Start next period |
---|
| 808 | ---------------------------------------------------------- |
---|
| 809 | |
---|
[53bb72e] | 810 | CALLING SEQUENCE: |
---|
| 811 | .. code-block:: c |
---|
[fd6dc8c8] | 812 | |
---|
[53bb72e] | 813 | rtems_status_code rtems_rate_monotonic_period( |
---|
| 814 | rtems_id id, |
---|
| 815 | rtems_interval length |
---|
| 816 | ); |
---|
[fd6dc8c8] | 817 | |
---|
[53bb72e] | 818 | DIRECTIVE STATUS CODES: |
---|
| 819 | .. list-table:: |
---|
| 820 | :class: rtems-table |
---|
[fd6dc8c8] | 821 | |
---|
[53bb72e] | 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 |
---|
[fd6dc8c8] | 832 | |
---|
[53bb72e] | 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. |
---|
[c660173] | 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. |
---|
[fd6dc8c8] | 842 | |
---|
[53bb72e] | 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. |
---|
[fd6dc8c8] | 847 | |
---|
[53bb72e] | 848 | NOTES: |
---|
| 849 | This directive will not cause the running task to be preempted. |
---|
[fd6dc8c8] | 850 | |
---|
[53bb72e] | 851 | .. raw:: latex |
---|
[fd6dc8c8] | 852 | |
---|
[53bb72e] | 853 | \clearpage |
---|
[fd6dc8c8] | 854 | |
---|
| 855 | .. index:: get status of period |
---|
| 856 | .. index:: obtain status of period |
---|
| 857 | .. index:: rtems_rate_monotonic_get_status |
---|
| 858 | |
---|
[3384994] | 859 | .. _rtems_rate_monotonic_get_status: |
---|
| 860 | |
---|
[6c56401] | 861 | RATE_MONOTONIC_GET_STATUS - Obtain status from a period |
---|
| 862 | ------------------------------------------------------- |
---|
| 863 | |
---|
[53bb72e] | 864 | CALLING SEQUENCE: |
---|
| 865 | .. code-block:: c |
---|
[fd6dc8c8] | 866 | |
---|
[53bb72e] | 867 | rtems_status_code rtems_rate_monotonic_get_status( |
---|
| 868 | rtems_id id, |
---|
| 869 | rtems_rate_monotonic_period_status *status |
---|
| 870 | ); |
---|
[fd6dc8c8] | 871 | |
---|
[53bb72e] | 872 | DIRECTIVE STATUS CODES: |
---|
| 873 | .. list-table:: |
---|
| 874 | :class: rtems-table |
---|
[fd6dc8c8] | 875 | |
---|
[53bb72e] | 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 |
---|
[b8d3f6b] | 882 | |
---|
[53bb72e] | 883 | *DESCRIPTION: |
---|
| 884 | This directive returns status information associated with the rate |
---|
| 885 | monotonic period id in the following data structure: |
---|
[fd6dc8c8] | 886 | |
---|
[53bb72e] | 887 | .. index:: rtems_rate_monotonic_period_status |
---|
[fd6dc8c8] | 888 | |
---|
[53bb72e] | 889 | .. code-block:: c |
---|
[b8d3f6b] | 890 | |
---|
[53bb72e] | 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; |
---|
[c660173] | 896 | uint32_t postponed_jobs_count; |
---|
[53bb72e] | 897 | } rtems_rate_monotonic_period_status; |
---|
[fd6dc8c8] | 898 | |
---|
[53bb72e] | 899 | .. COMMENT: RATE_MONOTONIC_INACTIVE does not have RTEMS in front of it. |
---|
[fd6dc8c8] | 900 | |
---|
[53bb72e] | 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 |
---|
[3384994] | 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 |
---|
[c660173] | 911 | ``rtems_rate_monotonic_period`` directive. In addition, the |
---|
[3384994] | 912 | ``postponed_jobs_count value`` contains the count of jobs which are not |
---|
| 913 | released yet. |
---|
[fd6dc8c8] | 914 | |
---|
[53bb72e] | 915 | NOTES: |
---|
| 916 | This directive will not cause the running task to be preempted. |
---|
[fd6dc8c8] | 917 | |
---|
[53bb72e] | 918 | .. raw:: latex |
---|
| 919 | |
---|
| 920 | \clearpage |
---|
[fd6dc8c8] | 921 | |
---|
| 922 | .. index:: get statistics of period |
---|
| 923 | .. index:: obtain statistics of period |
---|
| 924 | .. index:: rtems_rate_monotonic_get_statistics |
---|
| 925 | |
---|
[3384994] | 926 | .. _rtems_rate_monotonic_get_statistics: |
---|
| 927 | |
---|
[6c56401] | 928 | RATE_MONOTONIC_GET_STATISTICS - Obtain statistics from a period |
---|
| 929 | --------------------------------------------------------------- |
---|
| 930 | |
---|
[53bb72e] | 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 |
---|
[fd6dc8c8] | 991 | |
---|
[6c56401] | 992 | .. index:: reset statistics of period |
---|
| 993 | .. index:: rtems_rate_monotonic_reset_statistics |
---|
[b8d3f6b] | 994 | |
---|
[3384994] | 995 | .. _rtems_rate_monotonic_reset_statistics: |
---|
| 996 | |
---|
[fd6dc8c8] | 997 | RATE_MONOTONIC_RESET_STATISTICS - Reset statistics for a period |
---|
| 998 | --------------------------------------------------------------- |
---|
| 999 | |
---|
[53bb72e] | 1000 | CALLING SEQUENCE: |
---|
| 1001 | .. code-block:: c |
---|
[fd6dc8c8] | 1002 | |
---|
[53bb72e] | 1003 | rtems_status_code rtems_rate_monotonic_reset_statistics( |
---|
| 1004 | rtems_id id |
---|
| 1005 | ); |
---|
[fd6dc8c8] | 1006 | |
---|
[53bb72e] | 1007 | DIRECTIVE STATUS CODES: |
---|
| 1008 | .. list-table:: |
---|
| 1009 | :class: rtems-table |
---|
[b8d3f6b] | 1010 | |
---|
[53bb72e] | 1011 | * - ``RTEMS_SUCCESSFUL`` |
---|
| 1012 | - period initiated successfully |
---|
| 1013 | * - ``RTEMS_INVALID_ID`` |
---|
| 1014 | - invalid rate monotonic period id |
---|
[fd6dc8c8] | 1015 | |
---|
[53bb72e] | 1016 | DESCRIPTION: |
---|
| 1017 | This directive resets the statistics information associated with this rate |
---|
| 1018 | monotonic period instance. |
---|
[fd6dc8c8] | 1019 | |
---|
[53bb72e] | 1020 | NOTES: |
---|
| 1021 | This directive will not cause the running task to be preempted. |
---|
[fd6dc8c8] | 1022 | |
---|
[53bb72e] | 1023 | .. raw:: latex |
---|
[fd6dc8c8] | 1024 | |
---|
[53bb72e] | 1025 | \clearpage |
---|
[fd6dc8c8] | 1026 | |
---|
[6c56401] | 1027 | .. index:: reset statistics of all periods |
---|
| 1028 | .. index:: rtems_rate_monotonic_reset_all_statistics |
---|
[b8d3f6b] | 1029 | |
---|
[3384994] | 1030 | .. _rtems_rate_monotonic_reset_all_statistics: |
---|
| 1031 | |
---|
[fd6dc8c8] | 1032 | RATE_MONOTONIC_RESET_ALL_STATISTICS - Reset statistics for all periods |
---|
| 1033 | ---------------------------------------------------------------------- |
---|
| 1034 | |
---|
[53bb72e] | 1035 | CALLING SEQUENCE: |
---|
| 1036 | .. code-block:: c |
---|
[fd6dc8c8] | 1037 | |
---|
[53bb72e] | 1038 | void rtems_rate_monotonic_reset_all_statistics(void); |
---|
[fd6dc8c8] | 1039 | |
---|
[53bb72e] | 1040 | DIRECTIVE STATUS CODES: |
---|
| 1041 | NONE |
---|
[fd6dc8c8] | 1042 | |
---|
[53bb72e] | 1043 | DESCRIPTION: |
---|
| 1044 | This directive resets the statistics information associated with all rate |
---|
| 1045 | monotonic period instances. |
---|
[fd6dc8c8] | 1046 | |
---|
[53bb72e] | 1047 | NOTES: |
---|
| 1048 | This directive will not cause the running task to be preempted. |
---|
[fd6dc8c8] | 1049 | |
---|
[53bb72e] | 1050 | .. raw:: latex |
---|
[fd6dc8c8] | 1051 | |
---|
[53bb72e] | 1052 | \clearpage |
---|
[fd6dc8c8] | 1053 | |
---|
| 1054 | .. index:: print period statistics report |
---|
| 1055 | .. index:: period statistics report |
---|
| 1056 | .. index:: rtems_rate_monotonic_report_statistics |
---|
| 1057 | |
---|
[3384994] | 1058 | .. _rtems_rate_monotonic_report_statistics: |
---|
| 1059 | |
---|
[6c56401] | 1060 | RATE_MONOTONIC_REPORT_STATISTICS - Print period statistics report |
---|
| 1061 | ----------------------------------------------------------------- |
---|
| 1062 | |
---|
[53bb72e] | 1063 | CALLING SEQUENCE: |
---|
| 1064 | .. code-block:: c |
---|
[fd6dc8c8] | 1065 | |
---|
[53bb72e] | 1066 | void rtems_rate_monotonic_report_statistics(void); |
---|
[fd6dc8c8] | 1067 | |
---|
[53bb72e] | 1068 | DIRECTIVE STATUS CODES: |
---|
| 1069 | NONE |
---|
[fd6dc8c8] | 1070 | |
---|
[53bb72e] | 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. |
---|
[b8d3f6b] | 1075 | |
---|
[53bb72e] | 1076 | .. index:: rtems_rate_monotonic_period_statistics |
---|
[fd6dc8c8] | 1077 | |
---|
[53bb72e] | 1078 | .. code-block:: c |
---|
[fd6dc8c8] | 1079 | |
---|
[53bb72e] | 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 |
---|
[fd6dc8c8] | 1087 | |
---|
[53bb72e] | 1088 | NOTES: |
---|
| 1089 | This directive will not cause the running task to be preempted. |
---|