[rtems-docs commit] c-user: Clarify interrupt manager directives
Sebastian Huber
sebh at rtems.org
Thu Nov 30 09:15:14 UTC 2017
Module: rtems-docs
Branch: master
Commit: b2c766bc729d7a2be414802842a32d1860112575
Changeset: http://git.rtems.org/rtems-docs/commit/?id=b2c766bc729d7a2be414802842a32d1860112575
Author: Sebastian Huber <sebastian.huber at embedded-brains.de>
Date: Wed Nov 29 11:02:47 2017 +0100
c-user: Clarify interrupt manager directives
Use RTEMS coding style in all code blocks.
---
c-user/interrupt_manager.rst | 195 ++++++++++++++++++++++++++++++-------------
1 file changed, 137 insertions(+), 58 deletions(-)
diff --git a/c-user/interrupt_manager.rst b/c-user/interrupt_manager.rst
index 1a8e3cb..b1b2cbb 100644
--- a/c-user/interrupt_manager.rst
+++ b/c-user/interrupt_manager.rst
@@ -23,13 +23,13 @@ from an ISR. The interrupt manager includes the following directive:
- rtems_interrupt_disable_ - Disable Interrupts
-- rtems_interrupt_enable_ - Enable Interrupts
+- rtems_interrupt_enable_ - Restore Interrupt Level
- rtems_interrupt_flash_ - Flash Interrupt
- rtems_interrupt_local_disable_ - Disable Interrupts on Current Processor
-- rtems_interrupt_local_enable_ - Enable Interrupts on Current Processor
+- rtems_interrupt_local_enable_ - Restore Interrupt Level on Current Processor
- rtems_interrupt_lock_initialize_ - Initialize an ISR Lock
@@ -73,7 +73,7 @@ a prototype similar to the following:
.. code-block:: c
rtems_isr user_isr(
- rtems_vector_number vector
+ rtems_vector_number vector
);
The vector number argument is provided by RTEMS to allow the application to
@@ -278,9 +278,9 @@ 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
+ rtems_isr_entry new_isr_handler,
+ rtems_vector_number vector,
+ rtems_isr_entry *old_isr_handler
);
DIRECTIVE STATUS CODES:
@@ -322,7 +322,7 @@ CALLING SEQUENCE:
.. code-block:: c
void rtems_interrupt_disable(
- rtems_interrupt_level level
+ rtems_interrupt_level level
);
DIRECTIVE STATUS CODES:
@@ -330,55 +330,92 @@ DIRECTIVE STATUS CODES:
DESCRIPTION:
This directive disables all maskable interrupts and returns the previous
- ``level``. A later invocation of the ``rtems_interrupt_enable`` directive
- should be used to restore the interrupt level.
+ interrupt level in ``level``.
-.. sidebar:: *Macro*
+NOTES:
+ A later invocation of the ``rtems_interrupt_enable`` directive should be
+ used to restore the interrupt level.
- This directive is implemented as a macro which modifies the ``level``
- parameter.
+ This directive is implemented as a macro which sets the ``level``
+ parameter.
-NOTES:
This directive will not cause the calling task to be preempted.
- This directive is only available on uni-processor configurations. The
- directive ``rtems_interrupt_local_disable`` is available on all
+ This directive is only available in uni-processor configurations. The
+ directive ``rtems_interrupt_local_disable`` is available in all
configurations.
+ .. code-block:: c
+
+ void critical_section( void )
+ {
+ rtems_interrupt 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 );
+
+ /* Critical section, maskable interrupts are disabled */
+
+ {
+ rtems_interrupt level2;
+
+ rtems_interrupt_disable( level2 );
+
+ /* Nested critical section */
+
+ rtems_interrupt_enable( level2 );
+ }
+
+ /* Maskable interrupts are still disabled */
+
+ rtems_interrupt_enable( level );
+ }
+
.. raw:: latex
\clearpage
.. index:: enable interrupts
+.. index:: restore interrupt level
.. index:: rtems_interrupt_enable
.. _rtems_interrupt_enable:
-INTERRUPT_ENABLE - Enable Interrupts
-------------------------------------
+INTERRUPT_ENABLE - Restore Interrupt Level
+------------------------------------------
CALLING SEQUENCE:
.. code-block:: c
void rtems_interrupt_enable(
- rtems_interrupt_level level
+ rtems_interrupt_level level
);
DIRECTIVE STATUS CODES:
NONE
DESCRIPTION:
- This directive enables maskable interrupts to the ``level`` which was
- returned by a previous call to ``rtems_interrupt_disable``. Immediately
- prior to invoking this directive, maskable interrupts should be disabled by
- a call to ``rtems_interrupt_disable`` and will be enabled when this
- directive returns to the caller.
+ This directive restores the interrupt level specified by ``level``.
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.
+
+ This directive is unsuitable to enable particular interrupt sources, for
+ example in an interrupt controller.
+
This directive will not cause the calling task to be preempted.
- This directive is only available on uni-processor configurations. The
- directive ``rtems_interrupt_local_enable`` is available on all
+ This directive is only available in uni-processor configurations. The
+ directive ``rtems_interrupt_local_enable`` is available in all
configurations.
.. raw:: latex
@@ -397,7 +434,7 @@ CALLING SEQUENCE:
.. code-block:: c
void rtems_interrupt_flash(
- rtems_interrupt_level level
+ rtems_interrupt_level level
);
DIRECTIVE STATUS CODES:
@@ -411,6 +448,10 @@ DESCRIPTION:
this sequence.
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.
+
This directive will not cause the calling task to be preempted.
This directive is only available in uni-processor configurations. The
@@ -437,7 +478,7 @@ CALLING SEQUENCE:
.. code-block:: c
void rtems_interrupt_local_disable(
- rtems_interrupt_level level
+ rtems_interrupt_level level
);
DIRECTIVE STATUS CODES:
@@ -445,50 +486,88 @@ DIRECTIVE STATUS CODES:
DESCRIPTION:
This directive disables all maskable interrupts and returns the previous
- ``level``. A later invocation of the ``rtems_interrupt_local_enable``
- directive should be used to restore the interrupt level.
+ interrupt level in ``level``.
-.. sidebar:: *Macro*
+NOTES:
+ A later invocation of the ``rtems_interrupt_local_enable`` directive should
+ be used to restore the interrupt level.
- This directive is implemented as a macro which modifies the ``level``
- parameter.
+ This directive is implemented as a macro which sets the ``level``
+ parameter.
-NOTES:
This directive will not cause the calling task to be preempted.
In SMP configurations, this will not ensure system wide mutual exclusion.
Use interrupt locks instead.
+ .. code-block:: c
+
+ void local_critical_section( void )
+ {
+ rtems_interrupt 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 are disabled */
+
+ {
+ rtems_interrupt level2;
+
+ rtems_interrupt_local_disable( level2 );
+
+ /* Nested local critical section */
+
+ rtems_interrupt_local_enable( level2 );
+ }
+
+ /* Maskable interrupts are still disabled */
+
+ rtems_interrupt_local_enable( level );
+ }
+
.. raw:: latex
\clearpage
.. index:: enable interrupts
+.. index:: restore interrupt level
.. index:: rtems_interrupt_local_enable
.. _rtems_interrupt_local_enable:
-INTERRUPT_LOCAL_ENABLE - Enable Interrupts on Current Processor
----------------------------------------------------------------
+INTERRUPT_LOCAL_ENABLE - Restore Interrupt Level on Current Processor
+---------------------------------------------------------------------
CALLING SEQUENCE:
.. code-block:: c
void rtems_interrupt_local_enable(
- rtems_interrupt_level level
+ rtems_interrupt_level level
);
DIRECTIVE STATUS CODES:
NONE
DESCRIPTION:
- This directive enables maskable interrupts to the ``level`` which was
- returned by a previous call to ``rtems_interrupt_local_disable``.
- Immediately prior to invoking this directive, maskable interrupts should be
- disabled by a call to ``rtems_interrupt_local_disable`` and will be enabled
- when this directive returns to the caller.
+ This directive restores the interrupt level specified by ``level`` 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.
+
+ This directive is unsuitable to enable particular interrupt sources, for
+ example in an interrupt controller.
+
This directive will not cause the calling task to be preempted.
.. raw:: latex
@@ -506,8 +585,8 @@ CALLING SEQUENCE:
.. code-block:: c
void rtems_interrupt_lock_initialize(
- rtems_interrupt_lock *lock,
- const char *name
+ rtems_interrupt_lock *lock,
+ const char *name
);
DIRECTIVE STATUS CODES:
@@ -535,23 +614,23 @@ CALLING SEQUENCE:
.. code-block:: c
void rtems_interrupt_lock_acquire(
- rtems_interrupt_lock *lock,
- rtems_interrupt_lock_context *lock_context
+ rtems_interrupt_lock *lock,
+ rtems_interrupt_lock_context *lock_context
);
DIRECTIVE STATUS CODES:
NONE
DESCRIPTION:
- Interrupts will be disabled. In SMP configurations, this directive
- acquires an SMP lock.
+ Maskable interrupts will be disabled. In SMP configurations, this
+ directive acquires an SMP lock.
NOTES:
A separate lock context must be provided for each acquire/release pair, for
example an automatic variable.
An attempt to recursively acquire the lock may result in an infinite loop
- with interrupts disabled.
+ with maskable interrupts disabled.
This directive will not cause the calling thread to be preempted. This
directive can be used in thread and interrupt context.
@@ -571,15 +650,15 @@ CALLING SEQUENCE:
.. code-block:: c
void rtems_interrupt_lock_release(
- rtems_interrupt_lock *lock,
- rtems_interrupt_lock_context *lock_context
+ rtems_interrupt_lock *lock,
+ rtems_interrupt_lock_context *lock_context
);
DIRECTIVE STATUS CODES:
NONE
DESCRIPTION:
- The interrupt status will be restored. In SMP configurations, this
+ The interrupt level will be restored. In SMP configurations, this
directive releases an SMP lock.
NOTES:
@@ -604,15 +683,15 @@ CALLING SEQUENCE:
.. code-block:: c
void rtems_interrupt_lock_acquire_isr(
- rtems_interrupt_lock *lock,
- rtems_interrupt_lock_context *lock_context
+ rtems_interrupt_lock *lock,
+ rtems_interrupt_lock_context *lock_context
);
DIRECTIVE STATUS CODES:
NONE
DESCRIPTION:
- The interrupt status will remain unchanged. In SMP configurations, this
+ The interrupt level will remain unchanged. In SMP configurations, this
directive acquires an SMP lock.
NOTES:
@@ -643,15 +722,15 @@ CALLING SEQUENCE:
.. code-block:: c
void rtems_interrupt_lock_release_isr(
- rtems_interrupt_lock *lock,
- rtems_interrupt_lock_context *lock_context
+ rtems_interrupt_lock *lock,
+ rtems_interrupt_lock_context *lock_context
);
DIRECTIVE STATUS CODES:
NONE
DESCRIPTION:
- The interrupt status will remain unchanged. In SMP configurations, this
+ The interrupt level will remain unchanged. In SMP configurations, this
directive releases an SMP lock.
NOTES:
@@ -676,7 +755,7 @@ INTERRUPT_IS_IN_PROGRESS - Is an ISR in Progress
CALLING SEQUENCE:
.. code-block:: c
- bool rtems_interrupt_is_in_progress(void);
+ bool rtems_interrupt_is_in_progress( void );
DIRECTIVE STATUS CODES:
NONE
More information about the vc
mailing list