zephyr/doc/application/apps_microkernel.rst

245 lines
8.3 KiB
ReStructuredText

.. _microkernel_apps:
How to Develop Microkernel Applications
#######################################
Microkernel applications are comprised 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 explain how to accomplish this using examples.
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 this 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
:lineos:
% 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 name of an object must be an
alphanumeric, with an alphabetical first character. Upper- and lowercase
letters are allowed, but 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 needs to 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 will assume that there
is an application's root folder with 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 the 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 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 all the information regarding the 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 the 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. For more information
regarding these configuration snippets see: :ref:`configuration_snippets`.
The Application's Source Folders Makefiles
==========================================
The Makefiles in the source folders add the files within the folders to the
build system. All information about adding source files and directories to
your project can be found in :ref:`makefile_conventions`.
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.