136 lines
6.3 KiB
ReStructuredText
136 lines
6.3 KiB
ReStructuredText
==============================
|
|
Bottom-Half Interrupt Handlers
|
|
==============================
|
|
|
|
RTOS Interrupts
|
|
===============
|
|
|
|
A well-design RTOS depends on the most minimal of interrupt level processing.
|
|
This is a very different concept from that for bare metal programming:
|
|
|
|
* With bare metal programming most of the real-time work is usually performed
|
|
in interrupt handlers. Interrupt handler execution may then extend in time
|
|
considerably due to this interrupt level processing.
|
|
|
|
To compensate for this extended interrupt processing time, bare metal programmers
|
|
also need prioritized interrupts:
|
|
|
|
* If an interrupt request for a higher priority interrupt occurs during the
|
|
extended processing of the lower priority interrupt, then that interrupt handler
|
|
will itself be interrupted to service the higher priority interrupt requests.
|
|
In this way bare metal interrupt handling is nested.
|
|
|
|
With an RTOS, the real-time strategy is very different:
|
|
|
|
* Interrupts must run very, very briefly so that they do not interfere with the
|
|
RTOS real-time scheduling. Normally, the interrupt simply performs whatever
|
|
minor housekeeping is necessary and then immediately defers processing by waking up
|
|
some task via some Inter-Process Communication(IPC). The RTOS is then responsible for
|
|
the real-time behavior, not the interrupt. And,
|
|
|
|
* since the interrupts must be very brief, there is little or no gain from nesting of interrupts.
|
|
|
|
Extending interrupt processing
|
|
==============================
|
|
|
|
But what if extended interrupt processing is required?
|
|
What if there is a significant amount of hardware-related operations that absolutely
|
|
must be performed as quickly as possible before we can turn processing over to
|
|
general, real-time tasking?
|
|
|
|
In NuttX, this is handled through a high priority trampoline called
|
|
the "High Priority Work Queue". It is a trampoline because it changes the interrupt
|
|
processing context for extended interrupt processing before notifying the normal
|
|
real-time task.
|
|
|
|
Processing on that ultra-high priority work thread then completes the extended
|
|
interrupt processing with interrupts enabled, but without interference from any
|
|
other real-time tasks.
|
|
|
|
At the completion of the extended processing, the high priority worker thread can
|
|
then continue processing via some IPC to a normal real-time task.
|
|
|
|
The portion of interrupt processing that is performed in the interrupt handler with
|
|
interrupts disabled is referred to as Top Half Interrupt processing; the portion of
|
|
interrupt processing that is performed on the high priority work queue with interrupts
|
|
enabled is referred to as Bottom Half Interrupt processing.
|
|
|
|
High Priority Work Queue
|
|
========================
|
|
|
|
NuttX supports a high priority work queue as well as a low priority work queue with
|
|
somewhat different properties.
|
|
The high priority work queue is dedicated to the support of Bottom Half Interrupt
|
|
processing.
|
|
Other uses of the high priority work queue may be inappropriate and may harm the
|
|
real-time performance of your system.
|
|
|
|
The high priority work queue must have these properties:
|
|
|
|
* **Highest Priority** The high priority work queue must be the highest priority
|
|
task in your system. No other task should execute at a higher priority; No other
|
|
task can be permitted to interfere with execution of the high priority work queue.
|
|
|
|
* **Zero Latency Context Switches** Provided that the priority of the high priority
|
|
work queue is the highest in the system, then there will be no context switch
|
|
overhead in getting from the Top Half Interrupt processing to the Bottom Half
|
|
Interrupt processing other that the normal overhead of returning from an interrupt.
|
|
Upon return from the interrupt, the system will immediately vector to high priority
|
|
worker thread.
|
|
|
|
* **Brief Processing** Processing on the high priority work queue must still be brief.
|
|
If there is high priority work in progress when the high priority worker is signaled,
|
|
then that processing will be queued and delayed until it can be processed. That delay
|
|
will add jitter to your real-time response. You must not generate a backlog of work
|
|
for the high priority worker thread!
|
|
|
|
* **No Waiting** Work executing on the high priority work queue must not wait for
|
|
resources or events on the high priority worker thread. Waiting on the high priority
|
|
work queue blocks the queue and will, again, damage real-time performance.
|
|
|
|
Setting Up Bottom Half Interrupt Processing
|
|
===========================================
|
|
|
|
Bottom half interrupt processing is scheduled by top half interrupt processing by
|
|
simply calling the function ``work_queue()``:
|
|
|
|
.. code-block:: C
|
|
|
|
int work_queue(int qid, FAR struct work_s *work, worker_t worker,
|
|
FAR void *arg, clock_t delay);
|
|
|
|
This same interface is the same for both high- and low-priority.
|
|
The qid argument distinguishes which work queue will be used. For bottom half
|
|
interrupt processing, ``qid`` must be set to ``HPWORK``.
|
|
|
|
The work argument is memory that will be used to actually queue the work.
|
|
It has no meaning to the caller; it is simply a memory allocation by the caller.
|
|
Otherwise, the work structure is completely managed by the work queue logic.
|
|
The caller should never modify the contents of the work queue structure directly.
|
|
If ``work_queue()`` is called before the previous work as been performed and removed
|
|
from the queue, then any pending work will be canceled and lost.
|
|
The ``work_available()`` function can be called to determine if the work represented
|
|
by the work structure is still in-use.
|
|
|
|
For the interrupt handling case at hand, the work structure must be pre-allocated
|
|
or statically allocated since dynamic allocations are not supported from the
|
|
interrupt handling context.
|
|
|
|
The ``worker`` is the name of the function that will perform the bottom half interrupt
|
|
work.
|
|
``arg`` is an arbitrary value that the user provides and will be given to the worker
|
|
function when it executes.
|
|
Normally ``arg`` produces some context in which the work will be performed.
|
|
The type of the worker function is given by:
|
|
|
|
.. code-block:: C
|
|
|
|
typedef CODE void (*worker_t)(FAR void *arg);
|
|
|
|
Where ``arg`` has the same value as was passed to ``work_queue()``.
|
|
|
|
Processing or work can be delayed in time.
|
|
The ``work_queue()`` ``delay`` argument provides that time delay in units of system
|
|
clock ticks. However, when used to provide bottom half interrupt processing, the
|
|
delay should always be zero.
|