michaelh/zephyr
1
0
Fork 0
Code Releases Activity

doc: Cleanup prefix table on naming_conventions.rst

Browse source 
Table updated with examples column to eliminate Latin prefixes (e.g.) and
to enhance readability.

W/S fixed

Change-Id: Ia92e2d5454e816595e054cb44caa56364f9dc1b3
Signed-off-by: L.S. Cook <leonax.cook@intel.com>
This commit is contained in:
L.S. Cook 2016-02-16 07:59:23 -08:00 • committed by Gerrit Code Review
commit 3f4c347f35
1 changed files with 44 additions and 38 deletions
Download patch file Download diff file Expand all files Collapse all files

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

@ -21,41 +21,47 @@ permitted to reference. Symbols that do not begin with a kernel namespace
prefix are available to applications with a few exceptions. See `Exceptions prefix are available to applications with a few exceptions. See `Exceptions
to the Namespace`_ for details. to the Namespace`_ for details.
+-------------------+---------------------------------------------------------+ +-----------------+--------------------------------------+------------------------+
| Prefix | Description | | Prefix | Description | Example |
+===================+=========================================================+ +=================+======================================+========================+
| \_ | Denotes a private kernel symbol (e.g. _k_signal_event). | | \_ | Denotes a private kernel symbol. | ``_k_signal_event`` |
+-------------------+---------------------------------------------------------+ +-----------------+--------------------------------------+------------------------+
| atomic\_ | Denotes an atomic operation (e.g. atomic_inc). | | atomic\_ | Denotes an atomic operation. | ``atomic_inc`` |
+-------------------+---------------------------------------------------------+ +-----------------+--------------------------------------+------------------------+
| device\_ | Denotes an API relating to devices and their | | device\_ | Denotes an API relating to devices | ``device_get_binding`` |
| | initialization | | | and their initialization. | |
+-------------------+---------------------------------------------------------+ +-----------------+--------------------------------------+------------------------+
| fiber\_ | Denotes an operation invoked by a fiber; typically a | |fiber\_ | Denotes an operation invoked by a | ``fiber_event_send`` |
| | microkernel operation (e.g. fiber_event_send). | | | fiber; typically a microkernel | |
+-------------------+---------------------------------------------------------+ | | operation. | |
| irq\_ | Denotes an IRQ management operation (e.g. ireq_disable).| +-----------------+--------------------------------------+------------------------+
+-------------------+---------------------------------------------------------+ | irq\_ | Denotes an IRQ management operation. | ``irq_disable`` |
| isr\_ | Denotes an operation called by an Interrupt Service | +-----------------+--------------------------------------+------------------------+
| | Routine; typically a microkernel operation (e.g. | | isr\_ | Denotes an operation called by an | ``isr_event_send`` |
| | isr_event_send). | | | Interrupt Service Routine; typically | |
+-------------------+---------------------------------------------------------+ | | a microkernel operation. | |
| k\_ | Microkernel-specific function (e.g. k_memcpy) | +-----------------+--------------------------------------+------------------------+
+-------------------+---------------------------------------------------------+ | k\_ | Microkernel-specific function. | ``k_memcpy`` |
| k_do\_ | Microkernel-specific functions that indicate essential | +-----------------+--------------------------------------+------------------------+
| | operation within the kernel space. Do not use these | | k_do\_ | Microkernel-specific functions | ``k_do_event_signal`` |
| | functions unless absolutely necessary. | | | indicating essential operation | |
+-------------------+---------------------------------------------------------+ | | within the kernel space. Do not use | |
| nano\_ | Denotes an operation provided by the nanokernel; | | | these functions unless absolutely | |
| | typically may be used in a microkernel system, not just | | | necessary. | |
| | a nanokernel system (e.g. nano_fifo_put). | +-----------------+--------------------------------------+------------------------+
+-------------------+---------------------------------------------------------+ | nano\_ | Denotes an operation provided by the | ``nano_fifo_put`` |
| sys\_ | Catch-all for APIs that do not fit into the other | | | nanokernel; typically used in a | |
| | namespaces. | | | microkernel system, not just a | |
+-------------------+---------------------------------------------------------+ | | nanokernel system. | |
| task\_ | Denotes an operation invoked by a task; typically a | +-----------------+--------------------------------------+------------------------+
| | microkernel operation (e.g. task_send_event). | | 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 If your additional symbol does not fall into the above classification, consider
renaming it. renaming it.
@ -85,9 +91,9 @@ Subsystem Naming Conventions
Generally, any sub-system can define its own naming conventions for symbols. Generally, any sub-system can define its own naming conventions for symbols.
However, these should be implemented with their own namespace prefix (for However, these should be implemented with their own namespace prefix (for
example, bt\_ for BlueTooth, or net\_ for IP). This limits possible clashes example, ``bt\_`` for BlueTooth, or ``net\_`` for IP). This limits possible
with applications. Following this prefix convention with subsystems keeps a clashes with applications. Following this prefix convention with subsystems
consistent interface for all users. keeps a consistent interface for all users.
Minimize Include Paths Minimize Include Paths
********************** **********************