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 2BCF0457C0; Wed, 14 Aug 2024 12:10:39 +0200 (CEST) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id C12774066F; Wed, 14 Aug 2024 12:10:38 +0200 (CEST) Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.133.124]) by mails.dpdk.org (Postfix) with ESMTP id 6B32340274 for ; Wed, 14 Aug 2024 12:10:37 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1723630236; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=WdGT7luxko+CTlnuRRzuMBZf/MKLdcDOYstAJ7eRoYQ=; b=TijoA6QpV2hGN0gIfYgFqbG/q1q5bFsQk15boH10RwJS7tZx5+WRoOOyJ8bGgvBHHQPxsP DJQrqRZgLokRtCMyN0VH/9J+C7v2xD4PQde13YGu+E2dy8rhiriLvi6hqSPsKfbOvM984G 3pMHRNx9meU8gmz0TSyuh527Nit/w+0= Received: from mail-lf1-f71.google.com (mail-lf1-f71.google.com [209.85.167.71]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-156-JzWrvZgrNhuCzGXuUxHLUw-1; Wed, 14 Aug 2024 06:10:35 -0400 X-MC-Unique: JzWrvZgrNhuCzGXuUxHLUw-1 Received: by mail-lf1-f71.google.com with SMTP id 2adb3069b0e04-52efdae5be6so7111707e87.3 for ; Wed, 14 Aug 2024 03:10:35 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1723630234; x=1724235034; h=content-transfer-encoding:cc:to:subject:message-id:date:from :in-reply-to:references:mime-version:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=WdGT7luxko+CTlnuRRzuMBZf/MKLdcDOYstAJ7eRoYQ=; b=JEoC6dVpSJ4cQqatZ5W0MSWY7mdAR7sNJMiGP9PGgUep8fXNp7BThdH/CKa5cMmtWg vDdM+wbbgbTJuCJ+d+c3PJvvk4uYSnu/nbP3cyEdC7+SnOvfGI7pPBqtb1rJ3XwHlSBG qH5S6rkMQpf/gfnvkVm2yeSPYy+KUfJvIZ4hDXg7jXS3+bXAdET1fsMkwb8Ai5bHMPpj a/ng2ha8dQ8N+iDASamUwv0FU0ln8X5MnPCxcUqIdaaIQ+RQ3uxJht0HFe4V+VlPplOB m1zoihenWuHmpSIvK4j/slNj/NqZ7VAraysfMv+1LTDUxhS4DBGZaFwJkAkPyKtnfQNO Zq4A== X-Gm-Message-State: AOJu0YyjNdG162tDZBrSy2PVXYRRoST//cLc3EJp/U8bWVXk7K7QNpzT EkVKMyPqtF+HhEdpPHhtFu40Gy2YTpXpv/N/mh6ihJ/KSIVRKx8BhHwEh3SrQm9reF7HhpZ0WEF a42gTXEUPknhEofjNtzmvH9P85UJ34IKBQuSf95RnYraeY8G2zFtM/jtwBkPfqLoqtJWr67O0tQ pbqwNc3OIkyScFZ1Q= X-Received: by 2002:a05:6512:3a82:b0:52c:e312:2082 with SMTP id 2adb3069b0e04-532edbbf160mr1255101e87.54.1723630233604; Wed, 14 Aug 2024 03:10:33 -0700 (PDT) X-Google-Smtp-Source: AGHT+IHoq1mH5RFvnWRSNcc3eKUCmfnH/dEdwQ5zOFS3P3QsZGcPzjd0N7+eKxqV8jtSWCdQ/Oxuhv3n+9UVRQ6/pyE= X-Received: by 2002:a05:6512:3a82:b0:52c:e312:2082 with SMTP id 2adb3069b0e04-532edbbf160mr1255074e87.54.1723630232929; Wed, 14 Aug 2024 03:10:32 -0700 (PDT) MIME-Version: 1.0 References: <20240813201250.9383-1-nandinipersad361@gmail.com> <20240814023604.124686-1-stephen@networkplumber.org> In-Reply-To: <20240814023604.124686-1-stephen@networkplumber.org> From: David Marchand Date: Wed, 14 Aug 2024 12:10:21 +0200 Message-ID: Subject: Re: [PATCH v2] doc: add new driver guidelines To: Nandini Persad Cc: dev@dpdk.org, Stephen Hemminger X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Type: text/plain; charset="UTF-8" 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 On Wed, Aug 14, 2024 at 4:36=E2=80=AFAM Stephen Hemminger wrote: > > From: Nandini Persad > > This document was created to assist contributors in creating DPDK drivers > and provides suggestions and guidelines on how to upstream effectively. > > Signed-off-by: Nandini Persad > --- > v2 - text should be i file not patch > > doc/guides/contributing/index.rst | 1 + > doc/guides/contributing/new_driver.rst | 198 +++++++++++++++++++++++++ > 2 files changed, 199 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/contribu= ting/new_driver.rst > new file mode 100644 > index 0000000000..037b64bd24 > --- /dev/null > +++ b/doc/guides/contributing/new_driver.rst > @@ -0,0 +1,198 @@ > +.. SPDX-License-Identifier: BSD-3-Clause > + Copyright 2024 The DPDK contributors > + > + > +Upstreaming New DPDK Drivers Guide > +=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 > + > +The DPDK project continuously grows its ecosystem by adding support for = new > +devices. There is no need to break lines at 80 columns, prefer splitting at punctuation marks. > +This document is designed to assist contributors in creating DPDK > +drivers, also known as Poll Mode Drivers (PMD's). > + > +By having public support for a device, we can ensure accessibility acros= s 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.rs= t`. I think it should be :doc:`patches`. > + > + > + > +Splitting into Patches > +---------------------- > + > +We recommend that drivers are split into patches, so that each patch rep= resents > +a single feature. If the driver code is already developed, it may be cha= llenging > +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 intent= ion > +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 highlig= hts > +unnecessary or irrelevant code, as any code not belonging to any specifi= c > +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: > + > +* 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.rs= t`) > +* 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: > + > +=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 > +Net Crypto > +=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 > +Initialization Initialization > +Configure queues Configure queues > +Start queues Start queues > +Simple Rx / Tx Simple Data Processing > +Statistics Statistics > +Device info > +Link interrupt > +Burst mode info > +Promisc all-multicast > +RSS > +=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 > + > + > +Advanced features should be in the next group of patches. > +The suggestions for these, listed below, are in no specific order: > + > +=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 > +Net > +=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 > +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 > +=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 > + > + > +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 PM= D. > +* Do not include unused headers. Use the ./devtools/process-iwyu.py tool= . > +* Do not disable compiler warnings in the build file. > +* Do not use #ifdef with driver-defined macros, instead prefer runtime c= onfiguration. > +* Document device parameters in the driver guide. > +* Make device operations struct 'const'. > +* Use dynamic logging. > +* Do not use DPDK version checks in the upstream code. > +* Be sure to have SPDX license tags and copyright notice on each side. > + > + > +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, > +or this is a blocker for upstreaming the driver. > + > + > +.. _tool_list: > + > +Test Tools > +---------- > + > +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 As part of testing a patch, documentation generation should be checked too. --=20 David Marchand