X-Git-Url: http://git.droids-corp.org/?a=blobdiff_plain;f=doc%2Fguides%2Fcontributing%2Fcoding_style.rst;h=734d1901b22bb1e7fa6c16ec7374c3a6807e3035;hb=71b09bd95096610aaddb69497297103a129e0e7c;hp=e95a1a2be249d8f45e188263cc28b592d9b07535;hpb=a5d4ea594307c77af393386212a434c63e9dd96b;p=dpdk.git diff --git a/doc/guides/contributing/coding_style.rst b/doc/guides/contributing/coding_style.rst index e95a1a2be2..734d1901b2 100644 --- a/doc/guides/contributing/coding_style.rst +++ b/doc/guides/contributing/coding_style.rst @@ -54,8 +54,13 @@ To document a public API, a doxygen-like format must be used: refer to :ref:`dox License Header ~~~~~~~~~~~~~~ -Each file should begin with a special comment containing the appropriate copyright and license for the file. -Generally this is the BSD License, except for code for Linux Kernel modules. +Each file must begin with a special comment containing the +`Software Package Data Exchange (SPDX) License Identfier `_. + +Generally this is the BSD License, except for code granted special exceptions. +The SPDX licences identifier is sufficient, a file should not contain +an additional text version of the license (boilerplate). + After any copyright header, a blank line should be left before any other contents, e.g. include statements in a C file. C Preprocessor Directives @@ -278,6 +283,29 @@ Thus, the previous example would be better written: DPDK also provides an optimized way to store elements in lockless rings. This should be used in all data-path code, when there are several consumer and/or producers to avoid locking for concurrent access. +Naming +------ + +For symbol names and documentation, new usage of +'master / slave' (or 'slave' independent of 'master') and 'blacklist / +whitelist' is not allowed. + +Recommended replacements for 'master / slave' are: + '{primary,main} / {secondary,replica,subordinate}' + '{initiator,requester} / {target,responder}' + '{controller,host} / {device,worker,proxy}' + 'leader / follower' + 'director / performer' + +Recommended replacements for 'blacklist/whitelist' are: + 'denylist / allowlist' + 'blocklist / passlist' + +Exceptions for introducing new usage is to maintain compatibility +with an existing (as of 2020) hardware or protocol +specification that mandates those terms. + + Typedefs ~~~~~~~~ @@ -334,7 +362,7 @@ For example: typedef int (lcore_function_t)(void *); /* launch a function of lcore_function_t type */ - int rte_eal_remote_launch(lcore_function_t *f, void *arg, unsigned slave_id); + int rte_eal_remote_launch(lcore_function_t *f, void *arg, unsigned worker_id); C Indentation @@ -631,10 +659,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); @@ -760,7 +788,7 @@ specializations, run the ``app/test`` binary, and use the ``dump_log_types`` Python Code ----------- -All Python code should work with Python 2.7+ and 3.2+ and be compliant with +All Python code should be compliant with `PEP8 (Style Guide for Python Code) `_. The ``pep8`` tool can be used for testing compliance with the guidelines. @@ -768,54 +796,13 @@ The ``pep8`` tool can be used for testing compliance with the guidelines. Integrating with the Build System --------------------------------- -DPDK supports being built in two different ways: +DPDK is built using the tools ``meson`` and ``ninja``. -* using ``make`` - or more specifically "GNU make", i.e. ``gmake`` on FreeBSD -* using the tools ``meson`` and ``ninja`` - -Any new library or driver to be integrated into DPDK should support being -built with both systems. While building using ``make`` is a legacy approach, and -most build-system enhancements are being done using ``meson`` and ``ninja`` -there are no plans at this time to deprecate the legacy ``make`` build system. - -Therefore all new component additions should include both a ``Makefile`` and a -``meson.build`` file, and should be added to the component lists in both the -``Makefile`` and ``meson.build`` files in the relevant top-level directory: +Therefore all new component additions should include a ``meson.build`` file, +and should be added to the component lists in the ``meson.build`` files in the +relevant top-level directory: either ``lib`` directory or a ``driver`` subdirectory. -Makefile Contents -~~~~~~~~~~~~~~~~~ - -The ``Makefile`` for the component should be of the following format, where -```` corresponds to the name of the library in question, e.g. hash, -lpm, etc. For drivers, the same format of Makefile is used. - -.. code-block:: none - - # pull in basic DPDK definitions, including whether library is to be - # built or not - include $(RTE_SDK)/mk/rte.vars.mk - - # library name - LIB = librte_.a - - # any library cflags needed. Generally add "-O3 $(WERROR_FLAGS)" - CFLAGS += -O3 - CFLAGS += $(WERROR_FLAGS) - - # the symbol version information for the library, and .so version - EXPORT_MAP := rte__version.map - LIBABIVER := 1 - - # all source filenames are stored in SRCS-y - SRCS-$(CONFIG_RTE_LIBRTE_) += rte_.c - - # install includes - SYMLINK-$(CONFIG_RTE_LIBRTE_)-include += rte_.h - - # pull in rules to build the library - include $(RTE_SDK)/mk/rte.lib.mk - Meson Build File Contents - Libraries ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -843,12 +830,6 @@ 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 @@ -910,6 +891,18 @@ headers installed to $PREFIX/include when ``ninja install`` is run. As with source files, these should be specified using the meson ``files()`` function. + When ``check_includes`` build option is set to ``true``, each header file + has additional checks performed on it, for example to ensure that it is + not missing any include statements for dependent headers. + For header files which are public, but only included indirectly in + applications, these checks can be skipped by using the ``indirect_headers`` + variable rather than ``headers``. + +indirect_headers + **Default Value = []**. + As with ``headers`` option above, except that the files are not checked + for all needed include files as part of a DPDK build when + ``check_includes`` is set to ``true``. includes: **Default Value = []**. @@ -955,20 +948,12 @@ use_function_versioning twice with suitable parameters for each of shared or static library builds. -version - **Default Value = 1**. - Specifies the ABI version of the library, and is used as the major - version number of the resulting ``.so`` library. - 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. @@ -1014,5 +999,8 @@ reason sources [mandatory] As above +headers + As above + version As above