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 8EDFE45957; Tue, 10 Sep 2024 16:58:23 +0200 (CEST) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id 5B59742DC3; Tue, 10 Sep 2024 16:58:23 +0200 (CEST) Received: from mail-pg1-f177.google.com (mail-pg1-f177.google.com [209.85.215.177]) by mails.dpdk.org (Postfix) with ESMTP id 152AA402AB for ; Tue, 10 Sep 2024 16:58:22 +0200 (CEST) Received: by mail-pg1-f177.google.com with SMTP id 41be03b00d2f7-7d4ed6158bcso3997450a12.1 for ; Tue, 10 Sep 2024 07:58:22 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1725980301; x=1726585101; 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=hk0hITIzLser8R8K6rmvmBIdofWhv99sP1JpjIW0QmE=; b=Q7zv4bgvaSoRCwO8YOJA3cvVOj5KUFVczYkWYU1mtjCD9LZ5Q2akr2M/oWqMkJq/2x PbjB3W96y2MGXSPTzswEQfqxG07tDcsKNMyDOm+66gxTXtnd6lFLIqOvEBwBSIUsqkRT vdm2O/Tac91sdPwtJRubHlVEURTwRL4qBqs34ZFGOLPkvZpSVhAs8aR/c3PJGeI7JXoq OIdVJfWi2Otsi42xu45eKv8t+yo9VnhR36NnVABqb8shQ+XU4pvYcjcwidUuqVurYqBe Agec9RF0ftHCJ3H1qkL8zWVPyQq2MnQFktXo/dtTye8NjAgxcRVomPqUJT9v14P7x0oq MxTA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1725980301; x=1726585101; 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=hk0hITIzLser8R8K6rmvmBIdofWhv99sP1JpjIW0QmE=; b=qYqiRx7JjrT2COnU+er6UuXdBciMFILYFUMRDthUo+7Nfmj2ufA6IBYbMTYaHDjJ6i R1/Mqwl3QqsjeekWxa60yob+ZuUrcgyI0/DwgSNsrbLe+BInry8z+q4issPPc4/o0Iqk cA+NQCazVMIkPm2Uzlm6Z3AC9N7LTYcsfdF3k3Xptcrsn8faJZsS6dxrIZ/2TuRC5otG tAYs4eW5yJ71VdJNIVyhf1iOmOkxe4pcrYjd+DizxLNU/bzY96ycSOom71yaH+sBSMYd N9Pa67rpzynFfpMHjh3PID5oxDptYwKR49i3lnYd+S0FzTAHqIVEccQXn1TZjjmLdBJm EBbQ== X-Gm-Message-State: AOJu0YyLPH3rNenSioX2DnzXXcCVcYtMU6h3X0TzkT8sfeb1wbtHm4Ah HbhaWwqewswwqm2EDLfKrjz9x/8K5amIQcLQ7wgJP/M++ZCTUhsMWWklW3Kz X-Google-Smtp-Source: AGHT+IHYNJ5yM4acDzyhoMlKUBM92bp/b5oVWOHLN69PEkcBObuNRLnCUhadCKSFOdNEZwccJCVfQA== X-Received: by 2002:a05:6a21:b8b:b0:1cf:2c6f:4b88 with SMTP id adf61e73a8af0-1cf5de0ef57mr1388506637.0.1725980300525; Tue, 10 Sep 2024 07:58:20 -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-71908fc844asm1470373b3a.40.2024.09.10.07.58.19 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 10 Sep 2024 07:58:20 -0700 (PDT) From: Nandini Persad To: dev@dpdk.org Cc: Ferruh Yigit , Thomas Mojalon , Chengwen Feng Subject: [PATCH v3] doc: add new driver guidelines Date: Tue, 10 Sep 2024 07:58:01 -0700 Message-Id: <20240910145801.46186-1-nandinipersad361@gmail.com> X-Mailer: git-send-email 2.34.1 In-Reply-To: <20240814190901.14912-1-stephen@networkplumber.org> References: <20240814190901.14912-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 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 for how to upstream effectively. Co-authored-by: Ferruh Yigit Co-authored-by: Thomas Mojalon Signed-off-by: Nandini Persad Acked-by: Chengwen Feng --- 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 .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 .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