diff options
| -rw-r--r-- | doc/contribute/conventions.rst | 200 |
1 files changed, 2 insertions, 198 deletions
diff --git a/doc/contribute/conventions.rst b/doc/contribute/conventions.rst index 4f71d981a..588821abe 100644 --- a/doc/contribute/conventions.rst +++ b/doc/contribute/conventions.rst @@ -3,202 +3,6 @@ Coding Style and Conventions ################################# -Naming Conventions -****************** +Refer to the Zephyr project wiki to learn about Zephyr code 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 subsystem 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/drivers/pci.h`, and have set both ``-Iinclude/drivers`` -and ``-Iinclude`` for your compile, then any code using - -.. code-block:: c - - #include <pci.h> - -becomes ambiguous, while - -.. code-block:: c - - #include <drivers/pci.h> - -is not. Not having ``-Iinclude/drivers`` forces users to use the second -form which is more explicit. - -Return Codes -************ - -Zephyr uses the standard codes in :file:`errno.h` for all APIs. - -As a general rule, ``0`` indicates success; a negative errno.h code indicates -an error condition. The table below shows the error code conventions based on -device driver use cases, but they can also be applied to other kernel -components. - -+-----------------+------------------------------------------------+ -| Code | Meaning | -+=================+================================================+ -| 0 | Success. | -+-----------------+------------------------------------------------+ -| -EIO | General failure. | -+-----------------+------------------------------------------------+ -| -ENOTSUP | Operation is not supported or operation is | -| | invalid. | -+-----------------+------------------------------------------------+ -| -EINVAL | Device configuration is not valid or function | -| | argument is not valid. | -+-----------------+------------------------------------------------+ -| -EBUSY | Device controller is busy. | -+-----------------+------------------------------------------------+ -| -EACCES | Device controller is not accessible. | -+-----------------+------------------------------------------------+ -| -ENODEV | Device type is not supported. | -+-----------------+------------------------------------------------+ -| -EPERM | Device is not configured or operation is not | -| | permitted. | -+-----------------+------------------------------------------------+ -| -ENOSYS | Function is not implemented. | -+-----------------+------------------------------------------------+ - -.. _coding_style: - -Coding Style -************ - -Use this coding guideline to ensure that your development complies with -the project's style and naming conventions. - -In general, follow the `Linux kernel coding style`_, with the following -exceptions: - -* Add braces to every ``if`` and ``else`` body, even for single-line code - blocks. Use the ``--ignore BRACES`` flag to make :program:`checkpatch` - stop complaining. -* Use hard tab stops. Set the tab width 8 spaces. Break lines at 80 characters. - If you are trying to align comments after declarations, use spaces instead of - tabs to align them. -* Use C89-style single line comments, :literal:`/* */`. The C99-style - single line comment, //, is not allowed. -* Use :literal:`/** */` for any comments that need to appear in the - documentation. - -Checking for Conformity Using Checkpatch -======================================== - -The Linux kernel GPL-licensed tool :program:`checkpatch` is used to -check coding style conformity. :program:`Checkpatch` is available in the -scripts directory. To invoke it when committing code, edit your -:file:`.git/hooks/pre-commit` file to contain: - -.. code-block:: bash - - #!/bin/sh - - set -e exec - - exec git diff --cached | ${ZEPHYR_BASE}/scripts/checkpatch.pl - || true - -.. _Linux kernel coding style: https://www.kernel.org/doc/Documentation/CodingStyle +* https://wiki.zephyrproject.org/view/Coding_conventions
\ No newline at end of file |