RE: [EXTERNAL] [PATCH v2] doc: add new driver guidelines

[Akhil Goyal <gakhil@marvell.com>]

Few crypto specific suggestions.

> 
> v2 - review feedback
>    - add co-author and reviewed-by
> 
>  doc/guides/contributing/index.rst      |   1 +
>  doc/guides/contributing/new_driver.rst | 202 +++++++++++++++++++++++++
>  2 files changed, 203 insertions(+)
>  create mode 100644 doc/guides/contributing/new_driver.rst
> 
> diff --git a/doc/guides/contributing/index.rst b/doc/guides/contributing/index.rst
> index dcb9b1fbf0..7fc6511361 100644
> --- a/doc/guides/contributing/index.rst
> +++ b/doc/guides/contributing/index.rst
> @@ -15,6 +15,7 @@ Contributor's Guidelines
>      documentation
>      unit_test
>      new_library
> +    new_driver
>      patches
>      vulnerability
>      stable
> diff --git a/doc/guides/contributing/new_driver.rst
> b/doc/guides/contributing/new_driver.rst
> new file mode 100644
> index 0000000000..4aa1fd1d05
> --- /dev/null
> +++ b/doc/guides/contributing/new_driver.rst
> @@ -0,0 +1,202 @@
> +.. SPDX-License-Identifier: BSD-3-Clause
> +   Copyright 2024 The DPDK contributors
> +
> +
> +Upstreaming New DPDK Drivers Guide
> +==================================
> +
> +The DPDK project continuously grows its ecosystem by adding support for new
> devices.
> +This document is designed to assist contributors in creating DPDK
> +drivers, also known as Poll Mode Drivers (PMD's).
> +
> +By having public support for a device, we can 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.
> +
> +
> +Early Engagement with the Community
> +-----------------------------------
> +
> +When creating a new driver, we highly recommend engaging with the DPDK
> +community early instead of waiting 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 a LTS release. For this, it is
> +suggested to start upstreaming at least one release before a LTS release.
> +
> +
> +Progressive Work
> +----------------
> +
> +To continually progress your work, we recommend planning for incremental
> +upstreaming across multiple patch series or releases.
> +
> +It's important to prioritize quality of the driver over upstreaming
> +in a single release or single patch series.
> +
> +
> +Finalizing
> +----------
> +
> +Once the driver has been upstreamed, the author has
> +a responsibility to the community to maintain 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, the author should send a patch
> +to update the website with the name of the new PMD and supported devices
> +via the DPDK mailing list..
> +
> +For more information about the role of maintainers, see :doc:`patches`.
> +
> +
> +
> +Splitting into Patches
> +----------------------
> +
> +We recommend that drivers are split 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 is enabled for and helps users to 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 patch.
> +
> +The split should focus 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.
> +
> +We suggest splitting patches following this approach:
> +
> +* Each patch should be organized logically as a new feature.
> +* Run test tools per patch (See :ref:`tool_list`:).
> +* 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:
> +
> +* Maintainer's file update
> +* Driver documentation
> +* Document must have links to official product documentation web page
> +* The  new document should be added into the index (`doc/guides/index.rst`)
> +* Initial <drive>.ini file
> +* Release notes announcement for the new driver
> +
> +
> +The next patches should include basic device features.
> +The following is suggested sample list to include in these patches:
> +
> +=======================   ========================
> +Net                       Crypto
> +=======================   ========================
> +Initialization            Initialization
> +Configure queues          Configure queues
> +Start queues              Start queues
> +Simple Rx / Tx            Simple Data Processing
> +Statistics                Statistics
> +Device info
> +Link interrupt
> +Burst mode info
> +Promisc all-multicast
> +RSS
> +=======================   ========================

For crypto, 
Initialization
Configure queues
Configure sessions
Add capabilities.
Statistics and device info
Simple data processing

> +
> +
> +Advanced features should be in the next group of patches.
> +The suggestions for these, listed below, are in no specific order:
> +
> +=============================
> +Net
> +=============================
> +Advanced Rx / Tx
> +Scatter Support
> +Vector Support
> +TSO / LRO
> +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
> +Perf documentation
> +=============================
> +

=============================
Crypto
=============================
Chained operations
Scatter Gather
Security protocols - IPsec, MACsec etc.
Asymmetric crypto

> +
> +After all features are enabled, if there is remaining base code that
> +is not upstreamed, they can be upstreamed at the end of the patch series.
> +However, we recommend these patches are still split into logical groups.
> +
> +
> +Additional Suggestions
> +----------------------
> +
.ini file shall be updated for each of the new feature added in the same patch as code.

> +* We recommend using DPDK macros instead of inventing new ones in the PMD.
> +* Do not include unused headers. Use the ./devtools/process-iwyu.py tool.
> +* Do not disable compiler warnings in the build file.
> +* Do not use #ifdef with driver-defined macros, instead prefer runtime
> configuration.
> +* Document device parameters in the driver guide.
> +* Make device operations struct 'const'.
> +* Use dynamic logging.
> +* Do not use DPDK version checks in the upstream code.
> +* Be sure to have SPDX license tags and copyright notice on each side.
> +  Use ./devtools/check-spdx-tag.sh
> +* Run the Coccinelle scripts ./devtools/cocci.sh which check for common
> cleanups such as
> +  useless null checks before calling free routines.
> +
> +Dependencies
> +------------
> +
> +At times, drivers may have dependencies to external software.
> +For driver dependencies, same DPDK rules for dependencies applies.
> +Dependencies should be publicly and freely available,
> +or this is a blocker for upstreaming the driver.
> +
> +
> +.. _tool_list:
> +
> +Test Tools
> +----------
> +
> +Build and check the driver's documentation. Make sure there are no
> +warnings and driver shows up in the relevant index page.
> +
> +Be sure to 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
> --
> 2.43.0