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 353D2459B2; Mon, 16 Sep 2024 18:29:10 +0200 (CEST) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id F139F4025F; Mon, 16 Sep 2024 18:29:09 +0200 (CEST) Received: from mail-pg1-f182.google.com (mail-pg1-f182.google.com [209.85.215.182]) by mails.dpdk.org (Postfix) with ESMTP id 623B640150 for ; Mon, 16 Sep 2024 18:29:07 +0200 (CEST) Received: by mail-pg1-f182.google.com with SMTP id 41be03b00d2f7-6e7b121be30so2230693a12.1 for ; Mon, 16 Sep 2024 09:29:07 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=networkplumber-org.20230601.gappssmtp.com; s=20230601; t=1726504146; x=1727108946; 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=xH4yM+48ygfJ5kpDAQ4Q69rrPyQCnxgbMfUC7dwisvM=; b=it3+ylOcuSz4+u5wmJRRFwY0yHwV27h/aJqCxJw+75/90QoMQHMeTLJOTVd+Z0hVE8 yxfyIedoPXBlD85nju16qUpAADaUEK3I+kiPNa8UEA+BwWx9LhYl9gqps6SZv1edQmSB gi8PJM64vTMSEg7NxQ7qXFWDqRh/zOQWz3PvmqOCzd+EOHXapA1iBXMNWRb76whofyRG zJJPOYwQH3eVpfCg4neHq0jH6rjFTkEZzTBoYUSOYnpjgoloZ+q7dbdzeiAEwRUzFrkK iHIgDL5WHfsDQ17EgLC8wBx80FJrM7fI26JjjULGvT9G2wECOwaUnuHFji60phGuWr8z oyhA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1726504146; x=1727108946; 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=xH4yM+48ygfJ5kpDAQ4Q69rrPyQCnxgbMfUC7dwisvM=; b=JwS88lZv6kQWmMmnYqdjxASknXukBCl90MraObC2RhcPOQA3vA+khocbOEDxVpthJe MAePwGl9dBY7aILHYSDRSda4jCrGvZX2T1fA4wCoeEB646jtk1739yVgqq+R+3Vz+FeN 8JhoMqiwZZ4c6Ict6lQxG9cVaJGTTc8T32xChsDzLTHav+YtG2Lt21S9Ej5A7oW5gtlJ 19D+kw7Q8EjvsRlfb57tsN8eLfN7lh2080BtL7WlkKlKicoTs7w4wBIGZq+h/WADkcsG yt2r0hmpEt3z0orp9MEahSR3FyHXMFSNK0QG3RCCGbWuigKHHoNbgQrA96+70IYa6gRt VFRQ== X-Gm-Message-State: AOJu0YyEEizwNGrFxm2F0e3mc3+F5XoEljgn66JldFpQaukOlFVZ+zro njq43Gr8Jyj/kTHMbDT8A8Ocdtd+munIe8+OOoqRbSx9If4J2oEiuMSLVssmkBOfmTc+dwGBTlU i X-Google-Smtp-Source: AGHT+IHwAUlgWIL3vhCoPFQW5nsT9NkiuyTxJhGgPTe4cKahOOV9VSevC4aH/J+u4VHTc919jpkX5w== X-Received: by 2002:a17:90a:4b87:b0:2d8:f0b4:9acb with SMTP id 98e67ed59e1d1-2dbb9f08179mr16132357a91.34.1726504146122; Mon, 16 Sep 2024 09:29:06 -0700 (PDT) Received: from hermes.local (204-195-96-226.wavecable.com. [204.195.96.226]) by smtp.gmail.com with ESMTPSA id 98e67ed59e1d1-2dbb9c4ccf8sm7577235a91.3.2024.09.16.09.29.05 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 16 Sep 2024 09:29:05 -0700 (PDT) From: Stephen Hemminger To: dev@dpdk.org Cc: Nandini Persad , Ferruh Yigit , Thomas Monjalon , Stephen Hemminger , Chengwen Feng Subject: [PATCH v4] doc: add new driver guidelines Date: Mon, 16 Sep 2024 09:28:35 -0700 Message-ID: <20240916162856.11566-1-stephen@networkplumber.org> X-Mailer: git-send-email 2.45.2 In-Reply-To: <20240813201250.9383-1-nandinipersad361@gmail.com> References: <20240813201250.9383-1-nandinipersad361@gmail.com> 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 From: Nandini Persad This document was created to assist contributors in creating DPDK drivers and provides suggestions and guidelines on how to upstream effectively. Co-authored-by: Ferruh Yigit Co-authored-by: Thomas Monjalon Signed-off-by: Nandini Persad Reviewed-by: Stephen Hemminger Acked-by: Chengwen Feng --- doc/guides/contributing/index.rst | 1 + doc/guides/contributing/new_driver.rst | 207 +++++++++++++++++++++++++ 2 files changed, 208 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..f95d3b90bc --- /dev/null +++ b/doc/guides/contributing/new_driver.rst @@ -0,0 +1,207 @@ +.. 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). + +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 .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 .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 +* Adding driver private APIs. If a new feature is needed, it is + better to extend the corresponding framework API + +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: -- 2.45.2