178 lines
5.3 KiB
ReStructuredText
178 lines
5.3 KiB
ReStructuredText
.. _apps_code_dev:
|
|
|
|
Application Code Development
|
|
############################
|
|
|
|
.. contents::
|
|
:local:
|
|
:depth: 1
|
|
|
|
.. _develop_services:
|
|
|
|
Services
|
|
********
|
|
|
|
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`.
|
|
|
|
.. note::
|
|
|
|
There are more microkernel services than those defined in
|
|
the MDEF.
|
|
|
|
Nanokernel Services
|
|
===================
|
|
|
|
For a complete list of nanokernel services, including a description
|
|
of each with code examples, see :ref:`nanokernel`.
|
|
|
|
Common Services
|
|
===============
|
|
|
|
For a complete list of services common to both the nanokernel and
|
|
microkernel, including a description of each with code examples,
|
|
see :ref:`common`.
|
|
|
|
|
|
Procedures and Conventions
|
|
**************************
|
|
|
|
Understanding Naming Conventions
|
|
================================
|
|
|
|
The kernel limits the use of some prefixes to internal use only. For
|
|
more information, see :ref:`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.
|
|
|
|
Before You Begin
|
|
-----------------
|
|
|
|
* The Zephyr environment variable must be set for each console
|
|
terminal using :ref:`apps_common_procedures`.
|
|
|
|
Steps
|
|
-----
|
|
|
|
1. 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.
|
|
|
|
a) Use the following syntax to add file references:
|
|
|
|
.. code-block:: make
|
|
|
|
obj-y += file.o file.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:`rootDir/samples/philosophers/microkernel/src`.
|
|
|
|
.. code-block:: make
|
|
|
|
obj-y = phil_fiber.o phil_task.o
|
|
|
|
|
|
.. _`enhancing_kernel`:
|
|
|
|
Enhancing the Zephyr Kernel
|
|
===========================
|
|
|
|
When enhancing the Zephyr kernel, follow the subsystem naming
|
|
conventions and the :literal:`include path` usage guidelines.
|
|
|
|
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
|
|
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 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.
|
|
|
|
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.
|