michaelh/zephyr
1
0
Fork 0
Code Releases Activity

doc: Fix the Naming Conventions document markup.

Browse source 
Fixed the broken code blocks and rebased.
Content correction about architectures
Naming conventions fix broken line directive, comments, fix broken build
OK, really fixing the too-long line length this time...

Change-Id: Ib4aa60bed33ff40c5fbd6266670188c1c5e378c6
Signed-off-by: L.S. Cook <leonax.cook@intel.com>
This commit is contained in:
L.S. Cook 2015-09-25 12:43:35 -07:00 • committed by Anas Nashif
commit f833735bd2
1 changed files with 53 additions and 37 deletions
Download patch file Download diff file Expand all files Collapse all files

90
doc/collaboration/code/naming_conventions.rst
View file

@ -8,18 +8,18 @@ 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.
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 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.
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 |
@ -37,10 +37,10 @@ the Namespace`_ for details.
| | Routine; typically a microkernel operation (e.g. |
| | isr_event_send). |
+-------------------+---------------------------------------------------------+
| k\_ | Microkernel specific function (e.g. k_memcpy) |
| 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 |
| 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; |
@ -60,41 +60,57 @@ 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.
Some kernel APIs use well-known names that lack prefixes. A few examples are:
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().
* :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
****************************
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.
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 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/ia32`.
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:
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>.
.. 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::#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.
.. 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.