diff options
Diffstat (limited to 'doc/guides/contributing')
| -rw-r--r-- | doc/guides/contributing/coding_style.rst | 33 | ||||
| -rw-r--r-- | doc/guides/contributing/design.rst | 14 | ||||
| -rw-r--r-- | doc/guides/contributing/documentation.rst | 11 | ||||
| -rw-r--r-- | doc/guides/contributing/index.rst | 1 | ||||
| -rw-r--r-- | doc/guides/contributing/patches.rst | 169 | ||||
| -rw-r--r-- | doc/guides/contributing/stable.rst | 99 | ||||
| -rw-r--r-- | doc/guides/contributing/versioning.rst | 35 |
7 files changed, 319 insertions, 43 deletions
diff --git a/doc/guides/contributing/coding_style.rst b/doc/guides/contributing/coding_style.rst index 1eb67f34..d8e4a0f9 100644 --- a/doc/guides/contributing/coding_style.rst +++ b/doc/guides/contributing/coding_style.rst @@ -603,22 +603,30 @@ In the DPDK environment, use the logging interface provided: .. code-block:: c - #define RTE_LOGTYPE_TESTAPP1 RTE_LOGTYPE_USER1 - #define RTE_LOGTYPE_TESTAPP2 RTE_LOGTYPE_USER2 + /* register log types for this application */ + int my_logtype1 = rte_log_register("myapp.log1"); + int my_logtype2 = rte_log_register("myapp.log2"); - /* enable these logs type */ - rte_set_log_type(RTE_LOGTYPE_TESTAPP1, 1); - rte_set_log_type(RTE_LOGTYPE_TESTAPP2, 1); + /* set global log level to INFO */ + rte_log_set_global_level(RTE_LOG_INFO); + + /* only display messages higher than NOTICE for log2 (default + * 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); /* log in debug level */ - rte_set_log_level(RTE_LOG_DEBUG); - RTE_LOG(DEBUG, TESTAPP1, "this is is a debug level message\n"); - RTE_LOG(INFO, TESTAPP1, "this is is a info level message\n"); - RTE_LOG(WARNING, TESTAPP1, "this is is a warning level message\n"); + 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"); /* log in info level */ - rte_set_log_level(RTE_LOG_INFO); - RTE_LOG(DEBUG, TESTAPP2, "debug level message (not displayed)\n"); + rte_log_set_global_level(RTE_LOG_INFO); + RTE_LOG(DEBUG, my_logtype1, "debug level message (not displayed)\n"); Branch Prediction ~~~~~~~~~~~~~~~~~ @@ -690,6 +698,7 @@ Control Statements Python Code ----------- -All python code should be compliant with `PEP8 (Style Guide for Python Code) <https://www.python.org/dev/peps/pep-0008/>`_. +All Python code should work with Python 2.7+ and 3.2+ and be compliant with +`PEP8 (Style Guide for Python Code) <https://www.python.org/dev/peps/pep-0008/>`_. The ``pep8`` tool can be used for testing compliance with the guidelines. diff --git a/doc/guides/contributing/design.rst b/doc/guides/contributing/design.rst index bac3d1b4..88d3a433 100644 --- a/doc/guides/contributing/design.rst +++ b/doc/guides/contributing/design.rst @@ -158,3 +158,17 @@ cache bandwidth, memory bandwidth, etc) that depends on: branches are usually required. When processing a burst of packets that have been validated for header integrity, counting the number of bits set in a bitmask might be needed. + +PF and VF Considerations +------------------------ + +The primary goal of DPDK is to provide a userspace dataplane. Managing VFs from +a PF driver is a control plane feature and developers should generally rely on +the Linux Kernel for that. + +Developers should work with the Linux Kernel community to get the required +functionality upstream. PF functionality should only be added to DPDK for +testing and prototyping purposes while the kernel work is ongoing. It should +also be marked with an "EXPERIMENTAL" tag. If the functionality isn't +upstreamable then a case can be made to maintain the PF functionality in DPDK +without the EXPERIMENTAL tag. diff --git a/doc/guides/contributing/documentation.rst b/doc/guides/contributing/documentation.rst index 2cfb1a29..4c85da7b 100644 --- a/doc/guides/contributing/documentation.rst +++ b/doc/guides/contributing/documentation.rst @@ -332,7 +332,7 @@ Whitespace Section Headers ~~~~~~~~~~~~~~~ -* Section headers should use the use the following underline formats:: +* Section headers should use the following underline formats:: Level 1 Heading =============== @@ -380,12 +380,11 @@ Lists #. Item one. - #. Item two is a long line that is wrapped and then indented - to match the start of the e first line. - #. Item two is a long line that is wrapped and then indented to match the start of the previous line. + #. Item three. + * Definition lists can be written with or without a bullet:: * Item one. @@ -458,7 +457,7 @@ Code and Literal block sections For long literal lines that exceed that limit try to wrap the text at sensible locations. For example a long command line could be documented like this and still work if copied directly from the docs:: - build/app/testpmd -c7 -n3 --vdev=net_pcap0,iface=eth0 \ + build/app/testpmd -l 0-2 -n3 --vdev=net_pcap0,iface=eth0 \ --vdev=net_pcap1,iface=eth1 \ -- -i --nb-cores=2 --nb-ports=2 \ --total-num-mbufs=2048 @@ -477,7 +476,7 @@ Images * `Inkscape <http://inkscape.org>`_ is the recommended graphics editor for creating the images. Use some of the older images in ``doc/guides/prog_guide/img/`` as a template, for example ``mbuf1.svg`` - or ``ring-enqueue.svg``. + or ``ring-enqueue1.svg``. * The SVG images should include a copyright notice, as an XML comment. diff --git a/doc/guides/contributing/index.rst b/doc/guides/contributing/index.rst index f6af317f..329b678a 100644 --- a/doc/guides/contributing/index.rst +++ b/doc/guides/contributing/index.rst @@ -10,4 +10,5 @@ Contributor's Guidelines versioning documentation patches + stable cheatsheet diff --git a/doc/guides/contributing/patches.rst b/doc/guides/contributing/patches.rst index 729aea71..84a5dab8 100644 --- a/doc/guides/contributing/patches.rst +++ b/doc/guides/contributing/patches.rst @@ -7,12 +7,12 @@ This document outlines the guidelines for submitting code to DPDK. The DPDK development process is modelled (loosely) on the Linux Kernel development model so it is worth reading the Linux kernel guide on submitting patches: -`How to Get Your Change Into the Linux Kernel <http://www.kernel.org/doc/Documentation/SubmittingPatches>`_. +`How to Get Your Change Into the Linux Kernel <https://www.kernel.org/doc/html/latest/process/submitting-patches.html>`_. The rationale for many of the DPDK guidelines is explained in greater detail in the kernel guidelines. The DPDK Development Process ------------------------------ +---------------------------- The DPDK development process has the following features: @@ -20,7 +20,10 @@ The DPDK development process has the following features: * There is a mailing list where developers submit patches. * There are maintainers for hierarchical components. * Patches are reviewed publicly on the mailing list. -* Successfully reviewed patches are merged to the master branch of the repository. +* Successfully reviewed patches are merged to the repository. +* Patches should be sent to the target repository or sub-tree, see below. +* All sub-repositories are merged into main repository for ``-rc1`` and ``-rc2`` versions of the release. +* After the ``-rc2`` release all patches should target the main repository. The mailing list for DPDK development is `dev@dpdk.org <http://dpdk.org/ml/archives/dev/>`_. Contributors will need to `register for the mailing list <http://dpdk.org/ml/listinfo/dev>`_ in order to submit patches. @@ -30,15 +33,81 @@ The development process requires some familiarity with the ``git`` version contr Refer to the `Pro Git Book <http://www.git-scm.com/book/>`_ for further information. +Maintainers and Sub-trees +------------------------- + +The DPDK maintenance hierarchy is divided into a main repository ``dpdk`` and sub-repositories ``dpdk-next-*``. + +There are maintainers for the trees and for components within the tree. + +Trees and maintainers are listed in the ``MAINTAINERS`` file. For example:: + + Crypto Drivers + -------------- + M: Some Name <some.name@email.com> + B: Another Name <another.name@email.com> + T: git://dpdk.org/next/dpdk-next-crypto + + Intel AES-NI GCM PMD + M: Some One <some.one@email.com> + F: drivers/crypto/aesni_gcm/ + F: doc/guides/cryptodevs/aesni_gcm.rst + +Where: + +* ``M`` is a tree or component maintainer. +* ``B`` is a tree backup maintainer. +* ``T`` is a repository tree. +* ``F`` is a maintained file or directory. + +Additional details are given in the ``MAINTAINERS`` file. + +The role of the component maintainers is to: + +* Review patches for the component or delegate the review. + The review should be done, ideally, within 1 week of submission to the mailing list. +* Add an ``acked-by`` to patches, or patchsets, that are ready for committing to a tree. +* Reply to questions asked about the component. + +Component maintainers can be added or removed by submitting a patch to the ``MAINTAINERS`` file. +Maintainers should have demonstrated a reasonable level of contributions or reviews to the component area. +The maintainer should be confirmed by an ``ack`` from an established contributor. +There can be more than one component maintainer if desired. + +The role of the tree maintainers is to: + +* Maintain the overall quality of their tree. + This can entail additional review, compilation checks or other tests deemed necessary by the maintainer. +* Commit patches that have been reviewed by component maintainers and/or other contributors. + The tree maintainer should determine if patches have been reviewed sufficiently. +* Ensure that patches are reviewed in a timely manner. +* Prepare the tree for integration. +* Ensure that there is a designated back-up maintainer and coordinate a handover for periods where the + tree maintainer can't perform their role. + +Tree maintainers can be added or removed by submitting a patch to the ``MAINTAINERS`` file. +The proposer should justify the need for a new sub-tree and should have demonstrated a sufficient level of contributions in the area or to a similar area. +The maintainer should be confirmed by an ``ack`` from an existing tree maintainer. +Disagreements on trees or maintainers can be brought to the Technical Board. + +The backup maintainer for the master tree should be selected from the existing sub-tree maintainers from the project. +The backup maintainer for a sub-tree should be selected from among the component maintainers within that sub-tree. + + Getting the Source Code ----------------------- -The source code can be cloned using either of the following:: +The source code can be cloned using either of the following: - git clone git://dpdk.org/dpdk +main repository:: + git clone git://dpdk.org/dpdk git clone http://dpdk.org/git/dpdk +sub-repositories (`list <http://dpdk.org/browse/next>`_):: + + git clone git://dpdk.org/next/dpdk-next-* + git clone http://dpdk.org/git/next/dpdk-next-* Make your Changes ----------------- @@ -124,7 +193,7 @@ Here are some guidelines for the body of a commit message: git commit --signoff # or -s The purpose of the signoff is explained in the - `Developer's Certificate of Origin <http://www.kernel.org/doc/Documentation/SubmittingPatches>`_ + `Developer's Certificate of Origin <https://www.kernel.org/doc/html/latest/process/submitting-patches.html#developer-s-certificate-of-origin-1-1>`_ section of the Linux kernel guidelines. .. Note:: @@ -157,13 +226,9 @@ Here are some guidelines for the body of a commit message: * Use correct capitalization, punctuation and spelling. -In addition to the ``Signed-off-by:`` name the commit messages can also have one or more of the following: - -* ``Reported-by:`` The reporter of the issue. -* ``Tested-by:`` The tester of the change. -* ``Reviewed-by:`` The reviewer of the change. -* ``Suggested-by:`` The person who suggested the change. -* ``Acked-by:`` When a previous version of the patch was acked and the ack is still relevant. +In addition to the ``Signed-off-by:`` name the commit messages can also have +tags for who reported, suggested, tested and reviewed the patch being +posted. Please refer to the `Tested, Acked and Reviewed by`_ section. Creating Patches @@ -230,7 +295,7 @@ For example:: Checking the Patches -------------------- -Patches should be checked for formatting and syntax issues using the ``checkpatches.sh`` script in the ``scripts`` +Patches should be checked for formatting and syntax issues using the ``checkpatches.sh`` script in the ``devtools`` directory of the DPDK repo. This uses the Linux kernel development tool ``checkpatch.pl`` which can be obtained by cloning, and periodically, updating the Linux kernel sources. @@ -245,7 +310,7 @@ files, in order of preference:: Once the environment variable the script can be run as follows:: - scripts/checkpatches.sh ~/patch/ + devtools/checkpatches.sh ~/patch/ The script usage is:: @@ -272,10 +337,10 @@ Where the range is a ``git log`` option. Checking Compilation -------------------- -Compilation of patches and changes should be tested using the the ``test-build.sh`` script in the ``scripts`` +Compilation of patches and changes should be tested using the the ``test-build.sh`` script in the ``devtools`` directory of the DPDK repo:: - scripts/test-build.sh x86_64-native-linuxapp-gcc+next+shared + devtools/test-build.sh x86_64-native-linuxapp-gcc+next+shared The script usage is:: @@ -359,9 +424,57 @@ The options ``--annotate`` and ``confirm = always`` are recommended for checking The Review Process ------------------ -The more work you put into the previous steps the easier it will be to get a patch accepted. +Patches are reviewed by the community, relying on the experience and +collaboration of the members to double-check each other's work. There are a +number of ways to indicate that you have checked a patch on the mailing list. + + +Tested, Acked and Reviewed by +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To indicate that you have interacted with a patch on the mailing list you +should respond to the patch in an email with one of the following tags: + + * Reviewed-by: + * Acked-by: + * Tested-by: + * Reported-by: + * Suggested-by: + +The tag should be on a separate line as follows:: + + tag-here: Name Surname <email@address.com> + +Each of these tags has a specific meaning. In general, the DPDK community +follows the kernel usage of the tags. A short summary of the meanings of each +tag is given here for reference: + +.. _statement: https://www.kernel.org/doc/html/latest/process/submitting-patches.html#reviewer-s-statement-of-oversight + +``Reviewed-by:`` is a strong statement_ that the patch is an appropriate state +for merging without any remaining serious technical issues. Reviews from +community members who are known to understand the subject area and to perform +thorough reviews will increase the likelihood of the patch getting merged. + +``Acked-by:`` is a record that the person named was not directly involved in +the preparation of the patch but wishes to signify and record their acceptance +and approval of it. + +``Tested-by:`` indicates that the patch has been successfully tested (in some +environment) by the person named. + +``Reported-by:`` is used to acknowledge person who found or reported the bug. + +``Suggested-by:`` indicates that the patch idea was suggested by the named +person. + + + +Steps to getting your patch merged +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The general cycle for patch review and acceptance is: +The more work you put into the previous steps the easier it will be to get a +patch accepted. The general cycle for patch review and acceptance is: #. Submit the patch. @@ -392,4 +505,20 @@ The general cycle for patch review and acceptance is: #. In addition a patch will not be accepted if it doesn't address comments from a previous version with fixes or valid arguments. -#. Acked patches will be merged in the current or next merge window. +#. It is the responsibility of a maintainer to ensure that patches are reviewed and to provide an ``ack`` or + ``nack`` of those patches as appropriate. + +#. Once a patch has been acked by the relevant maintainer, reviewers may still comment on it for a further + two weeks. After that time, the patch should be merged into the relevant git tree for the next release. + Additional notes and restrictions: + + * Patches should be acked by a maintainer at least two days before the release merge + deadline, in order to make that release. + * For patches acked with less than two weeks to go to the merge deadline, all additional + comments should be made no later than two days before the merge deadline. + * After the appropriate time for additional feedback has passed, if the patch has not yet + been merged to the relevant tree by the committer, it should be treated as though it had, + in that any additional changes needed to it must be addressed by a follow-on patch, rather + than rework of the original. + * Trivial patches may be merged sooner than described above at the tree committer's + discretion. diff --git a/doc/guides/contributing/stable.rst b/doc/guides/contributing/stable.rst new file mode 100644 index 00000000..d52ec477 --- /dev/null +++ b/doc/guides/contributing/stable.rst @@ -0,0 +1,99 @@ +.. stable_lts_releases: + +DPDK Stable Releases and Long Term Support +========================================== + +This section sets out the guidelines for the DPDK Stable Releases and the DPDK +Long Term Support releases (LTS). + + +Introduction +------------ + +The purpose of the DPDK Stable Releases is to maintain releases of DPDK with +backported fixes over an extended period of time. This provides downstream +consumers of DPDK with a stable target on which to base applications or +packages. + +The Long Term Support release (LTS) is a designation applied to a Stable +Release to indicate longer term support. + + +Stable Releases +--------------- + +Any major release of DPDK can be designated as a Stable Release if a +maintainer volunteers to maintain it. + +A Stable Release is used to backport fixes from an ``N`` release back to an +``N-1`` release, for example, from 16.11 to 16.07. + +The duration of a stable is one complete release cycle (3 months). It can be +longer, up to 1 year, if a maintainer continues to support the stable branch, +or if users supply backported fixes, however the explicit commitment should be +for one release cycle. + +The release cadence is determined by the maintainer based on the number of +bugfixes and the criticality of the bugs. Releases should be coordinated with +the validation engineers to ensure that a tagged release has been tested. + + +LTS Release +----------- + +A stable release can be designated as an LTS release based on community +agreement and a commitment from a maintainer. An LTS release will have a +maintenance duration of 2 years. + +The current DPDK LTS release is 16.11. + +It is anticipated that there will be at least 4 releases per year of the LTS +or approximately 1 every 3 months. However, the cadence can be shorter or +longer depending on the number and criticality of the backported +fixes. Releases should be coordinated with the validation engineers to ensure +that a tagged release has been tested. + + +What changes should be backported +--------------------------------- + +Backporting should be limited to bug fixes. + +Features should not be backported to stable releases. It may be acceptable, in +limited cases, to back port features for the LTS release where: + +* There is a justifiable use case (for example a new PMD). +* The change is non-invasive. +* The work of preparing the backport is done by the proposer. +* There is support within the community. + + +The Stable Mailing List +----------------------- + +The Stable and LTS release are coordinated on the stable@dpdk.org mailing +list. + +All fix patches to the master branch that are candidates for backporting +should also be CCed to the `stable@dpdk.org <http://dpdk.org/ml/listinfo/stable>`_ +mailing list. + + +Releasing +--------- + +A Stable Release will be released by: + +* Tagging the release with YY.MM.n (year, month, number). +* Uploading a tarball of the release to dpdk.org. +* Sending an announcement to the `announce@dpdk.org <http://dpdk.org/ml/listinfo/announce>`_ + list. + +Stable releases are available on the `dpdk.org download page <http://dpdk.org/download>`_. + + +ABI +--- + +The Stable Release should not be seen as a way of breaking or circumventing +the DPDK ABI policy. diff --git a/doc/guides/contributing/versioning.rst b/doc/guides/contributing/versioning.rst index 08e2e217..8aaf370d 100644 --- a/doc/guides/contributing/versioning.rst +++ b/doc/guides/contributing/versioning.rst @@ -133,6 +133,31 @@ The macros exported are: fully qualified function ``p``, so that if a symbol becomes versioned, it can still be mapped back to the public symbol name. +Setting a Major ABI version +--------------------------- + +Downstreams might want to provide different DPDK releases at the same time to +support multiple consumers of DPDK linked against older and newer sonames. + +Also due to the interdependencies that DPDK libraries can have applications +might end up with an executable space in which multiple versions of a library +are mapped by ld.so. + +Think of LibA that got an ABI bump and LibB that did not get an ABI bump but is +depending on LibA. + +.. note:: + + Application + \-> LibA.old + \-> LibB.new -> LibA.new + +That is a conflict which can be avoided by setting ``CONFIG_RTE_MAJOR_ABI``. +If set, the value of ``CONFIG_RTE_MAJOR_ABI`` overwrites all - otherwise per +library - versions defined in the libraries ``LIBABIVER``. +An example might be ``CONFIG_RTE_MAJOR_ABI=16.11`` which will make all libraries +``librte<?>.so.16.11`` instead of ``librte<?>.so.<LIBABIVER>``. + Examples of ABI Macro use ------------------------- @@ -457,7 +482,7 @@ versions of the symbol. Running the ABI Validator ------------------------- -The ``scripts`` directory in the DPDK source tree contains a utility program, +The ``devtools`` directory in the DPDK source tree contains a utility program, ``validate-abi.sh``, for validating the DPDK ABI based on the Linux `ABI Compliance Checker <http://ispras.linuxbase.org/index.php/ABI_compliance_checker>`_. @@ -470,7 +495,7 @@ utilities which can be installed via a package manager. For example:: The syntax of the ``validate-abi.sh`` utility is:: - ./scripts/validate-abi.sh <REV1> <REV2> <TARGET> + ./devtools/validate-abi.sh <REV1> <REV2> <TARGET> Where ``REV1`` and ``REV2`` are valid gitrevisions(7) https://www.kernel.org/pub/software/scm/git/docs/gitrevisions.html @@ -479,13 +504,13 @@ on the local repo and target is the usual DPDK compilation target. For example:: # Check between the previous and latest commit: - ./scripts/validate-abi.sh HEAD~1 HEAD x86_64-native-linuxapp-gcc + ./devtools/validate-abi.sh HEAD~1 HEAD x86_64-native-linuxapp-gcc # Check between two tags: - ./scripts/validate-abi.sh v2.0.0 v2.1.0 x86_64-native-linuxapp-gcc + ./devtools/validate-abi.sh v2.0.0 v2.1.0 x86_64-native-linuxapp-gcc # Check between git master and local topic-branch "vhost-hacking": - ./scripts/validate-abi.sh master vhost-hacking x86_64-native-linuxapp-gcc + ./devtools/validate-abi.sh master vhost-hacking x86_64-native-linuxapp-gcc After the validation script completes (it can take a while since it need to compile both tags) it will create compatibility reports in the |