unified/doc: Update Application Development Primer
Removes references to nanokernel/microkernel. Corrects numerous errors in content. Improves consistency in presentation of information. Change-Id: I83895d2cb03181da377b23323afc104ae32865a2 Signed-off-by: Allan Stephens <allan.stephens@windriver.com>
This commit is contained in:
Allan Stephens
Anas Nashif
parent
a3e23bc022
commit
7567c979dd
@ -3,29 +3,38 @@
|
||||
Application Development Primer
|
||||
##############################
|
||||
|
||||
This section contains references that explain how to build microkernel
|
||||
and nanokernel applications.
|
||||
This section outlines how to create, build, and run a Zephyr application.
|
||||
|
||||
Audience
|
||||
--------
|
||||
|
||||
Although anybody may use this primer to learn how to build microkernel and
|
||||
nanokernel applications, the primary audience for this guide is:
|
||||
Although anybody may use this primer, 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:
|
||||
Before You Start
|
||||
----------------
|
||||
|
||||
* Check that your Linux host meets the minimum requirements specified in the
|
||||
:ref:`getting_started`.
|
||||
|
||||
* Check that environment variables have been configured correctly as outlined
|
||||
in :ref:`apps_common_procedures`.
|
||||
|
||||
Workflow
|
||||
--------
|
||||
|
||||
The following sections explain the application development process
|
||||
from start to finish.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
apps_overview
|
||||
apps_dev_process
|
||||
apps_structure
|
||||
apps_kernel_conf
|
||||
apps_object_conf
|
||||
apps_code_dev
|
||||
apps_build
|
||||
apps_run
|
||||
|
||||
@ -3,84 +3,115 @@
|
||||
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.
|
||||
The Zephyr build system compiles and links all components of an application
|
||||
into a single application image that can be run on simulated hardware or real
|
||||
hardware.
|
||||
|
||||
.. _building_base:
|
||||
.. contents:: Procedures
|
||||
:local:
|
||||
:depth: 1
|
||||
|
||||
Building a Base Application
|
||||
===========================
|
||||
Building an 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:
|
||||
The build system allows you to easily build an application using the
|
||||
application's existing configuration. However, you can also build it
|
||||
using different configuration settings, if desired.
|
||||
|
||||
* Each source code directory and sub-directory needs a directory-specific
|
||||
:file:`Makefile`.
|
||||
Before you begin
|
||||
----------------
|
||||
|
||||
* The :envvar:`$(ZEPHYR_BASE)` environment variable must be set for each
|
||||
console terminal as outlined in :ref:`apps_common_procedures`.
|
||||
* Ensure you have added all application-specific code to the application
|
||||
directory, as described in :ref:`apps_code_dev`. Ensure each source code
|
||||
directory and sub-directory has its own :file:`Makefile`.
|
||||
|
||||
To build the image, navigate to the :file:`~/appDir`. From here you can
|
||||
build an image for a single target with :command:`make`.
|
||||
* Ensure you have configured the application's kernel, as described
|
||||
in :ref:`apps_kernel_conf`.
|
||||
|
||||
* Ensure the Zephyr environment variables are set for each console terminal;
|
||||
see :ref:`apps_common_procedures`.
|
||||
|
||||
.. _developing_app:
|
||||
Steps
|
||||
-----
|
||||
|
||||
Developing the Application
|
||||
==========================
|
||||
#. Navigate to the application directory :file:`~/appDir`.
|
||||
|
||||
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
|
||||
rebuild and test after any major changes to source files, Makefiles,
|
||||
.conf, or .mdef.
|
||||
#. Enter the following command to build the application's :file:`zephyr.elf`
|
||||
image using the configuration settings for the board type specified
|
||||
in the application's :file:`Makefile`.
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ make
|
||||
|
||||
If desired, you can build the application using the configuration settings
|
||||
specified in an alternate :file:`.conf` file using the :code:`CONF_FILE`
|
||||
parameter. These settings will override the settings in the application's
|
||||
:file:`.config` file or its default :file:`.conf` file. For example:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ make CONF_FILE=prj.alternate.conf
|
||||
|
||||
If desired, you can build the application for a different board type
|
||||
than the one specified in the application's :file:`Makefile`
|
||||
using the :code:`BOARD` parameter. For example:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ make BOARD=arduino_101
|
||||
|
||||
Both the :code:`CONF_FILE` and :code:`BOARD` parameters can be specified
|
||||
when building the application.
|
||||
|
||||
Rebuilding an Application
|
||||
=========================
|
||||
|
||||
Application development is usually fastest when changes are continually tested.
|
||||
Frequently rebuilding your application makes debugging less painful
|
||||
as the application becomes more complex. It's usually a good idea to
|
||||
rebuild and test after any major changes to the application's source files,
|
||||
Makefiles, or configuration settings.
|
||||
|
||||
.. 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.
|
||||
The Zephyr build system rebuilds only the parts of the application image
|
||||
potentially affected by the changes. Consequently, rebuilding an application
|
||||
is often significantly faster than building it the first time.
|
||||
|
||||
Steps
|
||||
-----
|
||||
|
||||
Recovering from Build Failure
|
||||
-----------------------------
|
||||
#. Follow the steps specified in `Building an Application`_ above.
|
||||
|
||||
Recovering from a 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:
|
||||
|
||||
Steps
|
||||
-----
|
||||
|
||||
#. Navigate to the application directory :file:`~/appDir`.
|
||||
|
||||
#. Run :command:`$ make clean`, or manually delete the generated files,
|
||||
including the :file:`.config` file.
|
||||
#. Enter the following command to delete the application's generated files
|
||||
for the specified board type, except for the :file:`.config` file that
|
||||
contains the application's current configuration information.
|
||||
|
||||
#. Run :command:`$ make pristine`.
|
||||
.. code-block:: console
|
||||
|
||||
#. You have the option to configure your project by running
|
||||
:command:`$ make menuconfig`. If you choose not to configure your project
|
||||
via :command:`menuconfig`, you can choose a configuration tailored for a
|
||||
supported board later.
|
||||
If you choose to use :command:`$ make menuconfig` be prepared to configure
|
||||
all the parameters correctly for your specific board.
|
||||
$ make [BOARD=<type>] clean
|
||||
|
||||
#. Rebuild the application normally. Run :command:`$ make`. You can choose to
|
||||
specify a default configuration for a supported board using the parameter
|
||||
:command:`BOARD`. For example: :command:`$ make BOARD=arduino_101`.
|
||||
You can see the boards that currently support a default configuration by
|
||||
running the command :command:`$ make help`
|
||||
Alternatively, enter the following command to delete *all* generated files
|
||||
for *all* board types, including the :file:`.config` files that contain
|
||||
the application's current configuration information for those board types.
|
||||
|
||||
#. Optionally, you can override the :file:`.config` file configuration (obtained
|
||||
as a result of :command:`menuconfig` or :command:`BOARD` parameters) by using
|
||||
the application’s :file:`.conf` file. Declare the kernel configuration settings
|
||||
that cover the specific needs of your project.
|
||||
.. code-block:: console
|
||||
|
||||
$ make pristine
|
||||
|
||||
.. note::
|
||||
We recommend to use the :command:`BOARD` parameter, since it will load
|
||||
a preset configuration already tested to work properly with
|
||||
that board. You can always tune the board configuration. Override specific
|
||||
configuration elements by providing a configuration snippet file. Let the build
|
||||
system know about it with the :command:`CONF_FILE` environment variable.
|
||||
#. Rebuild the application normally following the steps specified
|
||||
in `Building an Application`_ above.
|
||||
|
||||
@ -1,122 +1,90 @@
|
||||
.. _apps_code_dev:
|
||||
|
||||
Application Code Development
|
||||
############################
|
||||
Add Application-Specific Code
|
||||
#############################
|
||||
|
||||
.. contents::
|
||||
Application-specific source code is typically added to an application
|
||||
by placing it in the application directory itself (:file:`~/appDir`).
|
||||
However, in some cases an application may also need to modify
|
||||
or enhance the kernel itself.
|
||||
|
||||
.. contents:: Procedures
|
||||
:local:
|
||||
:depth: 1
|
||||
|
||||
.. _develop_services:
|
||||
Adding Source Code to an Application Directory
|
||||
**********************************************
|
||||
|
||||
Services
|
||||
********
|
||||
Understanding Source Code Requirements
|
||||
======================================
|
||||
|
||||
The Zephyr kernel 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
|
||||
====================
|
||||
|
||||
For a complete list of microkernel services, including a description
|
||||
of each with code examples, see :ref:`microkernel`.
|
||||
Application-specific source code files are normally added to the application's
|
||||
:file:`src` directory. If the application adds a large number of files
|
||||
the developer can group them into sub-directories under :file:`src`,
|
||||
to whatever depth is needed. The developer must supply a :file:`Makefile`
|
||||
for the :file:`src` directory, as well as for each sub-directory under
|
||||
:file:`src`.
|
||||
|
||||
.. note::
|
||||
|
||||
There are more microkernel services than those defined in
|
||||
the MDEF.
|
||||
These Makefiles are distinct from the top-level application Makefile
|
||||
that appears in :file:`~/appDir`.
|
||||
|
||||
Nanokernel Services
|
||||
===================
|
||||
Application-specific source code should not use symbol name prefixes
|
||||
that have been reserved by the kernel for its own use.
|
||||
For more information, see
|
||||
`Naming Conventions <https://wiki.zephyrproject.org/view/Coding_conventions#Naming_Conventions>`_.
|
||||
|
||||
For a complete list of nanokernel services, including a description
|
||||
of each with code examples, see :ref:`nanokernel`.
|
||||
Understanding Makefile Requirements
|
||||
===================================
|
||||
|
||||
Common Services
|
||||
===============
|
||||
The following requirements apply to all Makefiles in the :file:`src`
|
||||
directory, including any sub-directories it may have.
|
||||
|
||||
For a complete list of services common to both the nanokernel and
|
||||
microkernel, including a description of each with code examples,
|
||||
see :ref:`common`.
|
||||
* During the build process, Kbuild identifies the source files to compile
|
||||
into object files by matching the file names identified in
|
||||
the application's Makefile(s).
|
||||
|
||||
.. important::
|
||||
|
||||
Procedures and Conventions
|
||||
**************************
|
||||
A source file that is not referenced by any Makefile is not included
|
||||
when the application is built.
|
||||
|
||||
Understanding Naming Conventions
|
||||
================================
|
||||
* A Makefile cannot directly reference source code. It can only
|
||||
reference object files (:file:`.o` files) produced from source code files.
|
||||
|
||||
The kernel limits the use of some prefixes to internal use only. For
|
||||
more information, see `naming conventions`_.
|
||||
* A Makefile can only reference files in its own directory or in the
|
||||
sub-directories of that directory.
|
||||
|
||||
.. _naming conventions: https://wiki.zephyrproject.org/view/Coding_conventions#Naming_Conventions
|
||||
|
||||
.. _src_makefiles_reqs:
|
||||
|
||||
Understanding src Directory Makefile Requirements
|
||||
=================================================
|
||||
|
||||
The src directory needs a Makefile to specify how to build the application
|
||||
source code. Likewise, any sub-directory within src must also have its own
|
||||
Makefile. The following requirements apply to all Makefiles in the src
|
||||
directory:
|
||||
|
||||
* A Makefile must reference only its own files and sub-directories.
|
||||
|
||||
* Code that references a file outside the directory cannot be included in the
|
||||
Makefile; the referenced file is included only in its own directory's
|
||||
Makefile.
|
||||
|
||||
* A Makefile cannot directly reference source code; it can only
|
||||
reference object files (.o files) produced by source code.
|
||||
|
||||
.. note::
|
||||
|
||||
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
|
||||
====================================================
|
||||
|
||||
Source code and associated Makefiles specify the how the
|
||||
application image is built. In a Makefile, multiple files may be
|
||||
referenced from a single-line entry. However, a separate line must
|
||||
be used to reference each directory. During the build process, Kbuild
|
||||
finds the source files to generate the object files by matching the
|
||||
file names identified in the Makefile.
|
||||
|
||||
.. note::
|
||||
|
||||
Source code without an associated Makefile is not included
|
||||
when the application is built.
|
||||
* A Makefile may reference multiple files from a single-line entry.
|
||||
However, a separate line must be used to reference each directory.
|
||||
|
||||
Before You Begin
|
||||
-----------------
|
||||
|
||||
* Ensure you have created an application directory, as described
|
||||
in :ref:`apps_structure`.
|
||||
|
||||
* The Zephyr environment variable must be set for each console
|
||||
terminal using :ref:`apps_common_procedures`.
|
||||
|
||||
* Many useful code examples cam be found at :file:`\$ZEPHYR_BASE/samples`.
|
||||
|
||||
Steps
|
||||
-----
|
||||
|
||||
1. Create a directory structure for your source code in :file:`src`
|
||||
#. Create a directory structure for your source code in :file:`src`
|
||||
and add your source code files to it.
|
||||
|
||||
For many useful code examples, see :ref:`common`,
|
||||
:ref:`microkernel`, and :ref:`nanokernel`.
|
||||
|
||||
2. Create a :file:`Makefile` for each :file:`src` directory.
|
||||
#. Create a :file:`Makefile` in the :file:`src` directory. Then create
|
||||
an additional :file:`Makefile` in each of the sub-directories under
|
||||
the :file:`src` directory, if any.
|
||||
|
||||
a) Use the following syntax to add file references:
|
||||
|
||||
.. code-block:: make
|
||||
|
||||
obj-y += file.o file.o
|
||||
|
||||
obj-y += file1.o file2.o
|
||||
|
||||
b) Use the following syntax to add directory references:
|
||||
|
||||
@ -124,56 +92,61 @@ Steps
|
||||
|
||||
obj-y += directory_name/**
|
||||
|
||||
|
||||
Example src Makefile
|
||||
--------------------
|
||||
|
||||
This example is taken from the Philosopher's Sample. To
|
||||
examine this file in context, navigate to:
|
||||
:file:`rootDir/samples/philosophers/microkernel/src`.
|
||||
:file:`\$ZEPHYR_BASE/samples/philosophers/src`.
|
||||
|
||||
.. code-block:: make
|
||||
|
||||
obj-y = phil_fiber.o phil_task.o
|
||||
obj-y = main.o
|
||||
|
||||
|
||||
.. _`enhancing_kernel`:
|
||||
|
||||
Enhancing the Zephyr Kernel
|
||||
===========================
|
||||
|
||||
When enhancing the Zephyr kernel, follow the subsystem naming
|
||||
conventions and the :literal:`include path` usage guidelines.
|
||||
Modifying and Enhancing the Kernel
|
||||
**********************************
|
||||
|
||||
Subsystem Naming Conventions
|
||||
----------------------------
|
||||
============================
|
||||
|
||||
In general, any sub-system can define its own naming conventions for
|
||||
symbols. However, naming conventions should be implemented with a
|
||||
unique namespace prefix (e.g. bt\_ for BlueTooth, or net\_ for IP) to
|
||||
limit possible clashes with applications. Naming within a sub-system
|
||||
When enhancing an existing kernel subsystem be sure to follow
|
||||
any existing naming conventions.
|
||||
For more information, see
|
||||
`Naming Conventions <https://wiki.zephyrproject.org/view/Coding_conventions#Naming_Conventions>`_.
|
||||
|
||||
When creating a new subsystem, the subsystem can define its own naming
|
||||
conventions for symbols. However, naming conventions should be implemented
|
||||
with a unique namespace prefix (e.g. bt\_ for BlueTooth, or net\_ for IP) to
|
||||
limit possible clashes with applications. Naming within a subsystem
|
||||
should continue to follow prefix conventions identified above; this
|
||||
keeps consistent interface for all users.
|
||||
|
||||
Include Paths Usage Guidelines
|
||||
------------------------------
|
||||
==============================
|
||||
|
||||
The current build system uses a series of defs.objs to define
|
||||
common pieces for a specific subsystem. For example, there
|
||||
are common defines for all architectures under :file:`\$ROOT/arch/x86`,
|
||||
and more specific defines for each supported board within
|
||||
the architecture, such as, :file:`\$ROOT/arch/x86/generic_pc`.
|
||||
Do not add unnecessary include paths to system or default include paths,
|
||||
as this can lead to ambiguous references when two or more directories
|
||||
contain a file with the same name.
|
||||
The only include path into :file:`\$ZEPHYR_BASE/include` should be
|
||||
:file:`\$ZEPHYR_BASE/include` itself.
|
||||
|
||||
Do not add every possible :literal:`include paths` in the defs.obj files.
|
||||
Too many default paths will cause problems when more than one file with
|
||||
the same name exists. The only :literal:`include path` into
|
||||
:file:`\${vBASE}/include` should be :file:`\${vBASE}/include` itself.
|
||||
Source files should use :code:`#include` directives that specify the full path
|
||||
from a common include directory. For example, you should always use
|
||||
directives of the form :code:`#include <path/to/[header].h>`, and not
|
||||
use directives of the form :code:`#include <[header].h>`.
|
||||
|
||||
Files should define includes to specific files with the complete path
|
||||
:file:`#include subdirectory/header.h`. For example, when there
|
||||
are two files, :file:`include/pci.h` and :file:`include/drvers/pci.h`,
|
||||
and both have been set to :file:`-Iinclude/drivers` and
|
||||
:file:`-Iinclude` for the compile, any code using
|
||||
:file:`#include pci.h` becomes ambiguous; using the complete path
|
||||
:file:`#include drivers/pci.h` is not. Not having :file:`-Iinclude/drivers`
|
||||
forces users to use the second form, which is more explicit.
|
||||
The following example illustrates the kind of problems that can arise when
|
||||
unnecessary default include paths are specified.
|
||||
|
||||
* Observe that the kernel contains both :file:`include/pci.h` and
|
||||
:file:`include/drivers/pci.h`.
|
||||
|
||||
* If both the :file:`include` and :file:`include/drivers` directories
|
||||
are added to the default include paths (e.g.
|
||||
:code:`gcc -Iinclude/drivers -Iinclude [...]`), then the directive
|
||||
:code:`#include <pci.h>` becomes ambiguous.
|
||||
|
||||
The solution is to avoid adding :file:`include/drivers` to the default
|
||||
include paths. Source files can then reference either :code:`#include <pci.h>`
|
||||
or :code:`#include <drivers/pci.h>`, as needed.
|
||||
|
||||
@ -30,7 +30,7 @@ Steps
|
||||
$ export ZEPHYR_GCC_VARIANT=zephyr
|
||||
$ export ZEPHYR_SDK_INSTALL_DIR=<yocto-installation-path>
|
||||
|
||||
2. To set the environment variable :envvar:`$(ZEPHYR_BASE)`, navigate to the
|
||||
2. To set the environment variable :envvar:`\$ZEPHYR_BASE`, navigate to the
|
||||
kernel's installation directory and enter:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
@ -1,58 +0,0 @@
|
||||
.. _apps_dev_process:
|
||||
|
||||
Application Development Workflow
|
||||
################################
|
||||
|
||||
The application development workflow identifies procedures needed to create, build, and
|
||||
run a Zephyr microkernel or nanokernel application.
|
||||
|
||||
Before you build
|
||||
----------------
|
||||
|
||||
* Check that your Linux host meets the minimum requirements specified in the
|
||||
:ref:`getting_started`.
|
||||
|
||||
* Check that environment variables have been configured correctly as outlined
|
||||
in :ref:`apps_common_procedures`.
|
||||
|
||||
Workflow
|
||||
--------
|
||||
|
||||
1. Create a directory structure for your Zephyr application.
|
||||
|
||||
a) :ref:`create_directory_structure`
|
||||
|
||||
2. Add a Makefile
|
||||
|
||||
b) :ref:`create_src_makefile`
|
||||
|
||||
3. Define the application's default kernel configuration using
|
||||
:ref:`define_default_kernel_conf`.
|
||||
|
||||
4. Define kernel configuration override options for the application
|
||||
using :ref:`override_kernel_conf`.
|
||||
|
||||
5. For a microkernel application, define objects as you develop code
|
||||
using :ref:`create_mdef`.
|
||||
|
||||
6. For all applications, define nanokernel objects as you need them in
|
||||
code.
|
||||
|
||||
7. Develop source code and add source code files to the src directory.
|
||||
|
||||
* `naming conventions`_
|
||||
* :ref:`src_makefiles_reqs`
|
||||
* :ref:`src_files_directories`
|
||||
|
||||
.. _naming conventions: https://wiki.zephyrproject.org/view/Coding_conventio ns#Naming_Conventions
|
||||
|
||||
8. Build an application image.
|
||||
|
||||
* :ref:`apps_build`
|
||||
|
||||
|
||||
9. To test the application image's functionality on simulated hardware
|
||||
with QEMU, see :ref:`apps_run`.
|
||||
|
||||
10. To load an application image on a target hardware, see using
|
||||
:ref:`board` documentation.
|
||||
@ -1,75 +1,69 @@
|
||||
.. _apps_kernel_conf:
|
||||
|
||||
Kernel Configuration
|
||||
####################
|
||||
Configure an Application's Kernel
|
||||
#################################
|
||||
|
||||
The application's kernel is configured from a set of options that
|
||||
can be customized for application-specific purposes. Each
|
||||
configuration option is derived from the first source in which
|
||||
it is specified:
|
||||
The application's kernel is configured using a set of configuration options
|
||||
that can be customized for application-specific purposes.
|
||||
The Zephyr build system takes a configuration option's value
|
||||
from the first source in which it is specified.
|
||||
The available sources are (in order):
|
||||
|
||||
a. The value specified by the application’s current
|
||||
configuration; that is, its :file:`.config` file.
|
||||
#. The application's current configuration.
|
||||
(i.e. The :file:`.config` file.)
|
||||
|
||||
b. The value specified by the application’s default
|
||||
configuration; that is, its :file:`prj.conf` file.
|
||||
#. The application's default configuration.
|
||||
(i.e. The :file:`.conf` file.)
|
||||
|
||||
c. The value specified by the board configuration.
|
||||
#. The board configuration used by the application.
|
||||
(i.e. The board's :file:`.defconfig` file.)
|
||||
|
||||
d. The kernel’s default value for the configuration option.
|
||||
#. The kernel's default configuration.
|
||||
(i.e. One of the kernel's :file:`Kconfig` files.)
|
||||
|
||||
.. note::
|
||||
For information on available kernel configuration options, including
|
||||
inter-dependencies between options, see the :ref:`configuration`.
|
||||
Be careful to note if an option is an experimental option
|
||||
that is not yet fully supported.
|
||||
|
||||
When the default board configuration settings are sufficient for your
|
||||
application, a :file:`prj.conf` file is not needed. Skip ahead to
|
||||
:ref:`override_kernel_conf`.
|
||||
|
||||
|
||||
Procedures
|
||||
**********
|
||||
|
||||
* `define_default_kernel_conf`_
|
||||
|
||||
* `Overriding 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
|
||||
inter-dependencies and board configuration-default options, see the
|
||||
:ref:`configuration`.
|
||||
|
||||
.. note::
|
||||
|
||||
There are currently a number of experimental options not yet
|
||||
fully supported.
|
||||
|
||||
.. _define_default_kernel_conf:
|
||||
.. contents:: Procedures
|
||||
:local:
|
||||
:depth: 1
|
||||
|
||||
Defining the Application's Default Kernel Configuration
|
||||
=======================================================
|
||||
|
||||
Create a :file:`prj.conf` file to define the application's
|
||||
default kernel configuration. This file can contain
|
||||
settings that override or augment board-configuration settings.
|
||||
An application's :file:`.conf` file defines its default kernel configuration.
|
||||
The settings in this file override or augment the board configuration settings.
|
||||
|
||||
The contents of the supported board configuration files
|
||||
can be viewed in :file:`~/rootDir/boards/BOARD/BOARD_defconfig`.
|
||||
The board configuration settings can be viewed
|
||||
in :file:`\$ZEPHYR_BASE/boards/ARCHITECTURE/BOARD/BOARD_defconfig`.
|
||||
|
||||
.. note::
|
||||
|
||||
When the default board configuration settings are sufficient for your
|
||||
application, a :file:`.conf` file is not needed. Skip ahead to
|
||||
:ref:`override_kernel_conf`.
|
||||
|
||||
Before you begin
|
||||
----------------
|
||||
|
||||
* Confirm Zephyr environment variables are set for each console
|
||||
terminal using :ref:`apps_common_procedures`.
|
||||
* Ensure you have created an application directory, as described
|
||||
in :ref:`apps_structure`.
|
||||
|
||||
* Review the kernel configuration options available and know
|
||||
which ones you want to set for your application.
|
||||
Be aware of any dependencies involving these options.
|
||||
See the :ref:`configuration` for a brief description of each option.
|
||||
|
||||
Steps
|
||||
-----
|
||||
|
||||
1. Navigate to the :file:`appDir`, and create the :file:`prj.conf` file. Enter:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ touch prj.conf
|
||||
.. code-block:: bash
|
||||
|
||||
$ touch prj.conf
|
||||
|
||||
The default name is :file:`prj.conf`. The filename must match
|
||||
the ``CONF_FILE`` entry in the application :file:`Makefile`.
|
||||
@ -85,13 +79,13 @@ Steps
|
||||
|
||||
d) Use a # followed by a space to comment a line.
|
||||
|
||||
This example shows a comment line and a board
|
||||
The example below shows a comment line and a board
|
||||
configuration override in the :file:`prj.conf`.
|
||||
|
||||
.. code-block:: c
|
||||
.. code-block:: c
|
||||
|
||||
# Change the number of IRQs supported by the application
|
||||
CONFIG_NUM_IRQS=43
|
||||
# Change the number of IRQs supported by the application
|
||||
CONFIG_NUM_IRQS=43
|
||||
|
||||
3. Save and close the file.
|
||||
|
||||
@ -102,7 +96,7 @@ Overriding the Application's Default Kernel Configuration
|
||||
=========================================================
|
||||
|
||||
Override the application's default kernel configuration to
|
||||
temporarily alter the application’s configuration, perhaps
|
||||
temporarily alter the application's configuration, perhaps
|
||||
to test the effect of a change.
|
||||
|
||||
.. note::
|
||||
@ -117,16 +111,15 @@ is a preferred method.
|
||||
Before you begin
|
||||
----------------
|
||||
|
||||
* Ensure you have created an application directory, as described
|
||||
in :ref:`apps_structure`.
|
||||
|
||||
* Review the kernel configuration options available and know
|
||||
which ones you want to temporarily set for your application.
|
||||
See the :ref:`configuration` for a brief description of each option.
|
||||
which ones you want to set for your application.
|
||||
Be aware of any dependencies involving these options.
|
||||
|
||||
* Be aware of any dependencies among the kernel configuration options.
|
||||
|
||||
* Confirm an application :file:`Makefile` exists for your application.
|
||||
|
||||
* Confirm the Zephyr environment variable is set for each console
|
||||
terminal; see :ref:`apps_common_procedures`.
|
||||
* Ensure the Zephyr environment variables are set for each console terminal;
|
||||
see :ref:`apps_common_procedures`.
|
||||
|
||||
Steps
|
||||
-----
|
||||
@ -141,7 +134,7 @@ Steps
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ make menuconfig
|
||||
$ make [BOARD=<type>] menuconfig
|
||||
|
||||
A question-based menu opens that allows you to set individual
|
||||
configuration options.
|
||||
@ -202,7 +195,7 @@ Steps
|
||||
|
||||
An :file:`outdir` directory is created in the application
|
||||
directory. The outdir directory contains symbolic links
|
||||
to files under $(ZEPHYR_BASE).
|
||||
to files under :file:`\$ZEPHYR_BASE`.
|
||||
|
||||
.. note::
|
||||
|
||||
@ -261,8 +254,3 @@ Steps
|
||||
|
||||
11. Press :kbd:`Enter` to retire the menu display and
|
||||
return to the console command line.
|
||||
|
||||
**Next Steps**: For microkernel applications, go to :ref:`Creating and
|
||||
Configuring an MDEF File for a Microkernel Application <create_mdef>`.
|
||||
|
||||
For nanokernel applications, go to :ref:`apps_code_dev`.
|
||||
|
||||
@ -1,96 +0,0 @@
|
||||
.. _apps_object_conf:
|
||||
|
||||
Microkernel Object Configuration
|
||||
################################
|
||||
|
||||
Microkernel objects are explained fully in the :ref:`kernel`.
|
||||
See :ref:`microkernel` for example MDEF entries.
|
||||
|
||||
Procedure
|
||||
*********
|
||||
|
||||
.. _create_mdef:
|
||||
|
||||
Creating and Configuring an MDEF for a Microkernel Application
|
||||
==============================================================
|
||||
|
||||
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
|
||||
writing code. However, all objects used in your code must be defined
|
||||
before your application will compile successfully.
|
||||
|
||||
.. note::
|
||||
|
||||
Nanokernel applications do not use an MDEF because microkernel
|
||||
objects cannot be used in applications of this type.
|
||||
|
||||
Before you begin
|
||||
----------------
|
||||
|
||||
* Confirm your :file:`~/appDir` already exists.
|
||||
|
||||
* Confirm Zephyr environment variables are set for each console
|
||||
terminal; for instructions, see :ref:`apps_common_procedures`.
|
||||
|
||||
Steps
|
||||
-----
|
||||
|
||||
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`).
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ touch 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`
|
||||
is:
|
||||
|
||||
TASK name priority entry_point stack_size groups
|
||||
|
||||
TASKGROUP name
|
||||
|
||||
MUTEX name
|
||||
|
||||
SEMA name
|
||||
|
||||
FIFO name depth width
|
||||
|
||||
PIPE name buffer_size
|
||||
|
||||
MAILBOX name
|
||||
|
||||
MAP name num_blocks block_size
|
||||
|
||||
POOL name min_block_size max_block_size numMax
|
||||
|
||||
.. note::
|
||||
|
||||
Some microkernel objects, such as Task IRQs, are not
|
||||
defined in an :file:`.mdef` file.
|
||||
|
||||
The following example shows the content of the
|
||||
:file:`samples/legacy/philosophers/microkernel/proj.mdef`
|
||||
for the Philosophers' sample application. The sample
|
||||
uses seven tasks and six mutexes.
|
||||
|
||||
Example MDEF
|
||||
------------
|
||||
|
||||
.. literalinclude:: ../../samples/legacy/philosophers/microkernel/prj.mdef
|
||||
:linenos:
|
||||
|
||||
Related Topics
|
||||
--------------
|
||||
|
||||
:ref:`src_makefiles_reqs`
|
||||
:ref:`src_files_directories`
|
||||
@ -13,21 +13,25 @@ The directory has the following structure.
|
||||
or more application-specific files, written in C or assembly language. These
|
||||
files are usually located in a sub-directory called :file:`src`.
|
||||
|
||||
* **Kernel configuration files**: 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.
|
||||
* **Kernel configuration files**: 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.
|
||||
|
||||
* **MDEF file**: A microkernel application typically provides a Microkernel
|
||||
DEFinitions file (:file:`.mdef`) that defines the public kernel objects
|
||||
used by the application and the kernel. If omitted, no public kernel objects
|
||||
are defined. This file is not used with a nanokernel-only application.
|
||||
|
||||
* **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
|
||||
board configuration and kernel type (either microkernel or nanokernel).
|
||||
* **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 board configuration.
|
||||
|
||||
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`.
|
||||
The results of the build process are located in a sub-directory
|
||||
called :file:`outdir/BOARD`. This directory contains the files generated
|
||||
by the build process, the most notable of which are listed below.
|
||||
|
||||
* The :file:`.config` file that contains the configuration settings
|
||||
used to build the application.
|
||||
|
||||
* The various object files (:file:`.o` files and :file:`.a` files) containing
|
||||
custom-built kernel and application-specific code.
|
||||
|
||||
* The :file:`zephyr.elf` file that contains the final application image.
|
||||
|
||||
@ -3,59 +3,56 @@
|
||||
Run an Application
|
||||
##################
|
||||
|
||||
The kernel's built-in simulator is QEMU. It creates an environment
|
||||
where you can run and test an application virtually, before (or
|
||||
in lieu of) loading and running it on actual target hardware.
|
||||
An appliction image can be run on real or simulated hardware.
|
||||
The kernel's built-in simulator is QEMU. It allows you to run and test
|
||||
an application virtually, before (or in lieu of)
|
||||
loading and running it on actual target hardware.
|
||||
|
||||
Procedures
|
||||
**********
|
||||
|
||||
.. _run_app_qemu:
|
||||
.. contents:: Procedures
|
||||
:local:
|
||||
:depth: 1
|
||||
|
||||
Running an Application using QEMU
|
||||
=================================
|
||||
|
||||
Run your application in QEMU for testing and demonstration purposes.
|
||||
|
||||
Prerequisites
|
||||
-------------
|
||||
|
||||
* You must have already generated a .elf image file for a
|
||||
QEMU-supported board configuration, such as qemu_cortex_m3 or qemu_x86.
|
||||
* Ensure the application can be built successfully using a QEMU-supported
|
||||
board configuration, such as qemu_cortex_m3 or qemu_x86, as described
|
||||
in :ref:`apps_build`.
|
||||
|
||||
* The environment variable must be set for each console
|
||||
terminal using :ref:`apps_common_procedures`.
|
||||
* Ensure the Zephyr environment variables are set for each console terminal;
|
||||
see :ref:`apps_common_procedures`.
|
||||
|
||||
Steps
|
||||
-----
|
||||
|
||||
1. Open a terminal console and navigate to the application directory
|
||||
#. Open a terminal console and navigate to the application directory
|
||||
:file:`~/appDir`.
|
||||
|
||||
2. Enter the following command to build and run an application
|
||||
in QEMU:
|
||||
#. Enter the following command to build and run the application
|
||||
using a QEMU-supported board configuration,
|
||||
such as qemu_cortex_m3 or qemu_x86.
|
||||
|
||||
.. code-block:: console
|
||||
.. code-block:: console
|
||||
|
||||
$ make qemu
|
||||
$ make [BOARD=<type> ...] qemu
|
||||
|
||||
The Zephyr build system generates a :file:`zephyr.elf` image file
|
||||
and then begins running it in the terminal console.
|
||||
|
||||
The application begins running in the terminal console.
|
||||
|
||||
3. Press :kbd:`Ctrl A, X` to stop the application from running
|
||||
#. Press :kbd:`Ctrl A, X` to stop the application from running
|
||||
in QEMU.
|
||||
|
||||
The application stops running and the terminal console prompt
|
||||
redisplays.
|
||||
|
||||
.. _loading_on_target:
|
||||
The application stops running and the terminal console prompt
|
||||
redisplays.
|
||||
|
||||
Loading and Running an Application on Target Hardware
|
||||
=====================================================
|
||||
|
||||
An application image is loaded on the target based on functionality
|
||||
available on the hardware device. Loading instructions are often
|
||||
unique to the particular target board. For this reason, loading
|
||||
instructions reside with the board-specific documentation.
|
||||
|
||||
For more information see :ref:`board`.
|
||||
The procedure required to load an application image (:file:`zephyr.elf`)
|
||||
on a target depends on the functionality available on its hardware,
|
||||
and is often unique to that target board.
|
||||
For this reason, loading instructions reside with the board-specific
|
||||
documentation; see :ref:`board`.
|
||||
|
||||
@ -1,39 +1,29 @@
|
||||
.. _apps_structure:
|
||||
|
||||
Application Development Directory Structure
|
||||
###########################################
|
||||
Create an Application Directory
|
||||
###############################
|
||||
|
||||
Each application resides in a uniquely-named application
|
||||
directory created by the developer, typically, in the developer's
|
||||
directory created by the developer, typically in the developer's
|
||||
workspace directory. The application developer also creates a
|
||||
:file:`src` directory for the application's source code.
|
||||
|
||||
.. note::
|
||||
.. contents:: Procedures
|
||||
:local:
|
||||
:depth: 1
|
||||
|
||||
The Zephyr Kernel either supplies or generates all other application
|
||||
directories.
|
||||
Creating an Application and Source Code Directory
|
||||
=================================================
|
||||
|
||||
Procedures
|
||||
**********
|
||||
|
||||
* `create_directory_structure`_
|
||||
|
||||
* `create_src_makefile`_
|
||||
|
||||
.. _create_directory_structure:
|
||||
|
||||
Creating an Application and Source Code Directory using the CLI
|
||||
===============================================================
|
||||
|
||||
Create one directory for your application and another for the application's
|
||||
source code; this makes it easier to organize directories and files in the
|
||||
structure that the kernel expects.
|
||||
Create one directory for your application and a sub-directory for the
|
||||
application's source code; this makes it easier to organize directories
|
||||
and files in the structure that the kernel expects.
|
||||
|
||||
Before You Begin
|
||||
----------------
|
||||
|
||||
* The environment variable must be set for each console terminal using
|
||||
:ref:`set_environment_variables`.
|
||||
* Ensure the Zephyr environment variables are set for each console terminal;
|
||||
see :ref:`apps_common_procedures`.
|
||||
|
||||
Steps
|
||||
-----
|
||||
@ -41,8 +31,8 @@ Steps
|
||||
1. Create an application directory structure outside of the kernel's
|
||||
installation directory tree. Often this is your workspace directory.
|
||||
|
||||
a) In a Linux console, navigate to a location where you want your
|
||||
applications to reside.
|
||||
a) In a console terminal, navigate to a location where you want your
|
||||
application to reside.
|
||||
|
||||
b) Create the application's directory, enter:
|
||||
|
||||
@ -68,16 +58,13 @@ Steps
|
||||
-- appDir
|
||||
|-- src
|
||||
|
||||
.. _create_src_makefile:
|
||||
|
||||
Creating an Application Makefile
|
||||
================================
|
||||
|
||||
Create an application Makefile to define basic information such as the kernel
|
||||
type, microkernel or nanokernel, and the board configuration used by the
|
||||
application. The build system uses the Makefile to build an image with both
|
||||
the application and the kernel libraries called either
|
||||
:file:`microkernel.elf` or :file:`nanokernel.elf`.
|
||||
Create an application Makefile to define basic information,
|
||||
such as the board configuration used by the application.
|
||||
The build system uses the Makefile to build a :file:`zephyr.elf` image
|
||||
that contains both the application and the kernel libraries.
|
||||
|
||||
Before You Begin
|
||||
----------------
|
||||
@ -87,8 +74,8 @@ Before You Begin
|
||||
* Be familiar with the board configuration used for your application
|
||||
and, if it is a custom board configuration, where it is located.
|
||||
|
||||
* Set the environment variable for each console terminal using
|
||||
:ref:`set_environment_variables`.
|
||||
* Ensure the Zephyr environment variables are set for each console terminal;
|
||||
see :ref:`apps_common_procedures`.
|
||||
|
||||
Steps
|
||||
-----
|
||||
@ -106,16 +93,7 @@ Steps
|
||||
|
||||
Ensure that there is a space after each ``=``.
|
||||
|
||||
a) Add the kernel type on a new line:
|
||||
|
||||
.. code-block:: make
|
||||
|
||||
KERNEL_TYPE = micro|nano
|
||||
|
||||
Either micro or nano, short for microkernel or
|
||||
nanokernel respectively.
|
||||
|
||||
b) Add the name of the board configuration for your application on a
|
||||
a) Add the name of the default board configuration for your application on a
|
||||
new line:
|
||||
|
||||
.. code-block:: make
|
||||
@ -124,30 +102,18 @@ Steps
|
||||
|
||||
The supported boards can be found in :ref:`board`.
|
||||
|
||||
c) Add the name of the default kernel configuration file for your
|
||||
b) Add the name of the default kernel configuration file for your
|
||||
application on a new line:
|
||||
|
||||
.. code-block:: make
|
||||
|
||||
CONF_FILE = prj.conf
|
||||
CONF_FILE ?= kernel_configuration_name
|
||||
|
||||
The default name is :file:`prj.conf`. If you are not using the default
|
||||
name, this entry must match the filename of the :file:`.conf` file you
|
||||
are using.
|
||||
The default kernel configuration file entry may be omitted if the file
|
||||
is called :file:`prj.conf`. It may also be omitted if the default board
|
||||
configuration's kernel settings are sufficient for your application.
|
||||
|
||||
d) For microkernel applications, add the name of the MDEF for your
|
||||
application:
|
||||
|
||||
.. code-block:: make
|
||||
|
||||
MDEF_FILE = prj.mdef
|
||||
|
||||
The default name is :file:`prj.mdef`. If you are not using the default
|
||||
name, this entry must match the filename of the :file:`.mdef` file you
|
||||
are using.
|
||||
|
||||
e) Include the mandatory :file:`Makefile` fragments on a new
|
||||
line:
|
||||
c) Include the mandatory :file:`Makefile` fragments on a new line:
|
||||
|
||||
.. code-block:: make
|
||||
|
||||
@ -160,8 +126,6 @@ Example Makefile
|
||||
|
||||
.. code-block:: make
|
||||
|
||||
KERNEL_TYPE = micro
|
||||
BOARD ?= qemu_x86
|
||||
CONF_FILE = prj.conf
|
||||
MDEF_FILE = prj.mdef
|
||||
CONF_FILE ?= prj.conf
|
||||
include ${ZEPHYR_BASE}/Makefile.inc
|
||||
|
||||
Loading…
Reference in New Issue
Block a user