doc: restructure application primer
Merge build system and application primer into one and put all in one file to make it easier to follow. Jira: ZEP-686 Change-Id: I64ec7ef7a6aa2ad80496ca0ee3ddc3d7fe09a5d7 Signed-off-by: Anas Nashif <anas.nashif@intel.com>
This commit is contained in:
parent
ebe9771d02
commit
7cb8a16c86
14 changed files with 758 additions and 1277 deletions
|
@ -3,39 +3,769 @@
|
|||
Application Development Primer
|
||||
##############################
|
||||
|
||||
This section outlines how to create, build, and run a Zephyr application.
|
||||
|
||||
Audience
|
||||
Overview
|
||||
========
|
||||
The Zephyr Kernel's build system is based on the Kbuild system used in the
|
||||
Linux kernel.
|
||||
|
||||
The build system is an application-centric system and requires an application
|
||||
build to initiate building the kernel source tree. The application build drives
|
||||
the configuration and build process of both the application and kernel,
|
||||
compiling them into a single binary.
|
||||
|
||||
The Zephyr Kernel's base directory hosts the kernel source code, the
|
||||
configuration options, and the kernel build definitions.
|
||||
|
||||
The files in the application directory links the kernel with the
|
||||
application. It hosts the definitions of the application, for example,
|
||||
application-specific configuration options and the application's source code.
|
||||
|
||||
An application in the simplest form has the following structure:
|
||||
|
||||
* **Application source code files**: An application typically provides one
|
||||
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.
|
||||
|
||||
* **Makefile**: This file tells 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 ``make``
|
||||
call.
|
||||
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 combined application and
|
||||
kernel binary.
|
||||
|
||||
|
||||
|
||||
Application Structure
|
||||
=====================
|
||||
|
||||
|
||||
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.
|
||||
|
||||
#. Create an application directory structure outside of the kernel's
|
||||
installation directory tree. Often this is your workspace directory.
|
||||
|
||||
#. In a console terminal, navigate to a location where you want your
|
||||
application to reside.
|
||||
|
||||
#. Create the application's directory, enter:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ mkdir app
|
||||
|
||||
.. note::
|
||||
|
||||
This directory and the path to it, are referred to in the documentation
|
||||
as :file:`~/app`.
|
||||
|
||||
#. Create a source code directory in your :file:`~/app`, enter:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ cd app
|
||||
$ mkdir src
|
||||
|
||||
The source code directory :file:`~/app/src` is created.
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
-- app
|
||||
|-- src
|
||||
|
||||
|
||||
Application Definition
|
||||
======================
|
||||
|
||||
An application is integrated into the build system by including the Makefile.inc
|
||||
file provided.
|
||||
|
||||
.. code-block:: make
|
||||
|
||||
include $(ZEPHYR_BASE)/Makefile.inc
|
||||
|
||||
The following predefined variables configure the development project:
|
||||
|
||||
* :makevar:`ZEPHYR_BASE`: Sets the path to the kernel's base directory.
|
||||
This variable is usually set by the :file:`zephyr_env.sh` script.
|
||||
It can be used to get the kernel's base directory, as used in the
|
||||
Makefile.inc inclusion above, or it can be overridden to select an
|
||||
specific instance of the kernel.
|
||||
|
||||
* :makevar:`PROJECT_BASE`: Provides the developer's application project
|
||||
directory path. It is set by the :file:`Makefile.inc` file.
|
||||
|
||||
* :makevar:`SOURCE_DIR`: Overrides the default value for the application's
|
||||
source code directory. The developer source code directory is set to
|
||||
:file:`$(PROJECT_BASE/)src/` by default. This directory name should end
|
||||
with slash **'/'**.
|
||||
|
||||
* :makevar:`BOARD`: Selects the board that the application's
|
||||
build will use for the default configuration.
|
||||
|
||||
* :makevar:`CONF_FILE`: Indicates the name of a configuration fragment file.
|
||||
This file includes the kconfig configuration values that override the
|
||||
default configuration values.
|
||||
|
||||
* :makevar:`O`: Optional. Indicates the output directory that Kconfig uses.
|
||||
The output directory stores all the files generated during the build
|
||||
process. The default output directory is the :file:`$(PROJECT_BASE)/outdir`
|
||||
directory.
|
||||
|
||||
|
||||
Makefiles
|
||||
=========
|
||||
|
||||
Overview
|
||||
--------
|
||||
|
||||
Although anybody may use this primer, the primary audience for this guide is:
|
||||
The build system defines a set of conventions for the correct use of Makefiles
|
||||
in the kernel source directories. The correct use of Makefiles is driven by the
|
||||
concept of recursion.
|
||||
|
||||
* Application developers coding an application.
|
||||
In the recursion model, each Makefile within a directory includes the source
|
||||
code and any subdirectories to the build process. Each subdirectory follows
|
||||
the same principle. Developers can focus exclusively in their own work. They
|
||||
integrate their module with the build system by adding a very simple Makefile
|
||||
following the recursive model.
|
||||
|
||||
* System architects learning key functionality and usage.
|
||||
.. _makefile_conventions:
|
||||
|
||||
Before You Start
|
||||
----------------
|
||||
Makefile Conventions
|
||||
--------------------
|
||||
|
||||
* Check that your Linux host meets the minimum requirements specified in the
|
||||
:ref:`getting_started`.
|
||||
The following conventions restrict how to add modules and Makefiles to the
|
||||
build system. These conventions ensure the correct implementation of the
|
||||
recursive model.
|
||||
|
||||
* Check that environment variables have been configured correctly as outlined
|
||||
in :ref:`apps_common_procedures`.
|
||||
* Each source code directory must contain a single Makefile. Directories
|
||||
without a Makefile are not considered source code directories.
|
||||
|
||||
Workflow
|
||||
--------
|
||||
* The scope of every Makefile is restricted to the contents of that directory.
|
||||
A Makefile can only make a direct reference to files and subdirectories on the
|
||||
same level or below.
|
||||
|
||||
The following sections explain the application development process
|
||||
from start to finish.
|
||||
* Makefiles list the object files that are included in the link process. The
|
||||
build system finds the source file that generates the object file by matching
|
||||
the object file name to the source file.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
* Parent directories add their child directories into the recursion model.
|
||||
|
||||
apps_overview
|
||||
apps_structure
|
||||
apps_kernel_conf
|
||||
apps_code_dev
|
||||
apps_build
|
||||
apps_run
|
||||
apps_common_procedures
|
||||
* The root Makefile adds the directories in the kernel base directory into the
|
||||
recursion model.
|
||||
|
||||
Adding Source Files
|
||||
-------------------
|
||||
|
||||
The Makefile must refer the source build indirectly, specifying the object file
|
||||
that results from the source file using the :literal:`obj-y` variable. For
|
||||
example, if the file that we want to add is a C file named :file:`<file>.c` the
|
||||
following line should be added in the Makefile:
|
||||
|
||||
.. code-block:: make
|
||||
|
||||
obj-y += <file>.o
|
||||
|
||||
.. note::
|
||||
|
||||
The same method applies for assembly files with the .S extension.
|
||||
|
||||
Source files can be added conditionally using configuration options. For
|
||||
example, if the option ``CONFIG_VAR`` is set and it implies that a source
|
||||
file must be added in the compilation process, then the following line adds the
|
||||
source code conditionally:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
obj-$(CONFIG_VAR) += <file>.o
|
||||
|
||||
Adding Directories
|
||||
------------------
|
||||
|
||||
Add a subdirectory to the build system by editing the Makefile in its
|
||||
directory. The subdirectory is added using the :literal:`obj-y` variable. The
|
||||
correct syntax to add a subdirectory into the build queue is:
|
||||
|
||||
.. code-block:: make
|
||||
|
||||
obj-y += <directory_name>/
|
||||
|
||||
The backslash at the end of the directory name signals the build system that a
|
||||
directory, and not a file, is being added to the build queue.
|
||||
|
||||
The conventions require us to add only one directory per line and never to mix
|
||||
source code with directory recursion in a single :literal:`obj-y` line. This
|
||||
helps keep the readability of the Makefile by making it clear when an item adds
|
||||
an additional lever of recursion.
|
||||
|
||||
Directories can also be conditionally added:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
obj-y-$(CONFIG_VAR) += <directory_name>/
|
||||
|
||||
The subdirectory must contain its own Makefile following the rules described in
|
||||
:ref:`makefile_conventions`.
|
||||
|
||||
|
||||
Application Makefile
|
||||
====================
|
||||
|
||||
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.
|
||||
|
||||
#. Open the :file:`Makefile` and add the following mandatory
|
||||
entries using any standard text editor.
|
||||
|
||||
.. note::
|
||||
|
||||
Ensure that there is a space before and after each ``=``.
|
||||
|
||||
#. Add the name of the default board configuration for your application on a
|
||||
new line:
|
||||
|
||||
.. code-block:: make
|
||||
|
||||
BOARD = board_configuration_name
|
||||
|
||||
The supported boards can be found in :ref:`board`.
|
||||
|
||||
#. Add the name of the default kernel configuration file for your
|
||||
application on a new line:
|
||||
|
||||
.. code-block:: make
|
||||
|
||||
CONF_FILE ?= kernel_configuration_name
|
||||
|
||||
#. Include the mandatory :file:`Makefile` on a new line:
|
||||
|
||||
.. code-block:: make
|
||||
|
||||
include ${ZEPHYR_BASE}/Makefile.inc
|
||||
|
||||
#. Save and close the :file:`Makefile`.
|
||||
|
||||
|
||||
Below is an example Makefile:
|
||||
|
||||
.. code-block:: make
|
||||
|
||||
BOARD = qemu_x86
|
||||
CONF_FILE = prj.conf
|
||||
|
||||
include ${ZEPHYR_BASE}/Makefile.inc
|
||||
|
||||
Application Configuration
|
||||
=========================
|
||||
|
||||
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):
|
||||
|
||||
#. The application's current configuration. (i.e. The :file:`.config` file.)
|
||||
|
||||
#. The application's default configuration. (i.e. The :file:`.conf` file.)
|
||||
|
||||
#. The board configuration used by the application.
|
||||
(i.e. The board's :file:`.defconfig` file.)
|
||||
|
||||
#. The kernel's default configuration.
|
||||
(i.e. One of the kernel's :file:`Kconfig` files.)
|
||||
|
||||
For information on available kernel configuration options, including
|
||||
inter-dependencies between options, see the :ref:`configuration`.
|
||||
|
||||
Default Board Configuration
|
||||
---------------------------
|
||||
|
||||
An application's :file:`.conf` file defines its default kernel configuration.
|
||||
The settings in this file override or augment the board configuration settings.
|
||||
|
||||
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`.
|
||||
|
||||
|
||||
#. Navigate to the :file:`app`, and create the :file:`prj.conf` file. Enter:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ vim prj.conf
|
||||
|
||||
The default name is :file:`prj.conf`. The filename must match the
|
||||
``CONF_FILE`` entry in the application :file:`Makefile`.
|
||||
|
||||
#. Edit the file and add the appropriate configuration entries.
|
||||
|
||||
a) Add each configuration entry on a new line.
|
||||
|
||||
b) Begin each entry with ``CONFIG_``.
|
||||
|
||||
c) Ensure that each entry contains no spaces
|
||||
(including on either side of the = sign).
|
||||
|
||||
d) Use a # followed by a space to comment a line.
|
||||
|
||||
The example below shows a comment line and a board
|
||||
configuration override in the :file:`prj.conf`.
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
# Enable printk for debugging
|
||||
CONFIG_PRINTK=y
|
||||
|
||||
#. Save and close the file.
|
||||
|
||||
.. _override_kernel_conf:
|
||||
|
||||
Overriding Default Configuration
|
||||
--------------------------------
|
||||
|
||||
Override the default board and kernel configuration to 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.
|
||||
|
||||
Configure the kernel options using a menu-driven interface. While you can add
|
||||
entries manually, using the configuration menu is a preferred method.
|
||||
|
||||
|
||||
#. Run the :command:`make menuconfig` rule to launch the menu-driven interface.
|
||||
|
||||
a) In a terminal session, navigate to the application directory
|
||||
(:file:`~/app`).
|
||||
|
||||
b) Enter the following command:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ make [BOARD=<type>] menuconfig
|
||||
|
||||
A question-based menu opens that allows you to set individual configuration
|
||||
options.
|
||||
|
||||
.. image:: figures/app_kernel_conf_1.png
|
||||
:width: 400px
|
||||
:align: center
|
||||
:height: 375px
|
||||
:alt: Main Configuration Menu
|
||||
|
||||
#. Set kernel configuration values using the following
|
||||
key commands:
|
||||
|
||||
* Use the arrow keys to navigate within any menu or list.
|
||||
|
||||
* Press :kbd:`Enter` to select a menu item.
|
||||
|
||||
* Type an upper case :kbd:`Y` or :kbd:`N` in the
|
||||
square brackets :guilabel:`[ ]` to
|
||||
enable or disable a kernel configuration option.
|
||||
|
||||
* Type a numerical value in the round brackets :guilabel:`( )`.
|
||||
|
||||
* Press :kbd:`Tab` to navigate the command menu at the bottom of the display.
|
||||
|
||||
.. note::
|
||||
|
||||
When a non-default entry is selected for options that are nonnumerical,
|
||||
an asterisk :kbd:`*` appears between the square brackets in the display.
|
||||
There is nothing added added the display when you select the option's
|
||||
default.
|
||||
|
||||
#. For information about any option, select the option and tab to
|
||||
:guilabel:`<Help >` and press :kbd:`Enter`.
|
||||
|
||||
Press :kbd:`Enter` to return to the menu.
|
||||
|
||||
#. After configuring the kernel options for your application, tab to
|
||||
:guilabel:`< Save >` and press :kbd:`Enter`.
|
||||
|
||||
The following dialog opens with the :guilabel:`< Ok >` command selected:
|
||||
|
||||
.. image:: figures/app_kernel_conf_2.png
|
||||
:width: 400px
|
||||
:align: center
|
||||
:height: 100px
|
||||
:alt: Save Configuration Dialog
|
||||
|
||||
|
||||
#. Press :kbd:`Enter` to save the kernel configuration options to the default
|
||||
file name; alternatively, type a file name and press :kbd:`Enter`.
|
||||
|
||||
Typically, you will save to the default file name unless you are
|
||||
experimenting with various configuration scenarios.
|
||||
|
||||
An :file:`outdir` directory is created in the application directory. The
|
||||
outdir directory contains symbolic links to files under
|
||||
:file:`\$ZEPHYR_BASE`.
|
||||
|
||||
.. note::
|
||||
|
||||
At present, only a :file:`.config` file can be built. If you have saved
|
||||
files with different file names and want to build with one of these,
|
||||
change the file name to :file:`.config`. To keep your original
|
||||
:file:`.config`, rename it to something other than :file:`.config`.
|
||||
|
||||
Kernel configuration files, such as the :file:`.config` file, are saved
|
||||
as hidden files in :file:`outdir`. To list all your kernel configuration
|
||||
files, enter :command:`ls -a` at the terminal prompt.
|
||||
|
||||
The following dialog opens, displaying the file name the configuration
|
||||
was saved to.
|
||||
|
||||
.. image:: figures/app_kernel_conf_3.png
|
||||
:width: 400px
|
||||
:align: center
|
||||
:height: 150px
|
||||
:alt: Saved Configuration Name Dialog
|
||||
|
||||
#. Press :kbd:`Enter` to return to the options menu.
|
||||
|
||||
#. To load any saved kernel configuration file, tab to :guilabel:`< Load >` and
|
||||
press :kbd:`Enter`.
|
||||
|
||||
The following dialog opens with the :guilabel:`< Ok >` command selected:
|
||||
|
||||
.. image:: figures/app_kernel_conf_4.png
|
||||
:width: 400px
|
||||
:align: center
|
||||
:height: 175px
|
||||
:alt: Configuration File Load Dialog
|
||||
|
||||
#. To load the last saved kernel configuration file, press :guilabel:`< Ok >`,
|
||||
or to load another saved configuration file, type the file name, then select
|
||||
:guilabel:`< Ok >`.
|
||||
|
||||
#. Press :kbd:`Enter` to load the file and return to the main menu.
|
||||
|
||||
#. To exit the menu configuration, tab to :guilabel:`< Exit >` and press
|
||||
:kbd:`Enter`.
|
||||
|
||||
The following confirmation dialog opens with the :guilabel:`< Yes >`
|
||||
command selected.
|
||||
|
||||
.. image:: figures/app_kernel_conf_5.png
|
||||
:width: 400px
|
||||
:align: center
|
||||
:height: 100px
|
||||
:alt: Exit Dialog
|
||||
|
||||
#. Press :kbd:`Enter` to retire the menu display and return to the console
|
||||
command line.
|
||||
|
||||
Application-Specific Code
|
||||
=========================
|
||||
|
||||
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::
|
||||
|
||||
These Makefiles are distinct from the top-level application Makefile
|
||||
that appears in :file:`~/app`.
|
||||
|
||||
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>`_.
|
||||
|
||||
|
||||
The following requirements apply to all Makefiles in the :file:`src`
|
||||
directory, including any sub-directories it may have.
|
||||
|
||||
* 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::
|
||||
|
||||
A source file that is not referenced by any Makefile is not included
|
||||
when the application is built.
|
||||
|
||||
* A Makefile cannot directly reference source code. It can only
|
||||
reference object files (:file:`.o` files) produced from source code files.
|
||||
|
||||
* A Makefile can only reference files in its own directory or in the
|
||||
sub-directories of that directory.
|
||||
|
||||
* A Makefile may reference multiple files from a single-line entry.
|
||||
However, a separate line must be used to reference each directory.
|
||||
|
||||
|
||||
|
||||
#. Create a directory structure for your source code in :file:`src`
|
||||
and add your source code files to it.
|
||||
|
||||
#. 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 += file1.o file2.o
|
||||
|
||||
b) Use the following syntax to add directory references:
|
||||
|
||||
.. code-block:: make
|
||||
|
||||
obj-y += directory_name/**
|
||||
|
||||
|
||||
This example is taken from the Philosopher's Sample. To examine this file in
|
||||
context, navigate to: :file:`\$ZEPHYR_BASE/samples/philosophers/src`.
|
||||
|
||||
.. code-block:: make
|
||||
|
||||
obj-y = main.o
|
||||
|
||||
|
||||
|
||||
Build an Application
|
||||
====================
|
||||
|
||||
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.
|
||||
|
||||
|
||||
#. Navigate to the application directory :file:`~/app`.
|
||||
|
||||
#. 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. Consequently, rebuilding an application
|
||||
is often significantly faster than building it the first time.
|
||||
|
||||
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:`~/app`.
|
||||
|
||||
#. 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.
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ make [BOARD=<type>] clean
|
||||
|
||||
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.
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ make pristine
|
||||
|
||||
#. Rebuild the application normally following the steps specified
|
||||
in `Build an Application`_ above.
|
||||
|
||||
|
||||
|
||||
Run an Application
|
||||
==================
|
||||
|
||||
An application image can be run on real or emulated hardware. The kernel has
|
||||
built-in emulator support for QEMU. It allows you to run and test an application
|
||||
virtually, before (or in lieu of) loading and running it on actual target
|
||||
hardware.
|
||||
|
||||
#. Open a terminal console and navigate to the application directory
|
||||
:file:`~/app`.
|
||||
|
||||
#. 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
|
||||
|
||||
$ make [BOARD=<type> ...] qemu
|
||||
|
||||
The Zephyr build system generates a :file:`zephyr.elf` image file
|
||||
and then begins running it in the terminal console.
|
||||
|
||||
#. Press :kbd:`Ctrl A, X` to stop the application from running
|
||||
in QEMU.
|
||||
|
||||
The application stops running and the terminal console prompt
|
||||
redisplays.
|
||||
|
||||
Application Debugging
|
||||
=====================
|
||||
|
||||
This section is a quick hands-on reference to start debugging your
|
||||
application with QEMU. Most content in this section is already covered on
|
||||
`QEMU`_ and `GNU_Debugger`_ reference manuals.
|
||||
|
||||
.. _QEMU: http://wiki.qemu.org/Main_Page
|
||||
|
||||
.. _GNU_Debugger: http://www.gnu.org/software/gdb
|
||||
|
||||
In this quick reference you find shortcuts, specific environmental variables
|
||||
and parameters that can help you to quickly set up your debugging
|
||||
environment.
|
||||
|
||||
The simplest way to debug an application running in QEMU is using the GNU
|
||||
Debugger and setting a local GDB server in your development system
|
||||
through QEMU.
|
||||
|
||||
You will need an ELF binary image for debugging purposes.
|
||||
The build system generates the image in the output directory.
|
||||
By default, the kernel binary name is :file:`zephyr.elf`. The name can be
|
||||
changed using a Kconfig option.
|
||||
|
||||
We will use the standard 1234 TCP port to open a :abbr:`GDB (GNU Debugger)`
|
||||
server instance. This port number can be changed for a port that best suits the
|
||||
development system.
|
||||
|
||||
QEMU is the supported emulation system of the kernel. QEMU must be invoked
|
||||
with the -s and -S options.
|
||||
|
||||
* ``-S`` Do not start CPU at startup; rather, you must type 'c' in the
|
||||
monitor.
|
||||
* ``-s`` Shorthand for :literal:`-gdb tcp::1234`: open a GDB server on
|
||||
TCP port 1234.
|
||||
|
||||
The build system can build the elf binary and call the QEMU process with
|
||||
the :makevar:`qemu` target. The QEMU debug options can be set using the
|
||||
environment variable :envvar:`QEMU_EXTRA_FLAGS`. To set the ``-s`` and
|
||||
``-S`` options:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
export QEMU_EXTRA_FLAGS="-s -S"
|
||||
|
||||
The build and emulation processes are called with the Makefile ``qemu``
|
||||
target:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
make qemu
|
||||
|
||||
The build system will start a QEMU instance with the CPU halted at startup
|
||||
and with a GDB server instance listening at the TCP port 1234.
|
||||
|
||||
The :file:`.gdbinit` will help initialize your GDB instance on every run.
|
||||
In this example, the initialization file points to the GDB server instance.
|
||||
It configures a connection to a remote target at the local host on the TCP
|
||||
port 1234. The initialization sets the kernel's root directory as a
|
||||
reference. The :file:`.gdbinit` file contains the following lines:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
target remote localhost:1234
|
||||
dir ZEPHYR_BASE
|
||||
|
||||
.. note::
|
||||
|
||||
Substitute ZEPHYR_BASE for the current kernel's root directory.
|
||||
|
||||
Execute the application to debug from the same directory that you chose for
|
||||
the :file:`gdbinit` file. The command can include the ``--tui`` option
|
||||
to enable the use of a terminal user interface. The following commands
|
||||
connects to the GDB server using :file:`gdb`. The command loads the symbol
|
||||
table from the elf binary file. In this example, the elf binary file name
|
||||
corresponds to :file:`zephyr.elf` file:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
gdb --tui zephyr.elf
|
||||
|
||||
.. note::
|
||||
|
||||
The GDB version on the development system might not support the --tui
|
||||
option.
|
||||
|
||||
Finally, this command connects to the GDB server using the Data
|
||||
Displayer Debugger (:file:`ddd`). The command loads the symbol table from the
|
||||
elf binary file, in this instance, the :file:`zephyr.elf` file.
|
||||
|
||||
The :abbr:`DDD (Data Displayer Debugger)` may not be installed in your
|
||||
development system by default. Follow your system instructions to install
|
||||
it.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
ddd --gdb --debugger "gdb zephyr.elf"
|
||||
|
||||
|
||||
Both commands execute the :abbr:`gdb (GNU Debugger)`. The command name might
|
||||
change depending on the toolchain you are using and your cross-development
|
||||
tools.
|
||||
|
|
|
@ -1,117 +0,0 @@
|
|||
.. _apps_build:
|
||||
|
||||
Build an Application
|
||||
####################
|
||||
|
||||
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.
|
||||
|
||||
.. contents:: Procedures
|
||||
:local:
|
||||
:depth: 1
|
||||
|
||||
Building an Application
|
||||
=======================
|
||||
|
||||
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.
|
||||
|
||||
Before you begin
|
||||
----------------
|
||||
|
||||
* 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`.
|
||||
|
||||
* 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`.
|
||||
|
||||
Steps
|
||||
-----
|
||||
|
||||
#. Navigate to the application directory :file:`~/appDir`.
|
||||
|
||||
#. 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. Consequently, rebuilding an application
|
||||
is often significantly faster than building it the first time.
|
||||
|
||||
Steps
|
||||
-----
|
||||
|
||||
#. 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`.
|
||||
|
||||
#. 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.
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ make [BOARD=<type>] clean
|
||||
|
||||
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.
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ make pristine
|
||||
|
||||
#. Rebuild the application normally following the steps specified
|
||||
in `Building an Application`_ above.
|
|
@ -1,152 +0,0 @@
|
|||
.. _apps_code_dev:
|
||||
|
||||
Add Application-Specific Code
|
||||
#############################
|
||||
|
||||
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
|
||||
|
||||
Adding Source Code to an Application Directory
|
||||
**********************************************
|
||||
|
||||
Understanding Source Code Requirements
|
||||
======================================
|
||||
|
||||
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::
|
||||
|
||||
These Makefiles are distinct from the top-level application Makefile
|
||||
that appears in :file:`~/appDir`.
|
||||
|
||||
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>`_.
|
||||
|
||||
Understanding Makefile Requirements
|
||||
===================================
|
||||
|
||||
The following requirements apply to all Makefiles in the :file:`src`
|
||||
directory, including any sub-directories it may have.
|
||||
|
||||
* 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::
|
||||
|
||||
A source file that is not referenced by any Makefile is not included
|
||||
when the application is built.
|
||||
|
||||
* A Makefile cannot directly reference source code. It can only
|
||||
reference object files (:file:`.o` files) produced from source code files.
|
||||
|
||||
* A Makefile can only reference files in its own directory or in the
|
||||
sub-directories of that directory.
|
||||
|
||||
* 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
|
||||
-----
|
||||
|
||||
#. Create a directory structure for your source code in :file:`src`
|
||||
and add your source code files to it.
|
||||
|
||||
#. 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 += file1.o file2.o
|
||||
|
||||
b) Use the following syntax to add directory references:
|
||||
|
||||
.. code-block:: make
|
||||
|
||||
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:`\$ZEPHYR_BASE/samples/philosophers/src`.
|
||||
|
||||
.. code-block:: make
|
||||
|
||||
obj-y = main.o
|
||||
|
||||
|
||||
Modifying and Enhancing the Kernel
|
||||
**********************************
|
||||
|
||||
Subsystem Naming Conventions
|
||||
============================
|
||||
|
||||
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
|
||||
==============================
|
||||
|
||||
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.
|
||||
|
||||
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>`.
|
||||
|
||||
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.
|
|
@ -1,38 +0,0 @@
|
|||
.. _apps_common_procedures:
|
||||
|
||||
Common Procedures
|
||||
#################
|
||||
|
||||
Instructions that are common to many procedures are provided here
|
||||
and referred to from the procedures that require them.
|
||||
|
||||
Procedures
|
||||
**********
|
||||
|
||||
.. _set_environment_variables:
|
||||
|
||||
Setting Environment Variables
|
||||
=============================
|
||||
|
||||
Set environment variables every time you open a terminal console to work on
|
||||
applications.
|
||||
|
||||
Steps
|
||||
-----
|
||||
|
||||
1. In a shell terminal console, enter an :command:`export` command that is
|
||||
consistent with your toolchain.
|
||||
|
||||
For the Zephyr SDK:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ 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
|
||||
kernel's installation directory and enter:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ source zephyr-env.sh
|
|
@ -1,256 +0,0 @@
|
|||
.. _apps_kernel_conf:
|
||||
|
||||
Configure an Application's Kernel
|
||||
#################################
|
||||
|
||||
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):
|
||||
|
||||
#. The application's current configuration.
|
||||
(i.e. The :file:`.config` file.)
|
||||
|
||||
#. The application's default configuration.
|
||||
(i.e. The :file:`.conf` file.)
|
||||
|
||||
#. The board configuration used by the application.
|
||||
(i.e. The board's :file:`.defconfig` file.)
|
||||
|
||||
#. The kernel's default configuration.
|
||||
(i.e. One of the kernel's :file:`Kconfig` files.)
|
||||
|
||||
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.
|
||||
|
||||
.. contents:: Procedures
|
||||
:local:
|
||||
:depth: 1
|
||||
|
||||
Defining the Application's Default Kernel Configuration
|
||||
=======================================================
|
||||
|
||||
An application's :file:`.conf` file defines its default kernel configuration.
|
||||
The settings in this file override or augment the board configuration settings.
|
||||
|
||||
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
|
||||
----------------
|
||||
|
||||
* 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
|
||||
|
||||
The default name is :file:`prj.conf`. The filename must match
|
||||
the ``CONF_FILE`` entry in the application :file:`Makefile`.
|
||||
|
||||
2. Edit the file and add the appropriate configuration entries.
|
||||
|
||||
a) Add each configuration entry on a new line.
|
||||
|
||||
b) Begin each entry with ``CONFIG_``.
|
||||
|
||||
c) Ensure that each entry contains no spaces
|
||||
(including on either side of the = sign).
|
||||
|
||||
d) Use a # followed by a space to comment a line.
|
||||
|
||||
The example below shows a comment line and a board
|
||||
configuration override in the :file:`prj.conf`.
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
# Change the number of IRQs supported by the application
|
||||
CONFIG_NUM_IRQS=43
|
||||
|
||||
3. Save and close the file.
|
||||
|
||||
|
||||
.. _override_kernel_conf:
|
||||
|
||||
Overriding the Application's Default Kernel Configuration
|
||||
=========================================================
|
||||
|
||||
Override the application's default kernel configuration to
|
||||
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.
|
||||
|
||||
Configure the kernel options using a menu-driven interface.
|
||||
While you can add entries manually, using the configuration menu
|
||||
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 set for your application.
|
||||
Be aware of any dependencies involving these options.
|
||||
|
||||
* Ensure the Zephyr environment variables are set for each console terminal;
|
||||
see :ref:`apps_common_procedures`.
|
||||
|
||||
Steps
|
||||
-----
|
||||
|
||||
1. Run the :command:`make menuconfig` rule to launch the
|
||||
menu-driven interface.
|
||||
|
||||
a) In a terminal session, navigate to the application directory
|
||||
(:file:`~/appDir`).
|
||||
|
||||
b) Enter the following command:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ make [BOARD=<type>] menuconfig
|
||||
|
||||
A question-based menu opens that allows you to set individual
|
||||
configuration options.
|
||||
|
||||
.. image:: figures/app_kernel_conf_1.png
|
||||
:width: 400px
|
||||
:align: center
|
||||
:height: 375px
|
||||
:alt: Main Configuration Menu
|
||||
|
||||
2. Set kernel configuration values using the following
|
||||
key commands:
|
||||
|
||||
* Use the arrow keys to navigate within any menu or list.
|
||||
|
||||
* Press :kbd:`Enter` to select a menu item.
|
||||
|
||||
* Type an upper case :kbd:`Y` or :kbd:`N` in the
|
||||
square brackets :guilabel:`[ ]` to
|
||||
enable or disable a kernel configuration option.
|
||||
|
||||
* Type a numerical value in the round brackets :guilabel:`( )`.
|
||||
|
||||
* Press :kbd:`Tab` to navigate the command menu at the
|
||||
bottom of the display.
|
||||
|
||||
.. note::
|
||||
|
||||
When a non-default entry is selected for options that
|
||||
are nonnumerical, an asterisk :kbd:`*` appears between the
|
||||
square brackets in the display. There is nothing added added
|
||||
the display when you select the option's default.
|
||||
|
||||
3. For information about any option, select the option and
|
||||
tab to :guilabel:`< Help >` and press :kbd:`Enter`.
|
||||
|
||||
Press :kbd:`Enter` to return to the menu.
|
||||
|
||||
4. After configuring the kernel options for your application,
|
||||
tab to :guilabel:`< Save >` and press :kbd:`Enter`.
|
||||
|
||||
The following dialog opens with the :guilabel:`< Ok >`
|
||||
command selected:
|
||||
|
||||
.. image:: figures/app_kernel_conf_2.png
|
||||
:width: 400px
|
||||
:align: center
|
||||
:height: 100px
|
||||
:alt: Save Configuration Dialog
|
||||
|
||||
|
||||
5. Press :kbd:`Enter` to save the kernel configuration options
|
||||
to the default file name; alternatively, type a file
|
||||
name and press :kbd:`Enter`.
|
||||
|
||||
Typically, you will save to the default file name unless
|
||||
you are experimenting with various configuration scenarios.
|
||||
|
||||
An :file:`outdir` directory is created in the application
|
||||
directory. The outdir directory contains symbolic links
|
||||
to files under :file:`\$ZEPHYR_BASE`.
|
||||
|
||||
.. note::
|
||||
|
||||
At present, only a :file:`.config` file can be built. If
|
||||
you have saved files with different file names and want to build
|
||||
with one of these, change the file name to :file:`.config`.
|
||||
To keep your original :file:`.config`, rename it to something
|
||||
other than :file:`.config`.
|
||||
|
||||
Kernel configuration files, such as the :file:`.config`
|
||||
file, are saved as hidden files in :file:`outdir`. To list
|
||||
all your kernel configuration files, enter :command:`ls -a`
|
||||
at the terminal prompt.
|
||||
|
||||
The following dialog opens, displaying the file name the
|
||||
configuration was saved to.
|
||||
|
||||
.. image:: figures/app_kernel_conf_3.png
|
||||
:width: 400px
|
||||
:align: center
|
||||
:height: 150px
|
||||
:alt: Saved Configuration Name Dialog
|
||||
|
||||
6. Press :kbd:`Enter` to return to the options menu.
|
||||
|
||||
7. To load any saved kernel configuration file,
|
||||
tab to :guilabel:`< Load >` and press :kbd:`Enter`.
|
||||
|
||||
The following dialog opens with the :guilabel:`< Ok >`
|
||||
command selected:
|
||||
|
||||
.. image:: figures/app_kernel_conf_4.png
|
||||
:width: 400px
|
||||
:align: center
|
||||
:height: 175px
|
||||
:alt: Configuration File Load Dialog
|
||||
|
||||
8. To load the last saved kernel configuration file, press
|
||||
:guilabel:`< Ok >`, or to load another saved configuration
|
||||
file, type the file name, then select :guilabel:`< Ok >`.
|
||||
|
||||
9. Press :kbd:`Enter` to load the file and return to the main
|
||||
menu.
|
||||
|
||||
10. To exit the menu configuration, tab to :guilabel:`< Exit >`
|
||||
and press :kbd:`Enter`.
|
||||
|
||||
The following confirmation dialog opens with the
|
||||
:guilabel:`< Yes >` command selected.
|
||||
|
||||
.. image:: figures/app_kernel_conf_5.png
|
||||
:width: 400px
|
||||
:align: center
|
||||
:height: 100px
|
||||
:alt: Exit Dialog
|
||||
|
||||
11. Press :kbd:`Enter` to retire the menu display and
|
||||
return to the console command line.
|
|
@ -1,37 +0,0 @@
|
|||
.. _apps_overview:
|
||||
|
||||
Application Overview
|
||||
####################
|
||||
|
||||
A Zephyr application is a collection of user-supplied files that can be built
|
||||
into an application image that executes on a board.
|
||||
|
||||
Each application resides in a distinct directory created by the developer.
|
||||
The directory has the following structure.
|
||||
|
||||
* **Application source code files**: An application typically provides one
|
||||
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.
|
||||
|
||||
* **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 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.
|
|
@ -1,58 +0,0 @@
|
|||
.. _apps_run:
|
||||
|
||||
Run an Application
|
||||
##################
|
||||
|
||||
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.
|
||||
|
||||
.. contents:: Procedures
|
||||
:local:
|
||||
:depth: 1
|
||||
|
||||
Running an Application using QEMU
|
||||
=================================
|
||||
|
||||
Prerequisites
|
||||
-------------
|
||||
|
||||
* 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`.
|
||||
|
||||
* Ensure the Zephyr environment variables are set for each console terminal;
|
||||
see :ref:`apps_common_procedures`.
|
||||
|
||||
Steps
|
||||
-----
|
||||
|
||||
#. Open a terminal console and navigate to the application directory
|
||||
:file:`~/appDir`.
|
||||
|
||||
#. 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
|
||||
|
||||
$ make [BOARD=<type> ...] qemu
|
||||
|
||||
The Zephyr build system generates a :file:`zephyr.elf` image file
|
||||
and then begins running it in the terminal console.
|
||||
|
||||
#. Press :kbd:`Ctrl A, X` to stop the application from running
|
||||
in QEMU.
|
||||
|
||||
The application stops running and the terminal console prompt
|
||||
redisplays.
|
||||
|
||||
Loading and Running an Application on Target Hardware
|
||||
=====================================================
|
||||
|
||||
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,166 +0,0 @@
|
|||
.. _apps_structure:
|
||||
|
||||
Create an Application Directory
|
||||
###############################
|
||||
|
||||
Each application resides in a uniquely-named application
|
||||
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.
|
||||
|
||||
.. contents:: Procedures
|
||||
:local:
|
||||
:depth: 1
|
||||
|
||||
Creating an Application and Source Code Directory
|
||||
=================================================
|
||||
|
||||
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
|
||||
----------------
|
||||
|
||||
* Ensure the Zephyr environment variables are set for each console terminal;
|
||||
see :ref:`apps_common_procedures`.
|
||||
|
||||
Steps
|
||||
-----
|
||||
|
||||
1. Create an application directory structure outside of the kernel's
|
||||
installation directory tree. Often this is your workspace directory.
|
||||
|
||||
a) In a console terminal, navigate to a location where you want your
|
||||
application to reside.
|
||||
|
||||
b) Create the application's directory, enter:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ mkdir application_name
|
||||
|
||||
.. note::
|
||||
|
||||
This directory and the path to it, are referred to in the documentation
|
||||
as :file:`~/appDir`.
|
||||
|
||||
2. Create a source code directory in your :file:`~/appDir`, enter:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ mkdir src
|
||||
|
||||
The source code directory :file:`~/appDir/src` is created.
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
-- appDir
|
||||
|-- src
|
||||
|
||||
Creating an Application Makefile
|
||||
================================
|
||||
|
||||
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
|
||||
----------------
|
||||
|
||||
* Be familiar with the standard GNU Make language.
|
||||
|
||||
* Be familiar with the board configuration used for your application
|
||||
and, if it is a custom board configuration, where it is located.
|
||||
|
||||
* Ensure the Zephyr environment variables are set for each console terminal;
|
||||
see :ref:`apps_common_procedures`.
|
||||
|
||||
Steps
|
||||
-----
|
||||
|
||||
1. In the :file:`appDir` directory, create a Makefile. Enter:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ touch Makefile
|
||||
|
||||
2. Open the :file:`Makefile` and add the following mandatory
|
||||
entries using any standard text editor.
|
||||
|
||||
.. note::
|
||||
|
||||
Ensure that there is a space after each ``=``.
|
||||
|
||||
a) Add the name of the default board configuration for your application on a
|
||||
new line:
|
||||
|
||||
.. code-block:: make
|
||||
|
||||
BOARD ?= board_configuration_name
|
||||
|
||||
The supported boards can be found in :ref:`board`.
|
||||
|
||||
b) Add the name of the default kernel configuration file for your
|
||||
application on a new line:
|
||||
|
||||
.. code-block:: make
|
||||
|
||||
CONF_FILE ?= kernel_configuration_name
|
||||
|
||||
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.
|
||||
|
||||
c) Include the mandatory :file:`Makefile` fragments on a new line:
|
||||
|
||||
.. code-block:: make
|
||||
|
||||
include ${ZEPHYR_BASE}/Makefile.inc
|
||||
|
||||
3. Save and close the :file:`Makefile`.
|
||||
|
||||
Example Makefile
|
||||
----------------
|
||||
|
||||
.. code-block:: make
|
||||
|
||||
BOARD ?= qemu_x86
|
||||
CONF_FILE ?= prj.conf
|
||||
include ${ZEPHYR_BASE}/Makefile.inc
|
||||
|
||||
Support for building third-party library code
|
||||
=============================================
|
||||
|
||||
When building library code it is important that both application and library
|
||||
code targets the same Application Binary Interface (ABI). On most architectures
|
||||
there are compiler flags that control the ABI targeted, making it important
|
||||
that both libraries and applications have certain compiler flags in common. It
|
||||
may also be useful for glue code to have access to Zephyr kernel header files.
|
||||
|
||||
To make it easier to integrate third-party components, the Zephyr project
|
||||
build system includes a special build target, ``outputexports``, that takes a
|
||||
number of critical variables from the Zephyr project build system and copies
|
||||
them into :file:`Makefile.export`. This allows the critical variables to be
|
||||
included by wrapper code for use in a third-party build system.
|
||||
|
||||
The following variables are recommended for use within the third-party build (see
|
||||
:file:`Makefile.export` for the complete list of exported variables):
|
||||
|
||||
* ``CROSS_COMPILE``, together with related convenience variables to call the
|
||||
cross-tools directly (including ``AR``, ``AS``, ``CC``, ``CXX``, ``CPP``
|
||||
and ``LD``).
|
||||
|
||||
* ``ARCH`` and ``BOARD``, together with several variables that identify the
|
||||
Zephyr kernel version.
|
||||
|
||||
* ``KBUILD_CFLAGS``, ``NOSTDINC_FLAGS`` and ``ZEPHYRINCLUDE`` all of which
|
||||
should normally be added, in that order, to ``CFLAGS`` (or
|
||||
``CXXFLAGS``).
|
||||
|
||||
* All kconfig variables, allowing features of the library code to be
|
||||
enabled/disabled automatically based on the Zephyr kernel configuration.
|
||||
|
||||
:file:`samples/static_lib` is a sample project that demonstrates
|
||||
some of these features.
|
|
@ -32,13 +32,13 @@ Sections
|
|||
getting_started/getting_started.rst
|
||||
board/board.rst
|
||||
kernel/kernel.rst
|
||||
application/application.rst
|
||||
porting/porting.rst
|
||||
drivers/drivers.rst
|
||||
subsystems/subsystems.rst
|
||||
api/api.rst
|
||||
application/application.rst
|
||||
reference/kconfig/index.rst
|
||||
contribute/code.rst
|
||||
porting/porting.rst
|
||||
reference/kbuild/kbuild.rst
|
||||
LICENSING.rst
|
||||
|
||||
You can find further information on the `Zephyr Project Wiki`_.
|
||||
|
|
|
@ -5,7 +5,7 @@ Zephyr Kernel Primer (version 2)
|
|||
|
||||
This document provides a general introduction of the Zephyr kernel's
|
||||
key capabilties and services. Additional details can be found by consulting
|
||||
the :ref:`api` and :ref:`apps_kernel_conf` documentation, and by examining
|
||||
the :ref:`api` and :ref:`application` documentation, and by examining
|
||||
the code in the Zephyr source tree.
|
||||
|
||||
.. toctree::
|
||||
|
|
|
@ -1,21 +0,0 @@
|
|||
.. _kbuild:
|
||||
|
||||
Build System User Guide
|
||||
#######################
|
||||
|
||||
The Zephyr Kernel's build system is based on the Kbuild system used in the
|
||||
Linux kernel. This way the kernel embraces the recursive model used in Linux
|
||||
and the configuration model implemented using Kconfig.
|
||||
|
||||
The build process is driven by applications, unlike the Linux Kbuild
|
||||
system. Therefore, the build system requires an application to initiate building
|
||||
the kernel source code. The build system compiles the kernel and the application
|
||||
into a single image.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
kbuild_kconfig
|
||||
../kconfig/index.rst
|
||||
kbuild_makefiles
|
||||
kbuild_project
|
|
@ -1,114 +0,0 @@
|
|||
.. _kconfig:
|
||||
|
||||
The Kconfig File Structure
|
||||
**************************
|
||||
|
||||
Introduction
|
||||
============
|
||||
|
||||
The Kconfig files describe: the configuration symbols supported in the build
|
||||
system, the logical organization and structure to group the symbols in menus
|
||||
and sub-menus, and the relationships between the different configuration
|
||||
symbols that govern the valid configuration combinations.
|
||||
|
||||
The Kconfig files are distributed across the build directory tree. The files
|
||||
are organized based on their common characteristics and on what new symbols
|
||||
they add to the configuration menus. For example:
|
||||
|
||||
* The Kconfig file at the root directory contains the general
|
||||
configuration options like :option:`CONFIG_ARCH` and
|
||||
``CONFIG_KERNEL VERSION``. These symbols are defined for and
|
||||
apply to the entire build system.
|
||||
|
||||
* The Kconfig file at the :file:`kernel` directory contains the general
|
||||
configuration related to the core kernel.
|
||||
|
||||
* The Kconfig file at the :file:`drivers` directory organizes the inclusion of
|
||||
the various Kconfig files needed for each supported driver in the system.
|
||||
|
||||
* The Kconfig file at the :file:`misc` directory contains the
|
||||
configuration symbols that affect different aspects of the build
|
||||
system. For example, the *Custom Compiler Options* and the
|
||||
``Minimal Libc`` are general build options that apply to the build
|
||||
system. *Debugging Options* and *System Monitoring Options* are
|
||||
also examples of build options that apply to the entire system.
|
||||
|
||||
* The Kconfig file at the :file:`net` directory contains the different symbols
|
||||
that define the configuration options for the communications stack code.
|
||||
|
||||
* The Kconfig file at the :file:`crypto` directory contains the different
|
||||
symbols that define the configuration options for the cryptography algorithms
|
||||
supported.
|
||||
|
||||
Dependencies
|
||||
============
|
||||
|
||||
Dependencies allow you to define the valid and invalid configuration
|
||||
combinations in the system. Each dependency is a rule that a particular symbol
|
||||
must follow to be either selected or allowed to have a specific value. For
|
||||
example, the configuration symbol *B* states a dependency on another one, *A*.
|
||||
|
||||
.. code-block:: kconfig
|
||||
|
||||
config B bool
|
||||
|
||||
config A depends on B
|
||||
|
||||
The symbol A does not exist as a configuration option in the system unless B is
|
||||
set to true.
|
||||
|
||||
The complete set of dependency rules defines the valid configuration
|
||||
combinations that the system can use.
|
||||
|
||||
|
||||
Default Configurations
|
||||
======================
|
||||
|
||||
The default configuration files define the default configuration for a specific
|
||||
kernel on a specific SoC. For example:
|
||||
|
||||
* :file:`arch/arm/configs`,
|
||||
* :file:`arch/x86/configs` and
|
||||
* :file:`arch/arc/configs`.
|
||||
|
||||
All the default configuration files must end with the suffix _defconfig. For
|
||||
example, the :file:`galileo_defconfig` file contains the configuration
|
||||
information for the galileo board.
|
||||
|
||||
The :file:`Makefile.inc` file uses defconfig files to provide a clean interface
|
||||
to developers using environment variables to define the kernel type and the
|
||||
board of new projects. Developers can provide the build system with a
|
||||
target's defconfig. The build system takes the specified defconfig file and
|
||||
sets it as the current :file:`.config` file for the current project. For
|
||||
example:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ make galileo_defconfig
|
||||
|
||||
The command takes the default configuration for the architecture
|
||||
and the galileo board configuration to compile the kernel.
|
||||
|
||||
.. _configuration_snippets:
|
||||
|
||||
Merging Configuration Fragments
|
||||
===============================
|
||||
|
||||
Configuration file fragment can be merged with the current project
|
||||
configuration during the build.
|
||||
|
||||
Developers can provide a configuration file that defines a small subset of
|
||||
configuration options. The subset must contain the specific configuration
|
||||
options that differ from the default configuration.
|
||||
|
||||
The **initconfig** target pulls the default configuration file and merges it
|
||||
with the local configuration fragments. For example, the sample application **hello
|
||||
world** overrides the base configuration with the configuration fragment in
|
||||
:file:`prj.conf`.
|
||||
|
||||
.. caution::
|
||||
Invalid configurations, or configurations that do not comply with
|
||||
the dependencies stated in the Kconfig files, are ignored by the merge process.
|
||||
When adding configuration options through a configuration fragment, ensure that
|
||||
the complete sequence complies with the dependency rules defined in the
|
||||
Kconfig files.
|
|
@ -1,96 +0,0 @@
|
|||
.. _kbuild_makefiles:
|
||||
|
||||
The Makefiles
|
||||
*************
|
||||
|
||||
Overview
|
||||
========
|
||||
|
||||
The build system defines a set of conventions for the correct use of Makefiles
|
||||
in the kernel source directories. The correct use of Makefiles is driven by the
|
||||
concept of recursion.
|
||||
|
||||
In the recursion model, each Makefile within a directory includes the source
|
||||
code and any subdirectories to the build process. Each subdirectory follows
|
||||
the same principle. Developers can focus exclusively in their own work. They
|
||||
integrate their module with the build system by adding a very simple Makefile
|
||||
following the recursive model.
|
||||
|
||||
.. _makefile_conventions:
|
||||
|
||||
Makefile Conventions
|
||||
====================
|
||||
|
||||
The following conventions restrict how to add modules and Makefiles to the
|
||||
build system. These conventions guard the correct implementation of the
|
||||
recursive model.
|
||||
|
||||
* Each source code directory must contain a single Makefile. Directories
|
||||
without a Makefile are not considered source code directories.
|
||||
|
||||
* The scope of every Makefile is restricted to the contents of that directory.
|
||||
A Makefile can only make a direct reference to its own files and subdirectories.
|
||||
Any file outside the directory has to be referenced in its home directory Makefile.
|
||||
|
||||
* Makefiles list the object files that are included in the link process. The
|
||||
build system finds the source file that generates the object file by matching
|
||||
the file name.
|
||||
|
||||
* Parent directories add their child directories into the recursion model.
|
||||
|
||||
* The root Makefile adds the directories in the kernel base directory into the
|
||||
recursion model.
|
||||
|
||||
|
||||
Adding Source Files
|
||||
===================
|
||||
A source file is added to the build system through its home directory Makefile.
|
||||
The Makefile must refer the source build indirectly, specifying the object file
|
||||
that results from the source file using the :literal:`obj-y` variable. For
|
||||
example, if the file that we want to add is a C file named :file:`<file>.c` the
|
||||
following line should be added in the Makefile:
|
||||
|
||||
.. code-block:: make
|
||||
|
||||
obj-y += <file>.o
|
||||
|
||||
.. note::
|
||||
|
||||
The same method applies for assembly files with .s extension.
|
||||
|
||||
Source files can be added conditionally using configuration options. For
|
||||
example, if the option ``CONFIG_VAR`` is set and it implies that a source
|
||||
file must be added in the compilation process, then the following line adds the
|
||||
source code conditionally:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
obj-$(CONFIG_VAR) += <file>.o
|
||||
|
||||
Adding Directories
|
||||
==================
|
||||
|
||||
Add a subdirectory to the build system by editing the Makefile in its
|
||||
directory. The subdirectory is added using the :literal:`obj-y` variable. The
|
||||
correct syntax to add a subdirectory into the recursion is:
|
||||
|
||||
.. code-block:: make
|
||||
|
||||
obj-y += <directory_name>/
|
||||
|
||||
The backslash at the end of the directory name signals the build system that a
|
||||
directory, and not a file, is being added to the recursion.
|
||||
|
||||
The conventions require us to add only one directory per line and never to mix
|
||||
source code with directory recursion in a single :literal:`obj-y` line. This
|
||||
helps keep the readability of the Makefile by making it clear when an item adds
|
||||
an additional lever of recursion.
|
||||
|
||||
Directories can also be conditionally added:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
obj-y-$(CONFIG_VAR) += <directory_name>/
|
||||
|
||||
The subdirectory must contain its own Makefile following the rules described in
|
||||
:ref:`makefile_conventions`.
|
|
@ -1,194 +0,0 @@
|
|||
.. _kbuild_project:
|
||||
|
||||
Developing an Application and the Build System
|
||||
**********************************************
|
||||
|
||||
The build system is an application centric system. The application drives the
|
||||
configuration and build process of the kernel binary.
|
||||
|
||||
Application development can be organized in three independent directories:
|
||||
the kernel base directory, the project directory, and the project source code
|
||||
directory.
|
||||
|
||||
The Zephyr Kernel's base directory hosts the kernel source code, the
|
||||
configuration options, and the kernel build definitions.
|
||||
|
||||
The application directory is the directory that puts together the kernel with
|
||||
the developer's application. It hosts the definitions of the developers'
|
||||
applications. For example, application-specific configuration options and the
|
||||
application's
|
||||
source code.
|
||||
|
||||
The Application Project
|
||||
=======================
|
||||
|
||||
A common application project is composed of the following files:
|
||||
|
||||
* **Makefile**: Defines the application's build process and integrates the
|
||||
developer's application with the kernel's build system.
|
||||
|
||||
* **Configuration file**: Allows the developer to override the board's
|
||||
default configuration.
|
||||
|
||||
* **The :file:`src/` directory**: By default, this directory hosts the
|
||||
application's source code. This location can be overridden and defined in a
|
||||
different directory.
|
||||
|
||||
* **Makefile**: Adds the developer's source code into the build system's
|
||||
recursion model.
|
||||
|
||||
The application's source code can be organized in subdirectories.
|
||||
Each directory must follow the Kbuild Makefile conventions; see
|
||||
:ref:`kbuild_makefiles`.
|
||||
|
||||
Application Definition
|
||||
======================
|
||||
|
||||
The developer defines the relationship of application to build system through
|
||||
the Makefiles. The application is integrated into the build system by
|
||||
including the Makefile.inc file provided.
|
||||
|
||||
.. code-block:: make
|
||||
|
||||
include $(ZEPHYR_BASE)/Makefile.inc
|
||||
|
||||
The following predefined variables configure the development project:
|
||||
|
||||
* :makevar:`ARCH`: Specifies the build architecture for the kernel. The
|
||||
architectures currently supported are x86, arm and arc. The build system
|
||||
sets C flags, selects the default configuration and uses the appropriate
|
||||
toolchain tools. The default value is x86.
|
||||
|
||||
* :makevar:`ZEPHYR_BASE`: Sets the path to the kernel's base directory.
|
||||
This variable is usually set by the :file:`zephyr_env.sh` script.
|
||||
It can be used to get the kernel's base directory, as used in the
|
||||
Makefile.inc inclusion above, or it can be overridden to select an
|
||||
specific instance of the kernel.
|
||||
|
||||
* :makevar:`PROJECT_BASE`: Provides the developer's application project
|
||||
directory path. It is set by the :file:`Makefile.inc` file.
|
||||
|
||||
* :makevar:`SOURCE_DIR`: Overrides the default value for the application's
|
||||
source code directory. The developer source code directory is set to
|
||||
:file:`$(PROJECT_BASE/)src/` by default. This directory name should end
|
||||
with slash **'/'**.
|
||||
|
||||
* :makevar:`BOARD`: Selects the board that the application's
|
||||
build will use for the default configuration.
|
||||
|
||||
* :makevar:`CONF_FILE`: Indicates the name of a configuration fragment file.
|
||||
This file includes the kconfig configuration values that override the
|
||||
default configuration values.
|
||||
|
||||
* :makevar:`O`: Optional. Indicates the output directory that Kconfig uses.
|
||||
The output directory stores all the files generated during the build
|
||||
process. The default output directory is the :file:`$(PROJECT_BASE)/outdir`
|
||||
directory.
|
||||
|
||||
Application Debugging
|
||||
=====================
|
||||
|
||||
This section is a quick hands-on reference to start debugging your
|
||||
application with QEMU. Most content in this section is already covered on
|
||||
`QEMU`_ and `GNU_Debugger`_ reference manuals.
|
||||
|
||||
.. _QEMU: http://wiki.qemu.org/Main_Page
|
||||
|
||||
.. _GNU_Debugger: http://www.gnu.org/software/gdb
|
||||
|
||||
In this quick reference you find shortcuts, specific environmental variables
|
||||
and parameters that can help you to quickly set up your debugging
|
||||
environment.
|
||||
|
||||
The simplest way to debug an application running in QEMU is using the GNU
|
||||
Debugger and setting a local GDB server in your development system
|
||||
through QEMU.
|
||||
|
||||
You will need an ELF binary image for debugging purposes.
|
||||
The build system generates the image in the output directory.
|
||||
By default, the kernel binary name is :file:`zephyr.elf`. The name can be
|
||||
changed using Kconfig.
|
||||
|
||||
.. note::
|
||||
|
||||
We will use the standard 1234 TCP port to open a
|
||||
:abbr:`GDB (GNU Debugger)` server instance. This port number can be
|
||||
changed for a port that best suits the development system.
|
||||
|
||||
QEMU is the supported emulation system of the kernel. QEMU must be invoked
|
||||
with the -s and -S options.
|
||||
|
||||
* ``-S`` Do not start CPU at startup; rather, you must type 'c' in the
|
||||
monitor.
|
||||
* ``-s`` Shorthand for :literal:`-gdb tcp::1234`: open a GDB server on
|
||||
TCP port 1234.
|
||||
|
||||
The build system can build the elf binary and call the QEMU process with
|
||||
the :makevar:`qemu` target. The QEMU debug options can be set using the
|
||||
environment variable :envvar:`QEMU_EXTRA_FLAGS`. To set the ``-s`` and
|
||||
``-S`` options:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
export QEMU_EXTRA_FLAGS="-s -S"
|
||||
|
||||
The build and emulation processes are called with the Makefile ``qemu``
|
||||
target:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
make qemu
|
||||
|
||||
The build system will start a QEMU instance with the CPU halted at startup
|
||||
and with a GDB server instance listening at the TCP port 1234.
|
||||
|
||||
The :file:`.gdbinit` will help initialize your GDB instance on every run.
|
||||
In this example, the initialization file points to the GDB server instance.
|
||||
It configures a connection to a remote target at the local host on the TCP
|
||||
port 1234. The initialization sets the kernel's root directory as a
|
||||
reference. The :file:`.gdbinit` file contains the following lines:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
target remote localhost:1234
|
||||
dir ZEPHYR_BASE
|
||||
|
||||
.. note::
|
||||
|
||||
Substitute ZEPHYR_BASE for the current kernel's root directory.
|
||||
|
||||
Execute the application to debug from the same directory that you chose for
|
||||
the :file:`gdbinit` file. The command can include the ``--tui`` option
|
||||
to enable the use of a terminal user interface. The following commands
|
||||
connects to the GDB server using :file:`gdb`. The command loads the symbol
|
||||
table from the elf binary file. In this example, the elf binary file name
|
||||
corresponds to :file:`zephyr.elf` file:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
gdb --tui zephyr.elf
|
||||
|
||||
.. note::
|
||||
|
||||
The GDB version on the development system might not support the --tui
|
||||
option.
|
||||
|
||||
Finally, this command connects to the GDB server using the Data
|
||||
Displayer Debugger (:file:`ddd`). The command loads the symbol table from the
|
||||
elf binary file, in this instance, the :file:`zephyr.elf` file.
|
||||
|
||||
.. note::
|
||||
|
||||
The :abbr:`DDD (Data Displayer Debugger)` may not be installed in your
|
||||
development system by default. Follow your system instructions to install
|
||||
it.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
ddd --gdb --debugger "gdb zephyr.elf"
|
||||
|
||||
.. note::
|
||||
|
||||
Both commands execute the :abbr:`gdb (GNU Debugger)`.
|
||||
The command name might change depending on the toolchain you are using
|
||||
and your cross-development tools.
|
Loading…
Add table
Add a link
Reference in a new issue