From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mails.dpdk.org (mails.dpdk.org [217.70.189.124]) by inbox.dpdk.org (Postfix) with ESMTP id 8A23D457B7; Tue, 13 Aug 2024 22:13:18 +0200 (CEST) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id 211C14065C; Tue, 13 Aug 2024 22:13:18 +0200 (CEST) Received: from mail-pl1-f178.google.com (mail-pl1-f178.google.com [209.85.214.178]) by mails.dpdk.org (Postfix) with ESMTP id 8E47C402A8 for ; Tue, 13 Aug 2024 22:13:16 +0200 (CEST) Received: by mail-pl1-f178.google.com with SMTP id d9443c01a7336-1fc65329979so54025305ad.0 for ; Tue, 13 Aug 2024 13:13:16 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1723579995; x=1724184795; darn=dpdk.org; h=content-transfer-encoding:mime-version:message-id:date:subject:cc :to:from:from:to:cc:subject:date:message-id:reply-to; bh=uX36cwVBKcQ7AudnskEvxZ79eMgbL6PM9CWIkU6GbOo=; b=VL09GsPJ4S8+KI5HM0NkYQm2BE9PFTK+Zl3feaPGoBCJl2q73daTTlABuDV06OWyhQ xEw+Adp5FP6cwd/u3vZeDxnQMeYi6VX552HyGaYdN0RfjI3ikKhSrGbQfG6BUY9lpeAt k43QPStR4ZJKbXySrtBnsr4QNNQ3uUuuSpptxWVpOR/Q2nQlPc6g/Mln6XvRCczeynGN otcMHjCX7X+OjPJXNz/JbmSatPKQOD4L13tLUphl7/5n6l/49H0zOkaRaxuDj76c7uIY V3d2/OyOCGWqvgP3YAHuE+ydSZQt7uxcC+ZLdcQ059ZCIKfaNNpnjd5lgz4czmPyAUsD Jn5Q== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1723579995; x=1724184795; h=content-transfer-encoding:mime-version:message-id:date:subject:cc :to:from:x-gm-message-state:from:to:cc:subject:date:message-id :reply-to; bh=uX36cwVBKcQ7AudnskEvxZ79eMgbL6PM9CWIkU6GbOo=; b=EzfMCLCYY9YuHfyR6PachLaGhDAsyPkt807HfiEaBAvyTstaMCNs5y7Y/xT0XxfNIA Pz31NsPpvZs6Y5c0jCWghPZeyecmyXymSk9ybw46cfq3rBKcue+n1pwgwvB2C/PxrDw6 ddzGQwWozPXyrqFyqJ3EsBdBHCe/UuOqIDwzwwE7XR/M6pTk9tk24gatyExYpFCv9nSl UOuln+4SOpD+T3uT8UefYE+S4tzG70xBMuP7WWhHtO2shArn2BkQKEixTLATi/YMGMH0 mZyuGPw4R481Uz4/mZEYos3EiF03U4/v1e6f56YdnGzSOUbMFTcJZfl0QwOsBMlVZf7Q k/xg== X-Gm-Message-State: AOJu0Yxnra93otuiFxJIHMiMgg4Z169AK9YtX4uGBTSKlv1RABwzDv7N PrfJAYBSJeTY2tT13KfPLcEgsrMM+z3oeVlyWR90Ll1AKcKL9T+ZfokoO5LaxSM= X-Google-Smtp-Source: AGHT+IHmyluGTEPamDOqhy+T8MVbVfavQby/69cF/U2jvBUbypLVJi4/xjl2NWugl7GNuWksqWn+Cg== X-Received: by 2002:a17:903:32d1:b0:1fd:791d:1437 with SMTP id d9443c01a7336-201d63b3e79mr11147135ad.6.1723579995068; Tue, 13 Aug 2024 13:13:15 -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 d9443c01a7336-201cd14b08dsm17525075ad.94.2024.08.13.13.13.14 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 13 Aug 2024 13:13:14 -0700 (PDT) From: Nandini Persad To: dev@dpdk.org Cc: Ferruh Yigit Subject: [PATCH] doc: add new driver guidelines Date: Tue, 13 Aug 2024 13:12:50 -0700 Message-Id: <20240813201250.9383-1-nandinipersad361@gmail.com> X-Mailer: git-send-email 2.34.1 MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: DPDK patches and discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: dev-bounces@dpdk.org This document was created to assist contributors in creating DPDK drivers, providing suggestions and guidelines on how to upstream effectively. Signed-off-by: Ferruh Yigit , Thomas Monjalon , Nandini Persad --- 0001-doc-add-new-driver-guidelines.patch | 206 +++++++++++++++++++++++ doc/guides/contributing/index.rst | 1 + 2 files changed, 207 insertions(+) create mode 100644 0001-doc-add-new-driver-guidelines.patch diff --git a/0001-doc-add-new-driver-guidelines.patch b/0001-doc-add-new-dr= iver-guidelines.patch new file mode 100644 index 0000000000..cba94a3789 --- /dev/null +++ b/0001-doc-add-new-driver-guidelines.patch @@ -0,0 +1,206 @@ ++.. SPDX-License-Identifier: BSD-3-Clause=0D ++ Copyright 2024 The DPDK contributors=0D ++=0D ++=0D ++Upstreaming New DPDK Drivers Guide=0D ++=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=0D ++=0D ++The DPDK project continuously grows its ecosystem by adding support for n= ew=0D ++devices.=0D ++This document is designed to assist contributors in creating DPDK=0D ++drivers, also known as Poll Mode Drivers (PMD's).=0D ++=0D ++By having public support for a device, we can ensure accessibility across= various=0D ++operating systems and guarantee community maintenance in future releases.= =0D ++If a new device is similar to a device already supported by an existing d= river,=0D ++it is more efficient to update the existing driver.=0D ++=0D ++Here are our best practice recommendations for creating a new driver.=0D ++=0D ++=0D ++Early Engagement with the Community=0D ++-----------------------------------=0D ++=0D ++When creating a new driver, we highly recommend engaging with the DPDK=0D ++community early instead of waiting the work to mature.=0D ++=0D ++These public discussions help align development of your driver with DPDK = expectations.=0D ++You may submit a roadmap before the release to inform the community of=0D ++your plans. Additionally, sending a Request for Comments (RFC) early in=0D ++the release cycle, or even during the prior release, is advisable.=0D ++=0D ++DPDK is mainly consumed via Long Term Support (LTS) releases.=0D ++It is common to target a new PMD to a LTS release. For this, it is=0D ++suggested to start upstreaming at least one release before a LTS release.= =0D ++=0D ++=0D ++Progressive Work=0D ++----------------=0D ++=0D ++To continually progress your work, we recommend planning for incremental= =0D ++upstreaming across multiple patch series or releases.=0D ++=0D ++It's important to prioritize quality of the driver over upstreaming=0D ++in a single release or single patch series.=0D ++=0D ++=0D ++Finalizing=0D ++----------=0D ++=0D ++Once the driver has been upstreamed, the author has=0D ++a responsibility to the community to maintain it.=0D ++=0D ++This includes the public test report. Authors must send a public=0D ++test report after the first upstreaming of the PMD. The same=0D ++public test procedure may be reproduced regularly per release.=0D ++=0D ++After the PMD is upstreamed, the author should send a patch=0D ++to update the website with the name of the new PMD and supported devices= =0D ++via the DPDK mailing list..=0D ++=0D ++For more information about the role of maintainers, see :doc:`patches.rst= `.=0D ++=0D ++=0D ++=0D ++Splitting into Patches=0D ++----------------------=0D ++=0D ++We recommend that drivers are split into patches, so that each patch repr= esents=0D ++a single feature. If the driver code is already developed, it may be chal= lenging=0D ++to split. However, there are many benefits to doing so.=0D ++=0D ++Splitting patches makes it easier to understand a feature and clarifies t= he=0D ++list of components/files that compose that specific feature.=0D ++=0D ++It also enables the ability to track from the source code to the feature= =0D ++it is enabled for and helps users to understand the reasoning and intenti= on=0D ++of implementation. This kind of tracing is regularly required=0D ++for defect resolution and refactoring.=0D ++=0D ++Another benefit of splitting the codebase per feature is that it highligh= ts=0D ++unnecessary or irrelevant code, as any code not belonging to any specific= =0D ++feature becomes obvious.=0D ++=0D ++Git bisect is also more useful if patches are split per patch.=0D ++=0D ++The split should focus on logical features=0D ++rather than file-based divisions.=0D ++=0D ++Each patch in the series must compile without errors=0D ++and should maintain functionality.=0D ++=0D ++Enable the build as early as possible within the series=0D ++to facilitate continuous integration and testing.=0D ++This approach ensures a clear and manageable development process.=0D ++=0D ++We suggest splitting patches following this approach:=0D ++=0D ++* Each patch should be organized logically as a new feature.=0D ++* Run test tools per patch (See :ref:`tool_list`:).=0D ++* Update relevant documentation and .ini file with each patch.=0D ++=0D ++=0D ++The following order in the patch series is as suggested below.=0D ++=0D ++The first patch should have the driver's skeleton which should include:=0D ++=0D ++* Maintainer's file update=0D ++* Driver documentation=0D ++* Document must have links to official product documentation web page=0D ++* The new document should be added into the index (`doc/guides/index.rst= `)=0D ++* Initial .ini file=0D ++* Release notes announcement for the new driver=0D ++=0D ++=0D ++The next patches should include basic device features.=0D ++The following is suggested sample list to include in these patches:=0D ++=0D ++=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D = =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=0D ++Net Crypto=0D ++=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D = =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=0D ++Initialization Initialization=0D ++Configure queues Configure queues=0D ++Start queues Start queues=0D ++Simple Rx / Tx Simple Data Processing=0D ++Statistics Statistics=0D ++Device info=0D ++Link interrupt =0D ++Burst mode info=0D ++Promisc all-multicast=0D ++RSS=0D ++=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D = =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=0D ++=0D ++=0D ++Advanced features should be in the next group of patches.=0D ++The suggestions for these, listed below, are in no specific order:=0D ++=0D ++=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=0D ++Net =0D ++=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D =0D ++Advanced Rx / Tx=0D ++Scatter Support=0D ++Vector Support=0D ++TSO / LRO=0D ++Rx / Tx Descriptor Status=0D ++RX / Tx Queue Info=0D ++Flow Offload=0D ++Traffic Management/Metering=0D ++Extended statistics=0D ++Secondary Process Support=0D ++FreeBSD / Windows Support=0D ++Flow control=0D ++FEC=0D ++EEPROM access=0D ++Register Dump=0D ++Time Synchronization, PTP=0D ++Perf documentation=0D ++=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=0D ++=0D ++=0D ++After all features are enabled, if there is remaining base code that=0D ++is not upstreamed, they can be upstreamed at the end of the patch series.= =0D ++However, we recommend these patches are still split into logical groups.= =0D ++=0D ++=0D ++Additional Suggestions=0D ++----------------------=0D ++=0D ++* We recommend using DPDK macros instead of inventing new ones in the PMD= .=0D ++* Do not include unused headers. Use the ./devtools/process-iwyu.py tool.= =0D ++* Do not disable compiler warnings in the build file.=0D ++* Do not use #ifdef with driver-defined macros, instead prefer runtime co= nfiguration.=0D ++* Document device parameters in the driver guide.=0D ++* Make device operations struct 'const'.=0D ++* Use dynamic logging.=0D ++* Do not use DPDK version checks in the upstream code.=0D ++* Be sure to have SPDX license tags and copyright notice on each side.=0D ++=0D ++=0D ++Dependencies=0D ++------------=0D ++=0D ++At times, drivers may have dependencies to external software.=0D ++For driver dependencies, same DPDK rules for dependencies applies.=0D ++Dependencies should be publicly and freely available,=0D ++or this is a blocker for upstreaming the driver.=0D ++=0D ++=0D ++.. _tool_list:=0D ++=0D ++Test Tools=0D ++----------=0D ++=0D ++Be sure to run the following test tools per patch in a patch series:=0D ++=0D ++* checkpatches.sh=0D ++* check-git-log.sh=0D ++* check-meson.py=0D ++* check-doc-vs-code.sh=0D ++* check-spdx-tag.sh=0D ++* Build documentation and validate how output looks=0D ++=0D ++For more information on contributing to DPDK,=0D ++refer to :doc:`patches.rst`.=0D +-- =0D +2.43.0=0D +=0D diff --git a/doc/guides/contributing/index.rst b/doc/guides/contributing/in= dex.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 --=20 2.34.1