michaelh/zephyr
1
0
Fork 0
Code Releases Activity

doc: Add clarification to common execution contexts docs

Browse source 
A couple paragraphs contain ambiguous verbs that are unclear.
(For example: Line 23. Does the kernel perform a busy-wait,
or does it merely permit a task or fiber to perform a busy-wait?)
Based on original, I guess the latter and attempted to correct this
in the docs.

Also fixed spelling error.

Change-Id: I0699835a9681c1a4873575fbf9a69bc6d854bee4
Signed-off-by: L.S. Cook <leonax.cook@intel.com>
This commit is contained in:
L.S. Cook 2016-02-22 11:36:51 -08:00 • committed by Gerrit Code Review
commit 32fd061e66
1 changed files with 25 additions and 24 deletions
Download patch file Download diff file Expand all files Collapse all files

49
doc/kernel/common/common_contexts.rst
View file

@ -6,36 +6,36 @@ Execution Context Services
Concepts Concepts
******** ********
Each kernel execution context has an associated *type*, which indicates whether Every kernel execution context has an associated *type* that indicates whether
the context is a task, a fiber, or the kernel's interrupt handling context. the context is a task, a fiber, or the kernel's interrupt handling context.
Task and fiber contexts also have an associated *thread identifier* value,
which is used to uniquely identify these threads.
Each task and fiber may also support a 32-bit *thread custom data* value. All task and fiber contexts have a unique *thread identifier* value used to
This value is accessible only by the task or fiber itself, and can be used uniquely identify them. Each task and fiber can also support a 32-bit *thread
by the application for any purpose. The default custom data value for a custom data* value. This value is accessible only by the task or fiber itself,
task or fiber is zero. and may be used by the application for any purpose. The default custom data
value for a task or fiber is zero.
.. note:: .. note::
The custom data value is not available to ISRs, which operate in the shared The custom data value is not available to ISRs because these operate
kernel interrupt handling context. only within the shared kernel interrupt handling context.
The kernel allows a task or fiber to delay its processing for a specified time The kernel permits a task or a fiber to perform a ``busy wait``, thus delaying
period by performing a busy wait. This allows the delay to occur without its processing for a specified time period. Such a delay occurs without
requiring the kernel to perform the context switching that occurs with its requiring the kernel to perform context switching, as it typically does with
more typical timer and timeout services. timer and timeout services.
Purpose Purpose
******* *******
Use the kernel execution context services when writing code that needs to Use kernel execution context services when writing code that should
operate differently when executed by different contexts. operate differently when it is executed by different contexts.
Use the busy wait service when the required delay is too short to warrant Use the ``busy wait`` service when the required delay is too short to
context switching to another task or fiber, or when performing a delay warrant context switching to another task or fiber. The ``busy wait``
as part of the nanokernel's background task (which is not allowed to service may also be used when performing a delay as part of the
volutarily relinquish the CPU). nanokernel's background task in a nanokernel-only system; this task is
not allowed to voluntarily relinquish the CPU.
Usage Usage
@ -51,10 +51,11 @@ support is disabled.
Example: Performing Execution Context-Specific Processing Example: Performing Execution Context-Specific Processing
========================================================= =========================================================
This code shows how a routine can use a thread's custom data value This code shows how a routine can use a thread's custom data value
to limit the number of times a thread may call the routine. to limit the number of times a thread may call the routine. Note that
Counting is not performed when the routine is called by an ISR, which does not counting is not performed when the routine is called by an ISR; ISRs
have a custom data value. do not have a custom data value.
.. note:: .. note::
Obviously, only a single routine can use this technique Obviously, only a single routine can use this technique
@ -83,8 +84,8 @@ have a custom data value.
APIs APIs
**** ****
The following kernel execution context APIs are provided by The following kernel execution context APIs are common to both
:file:`microkernel.h` and by :file:`nanokernel.h`: :file:`microkernel.h` and :file:`nanokernel.h`:
:c:func:`sys_thread_self_get()` :c:func:`sys_thread_self_get()`