206 lines
7.3 KiB
ReStructuredText
206 lines
7.3 KiB
ReStructuredText
.. _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.
|
|
|
|
* **MDEF**: Defines the set of kernel objects that the the application
|
|
instantiates. Required only by the microkernel.
|
|
|
|
* **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:`KERNEL_TYPE`: Selects the kernel type that the application's
|
|
build will use for the default configuration. It indicates whether to use a
|
|
nanokernel or microkernel architecture.
|
|
The supported values are **nano** and **micro**.
|
|
|
|
* :makevar:`MDEF_FILE`: Indicates the name of the MDEF file; required for
|
|
microkernel architectures only.
|
|
|
|
* :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.
|