X-Git-Url: http://git.droids-corp.org/?a=blobdiff_plain;f=doc%2Fguides%2Fcontributing%2Fcoding_style.rst;h=841ef6d5c82940d5e113f9f01cfc370e3789f883;hb=cba806e07d6f7e6cfa9749346f2dc75288f984f7;hp=d5fe67fd4acfe5e6b961a4198b55840c876d4c83;hpb=b114af1603db1e955c7efc94370b1d83bbb8f31f;p=dpdk.git diff --git a/doc/guides/contributing/coding_style.rst b/doc/guides/contributing/coding_style.rst index d5fe67fd4a..841ef6d5c8 100644 --- a/doc/guides/contributing/coding_style.rst +++ b/doc/guides/contributing/coding_style.rst @@ -1,3 +1,6 @@ +.. SPDX-License-Identifier: BSD-3-Clause + Copyright 2018 The DPDK contributors + .. _coding_style: DPDK Coding Style @@ -244,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 ~~~~~~ @@ -614,15 +626,15 @@ In the DPDK environment, use the logging interface provided: * is DEBUG) */ rte_log_set_level(my_logtype2, RTE_LOG_NOTICE); - /* enable all PMD logs (whose identifier string starts with "pmd") */ - rte_log_set_level_regexp("pmd.*", RTE_LOG_DEBUG); + /* enable all PMD logs (whose identifier string starts with "pmd.") */ + rte_log_set_level_pattern("pmd.*", 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); @@ -694,6 +706,56 @@ Control Statements /* NOTREACHED */ } +Dynamic Logging +--------------- + +DPDK provides infrastructure to perform logging during runtime. This is very +useful for enabling debug output without recompilation. To enable or disable +logging of a particular topic, the ``--log-level`` parameter can be provided +to EAL, which will change the log level. DPDK code can register topics, +which allows the user to adjust the log verbosity for that specific topic. + +In general, the naming scheme is as follows: ``type.section.name`` + + * Type is the type of component, where ``lib``, ``pmd``, ``bus`` and ``user`` + are the common options. + * Section refers to a specific area, for example a poll-mode-driver for an + ethernet device would use ``pmd.net``, while an eventdev PMD uses + ``pmd.event``. + * The name identifies the individual item that the log applies to. + The name section must align with + the directory that the PMD code resides. See examples below for clarity. + +Examples: + + * The virtio network PMD in ``drivers/net/virtio`` uses ``pmd.net.virtio`` + * The eventdev software poll mode driver in ``drivers/event/sw`` uses ``pmd.event.sw`` + * The octeontx mempool driver in ``drivers/mempool/octeontx`` uses ``pmd.mempool.octeontx`` + * The DPDK hash library in ``lib/librte_hash`` uses ``lib.hash`` + +Specializations +~~~~~~~~~~~~~~~ + +In addition to the above logging topic, any PMD or library can further split +logging output by using "specializations". A specialization could be the +difference between initialization code, and logs of events that occur at runtime. + +An example could be the initialization log messages getting one +specialization, while another specialization handles mailbox command logging. +Each PMD, library or component can create as many specializations as required. + +A specialization looks like this: + + * Initialization output: ``type.section.name.init`` + * 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.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 +specializations, run the ``app/test`` binary, and use the ``dump_log_types`` Python Code ----------- @@ -741,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 @@ -763,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. @@ -790,12 +851,15 @@ allow_experimental_apis 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 @@ -876,10 +940,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 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -929,6 +1002,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