[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). |
---|
| 5 | .. COMMENT: All rights reserved. |
---|
| 6 | |
---|
[6c56401] | 7 | .. index:: timers |
---|
| 8 | |
---|
[fd6dc8c8] | 9 | Timer Manager |
---|
[4da4a15] | 10 | ************* |
---|
[fd6dc8c8] | 11 | |
---|
| 12 | Introduction |
---|
| 13 | ============ |
---|
| 14 | |
---|
| 15 | The timer manager provides support for timer |
---|
| 16 | facilities. The directives provided by the timer manager are: |
---|
| 17 | |
---|
[b8d3f6b] | 18 | - rtems_timer_create_ - Create a timer |
---|
[fd6dc8c8] | 19 | |
---|
[b8d3f6b] | 20 | - rtems_timer_ident_ - Get ID of a timer |
---|
[fd6dc8c8] | 21 | |
---|
[b8d3f6b] | 22 | - rtems_timer_cancel_ - Cancel a timer |
---|
[fd6dc8c8] | 23 | |
---|
[b8d3f6b] | 24 | - rtems_timer_delete_ - Delete a timer |
---|
[fd6dc8c8] | 25 | |
---|
[b8d3f6b] | 26 | - rtems_timer_fire_after_ - Fire timer after interval |
---|
[fd6dc8c8] | 27 | |
---|
[b8d3f6b] | 28 | - rtems_timer_fire_when_ - Fire timer when specified |
---|
[fd6dc8c8] | 29 | |
---|
[b8d3f6b] | 30 | - rtems_timer_initiate_server_ - Initiate server for task-based timers |
---|
[fd6dc8c8] | 31 | |
---|
[b8d3f6b] | 32 | - rtems_timer_server_fire_after_ - Fire task-based timer after interval |
---|
[fd6dc8c8] | 33 | |
---|
[b8d3f6b] | 34 | - rtems_timer_server_fire_when_ - Fire task-based timer when specified |
---|
[fd6dc8c8] | 35 | |
---|
[b8d3f6b] | 36 | - rtems_timer_reset_ - Reset an interval timer |
---|
[fd6dc8c8] | 37 | |
---|
| 38 | Background |
---|
| 39 | ========== |
---|
| 40 | |
---|
| 41 | Required Support |
---|
| 42 | ---------------- |
---|
| 43 | |
---|
| 44 | A clock tick is required to support the functionality provided by this manager. |
---|
| 45 | |
---|
| 46 | Timers |
---|
| 47 | ------ |
---|
| 48 | |
---|
[b8d3f6b] | 49 | A timer is an RTEMS object which allows the application to schedule operations |
---|
| 50 | to occur at specific times in the future. User supplied timer service routines |
---|
[3a58bff] | 51 | are invoked by either a clock tick directive or a special Timer |
---|
[b8d3f6b] | 52 | Server task when the timer fires. Timer service routines may perform any |
---|
| 53 | operations or directives which normally would be performed by the application |
---|
[3a58bff] | 54 | code which invoked a clock tick directive. |
---|
[b8d3f6b] | 55 | |
---|
| 56 | The timer can be used to implement watchdog routines which only fire to denote |
---|
| 57 | that an application error has occurred. The timer is reset at specific points |
---|
| 58 | in the application to ensure that the watchdog does not fire. Thus, if the |
---|
| 59 | application does not reset the watchdog timer, then the timer service routine |
---|
| 60 | will fire to indicate that the application has failed to reach a reset point. |
---|
| 61 | This use of a timer is sometimes referred to as a "keep alive" or a "deadman" |
---|
| 62 | timer. |
---|
[fd6dc8c8] | 63 | |
---|
| 64 | Timer Server |
---|
| 65 | ------------ |
---|
| 66 | |
---|
[b8d3f6b] | 67 | The Timer Server task is responsible for executing the timer service routines |
---|
[1161ed1] | 68 | associated with all task-based timers. This task executes at a priority |
---|
| 69 | specified by :ref:`rtems_timer_initiate_server() <rtems_timer_initiate_server>` |
---|
[464d541] | 70 | and it may have a priority of zero (the highest priority). In uniprocessor |
---|
[1161ed1] | 71 | configurations, it is created non-preemptible. |
---|
[b8d3f6b] | 72 | |
---|
| 73 | By providing a mechanism where timer service routines execute in task rather |
---|
| 74 | than interrupt space, the application is allowed a bit more flexibility in what |
---|
| 75 | operations a timer service routine can perform. For example, the Timer Server |
---|
| 76 | can be configured to have a floating point context in which case it would be |
---|
| 77 | safe to perform floating point operations from a task-based timer. Most of the |
---|
| 78 | time, executing floating point instructions from an interrupt service routine |
---|
[1161ed1] | 79 | is not considered safe. The timer service routines invoked by the Timer Server |
---|
| 80 | may block, however, since this blocks the Timer Server itself, other timer |
---|
| 81 | service routines that are already pending do not run until the blocked timer |
---|
| 82 | service routine finished its work. |
---|
[b8d3f6b] | 83 | |
---|
| 84 | The Timer Server is designed to remain blocked until a task-based timer fires. |
---|
| 85 | This reduces the execution overhead of the Timer Server. |
---|
[fd6dc8c8] | 86 | |
---|
[6c56401] | 87 | .. index:: rtems_timer_service_routine |
---|
| 88 | |
---|
[fd6dc8c8] | 89 | Timer Service Routines |
---|
| 90 | ---------------------- |
---|
| 91 | |
---|
[b8d3f6b] | 92 | The timer service routine should adhere to C calling conventions and have a |
---|
| 93 | prototype similar to the following: |
---|
| 94 | |
---|
[25d55d4] | 95 | .. code-block:: c |
---|
[fd6dc8c8] | 96 | |
---|
| 97 | rtems_timer_service_routine user_routine( |
---|
[b8d3f6b] | 98 | rtems_id timer_id, |
---|
| 99 | void *user_data |
---|
[fd6dc8c8] | 100 | ); |
---|
| 101 | |
---|
[b8d3f6b] | 102 | Where the timer_id parameter is the RTEMS object ID of the timer which is being |
---|
| 103 | fired and user_data is a pointer to user-defined information which may be |
---|
| 104 | utilized by the timer service routine. The argument user_data may be NULL. |
---|
[fd6dc8c8] | 105 | |
---|
| 106 | Operations |
---|
| 107 | ========== |
---|
| 108 | |
---|
| 109 | Creating a Timer |
---|
| 110 | ---------------- |
---|
| 111 | |
---|
[b8d3f6b] | 112 | The ``rtems_timer_create`` directive creates a timer by allocating a Timer |
---|
| 113 | Control Block (TMCB), assigning the timer a user-specified name, and assigning |
---|
| 114 | it a timer ID. Newly created timers do not have a timer service routine |
---|
| 115 | associated with them and are not active. |
---|
[fd6dc8c8] | 116 | |
---|
| 117 | Obtaining Timer IDs |
---|
| 118 | ------------------- |
---|
| 119 | |
---|
[b8d3f6b] | 120 | When a timer is created, RTEMS generates a unique timer ID and assigns it to |
---|
| 121 | the created timer until it is deleted. The timer ID may be obtained by either |
---|
| 122 | of two methods. First, as the result of an invocation of the |
---|
| 123 | ``rtems_timer_create`` directive, the timer ID is stored in a user provided |
---|
| 124 | location. Second, the timer ID may be obtained later using the |
---|
| 125 | ``rtems_timer_ident`` directive. The timer ID is used by other directives to |
---|
| 126 | manipulate this timer. |
---|
[fd6dc8c8] | 127 | |
---|
| 128 | Initiating an Interval Timer |
---|
| 129 | ---------------------------- |
---|
| 130 | |
---|
[b8d3f6b] | 131 | The ``rtems_timer_fire_after`` and ``rtems_timer_server_fire_after`` directives |
---|
| 132 | initiate a timer to fire a user provided timer service routine after the |
---|
| 133 | specified number of clock ticks have elapsed. When the interval has elapsed, |
---|
[3a58bff] | 134 | the timer service routine will be invoked from a clock tick |
---|
[b8d3f6b] | 135 | directive if it was initiated by the ``rtems_timer_fire_after`` directive and |
---|
| 136 | from the Timer Server task if initiated by the |
---|
| 137 | ``rtems_timer_server_fire_after`` directive. |
---|
[fd6dc8c8] | 138 | |
---|
| 139 | Initiating a Time of Day Timer |
---|
| 140 | ------------------------------ |
---|
| 141 | |
---|
[b8d3f6b] | 142 | The ``rtems_timer_fire_when`` and ``rtems_timer_server_fire_when`` directive |
---|
| 143 | initiate a timer to fire a user provided timer service routine when the |
---|
| 144 | specified time of day has been reached. When the interval has elapsed, the |
---|
[3a58bff] | 145 | timer service routine will be invoked from a clock tick directive |
---|
[b8d3f6b] | 146 | by the ``rtems_timer_fire_when`` directive and from the Timer Server task if |
---|
| 147 | initiated by the ``rtems_timer_server_fire_when`` directive. |
---|
[fd6dc8c8] | 148 | |
---|
| 149 | Canceling a Timer |
---|
| 150 | ----------------- |
---|
| 151 | |
---|
[b8d3f6b] | 152 | The ``rtems_timer_cancel`` directive is used to halt the specified timer. Once |
---|
| 153 | canceled, the timer service routine will not fire unless the timer is |
---|
| 154 | reinitiated. The timer can be reinitiated using the ``rtems_timer_reset``, |
---|
| 155 | ``rtems_timer_fire_after``, and ``rtems_timer_fire_when`` directives. |
---|
[fd6dc8c8] | 156 | |
---|
| 157 | Resetting a Timer |
---|
| 158 | ----------------- |
---|
| 159 | |
---|
[b8d3f6b] | 160 | The ``rtems_timer_reset`` directive is used to restore an interval timer |
---|
| 161 | initiated by a previous invocation of ``rtems_timer_fire_after`` or |
---|
| 162 | ``rtems_timer_server_fire_after`` to its original interval length. If the |
---|
| 163 | timer has not been used or the last usage of this timer was by the |
---|
| 164 | ``rtems_timer_fire_when`` or ``rtems_timer_server_fire_when`` directive, then |
---|
| 165 | an error is returned. The timer service routine is not changed or fired by |
---|
| 166 | this directive. |
---|
[fd6dc8c8] | 167 | |
---|
| 168 | Initiating the Timer Server |
---|
| 169 | --------------------------- |
---|
| 170 | |
---|
[b8d3f6b] | 171 | The ``rtems_timer_initiate_server`` directive is used to allocate and start the |
---|
| 172 | execution of the Timer Server task. The application can specify both the stack |
---|
| 173 | size and attributes of the Timer Server. The Timer Server executes at a |
---|
| 174 | priority higher than any application task and thus the user can expect to be |
---|
| 175 | preempted as the result of executing the ``rtems_timer_initiate_server`` |
---|
[fd6dc8c8] | 176 | directive. |
---|
| 177 | |
---|
| 178 | Deleting a Timer |
---|
| 179 | ---------------- |
---|
| 180 | |
---|
[b8d3f6b] | 181 | The ``rtems_timer_delete`` directive is used to delete a timer. If the timer |
---|
| 182 | is running and has not expired, the timer is automatically canceled. The |
---|
| 183 | timer's control block is returned to the TMCB free list when it is deleted. A |
---|
| 184 | timer can be deleted by a task other than the task which created the timer. |
---|
[d389819] | 185 | Any subsequent references to the timer's name and ID are invalid. |
---|
[fd6dc8c8] | 186 | |
---|
| 187 | Directives |
---|
| 188 | ========== |
---|
| 189 | |
---|
[b8d3f6b] | 190 | This section details the timer manager's directives. A subsection is dedicated |
---|
| 191 | to each of this manager's directives and describes the calling sequence, |
---|
| 192 | related constants, usage, and status codes. |
---|
| 193 | |
---|
[53bb72e] | 194 | .. raw:: latex |
---|
| 195 | |
---|
| 196 | \clearpage |
---|
[6c56401] | 197 | .. index:: create a timer |
---|
| 198 | .. index:: rtems_timer_create |
---|
[fd6dc8c8] | 199 | |
---|
[3384994] | 200 | .. _rtems_timer_create: |
---|
| 201 | |
---|
[fd6dc8c8] | 202 | TIMER_CREATE - Create a timer |
---|
| 203 | ----------------------------- |
---|
| 204 | |
---|
[53bb72e] | 205 | CALLING SEQUENCE: |
---|
| 206 | .. code-block:: c |
---|
[fd6dc8c8] | 207 | |
---|
[53bb72e] | 208 | rtems_status_code rtems_timer_create( |
---|
| 209 | rtems_name name, |
---|
| 210 | rtems_id *id |
---|
| 211 | ); |
---|
[fd6dc8c8] | 212 | |
---|
[53bb72e] | 213 | DIRECTIVE STATUS CODES: |
---|
| 214 | .. list-table:: |
---|
| 215 | :class: rtems-table |
---|
[b8d3f6b] | 216 | |
---|
[53bb72e] | 217 | * - ``RTEMS_SUCCESSFUL`` |
---|
| 218 | - timer created successfully |
---|
| 219 | * - ``RTEMS_INVALID_ADDRESS`` |
---|
| 220 | - ``id`` is NULL |
---|
| 221 | * - ``RTEMS_INVALID_NAME`` |
---|
| 222 | - invalid timer name |
---|
| 223 | * - ``RTEMS_TOO_MANY`` |
---|
| 224 | - too many timers created |
---|
[fd6dc8c8] | 225 | |
---|
[53bb72e] | 226 | DESCRIPTION: |
---|
| 227 | This directive creates a timer. The assigned timer id is returned in id. |
---|
| 228 | This id is used to access the timer with other timer manager directives. |
---|
| 229 | For control and maintenance of the timer, RTEMS allocates a TMCB from the |
---|
| 230 | local TMCB free pool and initializes it. |
---|
[fd6dc8c8] | 231 | |
---|
[53bb72e] | 232 | NOTES: |
---|
[1161ed1] | 233 | This directive will obtain the allocator mutex and may cause the calling |
---|
| 234 | task to be preempted. |
---|
| 235 | |
---|
| 236 | In SMP configurations, the processor of the currently executing thread |
---|
| 237 | determines the processor used for the created timer. During the life-time |
---|
| 238 | of the timer this processor is used to manage the timer internally. |
---|
[fd6dc8c8] | 239 | |
---|
[53bb72e] | 240 | .. raw:: latex |
---|
[fd6dc8c8] | 241 | |
---|
[53bb72e] | 242 | \clearpage |
---|
[b8d3f6b] | 243 | |
---|
[6c56401] | 244 | .. index:: obtain the ID of a timer |
---|
| 245 | .. index:: rtems_timer_ident |
---|
[fd6dc8c8] | 246 | |
---|
[3384994] | 247 | .. _rtems_timer_ident: |
---|
| 248 | |
---|
[fd6dc8c8] | 249 | TIMER_IDENT - Get ID of a timer |
---|
| 250 | ------------------------------- |
---|
| 251 | |
---|
[53bb72e] | 252 | CALLING SEQUENCE: |
---|
| 253 | .. code-block:: c |
---|
[fd6dc8c8] | 254 | |
---|
[53bb72e] | 255 | rtems_status_code rtems_timer_ident( |
---|
| 256 | rtems_name name, |
---|
| 257 | rtems_id *id |
---|
| 258 | ); |
---|
[fd6dc8c8] | 259 | |
---|
[53bb72e] | 260 | DIRECTIVE STATUS CODES: |
---|
| 261 | .. list-table:: |
---|
| 262 | :class: rtems-table |
---|
[fd6dc8c8] | 263 | |
---|
[53bb72e] | 264 | * - ``RTEMS_SUCCESSFUL`` |
---|
| 265 | - timer identified successfully |
---|
| 266 | * - ``RTEMS_INVALID_ADDRESS`` |
---|
| 267 | - ``id`` is NULL |
---|
| 268 | * - ``RTEMS_INVALID_NAME`` |
---|
| 269 | - timer name not found |
---|
[b8d3f6b] | 270 | |
---|
[53bb72e] | 271 | DESCRIPTION: |
---|
| 272 | This directive obtains the timer id associated with the timer name to be |
---|
| 273 | acquired. If the timer name is not unique, then the timer id will match |
---|
| 274 | one of the timers with that name. However, this timer id is not guaranteed |
---|
| 275 | to correspond to the desired timer. The timer id is used to access this |
---|
| 276 | timer in other timer related directives. |
---|
[fd6dc8c8] | 277 | |
---|
[53bb72e] | 278 | NOTES: |
---|
| 279 | This directive will not cause the running task to be preempted. |
---|
[fd6dc8c8] | 280 | |
---|
[53bb72e] | 281 | .. raw:: latex |
---|
[fd6dc8c8] | 282 | |
---|
[53bb72e] | 283 | \clearpage |
---|
[b8d3f6b] | 284 | |
---|
[6c56401] | 285 | .. index:: cancel a timer |
---|
| 286 | .. index:: rtems_timer_cancel |
---|
[fd6dc8c8] | 287 | |
---|
[3384994] | 288 | .. _rtems_timer_cancel: |
---|
| 289 | |
---|
[fd6dc8c8] | 290 | TIMER_CANCEL - Cancel a timer |
---|
| 291 | ----------------------------- |
---|
| 292 | |
---|
[53bb72e] | 293 | CALLING SEQUENCE: |
---|
| 294 | .. code-block:: c |
---|
[fd6dc8c8] | 295 | |
---|
[53bb72e] | 296 | rtems_status_code rtems_timer_cancel( |
---|
| 297 | rtems_id id |
---|
| 298 | ); |
---|
[fd6dc8c8] | 299 | |
---|
[53bb72e] | 300 | DIRECTIVE STATUS CODES: |
---|
| 301 | .. list-table:: |
---|
| 302 | :class: rtems-table |
---|
[fd6dc8c8] | 303 | |
---|
[53bb72e] | 304 | * - ``RTEMS_SUCCESSFUL`` |
---|
| 305 | - timer canceled successfully |
---|
| 306 | * - ``RTEMS_INVALID_ID`` |
---|
| 307 | - invalid timer id |
---|
[b8d3f6b] | 308 | |
---|
[53bb72e] | 309 | DESCRIPTION: |
---|
| 310 | This directive cancels the timer id. This timer will be reinitiated by the |
---|
| 311 | next invocation of ``rtems_timer_reset``, ``rtems_timer_fire_after``, or |
---|
| 312 | ``rtems_timer_fire_when`` with this id. |
---|
[fd6dc8c8] | 313 | |
---|
[53bb72e] | 314 | NOTES: |
---|
| 315 | This directive will not cause the running task to be preempted. |
---|
[fd6dc8c8] | 316 | |
---|
[53bb72e] | 317 | .. raw:: latex |
---|
[fd6dc8c8] | 318 | |
---|
[53bb72e] | 319 | \clearpage |
---|
[fd6dc8c8] | 320 | |
---|
[6c56401] | 321 | .. index:: delete a timer |
---|
| 322 | .. index:: rtems_timer_delete |
---|
[b8d3f6b] | 323 | |
---|
[3384994] | 324 | .. _rtems_timer_delete: |
---|
| 325 | |
---|
[fd6dc8c8] | 326 | TIMER_DELETE - Delete a timer |
---|
| 327 | ----------------------------- |
---|
| 328 | |
---|
[53bb72e] | 329 | CALLING SEQUENCE: |
---|
| 330 | .. code-block:: c |
---|
[fd6dc8c8] | 331 | |
---|
[53bb72e] | 332 | rtems_status_code rtems_timer_delete( |
---|
| 333 | rtems_id id |
---|
| 334 | ); |
---|
[fd6dc8c8] | 335 | |
---|
[53bb72e] | 336 | DIRECTIVE STATUS CODES: |
---|
| 337 | .. list-table:: |
---|
| 338 | :class: rtems-table |
---|
[b8d3f6b] | 339 | |
---|
[53bb72e] | 340 | * - ``RTEMS_SUCCESSFUL`` |
---|
| 341 | - timer deleted successfully |
---|
| 342 | * - ``RTEMS_INVALID_ID`` |
---|
| 343 | - invalid timer id |
---|
[fd6dc8c8] | 344 | |
---|
[53bb72e] | 345 | DESCRIPTION: |
---|
| 346 | This directive deletes the timer specified by id. If the timer is running, |
---|
| 347 | it is automatically canceled. The TMCB for the deleted timer is reclaimed |
---|
| 348 | by RTEMS. |
---|
[fd6dc8c8] | 349 | |
---|
[53bb72e] | 350 | NOTES: |
---|
[1161ed1] | 351 | This directive will obtain the allocator mutex and may cause the calling |
---|
| 352 | task to be preempted. |
---|
[fd6dc8c8] | 353 | |
---|
[53bb72e] | 354 | A timer can be deleted by a task other than the task which created the |
---|
| 355 | timer. |
---|
[fd6dc8c8] | 356 | |
---|
[53bb72e] | 357 | .. raw:: latex |
---|
[b8d3f6b] | 358 | |
---|
[53bb72e] | 359 | \clearpage |
---|
[fd6dc8c8] | 360 | |
---|
[6c56401] | 361 | .. index:: fire a timer after an interval |
---|
| 362 | .. index:: rtems_timer_fire_after |
---|
[fd6dc8c8] | 363 | |
---|
[3384994] | 364 | .. _rtems_timer_fire_after: |
---|
| 365 | |
---|
[fd6dc8c8] | 366 | TIMER_FIRE_AFTER - Fire timer after interval |
---|
| 367 | -------------------------------------------- |
---|
| 368 | |
---|
[53bb72e] | 369 | CALLING SEQUENCE: |
---|
| 370 | .. code-block:: c |
---|
[fd6dc8c8] | 371 | |
---|
[53bb72e] | 372 | rtems_status_code rtems_timer_fire_after( |
---|
| 373 | rtems_id id, |
---|
| 374 | rtems_interval ticks, |
---|
| 375 | rtems_timer_service_routine_entry routine, |
---|
| 376 | void *user_data |
---|
| 377 | ); |
---|
[fd6dc8c8] | 378 | |
---|
[53bb72e] | 379 | DIRECTIVE STATUS CODES: |
---|
| 380 | .. list-table:: |
---|
| 381 | :class: rtems-table |
---|
[b8d3f6b] | 382 | |
---|
[53bb72e] | 383 | * - ``RTEMS_SUCCESSFUL`` |
---|
| 384 | - timer initiated successfully |
---|
| 385 | * - ``RTEMS_INVALID_ADDRESS`` |
---|
| 386 | - ``routine`` is NULL |
---|
| 387 | * - ``RTEMS_INVALID_ID`` |
---|
| 388 | - invalid timer id |
---|
| 389 | * - ``RTEMS_INVALID_NUMBER`` |
---|
| 390 | - invalid interval |
---|
[fd6dc8c8] | 391 | |
---|
[53bb72e] | 392 | DESCRIPTION: |
---|
| 393 | This directive initiates the timer specified by id. If the timer is |
---|
| 394 | running, it is automatically canceled before being initiated. The timer is |
---|
| 395 | scheduled to fire after an interval ticks clock ticks has passed. When the |
---|
| 396 | timer fires, the timer service routine routine will be invoked with the |
---|
| 397 | argument user_data. |
---|
[fd6dc8c8] | 398 | |
---|
[53bb72e] | 399 | NOTES: |
---|
| 400 | This directive will not cause the running task to be preempted. |
---|
[fd6dc8c8] | 401 | |
---|
[53bb72e] | 402 | .. raw:: latex |
---|
[fd6dc8c8] | 403 | |
---|
[53bb72e] | 404 | \clearpage |
---|
[b8d3f6b] | 405 | |
---|
[6c56401] | 406 | .. index:: fire a timer at wall time |
---|
| 407 | .. index:: rtems_timer_fire_when |
---|
[fd6dc8c8] | 408 | |
---|
[3384994] | 409 | .. _rtems_timer_fire_when: |
---|
| 410 | |
---|
[fd6dc8c8] | 411 | TIMER_FIRE_WHEN - Fire timer when specified |
---|
| 412 | ------------------------------------------- |
---|
| 413 | |
---|
[53bb72e] | 414 | CALLING SEQUENCE: |
---|
| 415 | .. code-block:: c |
---|
| 416 | |
---|
| 417 | rtems_status_code rtems_timer_fire_when( |
---|
| 418 | rtems_id id, |
---|
| 419 | rtems_time_of_day *wall_time, |
---|
| 420 | rtems_timer_service_routine_entry routine, |
---|
| 421 | void *user_data |
---|
| 422 | ); |
---|
| 423 | |
---|
| 424 | DIRECTIVE STATUS CODES: |
---|
| 425 | .. list-table:: |
---|
| 426 | :class: rtems-table |
---|
| 427 | |
---|
| 428 | * - ``RTEMS_SUCCESSFUL`` |
---|
| 429 | - timer initiated successfully |
---|
| 430 | * - ``RTEMS_INVALID_ADDRESS`` |
---|
| 431 | - ``routine`` is NULL |
---|
| 432 | * - ``RTEMS_INVALID_ADDRESS`` |
---|
| 433 | - ``wall_time`` is NULL |
---|
| 434 | * - ``RTEMS_INVALID_ID`` |
---|
| 435 | - invalid timer id |
---|
| 436 | * - ``RTEMS_NOT_DEFINED`` |
---|
| 437 | - system date and time is not set |
---|
| 438 | * - ``RTEMS_INVALID_CLOCK`` |
---|
| 439 | - invalid time of day |
---|
| 440 | |
---|
| 441 | DESCRIPTION: |
---|
| 442 | This directive initiates the timer specified by id. If the timer is |
---|
| 443 | running, it is automatically canceled before being initiated. The timer is |
---|
| 444 | scheduled to fire at the time of day specified by wall_time. When the |
---|
| 445 | timer fires, the timer service routine routine will be invoked with the |
---|
| 446 | argument user_data. |
---|
| 447 | |
---|
| 448 | NOTES: |
---|
| 449 | This directive will not cause the running task to be preempted. |
---|
| 450 | |
---|
| 451 | .. raw:: latex |
---|
| 452 | |
---|
| 453 | \clearpage |
---|
[b8d3f6b] | 454 | |
---|
[6c56401] | 455 | .. index:: initiate the Timer Server |
---|
| 456 | .. index:: rtems_timer_initiate_server |
---|
[fd6dc8c8] | 457 | |
---|
[3384994] | 458 | .. _rtems_timer_initiate_server: |
---|
| 459 | |
---|
[fd6dc8c8] | 460 | TIMER_INITIATE_SERVER - Initiate server for task-based timers |
---|
| 461 | ------------------------------------------------------------- |
---|
| 462 | |
---|
[53bb72e] | 463 | CALLING SEQUENCE: |
---|
| 464 | .. code-block:: c |
---|
[fd6dc8c8] | 465 | |
---|
[53bb72e] | 466 | rtems_status_code rtems_timer_initiate_server( |
---|
| 467 | uint32_t priority, |
---|
| 468 | uint32_t stack_size, |
---|
| 469 | rtems_attribute attribute_set |
---|
| 470 | ); |
---|
[fd6dc8c8] | 471 | |
---|
[53bb72e] | 472 | DIRECTIVE STATUS CODES: |
---|
| 473 | .. list-table:: |
---|
| 474 | :class: rtems-table |
---|
[b8d3f6b] | 475 | |
---|
[53bb72e] | 476 | * - ``RTEMS_SUCCESSFUL`` |
---|
| 477 | - Timer Server initiated successfully |
---|
| 478 | * - ``RTEMS_TOO_MANY`` |
---|
| 479 | - too many tasks created |
---|
[fd6dc8c8] | 480 | |
---|
[53bb72e] | 481 | DESCRIPTION: |
---|
| 482 | This directive initiates the Timer Server task. This task is responsible |
---|
| 483 | for executing all timers initiated via the |
---|
| 484 | ``rtems_timer_server_fire_after`` or ``rtems_timer_server_fire_when`` |
---|
| 485 | directives. |
---|
[fd6dc8c8] | 486 | |
---|
[53bb72e] | 487 | NOTES: |
---|
| 488 | This directive could cause the calling task to be preempted. |
---|
[fd6dc8c8] | 489 | |
---|
[53bb72e] | 490 | The Timer Server task is created using the ``rtems_task_create`` service |
---|
| 491 | and must be accounted for when configuring the system. |
---|
[fd6dc8c8] | 492 | |
---|
[53bb72e] | 493 | Even through this directive invokes the ``rtems_task_create`` and |
---|
| 494 | ``rtems_task_start`` directives, it should only fail due to resource |
---|
| 495 | allocation problems. |
---|
[fd6dc8c8] | 496 | |
---|
[53bb72e] | 497 | .. raw:: latex |
---|
[b8d3f6b] | 498 | |
---|
[53bb72e] | 499 | \clearpage |
---|
[fd6dc8c8] | 500 | |
---|
[6c56401] | 501 | .. index:: fire task-based a timer after an interval |
---|
| 502 | .. index:: rtems_timer_server_fire_after |
---|
[fd6dc8c8] | 503 | |
---|
[3384994] | 504 | .. _rtems_timer_server_fire_after: |
---|
| 505 | |
---|
[fd6dc8c8] | 506 | TIMER_SERVER_FIRE_AFTER - Fire task-based timer after interval |
---|
| 507 | -------------------------------------------------------------- |
---|
| 508 | |
---|
[53bb72e] | 509 | CALLING SEQUENCE: |
---|
| 510 | .. code-block:: c |
---|
[fd6dc8c8] | 511 | |
---|
[53bb72e] | 512 | rtems_status_code rtems_timer_server_fire_after( |
---|
| 513 | rtems_id id, |
---|
| 514 | rtems_interval ticks, |
---|
| 515 | rtems_timer_service_routine_entry routine, |
---|
| 516 | void *user_data |
---|
| 517 | ); |
---|
[fd6dc8c8] | 518 | |
---|
[53bb72e] | 519 | DIRECTIVE STATUS CODES: |
---|
| 520 | .. list-table:: |
---|
| 521 | :class: rtems-table |
---|
[b8d3f6b] | 522 | |
---|
[53bb72e] | 523 | * - ``RTEMS_SUCCESSFUL`` |
---|
| 524 | - timer initiated successfully |
---|
| 525 | * - ``RTEMS_INVALID_ADDRESS`` |
---|
| 526 | - ``routine`` is NULL |
---|
| 527 | * - ``RTEMS_INVALID_ID`` |
---|
| 528 | - invalid timer id |
---|
| 529 | * - ``RTEMS_INVALID_NUMBER`` |
---|
| 530 | - invalid interval |
---|
| 531 | * - ``RTEMS_INCORRECT_STATE`` |
---|
| 532 | - Timer Server not initiated |
---|
[fd6dc8c8] | 533 | |
---|
[53bb72e] | 534 | DESCRIPTION: |
---|
| 535 | This directive initiates the timer specified by id and specifies that when |
---|
| 536 | it fires it will be executed by the Timer Server. |
---|
[fd6dc8c8] | 537 | |
---|
[53bb72e] | 538 | If the timer is running, it is automatically canceled before being |
---|
| 539 | initiated. The timer is scheduled to fire after an interval ticks clock |
---|
| 540 | ticks has passed. When the timer fires, the timer service routine routine |
---|
| 541 | will be invoked with the argument user_data. |
---|
[fd6dc8c8] | 542 | |
---|
[53bb72e] | 543 | NOTES: |
---|
| 544 | This directive will not cause the running task to be preempted. |
---|
[fd6dc8c8] | 545 | |
---|
[53bb72e] | 546 | .. raw:: latex |
---|
[fd6dc8c8] | 547 | |
---|
[53bb72e] | 548 | \clearpage |
---|
[b8d3f6b] | 549 | |
---|
[6c56401] | 550 | .. index:: fire a task-based timer at wall time |
---|
| 551 | .. index:: rtems_timer_server_fire_when |
---|
[fd6dc8c8] | 552 | |
---|
[3384994] | 553 | .. _rtems_timer_server_fire_when: |
---|
| 554 | |
---|
[fd6dc8c8] | 555 | TIMER_SERVER_FIRE_WHEN - Fire task-based timer when specified |
---|
| 556 | ------------------------------------------------------------- |
---|
| 557 | |
---|
[53bb72e] | 558 | CALLING SEQUENCE: |
---|
| 559 | .. code-block:: c |
---|
| 560 | |
---|
| 561 | rtems_status_code rtems_timer_server_fire_when( |
---|
| 562 | rtems_id id, |
---|
| 563 | rtems_time_of_day *wall_time, |
---|
| 564 | rtems_timer_service_routine_entry routine, |
---|
| 565 | void *user_data |
---|
| 566 | ); |
---|
| 567 | |
---|
| 568 | DIRECTIVE STATUS CODES: |
---|
| 569 | .. list-table:: |
---|
| 570 | :class: rtems-table |
---|
| 571 | |
---|
| 572 | * - ``RTEMS_SUCCESSFUL`` |
---|
| 573 | - timer initiated successfully |
---|
| 574 | * - ``RTEMS_INVALID_ADDRESS`` |
---|
| 575 | - ``routine`` is NULL |
---|
| 576 | * - ``RTEMS_INVALID_ADDRESS`` |
---|
| 577 | - ``wall_time`` is NULL |
---|
| 578 | * - ``RTEMS_INVALID_ID`` |
---|
| 579 | - invalid timer id |
---|
| 580 | * - ``RTEMS_NOT_DEFINED`` |
---|
| 581 | - system date and time is not set |
---|
| 582 | * - ``RTEMS_INVALID_CLOCK`` |
---|
| 583 | - invalid time of day |
---|
| 584 | * - ``RTEMS_INCORRECT_STATE`` |
---|
| 585 | - Timer Server not initiated |
---|
| 586 | |
---|
| 587 | DESCRIPTION: |
---|
| 588 | This directive initiates the timer specified by id and specifies that when |
---|
| 589 | it fires it will be executed by the Timer Server. |
---|
| 590 | |
---|
| 591 | If the timer is running, it is automatically canceled before being |
---|
| 592 | initiated. The timer is scheduled to fire at the time of day specified by |
---|
| 593 | wall_time. When the timer fires, the timer service routine routine will be |
---|
| 594 | invoked with the argument user_data. |
---|
| 595 | |
---|
| 596 | NOTES: |
---|
| 597 | This directive will not cause the running task to be preempted. |
---|
| 598 | |
---|
| 599 | .. raw:: latex |
---|
| 600 | |
---|
| 601 | \clearpage |
---|
[b8d3f6b] | 602 | |
---|
[6c56401] | 603 | .. index:: reset a timer |
---|
| 604 | .. index:: rtems_timer_reset |
---|
[fd6dc8c8] | 605 | |
---|
[3384994] | 606 | .. _rtems_timer_reset: |
---|
| 607 | |
---|
[fd6dc8c8] | 608 | TIMER_RESET - Reset an interval timer |
---|
| 609 | ------------------------------------- |
---|
| 610 | |
---|
[53bb72e] | 611 | CALLING SEQUENCE: |
---|
| 612 | .. code-block:: c |
---|
| 613 | |
---|
| 614 | rtems_status_code rtems_timer_reset( |
---|
| 615 | rtems_id id |
---|
| 616 | ); |
---|
| 617 | |
---|
| 618 | DIRECTIVE STATUS CODES: |
---|
| 619 | .. list-table:: |
---|
| 620 | :class: rtems-table |
---|
| 621 | |
---|
| 622 | * - ``RTEMS_SUCCESSFUL`` |
---|
| 623 | - timer reset successfully |
---|
| 624 | * - ``RTEMS_INVALID_ID`` |
---|
| 625 | - invalid timer id |
---|
| 626 | * - ``RTEMS_NOT_DEFINED`` |
---|
| 627 | - attempted to reset a when or newly created timer |
---|
| 628 | |
---|
| 629 | DESCRIPTION: |
---|
| 630 | This directive resets the timer associated with id. This timer must have |
---|
| 631 | been previously initiated with either the ``rtems_timer_fire_after`` or |
---|
| 632 | ``rtems_timer_server_fire_after`` directive. If active the timer is |
---|
| 633 | canceled, after which the timer is reinitiated using the same interval and |
---|
| 634 | timer service routine which the original ``rtems_timer_fire_after`` or |
---|
| 635 | ``rtems_timer_server_fire_after`` directive used. |
---|
| 636 | |
---|
| 637 | NOTES: |
---|
| 638 | If the timer has not been used or the last usage of this timer was by a |
---|
| 639 | ``rtems_timer_fire_when`` or ``rtems_timer_server_fire_when`` directive, |
---|
| 640 | then the ``RTEMS_NOT_DEFINED`` error is returned. |
---|
| 641 | |
---|
| 642 | Restarting a cancelled after timer results in the timer being reinitiated |
---|
| 643 | with its previous timer service routine and interval. |
---|
| 644 | |
---|
| 645 | This directive will not cause the running task to be preempted. |
---|