8. Adding a New Driver

The DPDK project continuously grows its ecosystem by adding support for new devices. This document assists contributors in creating DPDK drivers, also known as Poll Mode Drivers (PMD).

By having public support for a device, we ensure accessibility across various operating systems and guarantee community maintenance in future releases. If a new device is similar to a device already supported by an existing driver, it is more efficient to update the existing driver.

Here are our best practice recommendations for creating a new driver.

8.1. Early Engagement with the Community

When creating a new driver, engage with the DPDK community early rather than waiting for the work to mature.

These public discussions help align development of your driver with DPDK expectations. You may submit a roadmap before the release to inform the community of your plans. Additionally, sending a Request For Comments (RFC) early in the release cycle, or even during the prior release, is advisable.

DPDK is mainly consumed via Long Term Support (LTS) releases. It is common to target a new PMD to an LTS release. For this, start upstreaming at least one release before an LTS release.

8.2. Progressive Work

To continually progress your work, plan for incremental upstreaming across multiple patch series or releases.

Prioritize quality of the driver over upstreaming in a single release or single patch series.

8.3. Finalizing

Once the driver is upstreamed, the author is responsible for maintaining it.

This includes the public test report. Authors must send a public test report after the first upstreaming of the PMD. The same public test procedure may be reproduced regularly per release.

After the PMD is upstreamed, send a patch to update the website with the name of the new PMD and supported devices via the DPDK web mailing list.

For more information about the role of maintainers, see Contributing Code to DPDK.

8.4. Splitting into Patches

Split drivers into patches so that each patch represents a single feature. If the driver code is already developed, it may be challenging to split. However, there are many benefits to doing so.

Splitting patches makes it easier to understand a feature and clarifies the list of components/files that compose that specific feature.

It also enables the ability to track from the source code to the feature it enables, and helps users understand the reasoning and intention of implementation. This kind of tracing is regularly required for defect resolution and refactoring.

Another benefit of splitting the codebase per feature is that it highlights unnecessary or irrelevant code, as any code not belonging to any specific feature becomes obvious.

Git bisect is also more useful if patches are split per feature.

Focus the split on logical features rather than file-based divisions.

Each patch in the series must compile without errors and should maintain functionality.

Enable the build as early as possible within the series to facilitate continuous integration and testing. This approach ensures a clear and manageable development process.

Split patches following this approach:

  • Organize each patch logically as a new feature.

  • Run test tools per patch (See Test Tools).

  • Update relevant documentation and <driver>.ini file with each patch.

The following order in the patch series is as suggested below.

The first patch should have the driver’s skeleton which should include:

  • Maintainers file update

  • Driver documentation

  • Document must have links to official product documentation web page

  • Add the new document to the index (index.rst)

  • Initial <driver>.ini file

  • Release notes announcement for the new driver

The next patches should include basic device features. The following is a suggested sample list of such patches:

Net

Crypto

Initialization

Initialization

Configure queues

Configure queues

Start queues

Configure sessions

Simple Rx / Tx

Add capabilities

Statistics

Statistics and device info

Device info

Simple data processing

Link interrupt

Burst mode info

Promisc all-multicast

RSS

Advanced features should be in the next group of patches. The suggestions for these, listed below, are in no specific order:

Net

Crypto

Advanced Rx / Tx

Chained operations

Vector Rx / Tx

Scatter Gather

Scatter support

Security protocols (IPsec, etc.)

TSO / LRO

Asymmetric crypto

Rx / Tx descriptor status

Rx / Tx queue info

Flow offload

Traffic management / metering

Extended statistics

Secondary process support

FreeBSD / Windows support

Flow control

FEC

EEPROM access

Register dump

Time synchronization, PTP

Performance documentation

After enabling all features, if there is remaining base code that is not upstreamed, upstream it at the end of the patch series. However, still split these patches into logical groups.

8.5. Additional Suggestions

Avoid doing the following:

  • Using PMD specific macros when DPDK macros exist

  • Including unused headers (see process-iwyu.py)

  • Disabling compiler warnings for a driver

  • #ifdef with driver-defined macros

  • DPDK version checks (via RTE_VERSION_NUM) in the upstream code

  • Introducing public API directly from the driver

Remember to do the following:

  • Runtime configuration when applicable

  • Document device parameters in the driver guide

  • Make device operations struct ‘const’

  • Dynamic logging

  • SPDX license tags and copyright notice on each file

  • Run the Coccinelle scripts devtools/cocci.sh which check for common cleanups such as useless null checks before calling free routines

8.6. Dependencies

At times, drivers may have dependencies on external software. For driver dependencies, the same DPDK rules for dependencies apply. Dependencies should be publicly and freely available; drivers that depend on unavailable components will not be accepted. If the required dependency is not yet publicly available, wait to submit the driver until the dependent library is available.

8.7. Test Tools

Build and check the driver’s documentation. Ensure there are no warnings and the driver shows up in the relevant index page.

Run the following test tools per patch in a patch series:

  • checkpatches.sh

  • check-git-log.sh

  • check-meson.py

  • check-doc-vs-code.sh

  • check-spdx-tag.sh

  • Build documentation and validate how output looks

  • Optionally run review-patch.py for AI-assisted review (see AI-Assisted Patch Review in the Contributing Guide)