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 895BC45962; Wed, 11 Sep 2024 18:04:25 +0200 (CEST) Received: from mails.dpdk.org (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id 772F542F45; Wed, 11 Sep 2024 18:04:25 +0200 (CEST) Received: from mail-ot1-f44.google.com (mail-ot1-f44.google.com [209.85.210.44]) by mails.dpdk.org (Postfix) with ESMTP id 3B30B42F43 for ; Wed, 11 Sep 2024 18:04:24 +0200 (CEST) Received: by mail-ot1-f44.google.com with SMTP id 46e09a7af769-710dad96bf7so1481177a34.0 for ; Wed, 11 Sep 2024 09:04:24 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1726070663; x=1726675463; darn=dpdk.org; h=cc:to:subject:message-id:date:from:in-reply-to:references :mime-version:from:to:cc:subject:date:message-id:reply-to; bh=PKL+5sPlbDwnvyi6ZpJw1se6uRDhdX39x1jQcsn6cxI=; b=CHgSMkvO2W5ud4km58rPyV5sf6jhDgYpwRkR2xXve1mCVrdj17mmo8SL8GowI/+Hh7 CZ2qzFwsKVeiTj5djzQZfSo+GXgfMHv0s42bvormcmY2MHLyjl3nphI31a7veDVJZguV cdS/6psXNK1ahlihspdPNfXXqKPa1yh88IfoVZsMRZelsMPhPblHjhCEx/1hRbUoMUrx 5nsLWPkieKYkT0m0XAobgdgf8WMJ8zRme/qdaKt4mOdz/52gEBujr9n1CHzG1xPCq5Tq K2BjiArfDC/gT/GQAXGtsT3b9tltTAGQ6os7Y80dF9sFc1PdpUzGCrMfYHGA/IzxYa9S mOPw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1726070663; x=1726675463; h=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=PKL+5sPlbDwnvyi6ZpJw1se6uRDhdX39x1jQcsn6cxI=; b=f0iFhxkgtlQmVg/fm3uyBqMRBb4VO5X8QBvqPScSL1BsEyfrsb05uVyJtJvA08ZAut RJBVTDW565RG/jP/vUHnt87400mPjXA2TbiLZbg7Eypv8Fbk6QJC2OGEESGjw3/l2XcH i2QTOFYBFyJrTJwfqGuc1TQTg2XWDJiOM+HM2ozckrCMIrAXp4n5CF8vN4GYjeHe0kVW IhKCuRk7qoz0nXWpXS5pFoE684UNFx9AwMJT1O7UsMVWC3CZjNxb1gcEjv5AACUmyC9f vX+TxHPa+2VWBRGsw5OdncIbKqFB/iEgeSwj1bEvuX7lktZnzOoKFI8HvGpr0paT4Dc/ omIA== X-Gm-Message-State: AOJu0YyoQtLeZCQkXsXw+wzCYvWJO0XkWmAALnIigU3dfvZp9/QizqHw DGcPr1h5ezEJxUo64BhqEAi1IvEbTLqG9ZKeS9gq44B0Kq3fDDO4nfITFvRm/YqVC2EbclovM11 e2/Vh1nk8NSkrxARMLotULX7WtTY= X-Google-Smtp-Source: AGHT+IGD6Sbfh6qh/gwBP58peCvM33JDZp1s/Ip8jqGZDdKhOEK4fYdwj+kDVsNlfBEEZSuW5CdnKUsMCowYdqeEngk= X-Received: by 2002:a05:6830:270e:b0:711:3ed:88d0 with SMTP id 46e09a7af769-7110957144emr23837a34.30.1726070663323; Wed, 11 Sep 2024 09:04:23 -0700 (PDT) MIME-Version: 1.0 References: <20240814190901.14912-1-stephen@networkplumber.org> <20240910145801.46186-1-nandinipersad361@gmail.com> <85f2e676-046b-4f2d-8c31-d0a5532fda6e@amd.com> In-Reply-To: <85f2e676-046b-4f2d-8c31-d0a5532fda6e@amd.com> From: Nandini Persad Date: Wed, 11 Sep 2024 09:04:12 -0700 Message-ID: Subject: Re: [PATCH v3] doc: add new driver guidelines To: Ferruh Yigit Cc: dev@dpdk.org, Thomas Mojalon , Stephen Hemminger Content-Type: multipart/alternative; boundary="000000000000beab370621da24f9" 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 --000000000000beab370621da24f9 Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: quoted-printable Hi Ferruh, I will work with Stephen on this. For the tone of the list, I believe we can try different ways to make the tone more friendly, while still being concise. What about something like this: - Avoid including unused headers (process-iwyu.py). - Keep compiler warnings enabled in the build file. - Instead of using #ifdef with driver-specific macros, opt for runtime configuration. - Document device parameters in the driver guide. - Make device operations structs 'const'. - Use dynamic logging. - Skip DPDK version checks (RTE_VERSION_NUM) in the upstream code. - Add SPDX license tags and copyright notices on all sides. - Don=E2=80=99t introduce public APIs directly from the driver. It's slightly more friendly. Let me know what you think, I'm open to trying another way. On Tue, Sep 10, 2024 at 5:16=E2=80=AFPM Ferruh Yigit = wrote: > On 9/10/2024 3:58 PM, Nandini Persad wrote: > > This document was created to assist contributors > > in creating DPDK drivers, providing suggestions > > and guidelines for how to upstream effectively. > > > > There are minor differences in this v3 and v2, isn't this version on top > of v2, can those changes be from Stephen? > > <...> > > > + > > +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. > > > > API (Application Programming Interface) is an acronym and should be all > uppercase, like 'APIs'. > > Overall the language in this list is imperative, I think it helps to > make it simple, but I am not sure about the tone, I wonder if we can do > better, do you have any suggestions? > > > > + > > + > > +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 > > > > `check-spdx-tag.sh` seems moved in v2 to "additional suggestions", I am > for keeping it here, as "additional suggestions" are more things to take > into consideration during design/development, above are actual scripts > that we can use to verify code. > > And long term intention was to move this "tools to run list" to a more > generic documentation, as these are not really specific to new PMD > guide, but "additional suggestions" will stay in this document. > > --000000000000beab370621da24f9 Content-Type: text/html; charset="UTF-8" Content-Transfer-Encoding: quoted-printable
Hi Ferruh,

I will work with Stephen on = this. For the tone of the list, I believe we can try different ways to make= the tone more friendly, while still being concise.

What about somet= hing like this:
  • Avoid including unused headers (process-iwyu.py).
  • Keep compiler warnings enabled in the build file.
  • Instead of = using #ifdef with driver-specific macros, opt for runtime configuration.
  • Document device parameters in the driver guide.
  • Make device o= perations structs 'const'.
  • Use dynamic logging.
  • Ski= p DPDK version checks (RTE_VERSION_NUM) in the upstream code.
  • Add S= PDX license tags and copyright notices on all sides.
  • Don=E2=80=99t = introduce public APIs directly from the driver.

    It's slightly mo= re friendly.

    Let me know what you think, I'm open to trying anot= her way.

    • On Tue, Sep 10, 2024 at 5:16=E2=80=AFPM Ferruh Yigit <= ;ferruh.yigit@amd.com> wrote= :
    On 9/10/2024 3= :58 PM, Nandini Persad wrote:
    > This document was created to assist contributors
    > in creating DPDK drivers, providing suggestions
    > and guidelines for how to upstream effectively.
    >

    There are minor differences in this v3 and v2, isn't this version on to= p
    of v2, can those changes be from Stephen?

    <...>

    > +
    > +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 runtim= e 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 upstrea= m code.
    > +* Be sure to have SPDX license tags and copyright notice on each side= .
    > +* Do not introduce public Apis directly from the driver.
    >

    API (Application Programming Interface) is an acronym and should be all
    uppercase, like 'APIs'.

    Overall the language in this list is imperative, I think it helps to
    make it simple, but I am not sure about the tone, I wonder if we can do
    better, do you have any suggestions?


    > +
    > +
    > +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
    >

    `check-spdx-tag.sh` seems moved in v2 to "additional suggestions"= , I am
    for keeping it here, as "additional suggestions" are more things = to take
    into consideration during design/development, above are actual scripts
    that we can use to verify code.

    And long term intention was to move this "tools to run list" to a= more
    generic documentation, as these are not really specific to new PMD
    guide, but "additional suggestions" will stay in this document.
    --000000000000beab370621da24f9--