129 lines
6.0 KiB
ReStructuredText
129 lines
6.0 KiB
ReStructuredText
.. _naming_conventions:
|
||
|
||
Coding Style and Conventions
|
||
#################################
|
||
|
||
Naming Conventions
|
||
******************
|
||
|
||
Unlike desktop operating systems, where applications are written in user-space
|
||
and drivers are used to cross the boundary between kernel and user space, *all*
|
||
applications in the Zephyr Kernel are written in kernel space. Applications are
|
||
linked with the kernel, creating a shared and common namespace.
|
||
|
||
To ensure proper execution of both kernel and applications, it makes sense to
|
||
divide the namespace into kernel and application subspaces. This is achieved
|
||
by restricting the kernel’s global symbols and macros to a well-defined set of
|
||
name prefixes. These prefixes apply both to public symbols, which applications
|
||
can reference, and to private symbols, which only the kernel itself is
|
||
permitted to reference. Symbols that do not begin with a kernel namespace
|
||
prefix are available to applications with a few exceptions. See `Exceptions
|
||
to the Namespace`_ for details.
|
||
|
||
+----------+--------------------------------------+------------------------+
|
||
| Prefix | Description | Example |
|
||
+==========+======================================+========================+
|
||
| \_ | Denotes a private symbol. | ``_k_signal_event`` |
|
||
+----------+--------------------------------------+------------------------+
|
||
| atomic\_ | Denotes an atomic operation. | ``atomic_inc`` |
|
||
+----------+--------------------------------------+------------------------+
|
||
| device\_ | Denotes an API relating to devices | ``device_get_binding`` |
|
||
| | and their initialization. | |
|
||
+----------+--------------------------------------+------------------------+
|
||
| fiber\_ | Denotes an operation invoked by a | ``fiber_event_send`` |
|
||
| | fiber; typically a microkernel | |
|
||
| | operation. | |
|
||
+----------+--------------------------------------+------------------------+
|
||
| irq\_ | Denotes an IRQ management operation. | ``irq_disable`` |
|
||
+----------+--------------------------------------+------------------------+
|
||
| isr\_ | Denotes an operation called by an | ``isr_event_send`` |
|
||
| | Interrupt Service Routine; typically | |
|
||
| | a microkernel operation. | |
|
||
+----------+--------------------------------------+------------------------+
|
||
| k\_ | Microkernel-specific function. | ``k_memcpy`` |
|
||
+----------+--------------------------------------+------------------------+
|
||
| k_do\_ | Microkernel-specific functions | ``k_do_event_signal`` |
|
||
| | indicating essential operation | |
|
||
| | within the kernel space. Do not use | |
|
||
| | these functions unless absolutely | |
|
||
| | necessary. | |
|
||
+----------+--------------------------------------+------------------------+
|
||
| nano\_ | Denotes an operation provided by the | ``nano_fifo_put`` |
|
||
| | nanokernel; typically used in a | |
|
||
| | microkernel system, not just a | |
|
||
| | nanokernel system. | |
|
||
+----------+--------------------------------------+------------------------+
|
||
| sys\_ | Catch-all for APIs that do not fit | ``sys_write32`` |
|
||
| | into the other namespaces. | |
|
||
+----------+--------------------------------------+------------------------+
|
||
| task\_ | Denotes an operation invoked by a | ``task_send_event`` |
|
||
| | task; typically a microkernel | |
|
||
| | operation. | |
|
||
+----------+--------------------------------------+------------------------+
|
||
|
||
|
||
If your additional symbol does not fall into the above classification, consider
|
||
renaming it.
|
||
|
||
Exceptions to the Namespace
|
||
===========================
|
||
|
||
Some kernel APIs use well-known names that lack prefixes. A few examples are:
|
||
|
||
* :code:`ntohl`
|
||
|
||
* :code:`open`
|
||
|
||
* :code:`close`
|
||
|
||
* :code:`read`
|
||
|
||
* :code:`write`
|
||
|
||
* :code:`ioctl`
|
||
|
||
In rare cases a few global symbols do not use the normal kernel prefixes;
|
||
:cpp:func:`kernel_version_get()` is one such example.
|
||
|
||
Subsystem Naming Conventions
|
||
============================
|
||
|
||
Generally, any sub-system can define its own naming conventions for symbols.
|
||
However, these should be implemented with their own namespace prefix (for
|
||
example, ``bt\_`` for BlueTooth, or ``net\_`` for IP). This limits possible
|
||
clashes with applications. Following this prefix convention with subsystems
|
||
keeps a consistent interface for all users.
|
||
|
||
Minimize Include Paths
|
||
======================
|
||
|
||
The current build system uses a series of :file:`defs.objs` files to define the
|
||
common pieces for a given subsystem. For example, common defines for x86
|
||
architecture are located under :file:`$ROOT/arch/x86`, with platform-specific
|
||
defines underneath it, like :file:`$ROOT/arch/x86/platform/ia32`.
|
||
Be careful to not add all possible :literal:`include` paths to the
|
||
:file:`defs.obj` files. Too many default paths can cause problems when more than
|
||
one file has the same name. The only :literal:`include paths` into
|
||
:file:`${vBASE}/include` should be :file:`${vBASE}/include` itself, and the header
|
||
files should be included with:
|
||
|
||
.. code-block:: c
|
||
|
||
#include <subdirectory/header.h>.
|
||
|
||
For example, if you have two files, :file:`include/pci.h` and
|
||
:file:`include/drvers/pci.h`, and have set both :option:`-Iinclude/drivers`
|
||
and :option:`-Iinclude` for your compile, then any code using
|
||
|
||
.. code-block:: c
|
||
|
||
#include <pci.h> becomes ambiguous, while
|
||
#include <drivers/pci.h>
|
||
|
||
is not. Not having :option:`-Iinclude/drivers` forces users to use the second
|
||
form which is more explicit.
|
||
|
||
.. include:: error_code_conventions.rst
|
||
|
||
.. include:: coding_style.rst
|