[PATCH v3] doc: add new driver guidelines

[Nandini Persad <nandinipersad361@gmail.com>]

This document was created to assist contributors
in creating DPDK drivers, providing suggestions
and guidelines for how to upstream effectively.

Co-authored-by: Ferruh Yigit <ferruh.yigit@amd.com>
Co-authored-by: Thomas Mojalon <thomas@monjalon.net>
Signed-off-by: Nandini Persad <nandinipersad361@gmail.com>
Acked-by: Chengwen Feng <fengChengwen@huawei.com>
---
 doc/guides/contributing/new_driver.rst | 200 +++++++++++++++++++++++++
 1 file changed, 200 insertions(+)
 create mode 100644 doc/guides/contributing/new_driver.rst

diff --git a/doc/guides/contributing/new_driver.rst b/doc/guides/contributing/new_driver.rst
new file mode 100644
index 0000000000..2a4781e673
--- /dev/null
+++ b/doc/guides/contributing/new_driver.rst
@@ -0,0 +1,200 @@
+..  SPDX-License-Identifier: BSD-3-Clause
+    Copyright 2024 The DPDK contributors
+
+
+Upsreaming New DPDK Drivers Guide
+=================================
+
+The DPDK project continously 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 (PMDs).
+
+Public support for a device ensures accessibility across various operating
+systems and guarantees community maintenance in future releases. 
+If a new device is similar to an existing one,
+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 allowing the work to mature.
+
+Public discussions help align development 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 your driver has been added, you, as the author,
+have 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.
+
+For more information about the role of maintainers, see the
+:doc:'dpdk/doc/guides/contributing/patches.rst' page.
+
+
+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 undertand 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 funtionality.
+
+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 (more on this below).
+* 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
+Device info               Configure queues
+Link interrupt            Start queues
+Configure queues          Simple Data Processing
+Start queues              Statistics
+Simple Rx / Tx
+Burst mode info
+Promisc all-multicast
+RSS
+Statistics
+
+=======================   ========================
+
+
+Advanced features should be in the next group of patches.
+The suggestions for these, listed below, are in no specific order:
+
+* 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
+
+
+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
+----------------------
+
+* We recommend using DPDK macros instead of inventing new ones in the PMD.
+* Do not include unused headers (process-iwyu.py).
+* Do not disable compiler warning 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 (via RTE_VERSION_NUM) in the upstream code.
+* Be sure to have SPDX license tags and copyright notice on each side.
+* Do not introduce public Apis directly from the driver.
+
+
+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 to
+upstream the driver.
+
+
+Test Tools
+----------
+
+Per patch in a patch series, be sure to use the proper test tools.
+
+* 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
+
+For more information on contributing to DPDK, 
+refer to the :doc:'dpdk/doc/guides/contributing/patches.rst'
+in the Contributor's Guidelines.
+
-- 
2.34.1