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 <leonax.cook@intel.com>
This commit is contained in:
parent
876c86e1a8
commit
0c2e25f73e
3 changed files with 51 additions and 53 deletions
|
@ -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`.
|
||||
|
||||
|
|
|
@ -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
|
||||
******************
|
||||
|
|
|
@ -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
|
||||
|
|
Loading…
Add table
Add a link
Reference in a new issue