From mboxrd@z Thu Jan 1 00:00:00 1970
Return-Path: <dev-bounces@dpdk.org>
Received: from mails.dpdk.org (mails.dpdk.org [217.70.189.124])
by inbox.dpdk.org (Postfix) with ESMTP id 3F77E45AC5;
Sun, 6 Oct 2024 20:44:03 +0200 (CEST)
Received: from mails.dpdk.org (localhost [127.0.0.1])
by mails.dpdk.org (Postfix) with ESMTP id 15930402C3;
Sun, 6 Oct 2024 20:44:03 +0200 (CEST)
Received: from mail-pf1-f179.google.com (mail-pf1-f179.google.com
[209.85.210.179])
by mails.dpdk.org (Postfix) with ESMTP id D65F34025D
for <dev@dpdk.org>; Sun, 6 Oct 2024 20:44:01 +0200 (CEST)
Received: by mail-pf1-f179.google.com with SMTP id
d2e1a72fcca58-71e023635acso210151b3a.2
for <dev@dpdk.org>; Sun, 06 Oct 2024 11:44:01 -0700 (PDT)
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed;
d=gmail.com; s=20230601; t=1728240241; x=1728845041; darn=dpdk.org;
h=content-transfer-encoding:mime-version:references:in-reply-to
:message-id:date:subject:cc:to:from:from:to:cc:subject:date
:message-id:reply-to;
bh=fU2+t5csV9gEjYsWs2z6SRr3O+7lJmpeo5iZrwlY5lQ=;
b=GeyspquWge0fBjUvAe6Z86tlgkLSnKXcsyAULoz4FJRn7sP0x1nk1XUhwbhTT30l5v
5ka/IIal3WuwRYvBs+nCQP1usMpvDcROJfmnnVCo+h9Xoakf/seAMeMbpyl2R3TPQMAs
LwxUj/MwRqIgTZW0dX87nu4Ldr4piFsPCmO6YbPPfeKXwWPHBhLujas0EGpSTxiaLalC
RMFbLh/Rw0mDAmeSIJJ4AwQWTmubXPjddfWBAJRRdP/PntNOVIDjQg1xIkMxs7j4VnFp
oQlXD1P1Ap+9ljGxltrGQc4BouMLS4EROpLX7OTZfysXPKRlMM1B5Zh3AiqzIE8XEj8/
u62g==
X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed;
d=1e100.net; s=20230601; t=1728240241; x=1728845041;
h=content-transfer-encoding:mime-version:references:in-reply-to
:message-id:date:subject:cc:to:from:x-gm-message-state:from:to:cc
:subject:date:message-id:reply-to;
bh=fU2+t5csV9gEjYsWs2z6SRr3O+7lJmpeo5iZrwlY5lQ=;
b=oXmTK+Q8laZ7l4JHx8dg1zPHR+NLe5JWfWX9Hj1OWbq9iuuMGd16BHValyvu52z8aG
/ppy3TAXscuAwene06YIQHJjKP5scROL35Id2xb+ZeLvMB3nvC1CMgi0uDi/wIesB1yD
9DqjTUwdROLIUO2X7V/Fp2bmcbbg32dseD4kAgmWSHqyk9v/D2nnyA5q/44gTcw5lbZc
SyFQOPqkVWnqZaubvERCkRFkSzXvWPDBlXoTnaieCCIkQXo7/yt/rdEciJgamxbvo29V
ShmHjcs+QkBypZ/V8He823JnMII/YuCxcEOA8JDKMM/0QzlXT3zps7x+VhG9vBGvGRYt
Avfw==
X-Gm-Message-State: AOJu0YzGwP0srmpv3sWIgm0mGATs206ZrRtoenIlU9wjYeapT2JmSTtn
F5K+lQedjDhu9CB+RES68HxN1jBvBnR399raWM8T9MCSIC/RiIvG+FEMpg==
X-Google-Smtp-Source: AGHT+IF3aI65vuqrg2lLiEaRbpfLID0yhS5JdpTMth0r8Sp3dHz6GYrKsy0ITZPb0TFuzOfherOynQ==
X-Received: by 2002:a05:6a00:a96:b0:714:2dc9:fbaf with SMTP id
d2e1a72fcca58-71de24514e3mr14119104b3a.18.1728240240682;
Sun, 06 Oct 2024 11:44:00 -0700 (PDT)
Received: from localhost.localdomain (syn-076-032-089-124.res.spectrum.com.
[76.32.89.124]) by smtp.gmail.com with ESMTPSA id
d2e1a72fcca58-71df0d477d4sm3045037b3a.134.2024.10.06.11.43.59
(version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256);
Sun, 06 Oct 2024 11:44:00 -0700 (PDT)
From: Nandini Persad <nandinipersad361@gmail.com>
To: dev@dpdk.org
Cc: Ferruh Yigit <ferruh.yigit@amd.com>,
Stephen Hemminger <stephen@networkplumber.org>,
Chengwen Feng <fengchengwen@huawei.com>
Subject: [PATCH v6] doc: add new driver guidelines
Date: Sun, 6 Oct 2024 11:42:54 -0700
Message-Id: <20241006184254.53499-1-nandinipersad361@gmail.com>
X-Mailer: git-send-email 2.34.1
In-Reply-To: <20240916162856.11566-1-stephen@networkplumber.org>
References: <20240916162856.11566-1-stephen@networkplumber.org>
MIME-Version: 1.0
Content-Transfer-Encoding: 8bit
X-BeenThere: dev@dpdk.org
X-Mailman-Version: 2.1.29
Precedence: list
List-Id: DPDK patches and discussions <dev.dpdk.org>
List-Unsubscribe: <https://mails.dpdk.org/options/dev>,
<mailto:dev-request@dpdk.org?subject=unsubscribe>
List-Archive: <http://mails.dpdk.org/archives/dev/>
List-Post: <mailto:dev@dpdk.org>
List-Help: <mailto:dev-request@dpdk.org?subject=help>
List-Subscribe: <https://mails.dpdk.org/listinfo/dev>,
<mailto:dev-request@dpdk.org?subject=subscribe>
Errors-To: dev-bounces@dpdk.org
This document was created to assist contributors in creating DPDK drivers
and provides suggestions and guidelines on how to upstream effectively.
Signed-off-by: Ferruh Yigit <ferruh.yigit@amd.com>
Signed-off-by: Nandini Persad <nandinipersad361@gmail.com>
Reviewed-by: Stephen Hemminger <stephen@networkplumber.org>
Acked-by: Chengwen Feng <fengchengwen@huawei.com>
---
doc/guides/contributing/index.rst | 1 +
doc/guides/contributing/new_driver.rst | 213 +++++++++++++++++++++++++
2 files changed, 214 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..a4edbc05d6
--- /dev/null
+++ b/doc/guides/contributing/new_driver.rst
@@ -0,0 +1,213 @@
+.. SPDX-License-Identifier: BSD-3-Clause
+ Copyright 2024 The DPDK contributors
+
+
+Adding a New Driver
+===================
+
+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).
+
+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:
+
+* Maintainers 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 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
+Scatter Support Scatter Gather
+Vector Support Security protocols - IPsec, MACsec 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
+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
+----------------------
+
+Avoid doing the following:
+
+* Using PMD specific macros when DPDK macros exist
+* Including unused headers (process-iwyu.py)
+* Disabling compiler warnings for driver
+* #ifdef with driver-defined macros
+* DPDK version checks (via RTE_VERSION_NUM) in the upstream code
+* Introducing Public APIs 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
+
+
+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,
+drivers which depend on non-available components will not be accepted.
+If the required dependency is not yet publicly available, then wait to submit
+the driver until the dependent library is available.
+
+
+.. _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
+* check-spdx-tag.sh
+* Build documentation and validate how output looks
+
--
2.34.1