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