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>

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,
+* **Kernel configuration files**: An application typically provides a configuration
-  written in C or assembly language. These files are usually located in a
+  file (:file:`.conf`) that specifies values for one or more kernel configuration
-  sub-directory called :file:`src`.
+  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
+  A microkernel application typically provides an additional :abbr:`Microkernel
-
+  Definitions File (MDEF)` under the extension :file:`.mdef`. This file defines
-  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
   all of the system's public microkernel objects. This file is not used with a
   nanokernel-only application.
 
-* Makefile
+* **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
-  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`.
 

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
+* The **interrupt context** is a special kernel context used to execute
-  Interrupt Service Routines (ISRs). The interrupt context takes
+  :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).
+interrupts by interrupt handlers, also known as ISRs. Interrupt handling takes
-Interrupt handling takes precedence over task and fiber processing, so that
+precedence over task and fiber processing, so that an ISR preempts the currently
-an ISR preempts the currently scheduled task or fiber whenever it needs
+scheduled task or fiber whenever it needs to run. The kernel also supports nested
-to run. The kernel also supports nested interrupt handling, allowing a higher
+interrupt handling, allowing a higher priority ISR to interrupt the execution of
-priority ISR to interrupt the execution of a lower priority ISR, should the
+a lower priority ISR, should the need arise.
-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
+Kernel clocking is based on time units called :dfn:`ticks` which have a
-configurable. A 64-bit *system clock* counts the number of ticks that have
+configurable duration. A 64-bit *system clock* counts the number of ticks
-elapsed since the kernel started executing.
+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
+* A :dfn:`microkernel FIFO` is a queuing mechanism that allows tasks to exchange
-  fixed-size data items in an asychronous, "first in, first out" manner.
+  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
+* 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.
+  variable-size data items in an asychronous, first-in, first-out manner.
 
-* A *nanokernel LIFO* is a queuing mechanism that allows contexts to exchange
+* 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.
+  variable-size data items in an asychronous, last-in, first-out manner.
 
-* A *nanokernel stack* is a queuing mechanism that allows contexts to exchange
+* A :dfn:`nanokernel stack` is a queuing mechanism that allows contexts to exchange
-  32-bit data items in an asynchronous, "last in, first out" manner.
+  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
+  numbers.
-  do not generate sequences of values that are truly random.)
+
+  .. important::
+
+    Certain implementations of this device driver do not generate sequences of
+    values that are truly random.
 
 Networking Library
 ******************

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