X-Git-Url: http://git.droids-corp.org/?a=blobdiff_plain;f=doc%2Fguides%2Fcontributing%2Fcoding_style.rst;h=4efde93f6af053dd63751ff54077955c588a829e;hb=770fabcd36ec11d64544e86ed7d2dda9f5c64daf;hp=b1bf0d15cf2b214cdce88a61428bd7d644a06a05;hpb=77c79de08c15ddf08b7f422ef797b434ff897d64;p=dpdk.git diff --git a/doc/guides/contributing/coding_style.rst b/doc/guides/contributing/coding_style.rst index b1bf0d15cf..4efde93f6a 100644 --- 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. +.. 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 `_ + 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); - 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); @@ -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 -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 @@ -794,9 +803,8 @@ lpm, etc. For drivers, the same format of Makefile is used. 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__version.map - LIBABIVER := 1 # all source filenames are stored in SRCS-y SRCS-$(CONFIG_RTE_LIBRTE_) += rte_.c @@ -816,10 +824,10 @@ format. .. 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. @@ -834,21 +842,18 @@ sources The optional fields are: -allow_experimental_apis - **Default Value = false** - Used to allow the library to make use of APIs marked as experimental. - Set to ``true`` if the C files in the library call any functions - marked as experimental in any included header files. - 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 - if host_machine.system() != 'linux' + if not is_linux build = false + reason = 'only supported on Linux' endif @@ -929,10 +934,19 @@ objs 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 = ''**. + 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 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -940,9 +954,6 @@ Meson Build File Contents - Drivers For drivers, the values are largely the same as for libraries. The variables supported are: -allow_experimental_apis - As above. - build As above. @@ -982,6 +993,9 @@ pkgconfig_extra_libs using static libraries. Anything added here will be appended to the end of the ``pkgconfig --libs`` output. +reason + As above. + sources [mandatory] As above