[PATCH v2] c-user: Generate interrupt manager documentation
Gedare Bloom
gedare at rtems.org
Tue Apr 27 16:02:38 UTC 2021
OK, thanks for the clarification.
On Mon, Apr 26, 2021 at 11:39 PM Sebastian Huber
<sebastian.huber at embedded-brains.de> wrote:
>
> The documentation is a consolidation of the comments in Doxygen markup
> and the documentation sources in Sphinx markup. The documentation was
> transfered to interface specification items. The documentation source
> files were generated from the items by a script.
>
> Update #3993.
> ---
> Here is the updated document for review:
>
> https://ftp.rtems.org/pub/rtems/people/sebh/c-user.pdf
>
> v2:
>
> * Clarify service of pending interrupts in the interrupt enable
> directives.
>
> c-user/glossary.rst | 5 +
> c-user/interrupt/directives.rst | 1250 +++++++++++++++++++++--------
> 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.
> --
> 2.26.2
>
> _______________________________________________
> devel mailing list
> devel at rtems.org
> http://lists.rtems.org/mailman/listinfo/devel
More information about the devel
mailing list