104 lines
5.6 KiB
ReStructuredText
104 lines
5.6 KiB
ReStructuredText
.. _code_naming_conventions:
|
||
|
||
Code_Naming_Conventions
|
||
#######################
|
||
|
||
|
||
The Purpose of 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. These are then
|
||
linked against 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 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 |
|
||
+===================+=========================================================+
|
||
| \_ | Denotes a private kernel symbol (e.g. _k_signal_event). |
|
||
+-------------------+---------------------------------------------------------+
|
||
| atomic\_ | Denotes an atomic operation (e.g. atomic_inc). |
|
||
+-------------------+---------------------------------------------------------+
|
||
| context\ | Denotes an operation invoked by a fiber or a task (e.g |
|
||
| | context_type_get). |
|
||
+-------------------+---------------------------------------------------------+
|
||
| fiber\_ | Denotes an operation invoked by a fiber; typically a |
|
||
| | microkernel operation (e.g. fiber_event_send). |
|
||
+-------------------+---------------------------------------------------------+
|
||
| irq\_ | Denotes an IRQ management operation (e.g. ireq_disable).|
|
||
+-------------------+---------------------------------------------------------+
|
||
| isr\_ | Denotes an operation called by an Interrupt Service |
|
||
| | Routine; typically a microkernel operation (e.g. |
|
||
| | isr_event_send). |
|
||
+-------------------+---------------------------------------------------------+
|
||
| k\_ | Microkernel specific function (e.g. k_memcpy) |
|
||
+-------------------+---------------------------------------------------------+
|
||
| k_do\_ | Microkernel specific functions that indicate essential |
|
||
| | operation within the kernel space. Do not use these |
|
||
| | functions unless absolutely necessary. |
|
||
+-------------------+---------------------------------------------------------+
|
||
| nano\_ | Denotes an operation provided by the nanokernel; |
|
||
| | typically may be used in a microkernel system, not just |
|
||
| | a nanokernel system (e.g. nano_fifo_put). |
|
||
+-------------------+---------------------------------------------------------+
|
||
| sys\_ | Catch-all for APIs that do not fit into the other |
|
||
| | namespaces. |
|
||
+-------------------+---------------------------------------------------------+
|
||
| task\_ | Denotes an operation invoked by a task; typically a |
|
||
| | microkernel operation (e.g. task_send_event). |
|
||
+-------------------+---------------------------------------------------------+
|
||
|
||
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 do not use the prefixes, for example:
|
||
ntohl, open, close, read, write, ioctl.
|
||
|
||
There are also a very limited and rare number of global symbols that do not use
|
||
the normal kernel prefixes; for example: kernel_version_get().
|
||
|
||
Subsystem Naming Conventions
|
||
****************************
|
||
|
||
In general any sub-system can define its own naming conventions for symbols.
|
||
However, they should be implemented using their own namespace prefix (for
|
||
example, bt\_ for BlueTooth, or net\_ for IP). This limits possible clashes
|
||
with applications. It is highly encouraged that any sub-system continue to
|
||
follow the above prefix conventions to keep 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 sub-system. For example, there are common defines for
|
||
all architectures under :file:`$ROOT/arch/x86`, and then more specific
|
||
defines for each supported board underneath it, like
|
||
:file:`$ROOT/arch/x86/generic_pc`.
|
||
|
||
Do not add all possible include paths in the :file:`defs.obj` files.
|
||
Too many default paths cause problems when more than one file have the same
|
||
name. The only include path into :file:`${vBASE}/include` should be
|
||
:file:`${vBASE}/include` itself, and the files should
|
||
code-block::#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::#include <pci.h> becomes ambiguous, while
|
||
code-block::#include <drivers/pci.h> is not. Not having
|
||
:option:`-Iinclude/drivers` forces users to use the second form which is more
|
||
explicit.
|