[PATCH v2 06/16] c-user: Split up interrupt manager
Sebastian Huber
sebastian.huber at embedded-brains.de
Wed Sep 2 16:01:00 UTC 2020
This makes it easier to automatically generate parts of the manager
documentation in the future.
Update #3993.
---
c-user/index.rst | 2 +-
c-user/interrupt/background.rst | 106 ++++++++
.../directives.rst} | 251 ------------------
c-user/interrupt/index.rst | 15 ++
c-user/interrupt/introduction.rst | 37 +++
c-user/interrupt/operations.rst | 112 ++++++++
6 files changed, 271 insertions(+), 252 deletions(-)
create mode 100644 c-user/interrupt/background.rst
rename c-user/{interrupt_manager.rst => interrupt/directives.rst} (61%)
create mode 100644 c-user/interrupt/index.rst
create mode 100644 c-user/interrupt/introduction.rst
create mode 100644 c-user/interrupt/operations.rst
diff --git a/c-user/index.rst b/c-user/index.rst
index 51998bf..d955cc8 100644
--- a/c-user/index.rst
+++ b/c-user/index.rst
@@ -31,7 +31,7 @@ RTEMS Classic API Guide (|version|).
scheduling_concepts
initialization
task_manager
- interrupt_manager
+ interrupt/index
clock/index
timer_manager
rate_monotonic_manager
diff --git a/c-user/interrupt/background.rst b/c-user/interrupt/background.rst
new file mode 100644
index 0000000..b626640
--- /dev/null
+++ b/c-user/interrupt/background.rst
@@ -0,0 +1,106 @@
+.. SPDX-License-Identifier: CC-BY-SA-4.0
+
+.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
+
+Background
+==========
+
+.. index:: interrupt processing
+
+Processing an Interrupt
+-----------------------
+
+The interrupt manager allows the application to connect a function to a
+hardware interrupt vector. When an interrupt occurs, the processor will
+automatically vector to RTEMS. RTEMS saves and restores all registers which
+are not preserved by the normal C calling convention for the target processor
+and invokes the user's ISR. The user's ISR is responsible for processing the
+interrupt, clearing the interrupt if necessary, and device specific
+manipulation.
+
+.. index:: rtems_vector_number
+
+The ``rtems_interrupt_catch`` directive connects a procedure to an interrupt
+vector. The vector number is managed using the ``rtems_vector_number`` data
+type.
+
+The interrupt service routine is assumed to abide by these conventions and have
+a prototype similar to the following:
+
+.. index:: rtems_isr
+
+.. code-block:: c
+
+ rtems_isr user_isr(
+ rtems_vector_number vector
+ );
+
+The vector number argument is provided by RTEMS to allow the application to
+identify the interrupt source. This could be used to allow a single routine to
+service interrupts from multiple instances of the same device. For example, a
+single routine could service interrupts from multiple serial ports and use the
+vector number to identify which port requires servicing.
+
+To minimize the masking of lower or equal priority level interrupts, the ISR
+should perform the minimum actions required to service the interrupt. Other
+non-essential actions should be handled by application tasks. Once the user's
+ISR has completed, it returns control to the RTEMS interrupt manager which will
+perform task dispatching and restore the registers saved before the ISR was
+invoked.
+
+The RTEMS interrupt manager guarantees that proper task scheduling and
+dispatching are performed at the conclusion of an ISR. A system call made by
+the ISR may have readied a task of higher priority than the interrupted task.
+Therefore, when the ISR completes, the postponed dispatch processing must be
+performed. No dispatch processing is performed as part of directives which
+have been invoked by an ISR.
+
+Applications must adhere to the following rule if proper task scheduling and
+dispatching is to be performed:
+
+.. note::
+
+ The interrupt manager must be used for all ISRs which may be interrupted by
+ the highest priority ISR which invokes an RTEMS directive.
+
+Consider a processor which allows a numerically low interrupt level to
+interrupt a numerically greater interrupt level. In this example, if an RTEMS
+directive is used in a level 4 ISR, then all ISRs which execute at levels 0
+through 4 must use the interrupt manager.
+
+Interrupts are nested whenever an interrupt occurs during the execution of
+another ISR. RTEMS supports efficient interrupt nesting by allowing the nested
+ISRs to terminate without performing any dispatch processing. Only when the
+outermost ISR terminates will the postponed dispatching occur.
+
+.. index:: interrupt levels
+
+RTEMS Interrupt Levels
+----------------------
+
+Many processors support multiple interrupt levels or priorities. The exact
+number of interrupt levels is processor dependent. RTEMS internally supports
+256 interrupt levels which are mapped to the processor's interrupt levels. For
+specific information on the mapping between RTEMS and the target processor's
+interrupt levels, refer to the Interrupt Processing chapter of the Applications
+Supplement document for a specific target processor.
+
+.. index:: disabling interrupts
+
+Disabling of Interrupts by RTEMS
+--------------------------------
+
+During the execution of directive calls, critical sections of code may be
+executed. When these sections are encountered, RTEMS disables all maskable
+interrupts before the execution of the section and restores them to the
+previous level upon completion of the section. RTEMS has been optimized to
+ensure that interrupts are disabled for a minimum length of time. The maximum
+length of time interrupts are disabled by RTEMS is processor dependent and is
+detailed in the Timing Specification chapter of the Applications Supplement
+document for a specific target processor.
+
+Non-maskable interrupts (NMI) cannot be disabled, and ISRs which execute at
+this level MUST NEVER issue RTEMS system calls. If a directive is invoked,
+unpredictable results may occur due to the inability of RTEMS to protect its
+critical sections. However, ISRs that make no system calls may safely execute
+as non-maskable interrupts.
diff --git a/c-user/interrupt_manager.rst b/c-user/interrupt/directives.rst
similarity index 61%
rename from c-user/interrupt_manager.rst
rename to c-user/interrupt/directives.rst
index 5eb7270..95181db 100644
--- a/c-user/interrupt_manager.rst
+++ b/c-user/interrupt/directives.rst
@@ -2,257 +2,6 @@
.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
-.. index:: interrupts
-
-Interrupt Manager
-*****************
-
-Introduction
-============
-
-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
-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:
-
-- rtems_interrupt_catch_ - Establish an ISR
-
-- rtems_interrupt_disable_ - Disable 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_ - Restore Interrupt Level on Current Processor
-
-- rtems_interrupt_lock_initialize_ - Initialize an ISR Lock
-
-- rtems_interrupt_lock_acquire_ - Acquire an ISR Lock
-
-- rtems_interrupt_lock_release_ - Release an ISR Lock
-
-- rtems_interrupt_lock_acquire_isr_ - Acquire an ISR Lock from ISR
-
-- rtems_interrupt_lock_release_isr_ - Release an ISR Lock from ISR
-
-- rtems_interrupt_is_in_progress_ - Is an ISR in Progress
-
-Background
-==========
-
-.. index:: interrupt processing
-
-Processing an Interrupt
------------------------
-
-The interrupt manager allows the application to connect a function to a
-hardware interrupt vector. When an interrupt occurs, the processor will
-automatically vector to RTEMS. RTEMS saves and restores all registers which
-are not preserved by the normal C calling convention for the target processor
-and invokes the user's ISR. The user's ISR is responsible for processing the
-interrupt, clearing the interrupt if necessary, and device specific
-manipulation.
-
-.. index:: rtems_vector_number
-
-The ``rtems_interrupt_catch`` directive connects a procedure to an interrupt
-vector. The vector number is managed using the ``rtems_vector_number`` data
-type.
-
-The interrupt service routine is assumed to abide by these conventions and have
-a prototype similar to the following:
-
-.. index:: rtems_isr
-
-.. code-block:: c
-
- rtems_isr user_isr(
- rtems_vector_number vector
- );
-
-The vector number argument is provided by RTEMS to allow the application to
-identify the interrupt source. This could be used to allow a single routine to
-service interrupts from multiple instances of the same device. For example, a
-single routine could service interrupts from multiple serial ports and use the
-vector number to identify which port requires servicing.
-
-To minimize the masking of lower or equal priority level interrupts, the ISR
-should perform the minimum actions required to service the interrupt. Other
-non-essential actions should be handled by application tasks. Once the user's
-ISR has completed, it returns control to the RTEMS interrupt manager which will
-perform task dispatching and restore the registers saved before the ISR was
-invoked.
-
-The RTEMS interrupt manager guarantees that proper task scheduling and
-dispatching are performed at the conclusion of an ISR. A system call made by
-the ISR may have readied a task of higher priority than the interrupted task.
-Therefore, when the ISR completes, the postponed dispatch processing must be
-performed. No dispatch processing is performed as part of directives which
-have been invoked by an ISR.
-
-Applications must adhere to the following rule if proper task scheduling and
-dispatching is to be performed:
-
-.. note::
-
- The interrupt manager must be used for all ISRs which may be interrupted by
- the highest priority ISR which invokes an RTEMS directive.
-
-Consider a processor which allows a numerically low interrupt level to
-interrupt a numerically greater interrupt level. In this example, if an RTEMS
-directive is used in a level 4 ISR, then all ISRs which execute at levels 0
-through 4 must use the interrupt manager.
-
-Interrupts are nested whenever an interrupt occurs during the execution of
-another ISR. RTEMS supports efficient interrupt nesting by allowing the nested
-ISRs to terminate without performing any dispatch processing. Only when the
-outermost ISR terminates will the postponed dispatching occur.
-
-.. index:: interrupt levels
-
-RTEMS Interrupt Levels
-----------------------
-
-Many processors support multiple interrupt levels or priorities. The exact
-number of interrupt levels is processor dependent. RTEMS internally supports
-256 interrupt levels which are mapped to the processor's interrupt levels. For
-specific information on the mapping between RTEMS and the target processor's
-interrupt levels, refer to the Interrupt Processing chapter of the Applications
-Supplement document for a specific target processor.
-
-.. index:: disabling interrupts
-
-Disabling of Interrupts by RTEMS
---------------------------------
-
-During the execution of directive calls, critical sections of code may be
-executed. When these sections are encountered, RTEMS disables all maskable
-interrupts before the execution of the section and restores them to the
-previous level upon completion of the section. RTEMS has been optimized to
-ensure that interrupts are disabled for a minimum length of time. The maximum
-length of time interrupts are disabled by RTEMS is processor dependent and is
-detailed in the Timing Specification chapter of the Applications Supplement
-document for a specific target processor.
-
-Non-maskable interrupts (NMI) cannot be disabled, and ISRs which execute at
-this level MUST NEVER issue RTEMS system calls. If a directive is invoked,
-unpredictable results may occur due to the inability of RTEMS to protect its
-critical sections. However, ISRs that make no system calls may safely execute
-as non-maskable interrupts.
-
-Operations
-==========
-
-Establishing an ISR
--------------------
-
-The ``rtems_interrupt_catch`` directive establishes an ISR for the system. The
-address of the ISR and its associated CPU vector number are specified to this
-directive. This directive installs the RTEMS interrupt wrapper in the
-processor's Interrupt Vector Table and the address of the user's ISR in the
-RTEMS' Vector Table. This directive returns the previous contents of the
-specified vector in the RTEMS' Vector Table.
-
-Directives Allowed from an ISR
-------------------------------
-
-Using the interrupt manager ensures that RTEMS knows when a directive is being
-called from an ISR. The ISR may then use system calls to synchronize itself
-with an application task. The synchronization may involve messages, events or
-signals being passed by the ISR to the desired task. Directives invoked by an
-ISR must operate only on objects which reside on the local node. The following
-is a list of RTEMS system calls that may be made from an ISR:
-
-- Task Management
- Although it is acceptable to operate on the RTEMS_SELF task (e.g. the
- currently executing task), while in an ISR, this will refer to the
- interrupted task. Most of the time, it is an application implementation
- error to use RTEMS_SELF from an ISR.
-
- - rtems_task_suspend
- - rtems_task_resume
-
-- Interrupt Management
-
- - rtems_interrupt_enable
- - rtems_interrupt_disable
- - rtems_interrupt_flash
- - rtems_interrupt_lock_acquire
- - rtems_interrupt_lock_release
- - rtems_interrupt_lock_acquire_isr
- - rtems_interrupt_lock_release_isr
- - rtems_interrupt_is_in_progress
- - rtems_interrupt_catch
-
-- Clock Management
-
- - rtems_clock_set
- - rtems_clock_get_tod
- - rtems_clock_get_tod_timeval
- - rtems_clock_get_seconds_since_epoch
- - rtems_clock_get_ticks_per_second
- - rtems_clock_get_ticks_since_boot
- - rtems_clock_get_uptime
-
-- Timer Management
-
- - rtems_timer_cancel
- - rtems_timer_reset
- - rtems_timer_fire_after
- - rtems_timer_fire_when
- - rtems_timer_server_fire_after
- - rtems_timer_server_fire_when
-
-- Event Management
-
- - rtems_event_send
- - rtems_event_system_send
- - rtems_event_transient_send
-
-- Semaphore Management
-
- - rtems_semaphore_release
-
-- Message Management
-
- - rtems_message_queue_broadcast
- - rtems_message_queue_send
- - rtems_message_queue_urgent
-
-- Signal Management
-
- - rtems_signal_send
-
-- Dual-Ported Memory Management
-
- - rtems_port_external_to_internal
- - rtems_port_internal_to_external
-
-- IO Management
- The following services are safe to call from an ISR if and only if
- the device driver service invoked is also safe. The IO Manager itself
- is safe but the invoked driver entry point may or may not be.
-
- - rtems_io_initialize
- - rtems_io_open
- - rtems_io_close
- - rtems_io_read
- - rtems_io_write
- - rtems_io_control
-
-- Fatal Error Management
-
- - rtems_fatal
- - rtems_fatal_error_occurred
-
-- Multiprocessing
-
- - rtems_multiprocessing_announce
-
Directives
==========
diff --git a/c-user/interrupt/index.rst b/c-user/interrupt/index.rst
new file mode 100644
index 0000000..e1c529e
--- /dev/null
+++ b/c-user/interrupt/index.rst
@@ -0,0 +1,15 @@
+.. SPDX-License-Identifier: CC-BY-SA-4.0
+
+.. Copyright (C) 2020 embedded brains GmbH (http://www.embedded-brains.de)
+
+.. index:: interrupts
+
+Interrupt Manager
+*****************
+
+.. toctree::
+
+ introduction
+ background
+ operations
+ directives
diff --git a/c-user/interrupt/introduction.rst b/c-user/interrupt/introduction.rst
new file mode 100644
index 0000000..272eba2
--- /dev/null
+++ b/c-user/interrupt/introduction.rst
@@ -0,0 +1,37 @@
+.. SPDX-License-Identifier: CC-BY-SA-4.0
+
+.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
+
+Introduction
+============
+
+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
+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:
+
+- :ref:`rtems_interrupt_catch`
+
+- :ref:`rtems_interrupt_disable`
+
+- :ref:`rtems_interrupt_enable`
+
+- :ref:`rtems_interrupt_flash`
+
+- :ref:`rtems_interrupt_local_disable`
+
+- :ref:`rtems_interrupt_local_enable`
+
+- :ref:`rtems_interrupt_lock_initialize`
+
+- :ref:`rtems_interrupt_lock_acquire`
+
+- :ref:`rtems_interrupt_lock_release`
+
+- :ref:`rtems_interrupt_lock_acquire_isr`
+
+- :ref:`rtems_interrupt_lock_release_isr`
+
+- :ref:`rtems_interrupt_is_in_progress`
diff --git a/c-user/interrupt/operations.rst b/c-user/interrupt/operations.rst
new file mode 100644
index 0000000..67988c3
--- /dev/null
+++ b/c-user/interrupt/operations.rst
@@ -0,0 +1,112 @@
+.. SPDX-License-Identifier: CC-BY-SA-4.0
+
+.. Copyright (C) 1988, 2008 On-Line Applications Research Corporation (OAR)
+
+Operations
+==========
+
+Establishing an ISR
+-------------------
+
+The ``rtems_interrupt_catch`` directive establishes an ISR for the system. The
+address of the ISR and its associated CPU vector number are specified to this
+directive. This directive installs the RTEMS interrupt wrapper in the
+processor's Interrupt Vector Table and the address of the user's ISR in the
+RTEMS' Vector Table. This directive returns the previous contents of the
+specified vector in the RTEMS' Vector Table.
+
+Directives Allowed from an ISR
+------------------------------
+
+Using the interrupt manager ensures that RTEMS knows when a directive is being
+called from an ISR. The ISR may then use system calls to synchronize itself
+with an application task. The synchronization may involve messages, events or
+signals being passed by the ISR to the desired task. Directives invoked by an
+ISR must operate only on objects which reside on the local node. The following
+is a list of RTEMS system calls that may be made from an ISR:
+
+- Task Management
+ Although it is acceptable to operate on the RTEMS_SELF task (e.g. the
+ currently executing task), while in an ISR, this will refer to the
+ interrupted task. Most of the time, it is an application implementation
+ error to use RTEMS_SELF from an ISR.
+
+ - rtems_task_suspend
+ - rtems_task_resume
+
+- Interrupt Management
+
+ - rtems_interrupt_enable
+ - rtems_interrupt_disable
+ - rtems_interrupt_flash
+ - rtems_interrupt_lock_acquire
+ - rtems_interrupt_lock_release
+ - rtems_interrupt_lock_acquire_isr
+ - rtems_interrupt_lock_release_isr
+ - rtems_interrupt_is_in_progress
+ - rtems_interrupt_catch
+
+- Clock Management
+
+ - rtems_clock_set
+ - rtems_clock_get_tod
+ - rtems_clock_get_tod_timeval
+ - rtems_clock_get_seconds_since_epoch
+ - rtems_clock_get_ticks_per_second
+ - rtems_clock_get_ticks_since_boot
+ - rtems_clock_get_uptime
+
+- Timer Management
+
+ - rtems_timer_cancel
+ - rtems_timer_reset
+ - rtems_timer_fire_after
+ - rtems_timer_fire_when
+ - rtems_timer_server_fire_after
+ - rtems_timer_server_fire_when
+
+- Event Management
+
+ - rtems_event_send
+ - rtems_event_system_send
+ - rtems_event_transient_send
+
+- Semaphore Management
+
+ - rtems_semaphore_release
+
+- Message Management
+
+ - rtems_message_queue_broadcast
+ - rtems_message_queue_send
+ - rtems_message_queue_urgent
+
+- Signal Management
+
+ - rtems_signal_send
+
+- Dual-Ported Memory Management
+
+ - rtems_port_external_to_internal
+ - rtems_port_internal_to_external
+
+- IO Management
+ The following services are safe to call from an ISR if and only if
+ the device driver service invoked is also safe. The IO Manager itself
+ is safe but the invoked driver entry point may or may not be.
+
+ - rtems_io_initialize
+ - rtems_io_open
+ - rtems_io_close
+ - rtems_io_read
+ - rtems_io_write
+ - rtems_io_control
+
+- Fatal Error Management
+
+ - rtems_fatal
+ - rtems_fatal_error_occurred
+
+- Multiprocessing
+
+ - rtems_multiprocessing_announce
--
2.26.2
More information about the devel
mailing list