From 0c2e25f73e9e8b88f10d19d1edc74f95565edf0b Mon Sep 17 00:00:00 2001 From: "L.S. Cook" Date: Wed, 21 Oct 2015 12:08:58 -0700 Subject: [PATCH] doc: Edits to the Overview and kernel primer Fixed typo in system_fundamentals. Acronyms FIFO and LIFO defined with capital letters in kernel_fundamentals. Added bold to paragraph lists to enhance readability in application_fundamentals Added lots of :dfn: syntax for better interlinking to API. Corrected whitespace for sub-bullet directive. Change-Id: If6c5bc78746686d1a4986974f1b56bf9b2caebca Signed-off-by: L.S. Cook --- .../overview/application_fundamentals.rst | 32 ++++----- doc/kernel/overview/kernel_fundamentals.rst | 70 ++++++++++--------- doc/kernel/overview/system_fundamentals.rst | 2 +- 3 files changed, 51 insertions(+), 53 deletions(-) diff --git a/doc/kernel/overview/application_fundamentals.rst b/doc/kernel/overview/application_fundamentals.rst index d41038baffd..c6abaa46e2d 100644 --- a/doc/kernel/overview/application_fundamentals.rst +++ b/doc/kernel/overview/application_fundamentals.rst @@ -6,32 +6,26 @@ Application Fundamentals A Zephyr application is defined by creating a directory containing the following files. -* Application source code files +* **Application source code files**: An application typically provides one + or more application-specific files, written in C or assembly language. These + files are usually located in a sub-directory called :file:`src`. - An application typically provides one or more application-specific files, - written in C or assembly language. These files are usually located in a - sub-directory called :file:`src`. +* **Kernel configuration files**: An application typically provides a configuration + file (:file:`.conf`) that specifies values for one or more kernel configuration + options. If omitted, the application's existing kernel configuration option values + are used; if no existing values are provided, the kernel's default configuration + values are used. -* Kernel configuration files - - An application typically provides a configuration file (:file:`.conf`) - that specifies values for one or more kernel configuration options. - If omitted, the application's existing kernel configuration option values - are used; if no existing values are provided, the kernel's default - configuration values are used. - - A microkernel application typically provides an additional :abbr:`MDEF (Microkernel - Definitions File)` under the extension :file:`.mdef`. This file defines + A microkernel application typically provides an additional :abbr:`Microkernel + Definitions File (MDEF)` under the extension :file:`.mdef`. This file defines all of the system's public microkernel objects. This file is not used with a nanokernel-only application. -* Makefile - - This file typically contains a handful of lines that tell the build system - where to find the files mentioned above, as well as the desired target +* **Makefile**: This file typically contains a handful of lines that tell the build + system where to find the files mentioned above, as well as the desired target platform configuration and kernel type (either microkernel or nanokernel). -Once the application has been defined it can be built using a single command. +Once the application has been defined, it can be built with a single command. The results of the build process, including the final application image, are located in a sub-directory called :file:`outdir`. diff --git a/doc/kernel/overview/kernel_fundamentals.rst b/doc/kernel/overview/kernel_fundamentals.rst index de37fd154dd..2b3cff3b255 100644 --- a/doc/kernel/overview/kernel_fundamentals.rst +++ b/doc/kernel/overview/kernel_fundamentals.rst @@ -43,14 +43,14 @@ Multi-threading The Zephyr kernel supports multi-threaded processing for three types of execution contexts. -* A *task context* is a preemptible thread, normally used to perform +* A **task context** is a preemptible thread, normally used to perform processing that is lengthy or complex. Task scheduling is priority-based, so that the execution of a higher priority task preempts the execution of a lower priority task. The kernel also supports an optional round-robin time slicing capability so that equal priority tasks can execute in turn, without the risk of any one task monopolizing the CPU. -* A *fiber context* is a lightweight and non-preemptible thread, typically +* A **fiber context** is a lightweight and non-preemptible thread, typically used for device drivers and performance critical work. Fiber scheduling is priority-based, so that a higher priority fiber is scheduled for execution before a lower priority fiber; however, once a fiber is scheduled it remains @@ -58,8 +58,8 @@ of execution contexts. Fiber execution takes precedence over task execution, so tasks execute only when no fiber can be scheduled. -* The *interrupt context* is a special kernel context used to execute - Interrupt Service Routines (ISRs). The interrupt context takes +* The **interrupt context** is a special kernel context used to execute + :abbr:`ISRs Interrupt Service Routines`. The interrupt context takes precedence over all other contexts, so tasks and fibers execute only when no ISR needs to run. (See below for more on interrupt handling.) @@ -76,12 +76,11 @@ Interrupts ********** The Zephyr kernel supports the handling of hardware interrupts and software -interrupts by interrupt handlers, known as *Interrupt Service Routines* (ISRs). -Interrupt handling takes precedence over task and fiber processing, so that -an ISR preempts the currently scheduled task or fiber whenever it needs -to run. The kernel also supports nested interrupt handling, allowing a higher -priority ISR to interrupt the execution of a lower priority ISR, should the -need arise. +interrupts by interrupt handlers, also known as ISRs. Interrupt handling takes +precedence over task and fiber processing, so that an ISR preempts the currently +scheduled task or fiber whenever it needs to run. The kernel also supports nested +interrupt handling, allowing a higher priority ISR to interrupt the execution of +a lower priority ISR, should the need arise. The nanokernel supplies ISRs for a few interrupt sources (IRQs), such as the hardware timer device and system console device. The ISRs for all other IRQs @@ -104,9 +103,9 @@ Related sections: Clocks and Timers ***************** -Kernel clocking is based on time units called *ticks*, whose duration is -configurable. A 64-bit *system clock* counts the number of ticks that have -elapsed since the kernel started executing. +Kernel clocking is based on time units called :dfn:`ticks` which have a +configurable duration. A 64-bit *system clock* counts the number of ticks +that have elapsed since the kernel started executing. Zephyr also supports a higher-resolution *hardware clock*, which can be used to measure durations requiring sub-tick interval precision. @@ -135,13 +134,13 @@ contexts to synchronize their execution. The microkernel provides the object types listed below. These types are intended for tasks, with limited ability to be used by fibers and ISRs. -* A *semaphore* is a counting semaphore, which indicates how many units +* A :dfn:`semaphore` is a counting semaphore, which indicates how many units of a particular resource are available. -* An *event* is a binary semaphore, which simply indicates if a particular +* An :dfn:`event` is a binary semaphore, which simply indicates if a particular resource is available or not. -* A *mutex* is a reentrant mutex with priority inversion protection. It is +* A :dfn:`mutex` is a reentrant mutex with priority inversion protection. It is similar to a binary semaphore, but contains additional logic to ensure that only the owner of the associated resource can release it and to expedite the execution of a lower priority thread that holds a resource needed by a @@ -150,7 +149,7 @@ are intended for tasks, with limited ability to be used by fibers and ISRs. The nanokernel provides the object type listed below. This type is intended for fibers, with only limited ability to be used by tasks and ISRs. -* A *nanokernel semaphore* is a counting semaphore, which indicates +* A :dfn:`nanokernel semaphore` is a counting semaphore that indicates how many units of a particular resource are available. Each type has specific capabilities and limitations that affect suitability @@ -171,15 +170,16 @@ contexts to exchange data. The microkernel provides the object types listed below. These types are designed to be used by tasks, and cannot be used by fibers and ISRs. -* A *microkernel FIFO* is a queuing mechanism that allows tasks to exchange - fixed-size data items in an asychronous, "first in, first out" manner. +* A :dfn:`microkernel FIFO` is a queuing mechanism that allows tasks to exchange + fixed-size data items in an asychronous :abbr:`First In, First Out (FIFO)` + manner. -* A *mailbox* is a queuing mechanism that allows tasks to exchange +* A :dfn:`mailbox` is a queuing mechanism that allows tasks to exchange variable-size data items in a synchronous, "first in, first out" manner. Mailboxes also support asynchronous exchanges, and allow tasks to exchange messages both anonymously and non-anonymously using the same mailbox. -* A *pipe* is a queuing mechanism that allows a task to send a stream +* A :dfn:`pipe` is a queuing mechanism that allows a task to send a stream of bytes to another task. Both asynchronous and synchronous exchanges can be supported by a pipe. @@ -187,14 +187,14 @@ The nanokernel provides the object types listed below. These types are primarily designed to be used by fibers, and have only a limited ability to be used by tasks and ISRs. -* A *nanokernel FIFO* is a queuing mechanism that allows contexts to exchange - variable-size data items in an asychronous, "first in, first out" manner. +* A :dfn:`nanokernel FIFO` is a queuing mechanism that allows contexts to exchange + variable-size data items in an asychronous, first-in, first-out manner. -* A *nanokernel LIFO* is a queuing mechanism that allows contexts to exchange - variable-size data items in an asychronous, "last in, first out" manner. +* A :dfn:`nanokernel LIFO` is a queuing mechanism that allows contexts to exchange + variable-size data items in an asychronous, last-in, first-out manner. -* A *nanokernel stack* is a queuing mechanism that allows contexts to exchange - 32-bit data items in an asynchronous, "last in, first out" manner. +* A :dfn:`nanokernel stack` is a queuing mechanism that allows contexts to exchange + 32-bit data items in an asynchronous first-in, first-out manner. Each of these types has specific capabilities and limitations that affect suitability for use in a given situation. For more details, see the @@ -216,12 +216,12 @@ This support can be used in place of C standard library calls like The microkernel provides two types of objects that allow tasks to dynamically allocate memory blocks. These object types cannot be used by fibers or ISRs. -* A *memory map* is a memory region that supports the dynamic allocation and +* A :dfn:`memory map` is a memory region that supports the dynamic allocation and release of memory blocks of a single fixed size. An application can have multiple memory maps, whose block size and block capacity can be configured individually. -* A *memory pool* is a memory region that supports the dynamic allocation and +* A :dfn:`memory pool` is a memory region that supports the dynamic allocation and release of memory blocks of multiple fixed sizes. This allows more efficient use of available memory when an application requires blocks of different sizes. An application can have multiple memory pools, whose block sizes @@ -240,11 +240,11 @@ Public and Private Microkernel Objects Microkernel objects, such as semaphores, mailboxes, or tasks, can usually be defined as a public object or a private object. -* A *public object* is one that is available for general use by all parts +* A :dfn:`public object` is one that is available for general use by all parts of the application. Any code that includes :file:`zephyr.h` can interact with the object by referencing the object's name. -* A *private object* is one that is intended for use only by a specific +* A :dfn:`private object` is one that is intended for use only by a specific part of the application, such as a single device driver or subsystem. The object's name is visible only to code within the file where the object is defined, hiding it from general use unless the code which defined the @@ -360,8 +360,12 @@ are listed below. system console subsystem. * **Random number generator**: This device driver provides a source of random - numbers. (**IMPORTANT**: Certain implementations of this device driver - do not generate sequences of values that are truly random.) + numbers. + + .. important:: + + Certain implementations of this device driver do not generate sequences of + values that are truly random. Networking Library ****************** diff --git a/doc/kernel/overview/system_fundamentals.rst b/doc/kernel/overview/system_fundamentals.rst index 18bd3258cf7..4db7c5f5dea 100644 --- a/doc/kernel/overview/system_fundamentals.rst +++ b/doc/kernel/overview/system_fundamentals.rst @@ -14,7 +14,7 @@ of the system, initializes it, and runs forever as the system's sole application Both application code and kernel code execute as privileged code within a single shared address space. -A :dfn:`application` is a set of user-supplied files that the Zephyr build +An :dfn:`application` is a set of user-supplied files that the Zephyr build system processes to generate an application image. The application consists of application-specific code, a collection of kernel configuration settings, and at least one Makefile. The application's kernel configuration settings enable the build