doc: Add an improved application development section.
Introduces the first part Carol's original contribution. The original contribution is broken up in multiple files. The updated toctree shows the files that will constitute the section. Edits for clarity, redability and markup were also included. The old files were removed. Change-Id: I29364c6bc94322c6235b51850c2d1b9f71eb1ad8 Signed-off-by: L.S. Cook <leonax.cook@intel.com> Signed-off-by: Rodrigo Caballero <rodrigo.caballero.abraham@intel.com>
This commit is contained in:
Rodrigo Caballero
Anas Nashif
parent
a2144857c6
commit
d3803bab2b
4 changed files with 90 additions and 251 deletions
|
|
@ -3,12 +3,30 @@
|
|||
Application Development Primer
|
||||
##############################
|
||||
|
||||
This section contains all information regarding the development of applications for the |codename|.
|
||||
Applications can be classified by whether or not they employ microkernel services in microkernel
|
||||
applications or nanokernel-only applications.
|
||||
This section contains references that explain how to build microkernel
|
||||
and nanokernel applications.
|
||||
|
||||
Audience
|
||||
--------
|
||||
|
||||
Although anybody may use this primer to learn how to build microkernel and
|
||||
nanokernel applications on |project|, the primary audience for this guide
|
||||
is:
|
||||
|
||||
* Application developers coding an application.
|
||||
|
||||
* System architects learning key functionality and usage.
|
||||
|
||||
These subsections explain the entire build process in more detail:
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
apps_microkernel
|
||||
apps_nanokernel
|
||||
apps_dev_process
|
||||
apps_structure
|
||||
apps_kernel_conf
|
||||
apps_object_conf
|
||||
apps_code_dev
|
||||
apps_build
|
||||
apps_run
|
||||
apps_common_procedures
|
||||
|
|
|
|||
67
doc/application/apps_build.rst
Normal file
67
doc/application/apps_build.rst
Normal file
|
|
@ -0,0 +1,67 @@
|
|||
.. _apps_build:
|
||||
|
||||
Build an Application
|
||||
####################
|
||||
|
||||
The build process unifies all components of the application into
|
||||
a coherent application image that can be run on both simulated and real
|
||||
hardware targets.
|
||||
|
||||
.. _building_base:
|
||||
|
||||
Building a Base Application
|
||||
===========================
|
||||
|
||||
Build a base application image to test functionality in a simulated
|
||||
environment and to ultimately run on your hardware target. Before
|
||||
building, keep in mind the following:
|
||||
|
||||
* Each source code directory and sub-directory needs a directory-specific
|
||||
:file:`Makefile`.
|
||||
|
||||
* The :envvar:`$(ZEPHYR_BASE)` environment variable must be set for each
|
||||
console terminal as outlined in :ref:`apps_common_procedures`.
|
||||
|
||||
To build the image, navigate to the :file:`~/appDir`. From here you can
|
||||
build an image for a single target with :command:`make`.
|
||||
|
||||
|
||||
.. _developing_app:
|
||||
|
||||
Developing the Application
|
||||
==========================
|
||||
|
||||
The app development process works best when changes are continually tested.
|
||||
Frequently rebuilding with :command:`make` makes debugging less painful
|
||||
as your application becomes more complex. It's usually a good idea to
|
||||
rebulild and test after any major changes to source files, Makefiles,
|
||||
.conf, or .mdef.
|
||||
|
||||
.. important::
|
||||
|
||||
The Zephyr build system rebuilds only the parts of the application image
|
||||
potentially affected by the changes; as such, the application may rebuild
|
||||
significantly faster than it did when it was first built.
|
||||
|
||||
|
||||
Recovering from Build Failure
|
||||
-----------------------------
|
||||
|
||||
Sometimes the build system doesn't rebuild the application correctly
|
||||
because it fails to recompile one or more necessary files. You can force
|
||||
the build system to rebuild the entire application from scratch with the
|
||||
following procedure:
|
||||
|
||||
#. Navigate to the application directory :file:`~/appDir`.
|
||||
|
||||
#. Run :command:`$ make clean`, or manually delete the generated files, including
|
||||
the :file:`.config` file.
|
||||
|
||||
#. Run :command:`$ make pristine`.
|
||||
|
||||
#. Optionally, override the values specified in the application’s :file:`.conf`
|
||||
file by specifying the kernel configuration option settings needed.
|
||||
|
||||
#. Run :command:`$ make menuconfig`.
|
||||
|
||||
#. Rebuild the application normally. Run :command:`$ make`
|
||||
|
|
@ -1,242 +0,0 @@
|
|||
.. _microkernel_apps:
|
||||
|
||||
How to Develop Microkernel Applications
|
||||
#######################################
|
||||
|
||||
Microkernel applications are composed of .c and . h files that are
|
||||
integrated with the |codename| using MDEF files, Makefiles and .conf files.
|
||||
|
||||
Developing a microkernel application can be accomplished in five steps:
|
||||
|
||||
#. Plan your application and take note of all microkernel objects it will
|
||||
need.
|
||||
|
||||
#. Create the MDEF file for those microkernel objects.
|
||||
|
||||
#. Code the application source files.
|
||||
|
||||
#. Create the Makefiles to add the application's source files to the
|
||||
kernel's build system.
|
||||
|
||||
#. Compile and test your application.
|
||||
|
||||
The following procedures show examples of how to accomplish this.
|
||||
|
||||
Before Starting the Development of a Microkernel App
|
||||
****************************************************
|
||||
|
||||
Before you begin, read the :ref:`overview` and the :ref:`quick_start`.
|
||||
Then read the :ref:`collaboration_guidelines`. Finally, review
|
||||
the developers information contained in :ref:`developing_zephyr` and build a
|
||||
sample application, like :file:`hello.c`.
|
||||
|
||||
Once you have completed those tasks, you should be able to answer:
|
||||
|
||||
* How does the |codename| and its key objects work?
|
||||
|
||||
* What is the difference between a nanokernel and a microkernel?
|
||||
|
||||
* How is the |codename| built?
|
||||
|
||||
* What rules and conventions must the development follow?
|
||||
|
||||
If you are able to answer these questions, you can start developing your
|
||||
application.
|
||||
|
||||
Creating an MDEF File
|
||||
*********************
|
||||
|
||||
The :abbr:`MDEF (Microkernel DEfinitions File)` contains the configuration
|
||||
entries for the kernel's objects. Therefore, it must include all microkernel
|
||||
objects used in the C code of the application. Each line in a MDEF file
|
||||
defines one item, unless it is empty or a comment line. All lines starting
|
||||
with a ``%`` are comments.
|
||||
|
||||
The contents of an MDEF file can be, for example:
|
||||
|
||||
.. code-block:: console
|
||||
:linenos:
|
||||
|
||||
% TASKGROUP NAME
|
||||
% =======================
|
||||
TASKGROUP ITERATIONS
|
||||
|
||||
% TASK NAME PRIO ENTRY STACK GROUPS
|
||||
% ========================================================
|
||||
TASK MASTER 7 master 1024 [EXE]
|
||||
TASK PLOTTER 5 plotter 1024 [EXE]
|
||||
TASK TASK10 6 task 2048 [ITERATIONS]
|
||||
TASK TASK11 6 task 2048 [ITERATIONS]
|
||||
TASK TASK12 6 task 2048 [ITERATIONS]
|
||||
TASK TASK13 6 task 2048 [ITERATIONS]
|
||||
|
||||
% FIFO NAME DEPTH WIDTH
|
||||
% =============================
|
||||
FIFO PLOTQ 200 20
|
||||
FIFO COORDQ 16 16
|
||||
FIFO SCREENQ 16 20
|
||||
|
||||
% SEMA NAME
|
||||
% =============
|
||||
SEMA FINISHED
|
||||
|
||||
% MUTEX NAME
|
||||
% =====================
|
||||
MUTEX PRINT
|
||||
MUTEX GRAPH
|
||||
MUTEX POPPARAM
|
||||
MUTEX PUSHPARAM
|
||||
|
||||
Each object must follow a specific syntax. The object name must be an
|
||||
alphanumeric, with an alphabetical first character. Upper- and lowercase
|
||||
letters are allowed; embedded spaces are not. The convention is to give
|
||||
each object a name that is in all uppercase letters. This makes it easy to
|
||||
distinguish between object names and variable names. Finally, all names must
|
||||
be unique. A pipe cannot have the same name as a FIFO, even though they are
|
||||
different types.
|
||||
|
||||
See :ref:`microkernel` for the correct syntax for the most important
|
||||
microkernel objects.
|
||||
|
||||
Coding the Application's Source Files
|
||||
*************************************
|
||||
|
||||
We recommend you follow the project's :ref:`coding_style` when coding your
|
||||
application. The required MDEF file can be in any folder of your
|
||||
application as long as the path is referenced in the application's Makefile.
|
||||
|
||||
The application's root folder must contain a Makefile that links the
|
||||
application to the kernel; see :ref:`root_makefile` for details. Each folder
|
||||
in your source tree must have a Makefile that links the folder's
|
||||
contents with the rest of your source tree; see :ref:`source_makefile` for
|
||||
details.
|
||||
|
||||
Finally, remember that your application will be compiled into the
|
||||
kernel. If all MDEF files and Makefiles are correct and in place, the build
|
||||
system links your application with the kernel. The kernel delivers binaries,
|
||||
one for each selected platform, for testing.
|
||||
|
||||
.. _app_makefile:
|
||||
|
||||
Creating the Makefiles for the Application
|
||||
******************************************
|
||||
|
||||
This section explains how the Makefiles within the folders of your
|
||||
application link it to the kernel. The build system's Makefile will assume that
|
||||
the application's root folder has a :file:`src` folder containing all
|
||||
source files. The name of the folder can be changed to whatever name suits
|
||||
your needs. The :file:`src` folder can have as many subfolders as needed but
|
||||
all folders must contain a Makefile.
|
||||
|
||||
The contents of the Makefiles can fit the needs of your application.
|
||||
However, some contents are required for a successful integration. The
|
||||
contents required in the application's Makefile at the main folder differ
|
||||
from those required in the Makefiles inside the source folders.
|
||||
|
||||
For detailed information regarding the build system's Makefiles see:
|
||||
:ref:`kbuild_makefiles`.
|
||||
|
||||
.. _root_makefile:
|
||||
|
||||
The Application's Root Folder Makefile
|
||||
======================================
|
||||
|
||||
The Makefile in the application's root folder must contain at least these
|
||||
entries:
|
||||
|
||||
* :makevar:`MDEF_FILE`: The name of the application's MDEF file.
|
||||
|
||||
* :makevar:`KERNEL_TYPE`: Either `nano` for nanokernel applications or
|
||||
`micro` for microkernel applications.
|
||||
|
||||
* :makevar:`PLATFORM_CONFIG`: The name of the platform configuration that
|
||||
will be used as a default.
|
||||
|
||||
* :makevar:`CONF_FILE`: The name of the .conf file or files of the
|
||||
application.
|
||||
|
||||
* ``include ${ZEPHYR_BASE}/Makefile.inc`` This instruction adds the contents
|
||||
of the :file:`Makefile.inc` found in the kernel's root folder.
|
||||
|
||||
For more information about Makefile variables see :ref:`kbuild_project`.
|
||||
|
||||
Examples
|
||||
--------
|
||||
|
||||
The following example shows a generic application's root folder Makefile:
|
||||
|
||||
.. code-block:: make
|
||||
:linenos:
|
||||
:emphasize-lines: 4, 6
|
||||
|
||||
MDEF_FILE = application.mdef
|
||||
KERNEL_TYPE = micro
|
||||
PLATFORM_CONFIG ?= basic_atom
|
||||
CONF_FILE = application_$(ARCH).conf
|
||||
|
||||
include ${ZEPHYR_BASE}/Makefile.inc
|
||||
|
||||
Line 4 shows how to conditionally add files. The build system replaces the
|
||||
variable ``$(ARCH)`` for each supported architecture.
|
||||
|
||||
The entry in line 6 includes all entries located in :file:`Makefile.inc`
|
||||
at the kernel's root folder. The entries let the build system know that
|
||||
your application has to be included as part of the build.
|
||||
|
||||
The next example comes from the kernel's code, specifically from
|
||||
:file:`samples/microkernel/apps/hello_world/Makefile`:
|
||||
|
||||
.. literalinclude:: ../../samples/microkernel/apps/hello_world/Makefile
|
||||
:language: make
|
||||
:lines: 1-6
|
||||
:emphasize-lines: 1, 4
|
||||
:linenos:
|
||||
|
||||
The file :file:`proj.mdef` from line 1 can be found in
|
||||
:file:`microkernel/apps/hello_world/` and contains the configuration entries
|
||||
of all microkernel objects used in the application. For more information
|
||||
regarding MDEF files see the :ref:`microkernel` documentation.
|
||||
|
||||
The entry in line 4 references the files :file:`proj_arm.conf` and
|
||||
:file:`proj_x86.conf` also found at that location. Those files include the
|
||||
configuration values that differ from the default. See
|
||||
:ref:`configuration_snippets` for details.
|
||||
|
||||
|
||||
The Application's Source Folders Makefiles
|
||||
==========================================
|
||||
|
||||
The Makefiles in the source folders add the files within the folders to the
|
||||
build system. See :ref:`makefile_conventions` for details.
|
||||
|
||||
Examples
|
||||
--------
|
||||
|
||||
Example 1 shows the source folder Makefile of the microkernel Hello World
|
||||
application.
|
||||
|
||||
Example 1:
|
||||
|
||||
.. literalinclude:: ../../samples/microkernel/apps/hello_world/src/Makefile
|
||||
:language: make
|
||||
:lines: 1-4
|
||||
:emphasize-lines: 1, 3
|
||||
:linenos:
|
||||
|
||||
Line 1 allows the application's source file access to the functions included
|
||||
in the project's .h files. Line 3 adds the :file:`hello.c` to the build
|
||||
system.
|
||||
|
||||
Example 2 shows the source folder Makefile of the microkernel Philosophers
|
||||
application.
|
||||
|
||||
Example 2:
|
||||
|
||||
.. literalinclude:: ../../samples/microkernel/apps/philosophers/src/Makefile
|
||||
:language: make
|
||||
:lines: 1-4
|
||||
:emphasize-lines: 3
|
||||
:linenos:
|
||||
|
||||
Line 3 adds the :file:`phil_fiber.c` and :file:`phil_task.c` files. Multiple
|
||||
files can be added on a single line by separating them with a space.
|
||||
|
|
@ -1,4 +0,0 @@
|
|||
.. _apps_nanokernel:
|
||||
|
||||
How to Develop nanokernel Applications
|
||||
######################################
|
||||
Loading…
Add table
Add a link
Reference in a new issue