[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:: interrupts |
---|
| 8 | |
---|
[fd6dc8c8] | 9 | Interrupt Manager |
---|
[4da4a15] | 10 | ***************** |
---|
[fd6dc8c8] | 11 | |
---|
| 12 | Introduction |
---|
| 13 | ============ |
---|
| 14 | |
---|
[b8d3f6b] | 15 | Any real-time executive must provide a mechanism for quick response to |
---|
| 16 | externally generated interrupts to satisfy the critical time constraints of the |
---|
| 17 | application. The interrupt manager provides this mechanism for RTEMS. This |
---|
| 18 | manager permits quick interrupt response times by providing the critical |
---|
| 19 | ability to alter task execution which allows a task to be preempted upon exit |
---|
| 20 | from an ISR. The interrupt manager includes the following directive: |
---|
[fd6dc8c8] | 21 | |
---|
[b8d3f6b] | 22 | - rtems_interrupt_catch_ - Establish an ISR |
---|
[fd6dc8c8] | 23 | |
---|
[b8d3f6b] | 24 | - rtems_interrupt_disable_ - Disable Interrupts |
---|
[fd6dc8c8] | 25 | |
---|
[b8d3f6b] | 26 | - rtems_interrupt_enable_ - Enable Interrupts |
---|
[fd6dc8c8] | 27 | |
---|
[b8d3f6b] | 28 | - rtems_interrupt_flash_ - Flash Interrupt |
---|
[fd6dc8c8] | 29 | |
---|
[b8d3f6b] | 30 | - rtems_interrupt_local_disable_ - Disable Interrupts on Current Processor |
---|
[fd6dc8c8] | 31 | |
---|
[b8d3f6b] | 32 | - rtems_interrupt_local_enable_ - Enable Interrupts on Current Processor |
---|
[fd6dc8c8] | 33 | |
---|
[b8d3f6b] | 34 | - rtems_interrupt_lock_initialize_ - Initialize an ISR Lock |
---|
[fd6dc8c8] | 35 | |
---|
[b8d3f6b] | 36 | - rtems_interrupt_lock_acquire_ - Acquire an ISR Lock |
---|
[fd6dc8c8] | 37 | |
---|
[b8d3f6b] | 38 | - rtems_interrupt_lock_release_ - Release an ISR Lock |
---|
[fd6dc8c8] | 39 | |
---|
[b8d3f6b] | 40 | - rtems_interrupt_lock_acquire_isr_ - Acquire an ISR Lock from ISR |
---|
[fd6dc8c8] | 41 | |
---|
[b8d3f6b] | 42 | - rtems_interrupt_lock_release_isr_ - Release an ISR Lock from ISR |
---|
[fd6dc8c8] | 43 | |
---|
[b8d3f6b] | 44 | - rtems_interrupt_is_in_progress_ - Is an ISR in Progress |
---|
[fd6dc8c8] | 45 | |
---|
| 46 | Background |
---|
| 47 | ========== |
---|
| 48 | |
---|
[6c56401] | 49 | .. index:: interrupt processing |
---|
| 50 | |
---|
[fd6dc8c8] | 51 | Processing an Interrupt |
---|
| 52 | ----------------------- |
---|
| 53 | |
---|
[b8d3f6b] | 54 | The interrupt manager allows the application to connect a function to a |
---|
| 55 | hardware interrupt vector. When an interrupt occurs, the processor will |
---|
| 56 | automatically vector to RTEMS. RTEMS saves and restores all registers which |
---|
| 57 | are not preserved by the normal C calling convention for the target processor |
---|
| 58 | and invokes the user's ISR. The user's ISR is responsible for processing the |
---|
| 59 | interrupt, clearing the interrupt if necessary, and device specific |
---|
| 60 | manipulation. |
---|
| 61 | |
---|
| 62 | .. index:: rtems_vector_number |
---|
| 63 | |
---|
| 64 | The ``rtems_interrupt_catch`` directive connects a procedure to an interrupt |
---|
| 65 | vector. The vector number is managed using the ``rtems_vector_number`` data |
---|
| 66 | type. |
---|
| 67 | |
---|
| 68 | The interrupt service routine is assumed to abide by these conventions and have |
---|
| 69 | a prototype similar to the following: |
---|
| 70 | |
---|
| 71 | .. index:: rtems_isr |
---|
[fd6dc8c8] | 72 | |
---|
[25d55d4] | 73 | .. code-block:: c |
---|
[fd6dc8c8] | 74 | |
---|
| 75 | rtems_isr user_isr( |
---|
[b8d3f6b] | 76 | rtems_vector_number vector |
---|
[fd6dc8c8] | 77 | ); |
---|
| 78 | |
---|
[b8d3f6b] | 79 | The vector number argument is provided by RTEMS to allow the application to |
---|
| 80 | identify the interrupt source. This could be used to allow a single routine to |
---|
| 81 | service interrupts from multiple instances of the same device. For example, a |
---|
| 82 | single routine could service interrupts from multiple serial ports and use the |
---|
| 83 | vector number to identify which port requires servicing. |
---|
| 84 | |
---|
| 85 | To minimize the masking of lower or equal priority level interrupts, the ISR |
---|
| 86 | should perform the minimum actions required to service the interrupt. Other |
---|
| 87 | non-essential actions should be handled by application tasks. Once the user's |
---|
| 88 | ISR has completed, it returns control to the RTEMS interrupt manager which will |
---|
| 89 | perform task dispatching and restore the registers saved before the ISR was |
---|
| 90 | invoked. |
---|
| 91 | |
---|
| 92 | The RTEMS interrupt manager guarantees that proper task scheduling and |
---|
| 93 | dispatching are performed at the conclusion of an ISR. A system call made by |
---|
| 94 | the ISR may have readied a task of higher priority than the interrupted task. |
---|
| 95 | Therefore, when the ISR completes, the postponed dispatch processing must be |
---|
| 96 | performed. No dispatch processing is performed as part of directives which |
---|
| 97 | have been invoked by an ISR. |
---|
| 98 | |
---|
| 99 | Applications must adhere to the following rule if proper task scheduling and |
---|
| 100 | dispatching is to be performed: |
---|
| 101 | |
---|
| 102 | .. note:: |
---|
| 103 | |
---|
| 104 | The interrupt manager must be used for all ISRs which may be interrupted by |
---|
| 105 | the highest priority ISR which invokes an RTEMS directive. |
---|
| 106 | |
---|
| 107 | Consider a processor which allows a numerically low interrupt level to |
---|
| 108 | interrupt a numerically greater interrupt level. In this example, if an RTEMS |
---|
| 109 | directive is used in a level 4 ISR, then all ISRs which execute at levels 0 |
---|
| 110 | through 4 must use the interrupt manager. |
---|
| 111 | |
---|
| 112 | Interrupts are nested whenever an interrupt occurs during the execution of |
---|
| 113 | another ISR. RTEMS supports efficient interrupt nesting by allowing the nested |
---|
| 114 | ISRs to terminate without performing any dispatch processing. Only when the |
---|
[fd6dc8c8] | 115 | outermost ISR terminates will the postponed dispatching occur. |
---|
| 116 | |
---|
[6c56401] | 117 | .. index:: interrupt levels |
---|
| 118 | |
---|
[fd6dc8c8] | 119 | RTEMS Interrupt Levels |
---|
| 120 | ---------------------- |
---|
| 121 | |
---|
[b8d3f6b] | 122 | Many processors support multiple interrupt levels or priorities. The exact |
---|
| 123 | number of interrupt levels is processor dependent. RTEMS internally supports |
---|
| 124 | 256 interrupt levels which are mapped to the processor's interrupt levels. For |
---|
| 125 | specific information on the mapping between RTEMS and the target processor's |
---|
| 126 | interrupt levels, refer to the Interrupt Processing chapter of the Applications |
---|
| 127 | Supplement document for a specific target processor. |
---|
[fd6dc8c8] | 128 | |
---|
[6c56401] | 129 | .. index:: disabling interrupts |
---|
| 130 | |
---|
[fd6dc8c8] | 131 | Disabling of Interrupts by RTEMS |
---|
| 132 | -------------------------------- |
---|
| 133 | |
---|
[b8d3f6b] | 134 | During the execution of directive calls, critical sections of code may be |
---|
| 135 | executed. When these sections are encountered, RTEMS disables all maskable |
---|
| 136 | interrupts before the execution of the section and restores them to the |
---|
| 137 | previous level upon completion of the section. RTEMS has been optimized to |
---|
| 138 | ensure that interrupts are disabled for a minimum length of time. The maximum |
---|
| 139 | length of time interrupts are disabled by RTEMS is processor dependent and is |
---|
| 140 | detailed in the Timing Specification chapter of the Applications Supplement |
---|
| 141 | document for a specific target processor. |
---|
| 142 | |
---|
| 143 | Non-maskable interrupts (NMI) cannot be disabled, and ISRs which execute at |
---|
| 144 | this level MUST NEVER issue RTEMS system calls. If a directive is invoked, |
---|
| 145 | unpredictable results may occur due to the inability of RTEMS to protect its |
---|
| 146 | critical sections. However, ISRs that make no system calls may safely execute |
---|
| 147 | as non-maskable interrupts. |
---|
[fd6dc8c8] | 148 | |
---|
| 149 | Operations |
---|
| 150 | ========== |
---|
| 151 | |
---|
| 152 | Establishing an ISR |
---|
| 153 | ------------------- |
---|
| 154 | |
---|
[b8d3f6b] | 155 | The ``rtems_interrupt_catch`` directive establishes an ISR for the system. The |
---|
| 156 | address of the ISR and its associated CPU vector number are specified to this |
---|
| 157 | directive. This directive installs the RTEMS interrupt wrapper in the |
---|
| 158 | processor's Interrupt Vector Table and the address of the user's ISR in the |
---|
| 159 | RTEMS' Vector Table. This directive returns the previous contents of the |
---|
| 160 | specified vector in the RTEMS' Vector Table. |
---|
[fd6dc8c8] | 161 | |
---|
| 162 | Directives Allowed from an ISR |
---|
| 163 | ------------------------------ |
---|
| 164 | |
---|
[b8d3f6b] | 165 | Using the interrupt manager ensures that RTEMS knows when a directive is being |
---|
| 166 | called from an ISR. The ISR may then use system calls to synchronize itself |
---|
| 167 | with an application task. The synchronization may involve messages, events or |
---|
| 168 | signals being passed by the ISR to the desired task. Directives invoked by an |
---|
| 169 | ISR must operate only on objects which reside on the local node. The following |
---|
| 170 | is a list of RTEMS system calls that may be made from an ISR: |
---|
[fd6dc8c8] | 171 | |
---|
| 172 | - Task Management |
---|
[b8d3f6b] | 173 | Although it is acceptable to operate on the RTEMS_SELF task (e.g. the |
---|
| 174 | currently executing task), while in an ISR, this will refer to the |
---|
| 175 | interrupted task. Most of the time, it is an application implementation |
---|
| 176 | error to use RTEMS_SELF from an ISR. |
---|
[859f0b7] | 177 | |
---|
[fd6dc8c8] | 178 | - rtems_task_suspend |
---|
| 179 | - rtems_task_resume |
---|
| 180 | |
---|
| 181 | - Interrupt Management |
---|
[859f0b7] | 182 | |
---|
[fd6dc8c8] | 183 | - rtems_interrupt_enable |
---|
| 184 | - rtems_interrupt_disable |
---|
| 185 | - rtems_interrupt_flash |
---|
| 186 | - rtems_interrupt_lock_acquire |
---|
| 187 | - rtems_interrupt_lock_release |
---|
| 188 | - rtems_interrupt_lock_acquire_isr |
---|
| 189 | - rtems_interrupt_lock_release_isr |
---|
| 190 | - rtems_interrupt_is_in_progress |
---|
| 191 | - rtems_interrupt_catch |
---|
| 192 | |
---|
| 193 | - Clock Management |
---|
[859f0b7] | 194 | |
---|
[fd6dc8c8] | 195 | - rtems_clock_set |
---|
| 196 | - rtems_clock_get_tod |
---|
| 197 | - rtems_clock_get_tod_timeval |
---|
| 198 | - rtems_clock_get_seconds_since_epoch |
---|
| 199 | - rtems_clock_get_ticks_per_second |
---|
| 200 | - rtems_clock_get_ticks_since_boot |
---|
| 201 | - rtems_clock_get_uptime |
---|
[3a58bff] | 202 | - rtems_timecounter_tick |
---|
| 203 | - rtems_timecounter_simple_downcounter_tick |
---|
| 204 | - rtems_timecounter_simple_upcounter_tick |
---|
[fd6dc8c8] | 205 | |
---|
| 206 | - Timer Management |
---|
[859f0b7] | 207 | |
---|
[fd6dc8c8] | 208 | - rtems_timer_cancel |
---|
| 209 | - rtems_timer_reset |
---|
| 210 | - rtems_timer_fire_after |
---|
| 211 | - rtems_timer_fire_when |
---|
| 212 | - rtems_timer_server_fire_after |
---|
| 213 | - rtems_timer_server_fire_when |
---|
| 214 | |
---|
| 215 | - Event Management |
---|
[859f0b7] | 216 | |
---|
[fd6dc8c8] | 217 | - rtems_event_send |
---|
| 218 | - rtems_event_system_send |
---|
| 219 | - rtems_event_transient_send |
---|
| 220 | |
---|
| 221 | - Semaphore Management |
---|
[859f0b7] | 222 | |
---|
[fd6dc8c8] | 223 | - rtems_semaphore_release |
---|
| 224 | |
---|
| 225 | - Message Management |
---|
[859f0b7] | 226 | |
---|
[fd6dc8c8] | 227 | - rtems_message_queue_send |
---|
| 228 | - rtems_message_queue_urgent |
---|
| 229 | |
---|
| 230 | - Signal Management |
---|
[859f0b7] | 231 | |
---|
[fd6dc8c8] | 232 | - rtems_signal_send |
---|
| 233 | |
---|
| 234 | - Dual-Ported Memory Management |
---|
[859f0b7] | 235 | |
---|
[fd6dc8c8] | 236 | - rtems_port_external_to_internal |
---|
| 237 | - rtems_port_internal_to_external |
---|
| 238 | |
---|
| 239 | - IO Management |
---|
| 240 | The following services are safe to call from an ISR if and only if |
---|
| 241 | the device driver service invoked is also safe. The IO Manager itself |
---|
| 242 | is safe but the invoked driver entry point may or may not be. |
---|
[859f0b7] | 243 | |
---|
[fd6dc8c8] | 244 | - rtems_io_initialize |
---|
| 245 | - rtems_io_open |
---|
| 246 | - rtems_io_close |
---|
| 247 | - rtems_io_read |
---|
| 248 | - rtems_io_write |
---|
| 249 | - rtems_io_control |
---|
| 250 | |
---|
| 251 | - Fatal Error Management |
---|
[859f0b7] | 252 | |
---|
[fd6dc8c8] | 253 | - rtems_fatal |
---|
| 254 | - rtems_fatal_error_occurred |
---|
| 255 | |
---|
| 256 | - Multiprocessing |
---|
[859f0b7] | 257 | |
---|
[fd6dc8c8] | 258 | - rtems_multiprocessing_announce |
---|
| 259 | |
---|
| 260 | Directives |
---|
| 261 | ========== |
---|
| 262 | |
---|
[b8d3f6b] | 263 | This section details the interrupt manager's directives. A subsection is |
---|
| 264 | dedicated to each of this manager's directives and describes the calling |
---|
| 265 | sequence, related constants, usage, and status codes. |
---|
| 266 | |
---|
[53bb72e] | 267 | .. raw:: latex |
---|
| 268 | |
---|
| 269 | \clearpage |
---|
| 270 | |
---|
[b8d3f6b] | 271 | .. _rtems_interrupt_catch: |
---|
[fd6dc8c8] | 272 | .. index:: establish an ISR |
---|
| 273 | .. index:: install an ISR |
---|
| 274 | .. index:: rtems_interrupt_catch |
---|
| 275 | |
---|
[6c56401] | 276 | INTERRUPT_CATCH - Establish an ISR |
---|
| 277 | ---------------------------------- |
---|
| 278 | |
---|
[53bb72e] | 279 | CALLING SEQUENCE: |
---|
| 280 | .. code-block:: c |
---|
[fd6dc8c8] | 281 | |
---|
[53bb72e] | 282 | rtems_status_code rtems_interrupt_catch( |
---|
| 283 | rtems_isr_entry new_isr_handler, |
---|
| 284 | rtems_vector_number vector, |
---|
| 285 | rtems_isr_entry *old_isr_handler |
---|
| 286 | ); |
---|
[fd6dc8c8] | 287 | |
---|
[53bb72e] | 288 | DIRECTIVE STATUS CODES: |
---|
| 289 | .. list-table:: |
---|
| 290 | :class: rtems-wrap |
---|
[1a72a98] | 291 | |
---|
[53bb72e] | 292 | * - ``RTEMS_SUCCESSFUL`` |
---|
| 293 | - ISR established successfully |
---|
| 294 | * - ``RTEMS_INVALID_NUMBER`` |
---|
| 295 | - illegal vector number |
---|
| 296 | * - ``RTEMS_INVALID_ADDRESS`` |
---|
| 297 | - illegal ISR entry point or invalid ``old_isr_handler`` |
---|
[fd6dc8c8] | 298 | |
---|
[53bb72e] | 299 | DESCRIPTION: |
---|
| 300 | This directive establishes an interrupt service routine (ISR) for the |
---|
| 301 | specified interrupt vector number. The ``new_isr_handler`` parameter |
---|
| 302 | specifies the entry point of the ISR. The entry point of the previous ISR |
---|
| 303 | for the specified vector is returned in ``old_isr_handler``. |
---|
[fd6dc8c8] | 304 | |
---|
[53bb72e] | 305 | To release an interrupt vector, pass the old handler's address obtained |
---|
| 306 | when the vector was first capture. |
---|
[fd6dc8c8] | 307 | |
---|
[53bb72e] | 308 | NOTES: |
---|
| 309 | This directive will not cause the calling task to be preempted. |
---|
[fd6dc8c8] | 310 | |
---|
[53bb72e] | 311 | .. raw:: latex |
---|
[fd6dc8c8] | 312 | |
---|
[53bb72e] | 313 | \clearpage |
---|
[fd6dc8c8] | 314 | |
---|
[b8d3f6b] | 315 | .. _rtems_interrupt_disable: |
---|
[6c56401] | 316 | .. index:: disable interrupts |
---|
| 317 | .. index:: rtems_interrupt_disable |
---|
[b8d3f6b] | 318 | |
---|
[fd6dc8c8] | 319 | INTERRUPT_DISABLE - Disable Interrupts |
---|
| 320 | -------------------------------------- |
---|
| 321 | |
---|
[53bb72e] | 322 | CALLING SEQUENCE: |
---|
| 323 | .. code-block:: c |
---|
[fd6dc8c8] | 324 | |
---|
[53bb72e] | 325 | void rtems_interrupt_disable( |
---|
| 326 | rtems_interrupt_level level |
---|
| 327 | ); |
---|
[fd6dc8c8] | 328 | |
---|
[53bb72e] | 329 | DIRECTIVE STATUS CODES: |
---|
| 330 | NONE |
---|
[fd6dc8c8] | 331 | |
---|
[53bb72e] | 332 | DESCRIPTION: |
---|
| 333 | This directive disables all maskable interrupts and returns the previous |
---|
| 334 | ``level``. A later invocation of the ``rtems_interrupt_enable`` directive |
---|
| 335 | should be used to restore the interrupt level. |
---|
[fd6dc8c8] | 336 | |
---|
[4da4a15] | 337 | .. sidebar:: *Macro* |
---|
| 338 | |
---|
| 339 | This directive is implemented as a macro which modifies the ``level`` |
---|
| 340 | parameter. |
---|
| 341 | |
---|
[53bb72e] | 342 | NOTES: |
---|
| 343 | This directive will not cause the calling task to be preempted. |
---|
[fd6dc8c8] | 344 | |
---|
[53bb72e] | 345 | This directive is only available on uni-processor configurations. The |
---|
| 346 | directive ``rtems_interrupt_local_disable`` is available on all |
---|
| 347 | configurations. |
---|
[fd6dc8c8] | 348 | |
---|
[53bb72e] | 349 | .. raw:: latex |
---|
| 350 | |
---|
| 351 | \clearpage |
---|
[b8d3f6b] | 352 | |
---|
| 353 | .. _rtems_interrupt_enable: |
---|
[6c56401] | 354 | .. index:: enable interrupts |
---|
| 355 | .. index:: rtems_interrupt_enable |
---|
[fd6dc8c8] | 356 | |
---|
| 357 | INTERRUPT_ENABLE - Enable Interrupts |
---|
| 358 | ------------------------------------ |
---|
| 359 | |
---|
[53bb72e] | 360 | CALLING SEQUENCE: |
---|
| 361 | .. code-block:: c |
---|
[fd6dc8c8] | 362 | |
---|
[53bb72e] | 363 | void rtems_interrupt_enable( |
---|
| 364 | rtems_interrupt_level level |
---|
| 365 | ); |
---|
[fd6dc8c8] | 366 | |
---|
[53bb72e] | 367 | DIRECTIVE STATUS CODES: |
---|
| 368 | NONE |
---|
[fd6dc8c8] | 369 | |
---|
[53bb72e] | 370 | DESCRIPTION: |
---|
| 371 | This directive enables maskable interrupts to the ``level`` which was |
---|
| 372 | returned by a previous call to ``rtems_interrupt_disable``. Immediately |
---|
| 373 | prior to invoking this directive, maskable interrupts should be disabled by |
---|
| 374 | a call to ``rtems_interrupt_disable`` and will be enabled when this |
---|
| 375 | directive returns to the caller. |
---|
[fd6dc8c8] | 376 | |
---|
[53bb72e] | 377 | NOTES: |
---|
| 378 | This directive will not cause the calling task to be preempted. |
---|
[fd6dc8c8] | 379 | |
---|
[53bb72e] | 380 | This directive is only available on uni-processor configurations. The |
---|
| 381 | directive ``rtems_interrupt_local_enable`` is available on all |
---|
| 382 | configurations. |
---|
[fd6dc8c8] | 383 | |
---|
[53bb72e] | 384 | .. raw:: latex |
---|
[fd6dc8c8] | 385 | |
---|
[53bb72e] | 386 | \clearpage |
---|
[b8d3f6b] | 387 | |
---|
| 388 | .. _rtems_interrupt_flash: |
---|
[6c56401] | 389 | .. index:: flash interrupts |
---|
| 390 | .. index:: rtems_interrupt_flash |
---|
[fd6dc8c8] | 391 | |
---|
| 392 | INTERRUPT_FLASH - Flash Interrupts |
---|
| 393 | ---------------------------------- |
---|
| 394 | |
---|
[53bb72e] | 395 | CALLING SEQUENCE: |
---|
| 396 | .. code-block:: c |
---|
[fd6dc8c8] | 397 | |
---|
[53bb72e] | 398 | void rtems_interrupt_flash( |
---|
| 399 | rtems_interrupt_level level |
---|
| 400 | ); |
---|
[fd6dc8c8] | 401 | |
---|
[53bb72e] | 402 | DIRECTIVE STATUS CODES: |
---|
| 403 | NONE |
---|
[fd6dc8c8] | 404 | |
---|
[53bb72e] | 405 | DESCRIPTION: |
---|
| 406 | This directive temporarily enables maskable interrupts to the ``level`` |
---|
| 407 | which was returned by a previous call to ``rtems_interrupt_disable``. |
---|
| 408 | Immediately prior to invoking this directive, maskable interrupts should be |
---|
| 409 | disabled by a call to ``rtems_interrupt_disable`` and will be redisabled |
---|
| 410 | when this directive returns to the caller. |
---|
[fd6dc8c8] | 411 | |
---|
[53bb72e] | 412 | NOTES: |
---|
| 413 | This directive will not cause the calling task to be preempted. |
---|
[fd6dc8c8] | 414 | |
---|
[53bb72e] | 415 | This directive is only available on uni-processor configurations. The |
---|
| 416 | directives ``rtems_interrupt_local_disable`` and |
---|
| 417 | ``rtems_interrupt_local_enable`` is available on all configurations. |
---|
[fd6dc8c8] | 418 | |
---|
[53bb72e] | 419 | .. raw:: latex |
---|
[fd6dc8c8] | 420 | |
---|
[53bb72e] | 421 | \clearpage |
---|
[b8d3f6b] | 422 | |
---|
| 423 | .. _rtems_interrupt_local_disable: |
---|
[6c56401] | 424 | .. index:: disable interrupts |
---|
| 425 | .. index:: rtems_interrupt_local_disable |
---|
[fd6dc8c8] | 426 | |
---|
| 427 | INTERRUPT_LOCAL_DISABLE - Disable Interrupts on Current Processor |
---|
| 428 | ----------------------------------------------------------------- |
---|
| 429 | |
---|
[53bb72e] | 430 | CALLING SEQUENCE: |
---|
| 431 | .. code-block:: c |
---|
[fd6dc8c8] | 432 | |
---|
[53bb72e] | 433 | void rtems_interrupt_local_disable( |
---|
| 434 | rtems_interrupt_level level |
---|
| 435 | ); |
---|
[fd6dc8c8] | 436 | |
---|
[53bb72e] | 437 | DIRECTIVE STATUS CODES: |
---|
| 438 | NONE |
---|
[fd6dc8c8] | 439 | |
---|
[53bb72e] | 440 | DESCRIPTION: |
---|
| 441 | This directive disables all maskable interrupts and returns the previous |
---|
| 442 | ``level``. A later invocation of the ``rtems_interrupt_local_enable`` |
---|
| 443 | directive should be used to restore the interrupt level. |
---|
| 444 | |
---|
[4da4a15] | 445 | .. sidebar:: *Macro* |
---|
| 446 | |
---|
| 447 | This directive is implemented as a macro which modifies the ``level`` |
---|
| 448 | parameter. |
---|
| 449 | |
---|
[53bb72e] | 450 | NOTES: |
---|
| 451 | This directive will not cause the calling task to be preempted. |
---|
[fd6dc8c8] | 452 | |
---|
[a0d2eee] | 453 | In SMP configurations, this will not ensure system wide mutual exclusion. |
---|
[53bb72e] | 454 | Use interrupt locks instead. |
---|
[fd6dc8c8] | 455 | |
---|
[53bb72e] | 456 | .. raw:: latex |
---|
[fd6dc8c8] | 457 | |
---|
[53bb72e] | 458 | \clearpage |
---|
[fd6dc8c8] | 459 | |
---|
[b8d3f6b] | 460 | .. _rtems_interrupt_local_enable: |
---|
[6c56401] | 461 | .. index:: enable interrupts |
---|
| 462 | .. index:: rtems_interrupt_local_enable |
---|
[b8d3f6b] | 463 | |
---|
[fd6dc8c8] | 464 | INTERRUPT_LOCAL_ENABLE - Enable Interrupts on Current Processor |
---|
| 465 | --------------------------------------------------------------- |
---|
| 466 | |
---|
[53bb72e] | 467 | CALLING SEQUENCE: |
---|
| 468 | .. code-block:: c |
---|
[fd6dc8c8] | 469 | |
---|
[53bb72e] | 470 | void rtems_interrupt_local_enable( |
---|
| 471 | rtems_interrupt_level level |
---|
| 472 | ); |
---|
[fd6dc8c8] | 473 | |
---|
[53bb72e] | 474 | DIRECTIVE STATUS CODES: |
---|
| 475 | NONE |
---|
[fd6dc8c8] | 476 | |
---|
[53bb72e] | 477 | DESCRIPTION: |
---|
| 478 | This directive enables maskable interrupts to the ``level`` which was |
---|
| 479 | returned by a previous call to ``rtems_interrupt_local_disable``. |
---|
| 480 | Immediately prior to invoking this directive, maskable interrupts should be |
---|
| 481 | disabled by a call to ``rtems_interrupt_local_disable`` and will be enabled |
---|
| 482 | when this directive returns to the caller. |
---|
[fd6dc8c8] | 483 | |
---|
[53bb72e] | 484 | NOTES: |
---|
| 485 | This directive will not cause the calling task to be preempted. |
---|
[fd6dc8c8] | 486 | |
---|
[53bb72e] | 487 | .. raw:: latex |
---|
[fd6dc8c8] | 488 | |
---|
[53bb72e] | 489 | \clearpage |
---|
[fd6dc8c8] | 490 | |
---|
[b8d3f6b] | 491 | .. _rtems_interrupt_lock_initialize: |
---|
[6c56401] | 492 | .. index:: rtems_interrupt_lock_initialize |
---|
[b8d3f6b] | 493 | |
---|
[fd6dc8c8] | 494 | INTERRUPT_LOCK_INITIALIZE - Initialize an ISR Lock |
---|
| 495 | -------------------------------------------------- |
---|
| 496 | |
---|
[53bb72e] | 497 | CALLING SEQUENCE: |
---|
| 498 | .. code-block:: c |
---|
[fd6dc8c8] | 499 | |
---|
[53bb72e] | 500 | void rtems_interrupt_lock_initialize( |
---|
[f776fe6] | 501 | rtems_interrupt_lock *lock, |
---|
| 502 | const char *name |
---|
[53bb72e] | 503 | ); |
---|
[fd6dc8c8] | 504 | |
---|
[53bb72e] | 505 | DIRECTIVE STATUS CODES: |
---|
| 506 | NONE |
---|
[fd6dc8c8] | 507 | |
---|
[53bb72e] | 508 | DESCRIPTION: |
---|
[f776fe6] | 509 | Initializes an interrupt lock. The name must be persistent throughout the |
---|
| 510 | lifetime of the lock. |
---|
[fd6dc8c8] | 511 | |
---|
[53bb72e] | 512 | NOTES: |
---|
| 513 | Concurrent initialization leads to unpredictable results. |
---|
[fd6dc8c8] | 514 | |
---|
[53bb72e] | 515 | .. raw:: latex |
---|
[fd6dc8c8] | 516 | |
---|
[53bb72e] | 517 | \clearpage |
---|
[fd6dc8c8] | 518 | |
---|
[b8d3f6b] | 519 | .. _rtems_interrupt_lock_acquire: |
---|
[6c56401] | 520 | .. index:: rtems_interrupt_lock_acquire |
---|
[b8d3f6b] | 521 | |
---|
[fd6dc8c8] | 522 | INTERRUPT_LOCK_ACQUIRE - Acquire an ISR Lock |
---|
| 523 | -------------------------------------------- |
---|
| 524 | |
---|
[53bb72e] | 525 | CALLING SEQUENCE: |
---|
| 526 | .. code-block:: c |
---|
[fd6dc8c8] | 527 | |
---|
[53bb72e] | 528 | void rtems_interrupt_lock_acquire( |
---|
[f776fe6] | 529 | rtems_interrupt_lock *lock, |
---|
| 530 | rtems_interrupt_lock_context *lock_context |
---|
[53bb72e] | 531 | ); |
---|
[fd6dc8c8] | 532 | |
---|
[53bb72e] | 533 | DIRECTIVE STATUS CODES: |
---|
| 534 | NONE |
---|
[fd6dc8c8] | 535 | |
---|
[53bb72e] | 536 | DESCRIPTION: |
---|
[a0d2eee] | 537 | Interrupts will be disabled. In SMP configurations, this directive |
---|
| 538 | acquires an SMP lock. |
---|
[fd6dc8c8] | 539 | |
---|
[53bb72e] | 540 | NOTES: |
---|
[f776fe6] | 541 | A separate lock context must be provided for each acquire/release pair, for |
---|
| 542 | example an automatic variable. |
---|
| 543 | |
---|
| 544 | An attempt to recursively acquire the lock may result in an infinite loop |
---|
| 545 | with interrupts disabled. |
---|
| 546 | |
---|
[53bb72e] | 547 | This directive will not cause the calling thread to be preempted. This |
---|
| 548 | directive can be used in thread and interrupt context. |
---|
[fd6dc8c8] | 549 | |
---|
[53bb72e] | 550 | .. raw:: latex |
---|
[fd6dc8c8] | 551 | |
---|
[53bb72e] | 552 | \clearpage |
---|
[fd6dc8c8] | 553 | |
---|
[b8d3f6b] | 554 | .. _rtems_interrupt_lock_release: |
---|
[6c56401] | 555 | .. index:: rtems_interrupt_lock_release |
---|
[b8d3f6b] | 556 | |
---|
[fd6dc8c8] | 557 | INTERRUPT_LOCK_RELEASE - Release an ISR Lock |
---|
| 558 | -------------------------------------------- |
---|
| 559 | |
---|
[53bb72e] | 560 | CALLING SEQUENCE: |
---|
| 561 | .. code-block:: c |
---|
[fd6dc8c8] | 562 | |
---|
[53bb72e] | 563 | void rtems_interrupt_lock_release( |
---|
[f776fe6] | 564 | rtems_interrupt_lock *lock, |
---|
| 565 | rtems_interrupt_lock_context *lock_context |
---|
[53bb72e] | 566 | ); |
---|
[fd6dc8c8] | 567 | |
---|
[53bb72e] | 568 | DIRECTIVE STATUS CODES: |
---|
| 569 | NONE |
---|
[fd6dc8c8] | 570 | |
---|
[53bb72e] | 571 | DESCRIPTION: |
---|
[a0d2eee] | 572 | The interrupt status will be restored. In SMP configurations, this |
---|
| 573 | directive releases an SMP lock. |
---|
[fd6dc8c8] | 574 | |
---|
[53bb72e] | 575 | NOTES: |
---|
[f776fe6] | 576 | The lock context must be the one used to acquire the lock, otherwise the |
---|
| 577 | result is unpredictable. |
---|
| 578 | |
---|
[53bb72e] | 579 | This directive will not cause the calling thread to be preempted. This |
---|
| 580 | directive can be used in thread and interrupt context. |
---|
[fd6dc8c8] | 581 | |
---|
[53bb72e] | 582 | .. raw:: latex |
---|
[fd6dc8c8] | 583 | |
---|
[53bb72e] | 584 | \clearpage |
---|
[fd6dc8c8] | 585 | |
---|
[b8d3f6b] | 586 | .. _rtems_interrupt_lock_acquire_isr: |
---|
[6c56401] | 587 | .. index:: rtems_interrupt_lock_acquire_isr |
---|
[b8d3f6b] | 588 | |
---|
[fd6dc8c8] | 589 | INTERRUPT_LOCK_ACQUIRE_ISR - Acquire an ISR Lock from ISR |
---|
| 590 | --------------------------------------------------------- |
---|
| 591 | |
---|
[53bb72e] | 592 | CALLING SEQUENCE: |
---|
| 593 | .. code-block:: c |
---|
[fd6dc8c8] | 594 | |
---|
[53bb72e] | 595 | void rtems_interrupt_lock_acquire_isr( |
---|
[f776fe6] | 596 | rtems_interrupt_lock *lock, |
---|
| 597 | rtems_interrupt_lock_context *lock_context |
---|
[53bb72e] | 598 | ); |
---|
[fd6dc8c8] | 599 | |
---|
[53bb72e] | 600 | DIRECTIVE STATUS CODES: |
---|
| 601 | NONE |
---|
[fd6dc8c8] | 602 | |
---|
[53bb72e] | 603 | DESCRIPTION: |
---|
[a0d2eee] | 604 | The interrupt status will remain unchanged. In SMP configurations, this |
---|
| 605 | directive acquires an SMP lock. |
---|
[fd6dc8c8] | 606 | |
---|
[f776fe6] | 607 | NOTES: |
---|
| 608 | A separate lock context must be provided for each acquire/release pair, for |
---|
| 609 | example an automatic variable. |
---|
| 610 | |
---|
| 611 | An attempt to recursively acquire the lock may result in an infinite loop. |
---|
| 612 | |
---|
| 613 | This directive is intended for device drivers and should be called from the |
---|
| 614 | corresponding interrupt service routine. |
---|
| 615 | |
---|
[53bb72e] | 616 | In case the corresponding interrupt service routine can be interrupted by |
---|
| 617 | higher priority interrupts and these interrupts enter the critical section |
---|
| 618 | protected by this lock, then the result is unpredictable. |
---|
[fd6dc8c8] | 619 | |
---|
[53bb72e] | 620 | .. raw:: latex |
---|
[fd6dc8c8] | 621 | |
---|
[53bb72e] | 622 | \clearpage |
---|
[fd6dc8c8] | 623 | |
---|
[b8d3f6b] | 624 | .. _rtems_interrupt_lock_release_isr: |
---|
[6c56401] | 625 | .. index:: rtems_interrupt_lock_release_isr |
---|
[b8d3f6b] | 626 | |
---|
[fd6dc8c8] | 627 | INTERRUPT_LOCK_RELEASE_ISR - Release an ISR Lock from ISR |
---|
| 628 | --------------------------------------------------------- |
---|
| 629 | |
---|
[53bb72e] | 630 | CALLING SEQUENCE: |
---|
| 631 | .. code-block:: c |
---|
[fd6dc8c8] | 632 | |
---|
[53bb72e] | 633 | void rtems_interrupt_lock_release_isr( |
---|
[f776fe6] | 634 | rtems_interrupt_lock *lock, |
---|
| 635 | rtems_interrupt_lock_context *lock_context |
---|
[53bb72e] | 636 | ); |
---|
[fd6dc8c8] | 637 | |
---|
[53bb72e] | 638 | DIRECTIVE STATUS CODES: |
---|
| 639 | NONE |
---|
[fd6dc8c8] | 640 | |
---|
[53bb72e] | 641 | DESCRIPTION: |
---|
[a0d2eee] | 642 | The interrupt status will remain unchanged. In SMP configurations, this |
---|
| 643 | directive releases an SMP lock. |
---|
[fd6dc8c8] | 644 | |
---|
[53bb72e] | 645 | NOTES: |
---|
[f776fe6] | 646 | The lock context must be the one used to acquire the lock, otherwise the |
---|
| 647 | result is unpredictable. |
---|
| 648 | |
---|
| 649 | This directive is intended for device drivers and should be called from the |
---|
| 650 | corresponding interrupt service routine. |
---|
[fd6dc8c8] | 651 | |
---|
[53bb72e] | 652 | .. raw:: latex |
---|
[fd6dc8c8] | 653 | |
---|
[53bb72e] | 654 | \clearpage |
---|
[fd6dc8c8] | 655 | |
---|
[b8d3f6b] | 656 | .. _rtems_interrupt_is_in_progress: |
---|
[6c56401] | 657 | .. index:: is interrupt in progress |
---|
| 658 | .. index:: rtems_interrupt_is_in_progress |
---|
[b8d3f6b] | 659 | |
---|
[fd6dc8c8] | 660 | INTERRUPT_IS_IN_PROGRESS - Is an ISR in Progress |
---|
| 661 | ------------------------------------------------ |
---|
| 662 | |
---|
[53bb72e] | 663 | CALLING SEQUENCE: |
---|
| 664 | .. code-block:: c |
---|
[fd6dc8c8] | 665 | |
---|
[53bb72e] | 666 | bool rtems_interrupt_is_in_progress(void); |
---|
[fd6dc8c8] | 667 | |
---|
[53bb72e] | 668 | DIRECTIVE STATUS CODES: |
---|
| 669 | NONE |
---|
[fd6dc8c8] | 670 | |
---|
[53bb72e] | 671 | DESCRIPTION: |
---|
| 672 | This directive returns ``TRUE`` if the processor is currently servicing an |
---|
| 673 | interrupt and ``FALSE`` otherwise. A return value of ``TRUE`` indicates |
---|
| 674 | that the caller is an interrupt service routine, *NOT* a task. The |
---|
| 675 | directives available to an interrupt service routine are restricted. |
---|
[fd6dc8c8] | 676 | |
---|
[53bb72e] | 677 | NOTES: |
---|
| 678 | This directive will not cause the calling task to be preempted. |
---|