doc: coding style: Introduce a naming conventions section

Add a new section with Zephyr-wide naming conventions, as well as a
first rule for C code: area prefixes.

Signed-off-by: Carles Cufi <[email protected]>

Author: carlescufi

doc/contribute/style/index.rst

@@ -7,6 +7,7 @@ Coding Style Guidelines
 .. toctree::
    :maxdepth: 1
 
+   naming.rst
    code.rst
    cmake.rst
    devicetree.rst

doc/contribute/style/naming.rst

@@ -0,0 +1,26 @@
+.. _naming_conventions:
+
+Naming conventions
+##################
+
+This section describes the naming conventions adopted by the Zephyr
+Project, for each individual programming language or tool used in it.
+
+C Code naming conventions
+*************************
+
+The naming conventions in this section apply to C source and header files,
+as stated in each individual sub-section.
+
+Public symbol prefixes
+======================
+
+All :term:`public APIs <public API>` in Zephyr must be prefixed according
+to the area or subsystem they belong to. Examples of area or subsystem prefixes
+are provided below for reference.
+
+* ``k_`` for the kernel
+* ``sys_`` for system-wide code and features
+* ``net_`` for the networking subsystem
+* ``bt_`` for the Bluetooth subsystem
+* ``i2c_`` for the I2C controller subsystem

doc/glossary.rst

@@ -107,6 +107,18 @@ Glossary of Terms
       architecture to implement an interrupt vector table. The IDT is used
       to determine the correct response to interrupts and exceptions.
 
+   internal API
+      Any internal function, structure or macro defined anywhere in the Zephyr
+      source tree. Internal APIs are intended to "extend" Zephyr, and are to be
+      used only between certain :term:`software components <software
+      component>`, usually in-tree but in some cases out-of-tree (e.g. adding an
+      out-of-tree architecture or driver). Applications must not invoke
+      internal APIs outside their own scope. The context where the API is
+      called or implemented is well defined. For example, functions prefixed
+      with ``arch_`` are intended for use by the Zephyr kernel to invoke
+      architecture-specific code. Internal APIs are mostly kept stable, but with
+      fewer guarantees than :term:`public APIs <public API>`.
+
    ISR
       (Interrupt Service Routine) Also known as an interrupt handler, an ISR
       is a callback function whose execution is triggered by a hardware
@@ -127,6 +139,22 @@ Glossary of Terms
       Power gating reduces power consumption by shutting off areas of an
       integrated circuit that are not in use.
 
+   private API
+      Any function, structure or macro defined anywhere in the Zephyr source
+      tree which are only intended for consumption inside the
+      :term:`software component` where they are defined. Private APIs may change
+      at any time and must not be used by code outside the corresponding
+      software component.
+
+   public API
+      Any function, structure or macro defined inside the ``include/zephyr``
+      folder that is not explicitly marked as private. Public APIs are intended
+      for consumption by any and all in-tree or out-of-tree :term:`software
+      components <software component>`. Public APIs cannot be modified without
+      following the provisions described in the :ref:`API lifecycle
+      <api_lifecycle>` section, which means they provide guarantees that they
+      will remain stable over time.
+
    SoC
       A `System on a chip`_, that is, an integrated circuit that contains at
       least one :term:`CPU cluster` (in turn with at least one :term:`CPU core`),
@@ -140,6 +168,11 @@ Glossary of Terms
       A number of different :term:`SoCs <SoC>` that share similar characteristics and
       features, and that the vendor typically names and markets together.
 
+   software component
+      A software component is a self-contained, modular, and replaceable part of
+      the Zephyr source code. A driver, a subsystem or an applications are all
+      examples of software components present in Zephyr.
+
    subsystem
        A subsystem refers to a logically distinct part of the operating system
        that handles specific functionality or provides certain services.