1.. SPDX-License-Identifier: BSD-3-Clause 2 Copyright 2024 The DPDK contributors 3 4 5Adding a New Driver 6=================== 7 8The DPDK project continuously grows its ecosystem by adding support for new devices. 9This document is designed to assist contributors in creating DPDK drivers, 10also known as Poll Mode Drivers (PMD). 11 12By having public support for a device, we can ensure accessibility across various 13operating systems and guarantee community maintenance in future releases. 14If a new device is similar to a device already supported by an existing driver, 15it is more efficient to update the existing driver. 16 17Here are our best practice recommendations for creating a new driver. 18 19 20Early Engagement with the Community 21----------------------------------- 22 23When creating a new driver, we highly recommend engaging with the DPDK 24community early instead of waiting the work to mature. 25 26These public discussions help align development of your driver with DPDK expectations. 27You may submit a roadmap before the release to inform the community of your plans. 28Additionally, sending a Request For Comments (RFC) early in the release cycle, 29or even during the prior release, is advisable. 30 31DPDK is mainly consumed via Long Term Support (LTS) releases. 32It is common to target a new PMD to a LTS release. For this, 33it is suggested to start upstreaming at least one release before a LTS release. 34 35 36Progressive Work 37---------------- 38 39To continually progress your work, we recommend planning 40for incremental upstreaming across multiple patch series or releases. 41 42It's important to prioritize quality of the driver over upstreaming 43in a single release or single patch series. 44 45 46Finalizing 47---------- 48 49Once the driver has been upstreamed, 50the author has a responsibility to the community to maintain it. 51 52This includes the public test report. 53Authors must send a public test report after the first upstreaming of the PMD. 54The same public test procedure may be reproduced regularly per release. 55 56After the PMD is upstreamed, the author should send a patch to update 57`the website <https://core.dpdk.org/supported/>`_ 58with the name of the new PMD and supported devices via the 59`DPDK web mailing list <https://mails.dpdk.org/listinfo/web>`_. 60 61For more information about the role of maintainers, see :doc:`patches`. 62 63 64Splitting into Patches 65---------------------- 66 67We recommend that drivers are split into patches, 68so that each patch represents a single feature. 69If the driver code is already developed, it may be challenging to split. 70However, there are many benefits to doing so. 71 72Splitting patches makes it easier to understand a feature 73and clarifies the list of components/files that compose that specific feature. 74 75It also enables the ability to track 76from the source code to the feature it is enabled for, 77and helps users to understand the reasoning and intention of implementation. 78This kind of tracing is regularly required for defect resolution and refactoring. 79 80Another benefit of splitting the codebase per feature is that 81it highlights unnecessary or irrelevant code, 82as any code not belonging to any specific feature becomes obvious. 83 84Git bisect is also more useful if patches are split per patch. 85 86The split should focus on logical features rather than file-based divisions. 87 88Each patch in the series must compile without errors 89and should maintain functionality. 90 91Enable the build as early as possible within the series 92to facilitate continuous integration and testing. 93This approach ensures a clear and manageable development process. 94 95We suggest splitting patches following this approach: 96 97* Each patch should be organized logically as a new feature. 98* Run test tools per patch (See :ref:`tool_list`). 99* Update relevant documentation and `<driver>.ini` file with each patch. 100 101The following order in the patch series is as suggested below. 102 103The first patch should have the driver's skeleton which should include: 104 105* Maintainers file update 106* Driver documentation 107* Document must have links to official product documentation web page 108* The new document should be added into the index (`index.rst`) 109* Initial `<driver>.ini` file 110* Release notes announcement for the new driver 111 112The next patches should include basic device features. 113The following is a suggested sample list of such patches: 114 115================================ ================================ 116Net Crypto 117================================ ================================ 118Initialization Initialization 119Configure queues Configure queues 120Start queues Configure sessions 121Simple Rx / Tx Add capabilities 122Statistics Statistics and device info 123Device info Simple data processing 124Link interrupt 125Burst mode info 126Promisc all-multicast 127RSS 128================================ ================================ 129 130Advanced features should be in the next group of patches. 131The suggestions for these, listed below, are in no specific order: 132 133================================ ================================ 134Net Crypto 135================================ ================================ 136Advanced Rx / Tx Chained operations 137Vector Rx / Tx Scatter Gather 138Scatter support Security protocols (IPsec, etc.) 139TSO / LRO Asymmetric crypto 140Rx / Tx descriptor status 141Rx / Tx queue info 142Flow offload 143Traffic management / metering 144Extended statistics 145Secondary process support 146FreeBSD / Windows support 147Flow control 148FEC 149EEPROM access 150Register dump 151Time synchronization, PTP 152Performance documentation 153================================ ================================ 154 155After all features are enabled, 156if there is remaining base code that is not upstreamed, 157they can be upstreamed at the end of the patch series. 158However, we recommend these patches are still split into logical groups. 159 160 161Additional Suggestions 162---------------------- 163 164Avoid doing the following: 165 166* Using PMD specific macros when DPDK macros exist 167* Including unused headers (see `process-iwyu.py`) 168* Disabling compiler warnings for a driver 169* #ifdef with driver-defined macros 170* DPDK version checks (via ``RTE_VERSION_NUM``) in the upstream code 171* Introducing public API directly from the driver 172 173Remember to do the following: 174 175* Runtime configuration when applicable 176* Document device parameters in the driver guide 177* Make device operations struct 'const' 178* Dynamic logging 179* SPDX license tags and copyright notice on each file 180* Run the Coccinelle scripts `devtools/cocci.sh` 181 which check for common cleanups 182 such as useless null checks before calling free routines 183 184 185Dependencies 186------------ 187 188At times, drivers may have dependencies to external software. 189For driver dependencies, same DPDK rules for dependencies applies. 190Dependencies should be publicly and freely available, 191drivers which depend on non-available components will not be accepted. 192If the required dependency is not yet publicly available, 193then wait to submit the driver until the dependent library is available. 194 195 196.. _tool_list: 197 198Test Tools 199---------- 200 201Build and check the driver's documentation. 202Make sure there are no warnings, 203and driver shows up in the relevant index page. 204 205Be sure to run the following test tools per patch in a patch series: 206 207* `checkpatches.sh` 208* `check-git-log.sh` 209* `check-meson.py` 210* `check-doc-vs-code.sh` 211* `check-spdx-tag.sh` 212* Build documentation and validate how output looks 213