From 32fd061e663f01cc47a3b00e3b7fd47bad9ea777 Mon Sep 17 00:00:00 2001 From: "L.S. Cook" Date: Mon, 22 Feb 2016 11:36:51 -0800 Subject: [PATCH] doc: Add clarification to common execution contexts docs 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 --- doc/kernel/common/common_contexts.rst | 49 ++++++++++++++------------- 1 file changed, 25 insertions(+), 24 deletions(-) diff --git a/doc/kernel/common/common_contexts.rst b/doc/kernel/common/common_contexts.rst index 0ab01b463bc..fea4f0c851d 100644 --- a/doc/kernel/common/common_contexts.rst +++ b/doc/kernel/common/common_contexts.rst @@ -6,36 +6,36 @@ Execution Context Services 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. -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. -This value is accessible only by the task or fiber itself, and can be used -by the application for any purpose. The default custom data value for a -task or fiber is zero. +All task and fiber contexts have a unique *thread identifier* value used to +uniquely identify them. Each task and fiber can also support a 32-bit *thread +custom data* value. This value is accessible only by the task or fiber itself, +and may be used by the application for any purpose. The default custom data +value for a task or fiber is zero. .. note:: - The custom data value is not available to ISRs, which operate in the shared - kernel interrupt handling context. + The custom data value is not available to ISRs because these operate + only within the shared kernel interrupt handling context. -The kernel allows a task or fiber to delay its processing for a specified time -period by performing a busy wait. This allows the delay to occur without -requiring the kernel to perform the context switching that occurs with its -more typical timer and timeout services. +The kernel permits a task or a fiber to perform a ``busy wait``, thus delaying +its processing for a specified time period. Such a delay occurs without +requiring the kernel to perform context switching, as it typically does with +timer and timeout services. Purpose ******* -Use the kernel execution context services when writing code that needs to -operate differently when executed by different contexts. +Use kernel execution context services when writing code that should +operate differently when it is executed by different contexts. -Use the busy wait service when the required delay is too short to warrant -context switching to another task or fiber, or when performing a delay -as part of the nanokernel's background task (which is not allowed to -volutarily relinquish the CPU). +Use the ``busy wait`` service when the required delay is too short to +warrant context switching to another task or fiber. The ``busy wait`` +service may also be used when performing a delay as part of the +nanokernel's background task in a nanokernel-only system; this task is +not allowed to voluntarily relinquish the CPU. Usage @@ -51,10 +51,11 @@ support is disabled. Example: Performing Execution Context-Specific Processing ========================================================= + 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. -Counting is not performed when the routine is called by an ISR, which does not -have a custom data value. +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; ISRs +do not have a custom data value. .. note:: Obviously, only a single routine can use this technique @@ -83,8 +84,8 @@ have a custom data value. APIs **** -The following kernel execution context APIs are provided by -:file:`microkernel.h` and by :file:`nanokernel.h`: +The following kernel execution context APIs are common to both +:file:`microkernel.h` and :file:`nanokernel.h`: :c:func:`sys_thread_self_get()`