diff --git a/doc/kernel/microkernel/microkernel_task_irqs.rst b/doc/kernel/microkernel/microkernel_task_irqs.rst index b36f8235702..232f44be158 100644 --- a/doc/kernel/microkernel/microkernel_task_irqs.rst +++ b/doc/kernel/microkernel/microkernel_task_irqs.rst @@ -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.