michaelh/zephyr
1
0
Fork 0
Code Releases Activity

doc: Edit microkernel_task_irqs.rst for consistency in styling.

Browse source 
Added some rst styling, minor punctuation fixes, and doc flow edits.

Change-Id: I1f4bd5dd1ac788b12fc498d1ad3297260f05e7fa
Signed-off-by: L.S. Cook <leonax.cook@intel.com>
This commit is contained in:
L.S. Cook 2016-03-16 08:28:46 -07:00 • committed by Gerrit Code Review
commit 0b04465a8c
1 changed files with 37 additions and 42 deletions
Download patch file Download diff file Expand all files Collapse all files

79
doc/kernel/microkernel/microkernel_task_irqs.rst
View file

@ -6,42 +6,36 @@ Interrupt Services
Concepts
********
The microkernel's task IRQ objects allow interrupts to be serviced
by tasks, rather than interrupt service routines (ISRs).
This allows a microkernel project to have task-level device drivers,
in addition to interrupt-level device drivers.
The microkernel's :dfn:`task IRQ` objects allow interrupts to be serviced
by tasks, rather than only by interrupt service routines (ISRs). These allow
a microkernel project to have both task-level device drivers and interrupt-level
device drivers.
Any number of task IRQs can be defined in a microkernel system.
Each task IRQ has a numeric identifier that uniquely identifies it.
These identifiers range from 0 to N-1, where N is the total number
of task IRQs in the system.
Any number of task IRQs can be defined in a microkernel system. Each task IRQ
has a numeric identifier that uniquely identifies it. These identifiers range
from 0 to N-1, where N is the total number of task IRQs in the system.
A task that wants to service interrupts from a device
must first allocate a task IRQ and bind it to the device's interrupt source
by specifying the IRQ and interrupt priority level
assigned to that device by the system designer.
Once a task IRQ has been allocated by a task
it cannot be utilized by other tasks;
this prevents other tasks from interfering with the proper processing
A task that wants to service interrupts from a device must first allocate a
task IRQ and bind it to the device's interrupt source by specifying the IRQ
and interrupt priority level assigned to that device by the system designer.
Once a task IRQ has been allocated by a task, it cannot be used by other
tasks; this prevents other tasks from interfering with the proper processing
of interrupts from that device.
When an interrupt is generated by the device, the kernel
runs an ISR that masks the interrupt and signals the occurrence
of the interrupt to the associated task IRQ.
The task can then use the task IRQ to recognize that
an interrupt has occurred
and then take action to service the interrupt.
At some point during interrupt servicing
the task must instruct the task IRQ to acknowledge the interrupt;
this causes the kernel to unmask the interrupt
so that future interrupts can be detected.
When an interrupt is generated by the device, the kernel runs an ISR that
masks the interrupt and signals the occurrence of the interrupt to the
associated task IRQ. The task can then use the task IRQ to recognize that
an interrupt has occurred and take action to service the interrupt. At some
point during interrupt servicing, the task must instruct the task IRQ to
acknowledge the interrupt; this causes the kernel to unmask the interrupt so
that future interrupts can be detected.
Purpose
*******
Use a task IRQ when the work required to process an interrupt
cannot be done in an ISR, either because it takes a long time
or it requires the processing routine to block.
Use a task IRQ when the work required to process an interrupt cannot be done
in an ISR -- either because it takes a long time, or because it requires the
processing routine to block.
Usage
*****
@ -49,8 +43,8 @@ Usage
Configuring Task IRQs
=====================
Set the :option:`MAX_NUM_TASK_IRQS` configuration option
to specify the number of task IRQs allowed in the project.
Set the :option:`MAX_NUM_TASK_IRQS` configuration option to specify the number
of task IRQs allowed in the project.
The default value of zero for this option disables task IRQs.
@ -59,12 +53,13 @@ The default value of zero for this option disables task IRQs.
as a group using a configuration option, rather than as individual
public objects in an MDEF or private objects in a source file.
Example: Allocating a Task IRQ
==============================
This code associates a task IRQ with interrupts generated by a device.
Interrupts from that device are then enabled
so they can be processed using the task IRQ.
Interrupts from that device are then enabled so they can be processed
using the task IRQ.
.. code-block:: c
@ -97,24 +92,24 @@ acknowledge the interrupt, and take the necessary steps to service it.
/* Device interrupt is now unmasked */
/* Do post-acknowledgement device processing (if any) */
The steps required to service a device are device-specific.
In some cases all processing may need to be completed
before the interrupt is acknowledged,
while in other cases no processing at all should be done
until the interrupt is acknowledged.
Some devices may require processing both before and after acknowledgement.
The steps required to service a device are device-specific. In some cases
all processing may need to be completed before the interrupt is acknowledged,
while in other cases no processing at all should be done until the interrupt
is acknowledged. Some devices may require processing both before and after
acknowledgement.
APIs
****
The following task IRQ APIs are provided by :file:`microkernel.h`:
Task IRQ APIs provided by :file:`microkernel.h`
===============================================
:cpp:func:`task_irq_alloc()`
Binds a task IRQ to a device and enables interrupts.
Bind a task IRQ to a device and enable interrupts.
:cpp:func:`task_irq_ack()`
Acknowledges an interrupt and re-enables the interrupt.
Acknowledge an interrupt and re-enable the interrupt.
:c:func:`task_irq_wait()`
Waits for an interrupt to occur within a specified time period.
Wait for an interrupt to occur within a specified time period.