Documentation: Fix typos

Documentation/reference/os/wqueue.rst:
    * Fix spelling, grammar, and typos.
    * Improve wording in a few areas.
    * Re-wrap the paragraphs that were modified.
This commit is contained in:
Nathan Hartman 2021-07-05 17:13:23 -04:00 committed by Xiang Xiao
parent 841a4922aa
commit 935c206bd4

View File

@ -10,10 +10,10 @@ for delayed processing, or for serializing activities.
Classes of Work Queues Classes of Work Queues
====================== ======================
There are three different classes of There are three different classes of work queues, each with
work queues, each with different properties and intended usage. different properties and intended usage. These classes of work
These class of work queues along with the common work queue queues along with the common work queue interface are described in
interface are described in the following paragraphs. the following paragraphs.
High Priority Kernel Work queue High Priority Kernel Work queue
------------------------------- -------------------------------
@ -89,9 +89,9 @@ work queue runs at a lower priority than the high priority work
queue, of course, and so is inappropriate to serve as a driver queue, of course, and so is inappropriate to serve as a driver
*bottom half*. It is, otherwise, very similar to the high priority *bottom half*. It is, otherwise, very similar to the high priority
work queue and most of the discussion above for the high priority work queue and most of the discussion above for the high priority
work queue applies equally here. The lower priority work queue work queue applies equally here. The lower priority work queue does
does have one important, however, that make it better suited for have one important property, however, that makes it better suited
some tasks: for some tasks:
**Priority Inheritance**. The lower priority worker thread(s) **Priority Inheritance**. The lower priority worker thread(s)
support *priority inheritance* (if <config> support *priority inheritance* (if <config>
@ -100,8 +100,8 @@ lower priority worker thread can then be adjusted to match the
highest priority client. highest priority client.
**NOTE:** This priority inheritance feature is not automatic. **NOTE:** This priority inheritance feature is not automatic.
The lower priority worker thread will always a fixed priority The lower priority worker thread will always have a fixed
unless additional logic implements that calls priority unless additional logic calls
``lpwork_boostpriority()`` to raise the priority of the lower ``lpwork_boostpriority()`` to raise the priority of the lower
priority worker thread (typically called before scheduling the priority worker thread (typically called before scheduling the
work) and then calls the matching ``lpwork_restorepriority()`` work) and then calls the matching ``lpwork_restorepriority()``
@ -144,19 +144,18 @@ User-Mode Work Queue
**Work Queue Accessibility**. The high- and low-priority worker **Work Queue Accessibility**. The high- and low-priority worker
threads are kernel-mode threads. In the normal, *flat* NuttX threads are kernel-mode threads. In the normal, *flat* NuttX
build, these work queues are are useful to application code and build, these work queues are useful to application code and
may be shared. However, in the NuttX protected and kernel build may be shared. However, in the NuttX protected and kernel build
modes, kernel mode code is isolated and cannot be accessed from modes, kernel mode code is isolated and cannot be accessed from
user-mode code. user-mode code.
**User-Mode Work Queue**. if either ``CONFIG_BUILD_PROTECTED`` or **User-Mode Work Queue**. if either ``CONFIG_BUILD_PROTECTED`` or
``CONFIG_BUILD_KERNEL`` are selected, then the option to enable a ``CONFIG_BUILD_KERNEL`` are selected, then the option to enable a
special user-mode work queue is enable. The interface to the special user-mode work queue is enabled. The interface to the user-
user-mode work queue is identical to the interface to the mode work queue is identical to that of the kernel-mode work queues
kernel-mode work queues and the user-mode work queue is and the user-mode work queue is functionally equivalent to the high
functionally equivalent to the high priority work queue. It priority work queue. It differs in that its implementation does not
differs in that its implementation does not depend on internal, depend on internal, kernel-space facilities.
kernel-space facilities.
**Configuration Options**. **Configuration Options**.
@ -182,10 +181,10 @@ interface function identifies the work queue:
**Kernel-Mode Work Queue IDs:** **Kernel-Mode Work Queue IDs:**
- ``HPWORK``. This ID of the high priority work queue that should - ``HPWORK``. This ID of the high priority work queue that should
only be used for hi-priority, time-critical, driver bottom-half only be used for high-priority, time-critical, driver bottom-half
functions. functions.
- ``LPWORK``. This is the ID of the low priority work queue that - ``LPWORK``. This is the ID of the low priority work queue that
can be used for any purpose. if ``CONFIG_SCHED_LPWORK`` is not can be used for any purpose. If ``CONFIG_SCHED_LPWORK`` is not
defined, then there is only one kernel work queue and defined, then there is only one kernel work queue and
``LPWORK`` is equal to ``HPWORK``. ``LPWORK`` is equal to ``HPWORK``.
@ -193,7 +192,7 @@ interface function identifies the work queue:
- ``USRWORK``. This is the ID of the user-mode work queue that - ``USRWORK``. This is the ID of the user-mode work queue that
can be used for any purpose by applications. In a flat build, can be used for any purpose by applications. In a flat build,
``LPWORK`` is equal to ``LPWORK`` so that user applications ``USRWORK`` is equal to ``LPWORK`` so that user applications
will use the lower priority work queue (if there is one). will use the lower priority work queue (if there is one).
Work Queue Interface Types Work Queue Interface Types
@ -222,14 +221,14 @@ Work Queue Interfaces
zero by the caller. Otherwise, the work structure is completely zero by the caller. Otherwise, the work structure is completely
managed by the work queue logic. The caller should never modify managed by the work queue logic. The caller should never modify
the contents of the work queue structure directly. If the contents of the work queue structure directly. If
``work_queue()`` is called before the previous work as been ``work_queue()`` is called before the previous work has been
performed and removed from the queue, then any pending work will performed and removed from the queue, then any pending work will
be canceled and lost. be canceled and lost.
:param qid: The work queue ID. :param qid: The work queue ID.
:param work: The work structure to queue :param work: The work structure to queue
:param worker: The worker callback to be invoked. The callback :param worker: The worker callback to be invoked. The callback
will invoked on the worker thread of execution. will be invoked on the worker thread of execution.
:param arg: The argument that will be passed to the worker :param arg: The argument that will be passed to the worker
callback function when it is invoked. callback function when it is invoked.
@ -244,10 +243,10 @@ Work Queue Interfaces
Cancel previously queued work. This removes work Cancel previously queued work. This removes work
from the work queue. After work has been cancelled, it may be from the work queue. After work has been cancelled, it may be
re-queue by calling ``work_queue()`` again. re-queued by calling ``work_queue()`` again.
:param qid: The work queue ID. :param qid: The work queue ID.
:param work: The previously queue work structure to cancel. :param work: The previously queued work structure to cancel.
:return: Zero is returned on success; a negated ``errno`` is returned on :return: Zero is returned on success; a negated ``errno`` is returned on
failure. failure.