mirror of
https://git.rtems.org/rtems-docs/
synced 2025-07-24 09:32:04 +08:00
c-user: Split up interrupt manager
This makes it easier to automatically generate parts of the manager documentation in the future. Update #3993.
This commit is contained in:
Sebastian Huber
parent
623a9a11e8
commit
72295d47f6
@ -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
|
||||
|
||||
106
c-user/interrupt/background.rst
Normal file
106
c-user/interrupt/background.rst
Normal file
@ -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.
|
||||
@ -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
|
||||
==========
|
||||
|
||||
15
c-user/interrupt/index.rst
Normal file
15
c-user/interrupt/index.rst
Normal file
@ -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
|
||||
37
c-user/interrupt/introduction.rst
Normal file
37
c-user/interrupt/introduction.rst
Normal file
@ -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`
|
||||
112
c-user/interrupt/operations.rst
Normal file
112
c-user/interrupt/operations.rst
Normal file
@ -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
|
||||
Loading…
x
Reference in New Issue
Block a user