doc: Add links from kernel API to overview docs

API documentation wasn't linking to important conceptual overview
material available in the primer documentation.

This will need to be done over again when we work on the combined
kernel documentation, but this will give us a peek at what that
will look like.

Jira: ZEP-746

Change-Id: Ib1142575272c72d93af8d409518d0d0a4304ef32
Signed-off-by: David B. Kinder <david.b.kinder@intel.com>

2 files changed, 145 insertions, 0 deletions

diff --git a/doc/api/microkernel_api.rst b/doc/api/microkernel_api.rst
index 4de0dda76..832cffdbd 100644
--- a/doc/api/microkernel_api.rst
+++ b/doc/api/microkernel_api.rst
@@ -11,6 +11,13 @@ Microkernel APIs
 Events
 ******
 
+The microkernel's :dfn:`event` objects are an implementation of traditional
+binary semaphores.
+
+For an overview and important information about Events, see :ref:`microkernel_events`.
+
+------
+
 .. doxygengroup:: microkernel_event
    :project: Zephyr
    :content-only:
@@ -18,6 +25,14 @@ Events
 FIFOs
 *****
 
+The microkernel's :dfn:`FIFO` object type is an implementation of a traditional
+first in, first out queue.
+A FIFO allows tasks to asynchronously send and receive fixed-size data items.
+
+For an overview and important information about FIFOs, see :ref:`microkernel_fifos`.
+
+------
+
 .. doxygengroup:: microkernel_fifo
    :project: Zephyr
    :content-only:
@@ -25,6 +40,13 @@ FIFOs
 Pipes
 *****
 
+The microkernel's :dfn:`pipe` object type is an implementation of a traditional
+anonymous pipe. A pipe allows a task to send a byte stream to another task.
+
+For an overview and important information about Pipes, see :ref:`microkernel_pipes`.
+
+------
+
 .. doxygengroup:: microkernel_pipe
    :project: Zephyr
    :content-only:
@@ -32,6 +54,13 @@ Pipes
 Mailboxes
 *********
 
+The microkernel's :dfn:`mailbox` object type is an implementation of a
+traditional message queue that allows tasks to exchange messages.
+
+For an overview and important information about Mailboxes, see :ref:`microkernel_mailboxes`.
+
+------
+
 .. doxygengroup:: microkernel_mailbox
    :project: Zephyr
    :content-only:
@@ -39,6 +68,13 @@ Mailboxes
 Memory Maps
 ***********
 
+The microkernel's memory map objects provide dynamic allocation and
+release of fixed-size memory blocks.
+
+For an overview and important information about Memory Maps, see :ref:`microkernel_memory_maps`.
+
+------
+
 .. doxygengroup:: microkernel_memorymap
    :project: Zephyr
    :content-only:
@@ -46,6 +82,13 @@ Memory Maps
 Memory Pools
 ************
 
+The microkernel's :dfn:`memory pool` objects provide dynamic allocation and
+release of variable-size memory blocks.
+
+For an overview and important information about Memory Pools, see :ref:`microkernel_memory_pools`.
+
+------
+
 .. doxygengroup:: microkernel_memorypool
    :project: Zephyr
    :content-only:
@@ -53,6 +96,15 @@ Memory Pools
 Mutexes
 *******
 
+The microkernel's :dfn:`mutex` objects provide reentrant mutex
+capabilities with basic priority inheritance.  A mutex allows
+tasks to safely share a resource by ensuring mutual exclusivity
+while the resource is being accessed by a task.
+
+For an overview and important information about Mutexes, see :ref:`microkernel_mutexes`.
+
+------
+
 .. doxygengroup:: microkernel_mutex
    :project: Zephyr
    :content-only:
@@ -60,6 +112,13 @@ Mutexes
 Semaphores
 **********
 
+The microkernel's :dfn:`semaphore` objects are an implementation of traditional
+counting semaphores.
+
+For an overview and important information about Semaphores, see :ref:`microkernel_semaphores`.
+
+------
+
 .. doxygengroup:: microkernel_semaphore
    :project: Zephyr
    :content-only:
@@ -67,6 +126,15 @@ Semaphores
 Timers
 ******
 
+A :dfn:`microkernel timer` allows a task to determine whether or not a
+specified time limit has been reached while the task is busy performing
+other work. The timer uses the kernel's system clock, measured in
+ticks, to monitor the passage of time.
+
+For an overview and important information about Timers, see :ref:`microkernel_timers`.
+
+------
+
 .. doxygengroup:: microkernel_timer
    :project: Zephyr
    :content-only:
@@ -74,6 +142,14 @@ Timers
 Tasks
 *****
 
+A task is a preemptible thread of execution that implements a portion of
+an application's processing. It is normally used for processing that
+is too lengthy or too complex to be performed by a fiber or an ISR.
+
+For an overview and important information about Tasks, see :ref:`microkernel_tasks`.
+
+------
+
 .. doxygengroup:: microkernel_task
    :project: Zephyr
    :content-only:
diff --git a/doc/api/nanokernel_api.rst b/doc/api/nanokernel_api.rst
index 0e0c6f45d..82c664306 100644
--- a/doc/api/nanokernel_api.rst
+++ b/doc/api/nanokernel_api.rst
@@ -11,6 +11,14 @@ Nanokernel APIs
 Fibers
 ******
 
+A :dfn:`fiber` is a lightweight, non-preemptible thread of execution that
+implements a portion of an application's processing. Fibers are often
+used in device drivers and for performance-critical work.
+
+For an overview and important information about Fibers, see :ref:`nanokernel_fibers`.
+
+------
+
 .. doxygengroup:: nanokernel_fiber
    :project: Zephyr
    :content-only:
@@ -18,6 +26,14 @@ Fibers
 Tasks
 ******
 
+A :dfn:`task` is a preemptible thread of execution that implements a portion of
+an application's processing. It is normally used to perform processing that is
+too lengthy or too complex to be performed by a fiber or an ISR.
+
+For an overview and important information about Tasks, see :ref:`nanokernel_tasks`.
+
+------
+
 .. doxygengroup:: nanokernel_task
    :project: Zephyr
    :content-only:
@@ -25,6 +41,13 @@ Tasks
 Semaphores
 **********
 
+The nanokernel's :dfn:`semaphore` object type is an implementation of a
+traditional counting semaphore. It is mainly intended for use by fibers.
+
+For an overview and important information about Semaphores, see :ref:`nanokernel_synchronization`.
+
+------
+
 .. doxygengroup:: nanokernel_semaphore
    :project: Zephyr
    :content-only:
@@ -32,6 +55,13 @@ Semaphores
 LIFOs
 *****
 
+The nanokernel's LIFO object type is an implementation of a traditional
+last in, first out queue. It is mainly intended for use by fibers.
+
+For an overview and important information about LIFOs, see :ref:`nanokernel_lifos`.
+
+------
+
 .. doxygengroup:: nanokernel_lifo
    :project: Zephyr
    :content-only:
@@ -39,6 +69,13 @@ LIFOs
 FIFOs
 *****
 
+The nanokernel's FIFO object type is an implementation of a traditional
+first in, first out queue. It is mainly intended for use by fibers.
+
+For an overview and important information about FIFOs, see :ref:`nanokernel_fifos`.
+
+------
+
 .. doxygengroup:: nanokernel_fifo
    :project: Zephyr
    :content-only:
@@ -46,6 +83,14 @@ FIFOs
 Ring Buffers
 ************
 
+The ring buffer is an array-based
+circular buffer, stored in first-in-first-out order. Concurrency control of
+ring buffers is not implemented at this level.
+
+For an overview and important information about ring buffers, see :ref:`nanokernel_ring_buffers`.
+
+------
+
 .. doxygengroup:: nanokernel_ringbuffer
    :project: Zephyr
    :content-only:
@@ -53,6 +98,14 @@ Ring Buffers
 Stacks
 ******
 
+The nanokernel's stack object type is an implementation of a traditional
+last in, first out queue for a limited number of 32-bit data values.
+It is mainly intended for use by fibers.
+
+For an overview and important information about stacks, see :ref:`nanokernel_stacks`.
+
+------
+
 .. doxygengroup:: nanokernel_stack
    :project: Zephyr
    :content-only:
@@ -60,6 +113,14 @@ Stacks
 Timers
 ******
 
+The nanokernel's :dfn:`timer` object type uses the kernel's system clock to
+monitor the passage of time, as measured in ticks. It is mainly intended for use
+by fibers.
+
+For an overview and important information about timers, see :ref:`nanokernel_timers`.
+
+------
+
 .. doxygengroup:: nanokernel_timer
    :project: Zephyr
    :content-only:
@@ -67,6 +128,14 @@ Timers
 Kernel Event Logger
 *******************
 
+The kernel event logger is a standardized mechanism to record events within the
+Kernel while providing a single interface for the user to collect the data.
+
+For an overview and important information about the kernel event logger API,
+see :ref:`nanokernel_event_logger`.
+
+------
+
 .. doxygengroup:: nanokernel_event_logger
    :project: Zephyr
    :content-only: