diff options
| -rw-r--r-- | c-user/glossary.rst | 5 | ||||
| -rw-r--r-- | c-user/interrupt/directives.rst | 1250 | ||||
| -rw-r--r-- | c-user/interrupt/introduction.rst | 101 |
3 files changed, 1012 insertions, 344 deletions
diff --git a/c-user/glossary.rst b/c-user/glossary.rst index 33d3097..b3527a7 100644 --- a/c-user/glossary.rst +++ b/c-user/glossary.rst @@ -928,6 +928,11 @@ Glossary target The system on which the application will ultimately execute. + target architecture + The target architecture is the instruction set architecture (ISA) of the + :term:`target`. Some RTEMS features depend on the target architecture. For + the details consult the *RTEMS CPU Architecture Supplement*. + TAS This term is an acronym for Test-And-Set. diff --git a/c-user/interrupt/directives.rst b/c-user/interrupt/directives.rst index 95181db..2b15fd6 100644 --- a/c-user/interrupt/directives.rst +++ b/c-user/interrupt/directives.rst @@ -1,521 +1,1111 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 +.. Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de) .. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) +.. This file is part of the RTEMS quality process and was automatically +.. generated. If you find something that needs to be fixed or +.. worded better please post a report or patch to an RTEMS mailing list +.. or raise a bug report: +.. +.. https://www.rtems.org/bugs.html +.. +.. For information on updating and regenerating please refer to the How-To +.. section in the Software Requirements Engineering chapter of the +.. RTEMS Software Engineering manual. The manual is provided as a part of +.. a release. For development sources please refer to the online +.. documentation at: +.. +.. https://docs.rtems.org + +.. _InterruptManagerDirectives: + Directives ========== -This section details the interrupt manager's directives. A subsection is -dedicated to each of this manager's directives and describes the calling -sequence, related constants, usage, and status codes. +This section details the directives of the Interrupt Manager. A subsection is +dedicated to each of this manager's directives and lists the calling sequence, +parameters, description, return values, and notes of the directive. + +.. Generated from spec:/rtems/intr/if/catch .. raw:: latex - \clearpage + \clearpage +.. index:: rtems_interrupt_catch() .. index:: establish an ISR .. index:: install an ISR -.. index:: rtems_interrupt_catch -.. _rtems_interrupt_catch: +.. _InterfaceRtemsInterruptCatch: -INTERRUPT_CATCH - Establish an ISR ----------------------------------- +rtems_interrupt_catch() +----------------------- + +Establishes an interrupt service routine. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + rtems_status_code rtems_interrupt_catch( + rtems_isr_entry new_isr_handler, + rtems_vector_number vector, + rtems_isr_entry *old_isr_handler + ); + +.. rubric:: PARAMETERS: + +``new_isr_handler`` + This parameter is the new interrupt service routine. + +``vector`` + This parameter is the interrupt vector number. + +``old_isr_handler`` + This parameter is the pointer to an :c:type:`rtems_isr_entry` variable. + When the directive call is successful, the previous interrupt service + routine established for this interrupt vector will be stored in this + variable. + +.. rubric:: DESCRIPTION: + +This directive establishes an interrupt service routine (ISR) for the interrupt +specified by the ``vector`` number. The ``new_isr_handler`` parameter +specifies the entry point of the ISR. The entry point of the previous ISR for +the specified vector is returned in ``old_isr_handler``. + +To release an interrupt vector, pass the old handler's address obtained when +the vector was first capture. + +.. rubric:: RETURN VALUES: + +:c:macro:`RTEMS_SUCCESSFUL` + The requested operation was successful. + +:c:macro:`RTEMS_INVALID_NUMBER` + The interrupt vector number was illegal. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``new_isr_handler`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. + +:c:macro:`RTEMS_INVALID_ADDRESS` + The ``old_isr_handler`` parameter was `NULL + <https://en.cppreference.com/w/c/types/NULL>`_. -CALLING SEQUENCE: - .. code-block:: c +.. rubric:: CONSTRAINTS: - rtems_status_code rtems_interrupt_catch( - rtems_isr_entry new_isr_handler, - rtems_vector_number vector, - rtems_isr_entry *old_isr_handler - ); +The following constraints apply to this directive: -DIRECTIVE STATUS CODES: - .. list-table:: - :class: rtems-wrap +* The directive may be called from within interrupt context. - * - ``RTEMS_SUCCESSFUL`` - - ISR established successfully - * - ``RTEMS_INVALID_NUMBER`` - - illegal vector number - * - ``RTEMS_INVALID_ADDRESS`` - - illegal ISR entry point or invalid ``old_isr_handler`` +* The directive may be called from within device driver initialization context. -DESCRIPTION: - This directive establishes an interrupt service routine (ISR) for the - specified interrupt vector number. The ``new_isr_handler`` parameter - specifies the entry point of the ISR. The entry point of the previous ISR - for the specified vector is returned in ``old_isr_handler``. +* The directive may be called from within task context. - To release an interrupt vector, pass the old handler's address obtained - when the vector was first capture. +* The directive will not cause the calling task to be preempted. -NOTES: - This directive will not cause the calling task to be preempted. +* The directive is only available where the :term:`target architecture` support + enabled simple vectored interrupts. + +.. Generated from spec:/rtems/intr/if/disable .. raw:: latex - \clearpage + \clearpage +.. index:: rtems_interrupt_disable() .. index:: disable interrupts -.. index:: rtems_interrupt_disable -.. _rtems_interrupt_disable: +.. _InterfaceRtemsInterruptDisable: + +rtems_interrupt_disable() +------------------------- + +Disables the maskable interrupts on the current processor. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + #define rtems_interrupt_disable( isr_cookie ) + +.. rubric:: PARAMETERS: + +``isr_cookie`` + This parameter is a variable of type :c:type:`rtems_interrupt_level` which + will be used to save the previous interrupt level. + +.. rubric:: DESCRIPTION: -INTERRUPT_DISABLE - Disable Interrupts --------------------------------------- +This directive disables all maskable interrupts on the current processor and +returns the previous interrupt level in ``isr_cookie``. -CALLING SEQUENCE: - .. code-block:: c +.. rubric:: NOTES: - void rtems_interrupt_disable( - rtems_interrupt_level level - ); +A later invocation of the :ref:`InterfaceRtemsInterruptEnable` directive should +be used to restore the previous interrupt level. -DIRECTIVE STATUS CODES: - NONE +This directive is implemented as a macro which sets the ``isr_cookie`` +parameter. -DESCRIPTION: - This directive disables all maskable interrupts and returns the previous - interrupt level in ``level``. +.. code-block:: c + :linenos: -NOTES: - A later invocation of the ``rtems_interrupt_enable`` directive should be - used to restore the interrupt level. + #include <rtems.h> - This directive is implemented as a macro which sets the ``level`` - parameter. + void local_critical_section( void ) + { + rtems_interrupt_level level; - This directive will not cause the calling task to be preempted. + // Please note that the rtems_interrupt_disable() is a macro. The + // previous interrupt level (before the maskable interrupts are + // disabled) is returned here in the level macro parameter. This + // would be wrong: + // + // rtems_interrupt_disable( &level ); + rtems_interrupt_disable( level ); - This directive is only available in uniprocessor configurations. The - directive ``rtems_interrupt_local_disable`` is available in all - configurations. + // Here is the critical section: maskable interrupts are disabled - .. code-block:: c + { + rtems_interrupt_level nested_level; - void critical_section( void ) - { - rtems_interrupt_level level; + rtems_interrupt_disable( nested_level ); - /* - * Please note that the rtems_interrupt_disable() is a macro. The - * previous interrupt level (before the maskable interrupts are - * disabled) is returned here in the level macro parameter. This - * would be wrong: - * - * rtems_interrupt_disable( &level ); - */ - rtems_interrupt_disable( level ); + // Here is a nested critical section - /* Critical section, maskable interrupts are disabled */ + rtems_interrupt_enable( nested_level ); + } - { - rtems_interrupt_level level2; + // Maskable interrupts are still disabled - rtems_interrupt_disable( level2 ); + rtems_interrupt_enable( level ); + } - /* Nested critical section */ +.. rubric:: CONSTRAINTS: - rtems_interrupt_enable( level2 ); - } +The following constraints apply to this directive: - /* Maskable interrupts are still disabled */ +* The directive may be called from within any runtime context. - rtems_interrupt_enable( level ); - } +* The directive will not cause the calling task to be preempted. + +* Where the system was built with SMP support enabled, the directive is not + available. Its use will result in compiler warnings and linker errors. The + :ref:`InterfaceRtemsInterruptLocalDisable` and + :ref:`InterfaceRtemsInterruptLocalEnable` directives are available in all + build configurations. + +.. Generated from spec:/rtems/intr/if/enable .. raw:: latex - \clearpage + \clearpage +.. index:: rtems_interrupt_enable() .. index:: enable interrupts .. index:: restore interrupt level -.. index:: rtems_interrupt_enable -.. _rtems_interrupt_enable: +.. _InterfaceRtemsInterruptEnable: + +rtems_interrupt_enable() +------------------------ + +Restores the previous interrupt level on the current processor. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + #define rtems_interrupt_enable( isr_cookie ) + +.. rubric:: PARAMETERS: + +``isr_cookie`` + This parameter is the previous interrupt level to restore. The value must + be obtained by a previous call to :ref:`InterfaceRtemsInterruptDisable` or + :ref:`InterfaceRtemsInterruptFlash`. -INTERRUPT_ENABLE - Restore Interrupt Level ------------------------------------------- +.. rubric:: DESCRIPTION: -CALLING SEQUENCE: - .. code-block:: c +This directive restores the interrupt level specified by ``isr_cookie`` on the +current processor. - void rtems_interrupt_enable( - rtems_interrupt_level level - ); +.. rubric:: NOTES: -DIRECTIVE STATUS CODES: - NONE +The ``isr_cookie`` parameter value must be obtained by a previous call to +:ref:`InterfaceRtemsInterruptDisable` or :ref:`InterfaceRtemsInterruptFlash`. +Using an otherwise obtained value is undefined behaviour. -DESCRIPTION: - This directive restores the interrupt level specified by ``level``. +This directive is unsuitable to enable particular interrupt sources, for +example in an interrupt controller. -NOTES: - The ``level`` parameter value must be obtained by a previous call to - ``rtems_interrupt_disable`` or ``rtems_interrupt_flash``. Using an - otherwise obtained value is undefined behaviour. +.. rubric:: CONSTRAINTS: - This directive is unsuitable to enable particular interrupt sources, for - example in an interrupt controller. +The following constraints apply to this directive: - This directive will not cause the calling task to be preempted. +* The directive may be called from within any runtime context. - This directive is only available in uniprocessor configurations. The - directive ``rtems_interrupt_local_enable`` is available in all - configurations. +* The directive will not cause the calling task to be preempted. + +* While at least one maskable interrupt is pending, when the directive enables + maskable interrupts, the pending interrupts are immediately serviced. The + interrupt service routines may unblock higher priority tasks which may + preempt the calling task. + +* Where the system was built with SMP support enabled, the directive is not + available. Its use will result in compiler warnings and linker errors. The + :ref:`InterfaceRtemsInterruptLocalDisable` and + :ref:`InterfaceRtemsInterruptLocalEnable` directives are available in all + build configurations. + +.. Generated from spec:/rtems/intr/if/flash .. raw:: latex - \clearpage + \clearpage +.. index:: rtems_interrupt_flash() .. index:: flash interrupts -.. index:: rtems_interrupt_flash -.. _rtems_interrupt_flash: +.. _InterfaceRtemsInterruptFlash: -INTERRUPT_FLASH - Flash Interrupts ----------------------------------- +rtems_interrupt_flash() +----------------------- + +Flashes interrupts on the current processor. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + #define rtems_interrupt_flash( isr_cookie ) + +.. rubric:: PARAMETERS: -CALLING SEQUENCE: - .. code-block:: c +``isr_cookie`` + This parameter is the previous interrupt level. - void rtems_interrupt_flash( - rtems_interrupt_level level - ); +.. rubric:: DESCRIPTION: -DIRECTIVE STATUS CODES: - NONE +This directive is functionally equivalent to a calling +:ref:`InterfaceRtemsInterruptEnable` immediately followed by a +:ref:`InterfaceRtemsInterruptDisable`. On some architectures it is possible to +provide an optimized implementation for this sequence. -DESCRIPTION: - This directive is functionally equivalent to a - ``rtems_interrupt_enable( level )`` immediately followed by a - ``rtems_interrupt_disable( level )``. On some - architectures it is possible to provide an optimized implementation for - this sequence. +.. rubric:: NOTES: -NOTES: - The ``level`` parameter value must be obtained by a previous call to - ``rtems_interrupt_disable`` or ``rtems_interrupt_flash``. Using an - otherwise obtained value is undefined behaviour. +The ``isr_cookie`` parameter value must be obtained by a previous call to +:ref:`InterfaceRtemsInterruptDisable` or :ref:`InterfaceRtemsInterruptFlash`. +Using an otherwise obtained value is undefined behaviour. - This directive will not cause the calling task to be preempted. +Historically, the interrupt flash directive was heavily used in the operating +system implementation. However, this is no longer the case. The interrupt +flash directive is provided for backward compatibility reasons. - This directive is only available in uniprocessor configurations. The - directives ``rtems_interrupt_local_disable`` and - ``rtems_interrupt_local_enable`` are available in all configurations. +.. rubric:: CONSTRAINTS: - Historically, the interrupt flash directive was heavily used in the - operating system implementation. However, this is no longer the case. The - interrupt flash directive is provided for backward compatibility reasons. +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +* Where the system was built with SMP support enabled, the directive is not + available. Its use will result in compiler warnings and linker errors. The + :ref:`InterfaceRtemsInterruptLocalDisable` and + :ref:`InterfaceRtemsInterruptLocalEnable` directives are available in all + build configurations. + +.. Generated from spec:/rtems/intr/if/local-disable .. raw:: latex - \clearpage + \clearpage +.. index:: rtems_interrupt_local_disable() .. index:: disable interrupts -.. index:: rtems_interrupt_local_disable -.. _rtems_interrupt_local_disable: +.. _InterfaceRtemsInterruptLocalDisable: + +rtems_interrupt_local_disable() +------------------------------- + +Disables the maskable interrupts on the current processor. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + #define rtems_interrupt_local_disable( isr_cookie ) -INTERRUPT_LOCAL_DISABLE - Disable Interrupts on Current Processor ------------------------------------------------------------------ +.. rubric:: PARAMETERS: -CALLING SEQUENCE: - .. code-block:: c +``isr_cookie`` + This parameter is a variable of type :c:type:`rtems_interrupt_level` which + will be used to save the previous interrupt level. - void rtems_interrupt_local_disable( - rtems_interrupt_level level - ); +.. rubric:: DESCRIPTION: -DIRECTIVE STATUS CODES: - NONE +This directive disables all maskable interrupts on the current processor and +returns the previous interrupt level in ``isr_cookie``. -DESCRIPTION: - This directive disables all maskable interrupts on the current processor - and returns the previous interrupt level in ``level``. +.. rubric:: NOTES: -NOTES: - A later invocation of the ``rtems_interrupt_local_enable`` directive should - be used to restore the interrupt level. +A later invocation of the :ref:`InterfaceRtemsInterruptLocalEnable` directive +should be used to restore the previous interrupt level. - This directive is implemented as a macro which sets the ``level`` - parameter. +This directive is implemented as a macro which sets the ``isr_cookie`` +parameter. - This directive will not cause the calling task to be preempted. +Where the system was built with SMP support enabled, this will not ensure +system wide mutual exclusion. Use interrupt locks instead, see +:ref:`InterfaceRtemsInterruptLockAcquire`. Interrupt disabled critical +sections may be used to access processor-specific data structures or disable +thread dispatching. - In SMP configurations, this will not ensure system wide mutual exclusion. - Use interrupt locks instead. +.. code-block:: c + :linenos: - .. code-block:: c + #include <rtems.h> - void local_critical_section( void ) - { - rtems_interrupt_level level; + void local_critical_section( void ) + { + rtems_interrupt_level level; - /* - * Please note that the rtems_interrupt_local_disable() is a macro. - * The previous interrupt level (before the maskable interrupts are - * disabled) is returned here in the level macro parameter. This - * would be wrong: - * - * rtems_interrupt_local_disable( &level ); - */ - rtems_interrupt_local_disable( level ); + // Please note that the rtems_interrupt_local_disable() is a macro. + // The previous interrupt level (before the maskable interrupts are + // disabled) is returned here in the level macro parameter. This would + // be wrong: + // + // rtems_interrupt_local_disable( &level ); + rtems_interrupt_local_disable( level ); - /* - * Local critical section, maskable interrupts on the current - * processor are disabled. - */ + // Here is the critical section: maskable interrupts are disabled - { - rtems_interrupt_level level2; + { + rtems_interrupt_level nested_level; - rtems_interrupt_local_disable( level2 ); + rtems_interrupt_local_disable( nested_level ); - /* Nested local critical section */ + // Here is a nested critical section - rtems_interrupt_local_enable( level2 ); - } + rtems_interrupt_local_enable( nested_level ); + } - /* Maskable interrupts are still disabled */ + // Maskable interrupts are still disabled - rtems_interrupt_local_enable( level ); - } + rtems_interrupt_local_enable( level ); + } + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/intr/if/local-enable .. raw:: latex - \clearpage + \clearpage +.. index:: rtems_interrupt_local_enable() .. index:: enable interrupts .. index:: restore interrupt level -.. index:: rtems_interrupt_local_enable -.. _rtems_interrupt_local_enable: +.. _InterfaceRtemsInterruptLocalEnable: + +rtems_interrupt_local_enable() +------------------------------ + +Restores the previous interrupt level on the current processor. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c -INTERRUPT_LOCAL_ENABLE - Restore Interrupt Level on Current Processor ---------------------------------------------------------------------- + #define rtems_interrupt_local_enable( isr_cookie ) -CALLING SEQUENCE: - .. code-block:: c +.. rubric:: PARAMETERS: - void rtems_interrupt_local_enable( - rtems_interrupt_level level - ); +``isr_cookie`` + This parameter is the previous interrupt level to restore. The value must + be obtained by a previous call to + :ref:`InterfaceRtemsInterruptLocalDisable`. -DIRECTIVE STATUS CODES: - NONE +.. rubric:: DESCRIPTION: -DESCRIPTION: - This directive restores the interrupt level specified by ``level`` on the - current processor. +This directive restores the interrupt level specified by ``isr_cookie`` on the +current processor. -NOTES: - The ``level`` parameter value must be obtained by a previous call to - ``rtems_interrupt_local_disable``. Using an otherwise obtained value is - undefined behaviour. +.. rubric:: NOTES: - This directive is unsuitable to enable particular interrupt sources, for - example in an interrupt controller. +The ``isr_cookie`` parameter value must be obtained by a previous call to +:ref:`InterfaceRtemsInterruptLocalDisable`. Using an otherwise obtained value +is undefined behaviour. - This directive will not cause the calling task to be preempted. +This directive is unsuitable to enable particular interrupt sources, for +example in an interrupt controller. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +* While at least one maskable interrupt is pending, when the directive enables + maskable interrupts, the pending interrupts are immediately serviced. The + interrupt service routines may unblock higher priority tasks which may + preempt the calling task. + +.. Generated from spec:/rtems/intr/if/is-in-progress .. raw:: latex - \clearpage + \clearpage + +.. index:: rtems_interrupt_is_in_progress() +.. index:: is interrupt in progress + +.. _InterfaceRtemsInterruptIsInProgress: -.. index:: rtems_interrupt_lock_initialize +rtems_interrupt_is_in_progress() +-------------------------------- -.. _rtems_interrupt_lock_initialize: +Checks if an ISR is in progress on the current processor. -INTERRUPT_LOCK_INITIALIZE - Initialize an ISR Lock --------------------------------------------------- +.. rubric:: CALLING SEQUENCE: -CALLING SEQUENCE: - .. code-block:: c +.. code-block:: c - void rtems_interrupt_lock_initialize( - rtems_interrupt_lock *lock, - const char *name - ); + #define rtems_interrupt_is_in_progress() -DIRECTIVE STATUS CODES: - NONE +.. rubric:: DESCRIPTION: -DESCRIPTION: - Initializes an interrupt lock. The name must be persistent throughout the - lifetime of the lock. +This directive returns ``true``, if the current processor is currently +servicing an interrupt, and ``false`` otherwise. A return value of ``true`` +indicates that the caller is an interrupt service routine, **not** a task. The +directives available to an interrupt service routine are restricted. -NOTES: - Concurrent initialization leads to unpredictable results. +.. rubric:: RETURN VALUES: + +Returns true, if the current processor is currently servicing an interrupt, +otherwise false. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/intr/if/cause .. raw:: latex - \clearpage + \clearpage + +.. index:: rtems_interrupt_cause() + +.. _InterfaceRtemsInterruptCause: + +rtems_interrupt_cause() +----------------------- -.. index:: rtems_interrupt_lock_acquire +Causes the interrupt. -.. _rtems_interrupt_lock_acquire: +.. rubric:: CALLING SEQUENCE: -INTERRUPT_LOCK_ACQUIRE - Acquire an ISR Lock --------------------------------------------- +.. code-block:: c -CALLING SEQUENCE: - .. code-block:: c + #define rtems_interrupt_cause( vector ) - void rtems_interrupt_lock_acquire( - rtems_interrupt_lock *lock, - rtems_interrupt_lock_context *lock_context - ); +.. rubric:: PARAMETERS: -DIRECTIVE STATUS CODES: - NONE +``vector`` + This parameter is the vector number of the interrupt to cause. -DESCRIPTION: - Maskable interrupts will be disabled. In SMP configurations, this - directive acquires an SMP lock. +.. rubric:: CONSTRAINTS: -NOTES: - A separate lock context must be provided for each acquire/release pair, for - example an automatic variable. +The following constraints apply to this directive: - An attempt to recursively acquire the lock may result in an infinite loop - with maskable interrupts disabled. +* The directive is not implemented. - This directive will not cause the calling thread to be preempted. This - directive can be used in thread and interrupt context. +.. Generated from spec:/rtems/intr/if/clear .. raw:: latex - \clearpage + \clearpage -.. index:: rtems_interrupt_lock_release +.. index:: rtems_interrupt_clear() -.. _rtems_interrupt_lock_release: +.. _InterfaceRtemsInterruptClear: -INTERRUPT_LOCK_RELEASE - Release an ISR Lock --------------------------------------------- +rtems_interrupt_clear() +----------------------- -CALLING SEQUENCE: - .. code-block:: c +Clears the interrupt. - void rtems_interrupt_lock_release( - rtems_interrupt_lock *lock, - rtems_interrupt_lock_context *lock_context - ); +.. rubric:: CALLING SEQUENCE: -DIRECTIVE STATUS CODES: - NONE +.. code-block:: c -DESCRIPTION: - The interrupt level will be restored. In SMP configurations, this - directive releases an SMP lock. + #define rtems_interrupt_clear( vector ) -NOTES: - The lock context must be the one used to acquire the lock, otherwise the - result is unpredictable. +.. rubric:: PARAMETERS: - This directive will not cause the calling thread to be preempted. This - directive can be used in thread and interrupt context. +``vector`` + This parameter is the vector number of the interrupt to clear. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive is not implemented. + +.. Generated from spec:/rtems/intr/if/lock-initialize .. raw:: latex - \clearpage + \clearpage + +.. index:: rtems_interrupt_lock_initialize() -.. index:: rtems_interrupt_lock_acquire_isr +.. _InterfaceRtemsInterruptLockInitialize: -.. _rtems_interrupt_lock_acquire_isr: +rtems_interrupt_lock_initialize() +--------------------------------- -INTERRUPT_LOCK_ACQUIRE_ISR - Acquire an ISR Lock from ISR ---------------------------------------------------------- +Initializes the ISR lock. -CALLING SEQUENCE: - .. code-block:: c +.. rubric:: CALLING SEQUENCE: - void rtems_interrupt_lock_acquire_isr( - rtems_interrupt_lock *lock, - rtems_interrupt_lock_context *lock_context - ); +.. code-block:: c -DIRECTIVE STATUS CODES: - NONE + #define rtems_interrupt_lock_initialize( lock, name ) -DESCRIPTION: - The interrupt level will remain unchanged. In SMP configurations, this - directive acquires an SMP lock. +.. rubric:: PARAMETERS: -NOTES: - A separate lock context must be provided for each acquire/release pair, for - example an automatic variable. +``lock`` + This parameter is the ISR lock to initialize. - An attempt to recursively acquire the lock may result in an infinite loop. +``name`` + This parameter is the ISR lock name. It shall be a string. The name is + only used where the system was built with profiling support enabled. - This directive is intended for device drivers and should be called from the - corresponding interrupt service routine. +.. rubric:: NOTES: - In case the corresponding interrupt service routine can be interrupted by - higher priority interrupts and these interrupts enter the critical section - protected by this lock, then the result is unpredictable. +ISR locks may also be statically defined by +:ref:`InterfaceRTEMSINTERRUPTLOCKDEFINE` or statically initialized by +:ref:`InterfaceRTEMSINTERRUPTLOCKINITIALIZER`. + +.. Generated from spec:/rtems/intr/if/lock-destroy .. raw:: latex - \clearpage + \clearpage + +.. index:: rtems_interrupt_lock_destroy() + +.. _InterfaceRtemsInterruptLockDestroy: + +rtems_interrupt_lock_destroy() +------------------------------ -.. index:: rtems_interrupt_lock_release_isr +Destroys the ISR lock. -.. _rtems_interrupt_lock_release_isr: +.. rubric:: CALLING SEQUENCE: -INTERRUPT_LOCK_RELEASE_ISR - Release an ISR Lock from ISR ---------------------------------------------------------- +.. code-block:: c -CALLING SEQUENCE: - .. code-block:: c + #define rtems_interrupt_lock_destroy( lock ) - void rtems_interrupt_lock_release_isr( - rtems_interrupt_lock *lock, - rtems_interrupt_lock_context *lock_context - ); +.. rubric:: PARAMETERS: -DIRECTIVE STATUS CODES: - NONE +``lock`` + This parameter is the ISR lock to destroy. -DESCRIPTION: - The interrupt level will remain unchanged. In SMP configurations, this - directive releases an SMP lock. +.. rubric:: NOTES: -NOTES: - The lock context must be the one used to acquire the lock, otherwise the - result is unpredictable. +The lock must have been dynamically initialized by +:ref:`InterfaceRtemsInterruptLockInitialize`, statically defined by +:ref:`InterfaceRTEMSINTERRUPTLOCKDEFINE`, or statically initialized by +:ref:`InterfaceRTEMSINTERRUPTLOCKINITIALIZER`. - This directive is intended for device drivers and should be called from the - corresponding interrupt service routine. +Concurrent lock use during the destruction or concurrent destruction leads to +unpredictable results. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/intr/if/lock-acquire .. raw:: latex - \clearpage + \clearpage -.. index:: is interrupt in progress -.. index:: rtems_interrupt_is_in_progress +.. index:: rtems_interrupt_lock_acquire() + +.. _InterfaceRtemsInterruptLockAcquire: + +rtems_interrupt_lock_acquire() +------------------------------ + +Acquires the ISR lock. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + #define rtems_interrupt_lock_acquire( lock, lock_context ) + +.. rubric:: PARAMETERS: + +``lock`` + This parameter is the ISR lock to acquire. + +``lock_context`` + This parameter is the ISR lock context. This lock context shall be used to + release the lock by calling :ref:`InterfaceRtemsInterruptLockRelease`. + +.. rubric:: DESCRIPTION: + +This directive acquires the ISR lock specified by ``lock`` using the lock +context provided by ``lock_context``. Maskable interrupts will be disabled on +the current processor. + +.. rubric:: NOTES: + +A caller-specific lock context shall be provided for each acquire/release pair, +for example an automatic variable. + +Where the system was built with SMP support enabled, this directive acquires an +SMP lock. An attempt to recursively acquire the lock may result in an infinite +loop with maskable interrupts disabled. + +This directive establishes a non-preemptive critical section with system wide +mutual exclusion on the local node in all RTEMS build configurations. + +.. code-block:: c + :linenos: + + #include <rtems.h> + + void critical_section( rtems_interrupt_lock *lock ) + { + rtems_interrupt_lock_context lock_context; + + rtems_interrupt_lock_acquire( lock, &lock_context ); + + // Here is the critical section. Maskable interrupts are disabled. + // Where the system was built with SMP support enabled, this section + // is protected by an SMP lock. + + rtems_interrupt_lock_release( lock, &lock_context ); + } + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/intr/if/lock-release + +.. raw:: latex + + \clearpage + +.. index:: rtems_interrupt_lock_release() + +.. _InterfaceRtemsInterruptLockRelease: + +rtems_interrupt_lock_release() +------------------------------ + +Releases the ISR lock. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + #define rtems_interrupt_lock_release( lock, lock_context ) + +.. rubric:: PARAMETERS: + +``lock`` + This parameter is the ISR lock to release. + +``lock_context`` + This parameter is the ISR lock context. This lock context shall have been + used to acquire the lock by calling + :ref:`InterfaceRtemsInterruptLockAcquire`. + +.. rubric:: DESCRIPTION: + +This directive releases the ISR lock specified by ``lock`` using the lock +context provided by ``lock_context``. The previous interrupt level will be +restored on the current processor. + +.. rubric:: NOTES: + +The lock context shall be the one used to acquire the lock, otherwise the +result is unpredictable. + +Where the system was built with SMP support enabled, this directive releases an +SMP lock. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +* While at least one maskable interrupt is pending, when the directive enables + maskable interrupts, the pending interrupts are immediately serviced. The + interrupt service routines may unblock higher priority tasks which may + preempt the calling task. + +.. Generated from spec:/rtems/intr/if/lock-acquire-isr + +.. raw:: latex + + \clearpage + +.. index:: rtems_interrupt_lock_acquire_isr() + +.. _InterfaceRtemsInterruptLockAcquireIsr: + +rtems_interrupt_lock_acquire_isr() +---------------------------------- + +Acquires the ISR lock from within an ISR. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + #define rtems_interrupt_lock_acquire_isr( lock, lock_context ) + +.. rubric:: PARAMETERS: + +``lock`` + This parameter is the ISR lock to acquire within an ISR. + +``lock_context`` + This parameter is the ISR lock context. This lock context shall be used to + release the lock by calling :ref:`InterfaceRtemsInterruptLockReleaseIsr`. + +.. rubric:: DESCRIPTION: + +This directive acquires the ISR lock specified by ``lock`` using the lock +context provided by ``lock_context``. The interrupt level will remain +unchanged. + +.. rubric:: NOTES: + +A caller-specific lock context shall be provided for each acquire/release pair, +for example an automatic variable. + +Where the system was built with SMP support enabled, this directive acquires an +SMP lock. An attempt to recursively acquire the lock may result in an infinite +loop. + +This directive is intended for device drivers and should be called from the +corresponding interrupt service routine. + +In case the corresponding interrupt service routine can be interrupted by +higher priority interrupts and these interrupts enter the critical section +protected by this lock, then the result is unpredictable. This directive may +be used under specific circumstances as an optimization. In doubt, use +:ref:`InterfaceRtemsInterruptLockAcquire` and +:ref:`InterfaceRtemsInterruptLockRelease`. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/intr/if/lock-release-isr + +.. raw:: latex + + \clearpage + +.. index:: rtems_interrupt_lock_release_isr() + +.. _InterfaceRtemsInterruptLockReleaseIsr: + +rtems_interrupt_lock_release_isr() +---------------------------------- + +Releases the ISR lock from within an ISR. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + #define rtems_interrupt_lock_release_isr( lock, lock_context ) + +.. rubric:: PARAMETERS: + +``lock`` + This parameter is the ISR lock to release within an ISR. + +``lock_context`` + This parameter is the ISR lock context. This lock context shall have been + used to acquire the lock by calling + :ref:`InterfaceRtemsInterruptLockAcquireIsr`. + +.. rubric:: DESCRIPTION: + +This directive releases the ISR lock specified by ``lock`` using the lock +context provided by ``lock_context``. The interrupt level will remain +unchanged. + +.. rubric:: NOTES: + +The lock context shall be the one used to acquire the lock, otherwise the +result is unpredictable. + +Where the system was built with SMP support enabled, this directive releases an +SMP lock. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/intr/if/lock-isr-disable + +.. raw:: latex + + \clearpage + +.. index:: rtems_interrupt_lock_interrupt_disable() + +.. _InterfaceRtemsInterruptLockInterruptDisable: + +rtems_interrupt_lock_interrupt_disable() +---------------------------------------- + +Disables maskable interrupts on the current processor. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + #define rtems_interrupt_lock_interrupt_disable( lock_context ) + +.. rubric:: PARAMETERS: + +``lock_context`` + This parameter is the ISR lock context for an acquire and release pair. + +.. rubric:: DESCRIPTION: + +This directive disables maskable interrupts on the current processor and stores +the previous interrupt level in ``lock_context``. + +.. rubric:: CONSTRAINTS: + +The following constraints apply to this directive: + +* The directive may be called from within any runtime context. + +* The directive will not cause the calling task to be preempted. + +.. Generated from spec:/rtems/intr/if/lock-declare + +.. raw:: latex + + \clearpage + +.. index:: RTEMS_INTERRUPT_LOCK_DECLARE() + +.. _InterfaceRTEMSINTERRUPTLOCKDECLARE: + +RTEMS_INTERRUPT_LOCK_DECLARE() +------------------------------ + +Declares an ISR lock object. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + #define RTEMS_INTERRUPT_LOCK_DECLARE( specifier, designator ) + +.. rubric:: PARAMETERS: + +``specifier`` + This parameter is the storage-class specifier for the ISR lock to declare, + for example ``extern`` or ``static``. + +``designator`` + This parameter is the ISR lock object designator. + +.. rubric:: NOTES: + +Do not add a ";" after this macro. + +.. Generated from spec:/rtems/intr/if/lock-define + +.. raw:: latex + + \clearpage + +.. index:: RTEMS_INTERRUPT_LOCK_DEFINE() + +.. _InterfaceRTEMSINTERRUPTLOCKDEFINE: + +RTEMS_INTERRUPT_LOCK_DEFINE() +----------------------------- + +Defines an ISR lock object. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + #define RTEMS_INTERRUPT_LOCK_DEFINE( specifier, designator, name ) + +.. rubric:: PARAMETERS: + +``specifier`` + This parameter is the storage-class specifier for the ISR lock to declare, + for example ``extern`` or ``static``. + +``designator`` + This parameter is the ISR lock object designator. + +``name`` + This parameter is the ISR lock name. It shall be a string. The name is + only used where the system was built with profiling support enabled. + +.. rubric:: NOTES: + +Do not add a ";" after this macro. + +ISR locks may also be dynamically initialized by +:ref:`InterfaceRtemsInterruptLockInitialize` or statically by +:ref:`InterfaceRTEMSINTERRUPTLOCKINITIALIZER`. + +.. Generated from spec:/rtems/intr/if/lock-initializer + +.. raw:: latex + + \clearpage + +.. index:: RTEMS_INTERRUPT_LOCK_INITIALIZER() + +.. _InterfaceRTEMSINTERRUPTLOCKINITIALIZER: + +RTEMS_INTERRUPT_LOCK_INITIALIZER() +---------------------------------- + +Statically initializes an ISR lock object. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + #define RTEMS_INTERRUPT_LOCK_INITIALIZER( name ) + +.. rubric:: PARAMETERS: + +``name`` + This parameter is the ISR lock name. It shall be a string. The name is + only used where the system was built with profiling support enabled. + +.. rubric:: NOTES: + +ISR locks may also be dynamically initialized by +:ref:`InterfaceRtemsInterruptLockInitialize` or statically defined by +:ref:`InterfaceRTEMSINTERRUPTLOCKDEFINE`. + +.. Generated from spec:/rtems/intr/if/lock-member + +.. raw:: latex + + \clearpage + +.. index:: RTEMS_INTERRUPT_LOCK_MEMBER() + +.. _InterfaceRTEMSINTERRUPTLOCKMEMBER: + +RTEMS_INTERRUPT_LOCK_MEMBER() +----------------------------- + +Defines an ISR lock member. + +.. rubric:: CALLING SEQUENCE: + +.. code-block:: c + + #define RTEMS_INTERRUPT_LOCK_MEMBER( designator ) + +.. rubric:: PARAMETERS: + +``designator`` + This parameter is the ISR lock member designator. + +.. rubric:: NOTES: + +Do not add a ";" after this macro. + +.. Generated from spec:/rtems/intr/if/lock-reference + +.. raw:: latex + + \clearpage + +.. index:: RTEMS_INTERRUPT_LOCK_REFERENCE() + +.. _InterfaceRTEMSINTERRUPTLOCKREFERENCE: + +RTEMS_INTERRUPT_LOCK_REFERENCE() +-------------------------------- + +Defines an ISR lock object reference. + +.. rubric:: CALLING SEQUENCE: -.. _rtems_interrupt_is_in_progress: +.. code-block:: c -INTERRUPT_IS_IN_PROGRESS - Is an ISR in Progress ------------------------------------------------- + #define RTEMS_INTERRUPT_LOCK_REFERENCE( designator, target ) -CALLING SEQUENCE: - .. code-block:: c +.. rubric:: PARAMETERS: - bool rtems_interrupt_is_in_progress( void ); +``designator`` + This parameter is the ISR lock reference designator. -DIRECTIVE STATUS CODES: - NONE +``target`` + This parameter is the target object to reference. -DESCRIPTION: - This directive returns ``TRUE`` if the processor is currently servicing an - interrupt and ``FALSE`` otherwise. A return value of ``TRUE`` indicates - that the caller is an interrupt service routine, *NOT* a task. The - directives available to an interrupt service routine are restricted. +.. rubric:: NOTES: -NOTES: - This directive will not cause the calling task to be preempted. +Do not add a ";" after this macro. diff --git a/c-user/interrupt/introduction.rst b/c-user/interrupt/introduction.rst index 272eba2..3d5c71d 100644 --- a/c-user/interrupt/introduction.rst +++ b/c-user/interrupt/introduction.rst @@ -1,37 +1,110 @@ .. SPDX-License-Identifier: CC-BY-SA-4.0 +.. Copyright (C) 2021 embedded brains GmbH (http://www.embedded-brains.de) .. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR) +.. This file is part of the RTEMS quality process and was automatically +.. generated. If you find something that needs to be fixed or +.. worded better please post a report or patch to an RTEMS mailing list +.. or raise a bug report: +.. +.. https://www.rtems.org/bugs.html +.. +.. For information on updating and regenerating please refer to the How-To +.. section in the Software Requirements Engineering chapter of the +.. RTEMS Software Engineering manual. The manual is provided as a part of +.. a release. For development sources please refer to the online +.. documentation at: +.. +.. https://docs.rtems.org + +.. Generated from spec:/rtems/intr/if/group + +.. _InterruptManagerIntroduction: + Introduction ============ +.. The following list was generated from: +.. spec:/rtems/intr/if/catch +.. spec:/rtems/intr/if/disable +.. spec:/rtems/intr/if/enable +.. spec:/rtems/intr/if/flash +.. spec:/rtems/intr/if/local-disable +.. spec:/rtems/intr/if/local-enable +.. spec:/rtems/intr/if/is-in-progress +.. spec:/rtems/intr/if/cause +.. spec:/rtems/intr/if/clear +.. spec:/rtems/intr/if/lock-initialize +.. spec:/rtems/intr/if/lock-destroy +.. spec:/rtems/intr/if/lock-acquire +.. spec:/rtems/intr/if/lock-release +.. spec:/rtems/intr/if/lock-acquire-isr +.. spec:/rtems/intr/if/lock-release-isr +.. spec:/rtems/intr/if/lock-isr-disable +.. spec:/rtems/intr/if/lock-declare +.. spec:/rtems/intr/if/lock-define +.. spec:/rtems/intr/if/lock-initializer +.. spec:/rtems/intr/if/lock-member +.. spec:/rtems/intr/if/lock-reference + Any real-time executive must provide a mechanism for quick response to externally generated interrupts to satisfy the critical time constraints of the -application. The interrupt manager provides this mechanism for RTEMS. This +application. The Interrupt Manager provides this mechanism for RTEMS. This manager permits quick interrupt response times by providing the critical ability to alter task execution which allows a task to be preempted upon exit -from an ISR. The interrupt manager includes the following directive: +from an ISR. The directives provided by the Interrupt Manager are: + +* :ref:`InterfaceRtemsInterruptCatch` - Establishes an interrupt service + routine. + +* :ref:`InterfaceRtemsInterruptDisable` - Disables the maskable interrupts on + the current processor. + +* :ref:`InterfaceRtemsInterruptEnable` - Restores the previous interrupt level + on the current processor. + +* :ref:`InterfaceRtemsInterruptFlash` - Flashes interrupts on the current + processor. + +* :ref:`InterfaceRtemsInterruptLocalDisable` - Disables the maskable interrupts + on the current processor. + +* :ref:`InterfaceRtemsInterruptLocalEnable` - Restores the previous interrupt + level on the current processor. + +* :ref:`InterfaceRtemsInterruptIsInProgress` - Checks if an ISR is in progress + on the current processor. + +* :ref:`InterfaceRtemsInterruptCause` - Causes the interrupt. + +* :ref:`InterfaceRtemsInterruptClear` - Clears the interrupt. -- :ref:`rtems_interrupt_catch` +* :ref:`InterfaceRtemsInterruptLockInitialize` - Initializes the ISR lock. -- :ref:`rtems_interrupt_disable` +* :ref:`InterfaceRtemsInterruptLockDestroy` - Destroys the ISR lock. -- :ref:`rtems_interrupt_enable` +* :ref:`InterfaceRtemsInterruptLockAcquire` - Acquires the ISR lock. -- :ref:`rtems_interrupt_flash` +* :ref:`InterfaceRtemsInterruptLockRelease` - Releases the ISR lock. -- :ref:`rtems_interrupt_local_disable` +* :ref:`InterfaceRtemsInterruptLockAcquireIsr` - Acquires the ISR lock from + within an ISR. -- :ref:`rtems_interrupt_local_enable` +* :ref:`InterfaceRtemsInterruptLockReleaseIsr` - Releases the ISR lock from + within an ISR. -- :ref:`rtems_interrupt_lock_initialize` +* :ref:`InterfaceRtemsInterruptLockInterruptDisable` - Disables maskable + interrupts on the current processor. -- :ref:`rtems_interrupt_lock_acquire` +* :ref:`InterfaceRTEMSINTERRUPTLOCKDECLARE` - Declares an ISR lock object. -- :ref:`rtems_interrupt_lock_release` +* :ref:`InterfaceRTEMSINTERRUPTLOCKDEFINE` - Defines an ISR lock object. -- :ref:`rtems_interrupt_lock_acquire_isr` +* :ref:`InterfaceRTEMSINTERRUPTLOCKINITIALIZER` - Statically initializes an ISR + lock object. -- :ref:`rtems_interrupt_lock_release_isr` +* :ref:`InterfaceRTEMSINTERRUPTLOCKMEMBER` - Defines an ISR lock member. -- :ref:`rtems_interrupt_is_in_progress` +* :ref:`InterfaceRTEMSINTERRUPTLOCKREFERENCE` - Defines an ISR lock object + reference. |