doc: Fix labels markup and add figures to Application Primer.

Changes the labels to be consistent with the rest of the documentation.
Fixed other minor markup and language issues.
Adds the missing figures for apps_kernel_conf.rst

Change-Id: I34a7650c04bb2d1f525eaad4efa7395f8272c88f
Signed-off-by: Rodrigo Caballero <rodrigo.caballero.abraham@intel.com>

doc/application/application.rst

@@ -10,7 +10,7 @@ Audience
 --------
 
 Although anybody may use this primer to learn how to build microkernel and
-nanokernel applications on |project|, the primary audience for this guide
+nanokernel applications on the |codename|, the primary audience for this guide
 is:
 
 * Application developers coding an application.

doc/application/apps_build.rst

@@ -54,8 +54,8 @@ following procedure:
 
 #. Navigate to the application directory :file:`~/appDir`.
 
-#. Run :command:`$ make clean`, or manually delete the generated files, including
+#. Run :command:`$ make clean`, or manually delete the generated files,
-   the :file:`.config` file.
+   including the :file:`.config` file.
 
 #. Run :command:`$ make pristine`.
 

doc/application/apps_code_dev.rst

@@ -3,55 +3,55 @@
 Application Code Development
 ############################
 
-* `Services`_
+.. contents::
-* `Understanding Naming Conventions`_
+   :local:
-* `Understanding src Directory Makefile Requirements`_
+   :depth: 1
-* `Adding Source Files and Makefiles to src Directories`_
+
-* `Enhancing the Zephyr Kernel`_
+.. _develop_services:
 
 Services
 ********
-.. _Services:
 
-The |codename| kernel services architecture has services that are
+The |codename| services architecture has services that are
 specific to the microkernel, services that are specific to the
 nanokernel, and services that are common, or shared, between the
 two.
 
-**Microkernel Services**
+Microkernel Services
+====================
 
 For a complete list of microkernel services, including a description
-of each with code examples, see :ref:`Microkernel Services`.
+of each with code examples, see :ref:`microkernel`.
 
 .. _note::
 
-  There are more microkernel services than those defined in
+   There are more microkernel services than those defined in
-  the MDEF.
+   the MDEF.
 
-**Nanokernel Services**
+Nanokernel Services
+===================
 
 For a complete list of nanokernel services, including a description
-of each with code examples, see :ref:`Nanokernel Services`.
+of each with code examples, see :ref:`nanokernel`.
 
-**Common Services**
+Common Services
+===============
 
 For a complete list of services common to both the nanokernel and
 microkernel, including a description of each with code examples,
-see :ref:`Common Services`.
+see :ref:`common_kernel_services`.
 
 
 Procedures and Conventions
 **************************
 
-. ._Understanding Naming Conventions:
-
 Understanding Naming Conventions
 ================================
 
-|codename| limits the use of some prefixes to internal use only. For
+The kernel limits the use of some prefixes to internal use only. For
 more information, see :ref:`naming_conventions`.
 
-.. _Understanding src Directory Makefile Requirements:
+.. _src_makefiles_reqs:
 
 Understanding src Directory Makefile Requirements
 =================================================
@@ -75,8 +75,7 @@ directory:
    The src directory Makefiles discussed here are distinct from
    the top-level application Makefile.
 
-
+.. _src_files_directories:
-.. _Adding Source Files and Makefiles to src Directories:
 
 Adding Source Files and Makefiles to src Directories
 ====================================================
@@ -90,8 +89,8 @@ file names identified in the Makefile.
 
 .. _note::
 
-  Source code without an associated Makefile is not included
+   Source code without an associated Makefile is not included
-  when the application is built.
+   when the application is built.
 
 Before You Begin
 -----------------
@@ -110,25 +109,25 @@ Steps
 
 2. Create a :file:`Makefile` for each :file:`src` directory.
 
- a) Add the following line to each :file:`Makefile`:
+   a) Add the following line to each :file:`Makefile`:
 
-  .. code-block:: make
+      .. code-block:: make
 
-     ccflags-y += ${PROJECTINCLUDE}
+         ccflags-y += ${PROJECTINCLUDE}
 
 
- b) Use the following syntax to add file references:
+   b) Use the following syntax to add file references:
 
-  .. code-block:: make
+      .. code-block:: make
 
-     obj-y += file.o file.o
+         obj-y += file.o file.o
 
 
- c) Use the following syntax to add directory references:
+   c) Use the following syntax to add directory references:
 
-  .. code-block:: make
+      .. code-block:: make
 
-     obj-y += directory_name/**
+         obj-y += directory_name/**
 
 
 Example src Makefile
@@ -144,7 +143,7 @@ examine this file in context, navigate to:
    obj-y = phil_fiber.o phil_task.o
 
 
-.. _`Enhancing the Zephyr Kernel:
+.. _`enhancing_kernel`:
 
 Enhancing the Zephyr Kernel
 ===========================

doc/application/apps_common_procedures.rst

@@ -9,13 +9,13 @@ and referred to from the procedures that require them.
 Procedures
 **********
 
-* `Setting Environment Variables`_
+* `set_environment_variables`_
 
 Setting Environment Variables
 =============================
 
 Set environment variables every time you open a terminal console to work on
-|codename| applications.
+|codename|'s applications.
 
 Steps
 -----
@@ -25,25 +25,24 @@ Steps
 
    a) For a Yocto toolchain:
 
-    .. code-block:: bash
+      .. code-block:: bash
 
-     $ export ZEPHYR_GCC_VARIANT=yocto
+         $ export ZEPHYR_GCC_VARIANT=yocto
-     $ export YOCTO_SDK_INSTALL_DIR=<yocto-installation-path>
+         $ export YOCTO_SDK_INSTALL_DIR=<yocto-installation-path>
 
    Go to Step 2.
 
    b) For an Xtools toolchain:
 
-    .. code-block:: bash
+      .. code-block:: bash
 
-     $ export ZEPHYR_GCC_VARIANT=xtools
+         $ export ZEPHYR_GCC_VARIANT=xtools
-     $ export XTOOLS_TOOLCHAIN_PATH=/opt/otc_viper/x-tools/
+         $ export XTOOLS_TOOLCHAIN_PATH=/opt/otc_viper/x-tools/
-     $ export QEMU_BIN_PATH=/usr/local/bin
+         $ export QEMU_BIN_PATH=/usr/local/bin
 
-2. Navigate to the |codename| installation directory and enter:
+2. To set the environment variable :envvar:`$(ZEPHYR_BASE)`, navigate to the
+   kernel's installation directory and enter:
 
-  .. code-block:: bash
+      .. code-block:: bash
 
-   $ source zephyr-env.sh
+         $ source zephyr-env.sh
-
-  To set the environment variable :envvar:`$(ZEPHYR_BASE)`.

doc/application/apps_dev_process.rst

@@ -3,13 +3,13 @@
 Application Development Workflow
 ################################
 
-The application development workflow identifies procedures needed to create, build, and
+The application development workflow identifies the procedures needed to
-run a |codename| microkernel or nanokernel application.
+create, build, and run a |codename|'s microkernel or nanokernel application.
 
 Before you build
 ----------------
 
-* Check that your Linux host meets the minimum requirements specified in the |codename|
+* Check that your Linux host meets the minimum requirements specified in the
   :ref:`quick_start`.
 
 * Check that environment variables have been configured correctly as outlined
@@ -18,42 +18,41 @@ Before you build
 Workflow
 --------
 
-1. Create a directory structure for your Zephyr application
+1. Create a directory structure for your Zephyr application.
 
-   a) :ref:`Creating an Application and Source Code Directory using the
+   a) :ref:`create_directory_structure`
-      CLI`
 
-  and add a Makefile
+2. Add a Makefile
 
-   b) :ref:`Creating an Application Makefile`
+   b) :ref:`create_src_makefile`
 
-2. Define the application's default kernel configuration using
+3. Define the application's default kernel configuration using
    :ref:`Defining the Application's Default Kernel Configuration`.
 
-3. Define kernel configuration override options for the application
+4. Define kernel configuration override options for the application
    using :ref:`Overriding the Application's Default Kernel
    Configuration`.
 
-4. For a microkernel application, define objects as you develop code
+5. For a microkernel application, define objects as you develop code
    using :ref:`Creating and Configuring an MDEF File for a Microkernel
    Application`.
 
-5. For all applications, define nanokernel objects as you need them in
+6. For all applications, define nanokernel objects as you need them in
    code.
 
-6. Develop source code and add source code files to the src directory.
+7. Develop source code and add source code files to the src directory.
 
    * :ref:`Understanding Naming Conventions`
    * :ref:`Understanding src Directory Makefile Requirements`
    * :ref:`Adding Source Files and Makefiles to src Directories`
 
-7. Build an application image.
+8. Build an application image.
 
    * :ref:`Building an Application`
    * :ref:`Rebuilding an Application`
 
-8. To test the application image's functionality on simulated hardware
+9. To test the application image's functionality on simulated hardware
-   with QEMU, see :ref:`Running an Application`
+   with QEMU, see :ref:`Running an Application`.
 
-9. To load an application image on a target hardware, see  using :ref:`Platform`
+10. To load an application image on a target hardware, see using
-   documentation.
+    :ref:`Platform` documentation.

doc/application/apps_kernel_conf.rst

@@ -23,18 +23,16 @@ it is specified:
    When the default platform configuration settings are sufficient
    for your application, a :file:`prj.conf` file is not needed.
    Skip ahead to
-  :ref:`Overriding the Application's Default Kernel Configuration`.
+  :ref:`override_kernel_conf`.
 
 
 Procedures
 **********
 
-* `Defining the Application's Default Kernel Configuration`_
+* `define_default_kernel_conf`_
 
 * `Overriding the Application's Default Kernel Configuration`_
 
-.. _Defining the Application's Default Kernel Configuration:
-
 The procedures that follow describe how to configure a :file:`prj.conf`
 file and how to configure kernel options for microkernel and nanokernel
 applications. For information on how to work with kernel option
@@ -46,6 +44,8 @@ inter-dependencies and platform configuration-default options, see the
    There are currently a number of experimental options not yet
    fully supported.
 
+.. _define_default_kernel_conf:
+
 Defining the Application's Default Kernel Configuration
 =======================================================
 
@@ -97,7 +97,7 @@ Steps
 3. Save and close the file.
 
 
-.. _Overriding the Application's Default Kernel Configuration:
+.. _override_kernel_conf:
 
 Overriding the Application's Default Kernel Configuration
 =========================================================
@@ -107,6 +107,7 @@ temporarily alter the application’s configuration, perhaps
 to test the effect of a change.
 
 .. _note::
+
    If you want to permanently alter the configuration you
    should revise the :file:`.conf` file.
 

doc/application/apps_object_conf.rst

@@ -9,12 +9,12 @@ See :ref:`microkernel` for example MDEF entries.
 Procedure
 *********
 
-.. _Creating and Configuring an MDEF File for a Microkernel Application:
+.. _create_mdef:
 
-Creating and Configuring an MDEF File for a Microkernel Application
+Creating and Configuring an MDEF for a Microkernel Application
-===================================================================
+==============================================================
 
-Create the MDEF file to define microkernel objects used in your
+Create the MDEF to define microkernel objects used in your
 application when they apply to the application as a whole.
 You do not need to define every object before writing code. In
 some cases, the necessary objects aren't obvious until you begin
@@ -23,7 +23,7 @@ before your application will compile successfully.
 
 .. _note::
 
-  Nanokernel applications do not use an MDEF file because microkernel
+  Nanokernel applications do not use an MDEF because microkernel
   objects cannot be used in applications of this type.
 
 Before you begin
@@ -37,7 +37,7 @@ Before you begin
 Steps
 -----
 
-1. Create an MDEF file in your application directory
+1. Create an MDEF in your application directory
    (:file:`~/appDir ~) using
    the name you specified in your application Makefile.
    (See :ref:`Creating an Application Makefile`).
@@ -46,72 +46,51 @@ Steps
 
   $ touch prj.mdef
 
- The default MDEF file name is :file:`prj.mdef`.
+ The default MDEF name is :file:`prj.mdef`.
 
 2. Open the file using a standard text editor.
 
 3. Add settings to the file to suit your application.
 
- The syntax for objects that can be defined in :file:`.mdef`
+   The syntax for objects that can be defined in :file:`.mdef`
- is:
+   is:
 
- TASK name priority entry_point stack_size groups
+   TASK name priority entry_point stack_size groups
 
- TASKGROUP name
+   TASKGROUP name
 
- MUTEX name
+   MUTEX name
 
- SEMA name
+   SEMA name
 
- FIFO name depth width
+   FIFO name depth width
 
- PIPE name buffer_size
+   PIPE name buffer_size
 
- MAILBOX name
+   MAILBOX name
 
- MAP name num_blocks block_size
+   MAP name num_blocks block_size
 
- POOL name min_block_size max_block_size numMax
+   POOL name min_block_size max_block_size numMax
 
 .. _note::
 
-  Some microkernel objects, such as Task IRQs, are not
+   Some microkernel objects, such as Task IRQs, are not
-  defined in an :file:`.mdef` file.
+   defined in an :file:`.mdef` file.
 
-The following example shows the content of the :file:`.mdef`
+The following example shows the content of the
-file for the Philosophers' sample application. The sample
+:file:`samples/microkernel/apps/philosophers/proj.mdef`
+for the Philosophers' sample application. The sample
 uses seven tasks and six mutexes.
 
-Example MDEF File
+Example MDEF
------------------
+------------
-
-.. code-block:: c
-
- % Application : DiningPhilosophers
- % TASKGROUP NAME
- % ==============
- TASKGROUP PHI
- % TASK NAME PRIO ENTRY STACK GROUPS
- % ==================================================
- TASK philTask 5 philDemo 1024 [EXE]
- TASK phi1Task0 6 philEntry 1024 [PHI]
- TASK philTask1 6 philEntry 1024 [PHI]
- TASK philTask2 6 philEntry 1024 [PHI]
- TASK philTask3 6 philEntry 1024 [PHI]
- TASK philTask4 6 philEntry 1024 [PHI]
- TASK philTask5 6 philEntry 1024 [PHI]
- % MUTEX NAME
- % ================
- MUTEX forkMutex0
- MUTEX forkMutex1
- MUTEX forkMutex2
- MUTEX forkMutex3
- MUTEX forkMutex4
- MUTEX forkMutex5
 
+.. literalinclude:: ../../samples/microkernel/apps/philosophers/proj.mdef
+   :linenos:
 
 Related Topics
 --------------
 
-:ref:`Understanding src Directory Makefile Requirements`
+:ref:`src_makefiles_reqs`
-:ref:`Adding Source Files and Makefiles to src Directories`
+:ref:`src_files_directories`

doc/application/apps_run.rst

@@ -10,7 +10,7 @@ in lieu of) loading and running it on actual target hardware.
 Procedures
 **********
 
-.. _qemu:
+.. _run_app_qemu:
 
 Running an Application using QEMU
 =================================