build: change ABI versioning to global

[dpdk.git] / doc / guides / contributing / coding_style.rst

diff --git a/doc/guides/contributing/coding_style.rst b/doc/guides/contributing/coding_style.rst
index b1bf0d1..841ef6d 100644 (file)
--- a/doc/guides/contributing/coding_style.rst
+++ b/doc/guides/contributing/coding_style.rst
@@ -247,6 +247,15 @@ Structure Declarations
 * Use of the structures should be by separate variable declarations and those declarations must be extern if they are declared in a header file.
 * Externally visible structure definitions should have the structure name prefixed by ``rte_`` to avoid namespace collisions.
 
 * Use of the structures should be by separate variable declarations and those declarations must be extern if they are declared in a header file.
 * Externally visible structure definitions should have the structure name prefixed by ``rte_`` to avoid namespace collisions.
 

+.. note::
+
+    Uses of ``bool`` in structures are not preferred as is wastes space and
+    it's also not clear as to what type size the bool is. A preferred use of
+    ``bool`` is mainly as a return type from functions that return true/false,
+    and maybe local variable functions.
+
+    Ref: `LKML <https://lkml.org/lkml/2017/11/21/384>`_
+

 Queues
 ~~~~~~
 
 Queues
 ~~~~~~
 


@@ -622,10 +631,10 @@ In the DPDK environment, use the logging interface provided:
 
  /* log in debug level */
  rte_log_set_global_level(RTE_LOG_DEBUG);
 
  /* log in debug level */
  rte_log_set_global_level(RTE_LOG_DEBUG);

- RTE_LOG(DEBUG, my_logtype1, "this is is a debug level message\n");
- RTE_LOG(INFO, my_logtype1, "this is is a info level message\n");
- RTE_LOG(WARNING, my_logtype1, "this is is a warning level message\n");
- RTE_LOG(WARNING, my_logtype2, "this is is a debug level message (not displayed)\n");
+ RTE_LOG(DEBUG, my_logtype1, "this is a debug level message\n");
+ RTE_LOG(INFO, my_logtype1, "this is a info level message\n");
+ RTE_LOG(WARNING, my_logtype1, "this is a warning level message\n");
+ RTE_LOG(WARNING, my_logtype2, "this is a debug level message (not displayed)\n");

 
  /* log in info level */
  rte_log_set_global_level(RTE_LOG_INFO);
 
  /* log in info level */
  rte_log_set_global_level(RTE_LOG_INFO);


@@ -741,8 +750,8 @@ A specialization looks like this:
  * PF/VF mailbox output: ``type.section.name.mbox``
 
 A real world example is the i40e poll mode driver which exposes two
  * PF/VF mailbox output: ``type.section.name.mbox``
 
 A real world example is the i40e poll mode driver which exposes two

-specializations, one for initialization ``pmd.i40e.init`` and the other for
-the remaining driver logs ``pmd.i40e.driver``.
+specializations, one for initialization ``pmd.net.i40e.init`` and the other for
+the remaining driver logs ``pmd.net.i40e.driver``.

 
 Note that specializations have no formatting rules, but please follow
 a precedent if one exists. In order to see all current log topics and
 
 Note that specializations have no formatting rules, but please follow
 a precedent if one exists. In order to see all current log topics and


@@ -794,9 +803,8 @@ lpm, etc. For drivers, the same format of Makefile is used.
        CFLAGS += -O3
        CFLAGS += $(WERROR_FLAGS)
 
        CFLAGS += -O3
        CFLAGS += $(WERROR_FLAGS)
 

-       # the symbol version information for the library, and .so version
+       # the symbol version information for the library

        EXPORT_MAP := rte_<name>_version.map
        EXPORT_MAP := rte_<name>_version.map

-       LIBABIVER := 1

 
        # all source filenames are stored in SRCS-y
        SRCS-$(CONFIG_RTE_LIBRTE_<NAME>) += rte_<name>.c
 
        # all source filenames are stored in SRCS-y
        SRCS-$(CONFIG_RTE_LIBRTE_<NAME>) += rte_<name>.c


@@ -816,10 +824,10 @@ format.
 .. code-block:: python
 
        sources = files('file1.c', ...)
 .. code-block:: python
 
        sources = files('file1.c', ...)

-       headers = files('file1.c', ...)
+       headers = files('file1.h', ...)

 
 
 
 

-The will build based on a number of conventions and assumptions within the DPDK
+This will build based on a number of conventions and assumptions within the DPDK

 itself, for example, that the library name is the same as the directory name in
 which the files are stored.
 
 itself, for example, that the library name is the same as the directory name in
 which the files are stored.
 


@@ -843,12 +851,15 @@ allow_experimental_apis
 build
        **Default Value = true**
        Used to optionally compile a library, based on its dependencies or
 build
        **Default Value = true**
        Used to optionally compile a library, based on its dependencies or

-       environment. A simple example of use would be:
+       environment. When set to "false" the ``reason`` value, explained below, should
+       also be set to explain to the user why the component is not being built.
+       A simple example of use would be:

 
 .. code-block:: python
 
 
 .. code-block:: python
 

-       if host_machine.system() != 'linux'
+       if not is_linux

                build = false
                build = false

+               reason = 'only supported on Linux'

        endif
 
 
        endif
 
 


@@ -929,10 +940,19 @@ objs
        objects that were compiled up as part of another target given in the
        included library ``meson.build`` file.
 
        objects that were compiled up as part of another target given in the
        included library ``meson.build`` file.
 

-version
-       **Default Value = 1**.
-       Specifies the ABI version of the library, and is used as the major
-       version number of the resulting ``.so`` library.
+reason
+       **Default Value = '<unknown reason>'**.
+       This variable should be used when a library is not to be built i.e. when
+       ``build`` is set to "false", to specify the reason why a library will not be
+       built. For missing dependencies this should be of the form
+       ``'missing dependency, "libname"'``.
+
+use_function_versioning
+       **Default Value = false**.
+       Specifies if the library in question has ABI versioned functions. If it
+       has, this value should be set to ensure that the C files are compiled
+       twice with suitable parameters for each of shared or static library
+       builds.

 
 Meson Build File Contents - Drivers
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Meson Build File Contents - Drivers
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~


@@ -982,6 +1002,9 @@ pkgconfig_extra_libs
        using static libraries. Anything added here will be appended to the end
        of the ``pkgconfig --libs`` output.
 
        using static libraries. Anything added here will be appended to the end
        of the ``pkgconfig --libs`` output.
 

+reason
+       As above.
+

 sources [mandatory]
        As above
 
 sources [mandatory]
        As above