From: Ferruh Yigit <ferruh.yigit@amd.com>
To: Nandini Persad <nandinipersad361@gmail.com>
Cc: dev@dpdk.org, Thomas Mojalon <thomas@monjalon.net>,
Stephen Hemminger <stephen@networkplumber.org>
Subject: Re: [PATCH v3] doc: add new driver guidelines
Date: Thu, 12 Sep 2024 09:13:33 +0100 [thread overview]
Message-ID: <1f0665f9-4fed-4880-bbea-51781a2d9710@amd.com> (raw)
In-Reply-To: <CAAKk0T7evQaQb78E_qKWeRyUE94Luq4wdJFkakHU=M+Z3Q+tag@mail.gmail.com>
On 9/11/2024 5:04 PM, Nandini Persad wrote:
> 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’t 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.
>
I think above is better.
Another option can be separating it as "Do" and "Do Not" list, as
following, do you think does it help, or makes it harder to understand?
Avoid doing:
- Using PMD specific macros when DPDK ones exist
- Including unused headers
- Disable compiler warnings for driver
- #ifdef with driver-defined macros
- DPDK version checks (via RTE_VERSION_NUM) in the upstream code
- Public APIs directly from the driver
Suggested to do:
- 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
> On Tue, Sep 10, 2024 at 5:16 PM Ferruh Yigit <ferruh.yigit@amd.com
> <mailto: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 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.
>
next prev parent reply other threads:[~2024-09-12 8:13 UTC|newest]
Thread overview: 29+ messages / expand[flat|nested] mbox.gz Atom feed top
2024-08-13 20:12 [PATCH] " Nandini Persad
2024-08-14 2:35 ` [PATCH v2] " Stephen Hemminger
2024-08-14 10:10 ` David Marchand
2024-08-14 19:08 ` Stephen Hemminger
2024-09-05 9:16 ` [EXTERNAL] " Akhil Goyal
2024-09-05 9:49 ` Ferruh Yigit
2024-09-05 9:52 ` Akhil Goyal
2024-09-06 8:05 ` fengchengwen
2024-09-06 8:27 ` Ferruh Yigit
2024-09-09 1:01 ` fengchengwen
2024-09-10 14:58 ` [PATCH v3] " Nandini Persad
2024-09-11 0:16 ` Ferruh Yigit
2024-09-11 16:04 ` Nandini Persad
2024-09-12 8:13 ` Ferruh Yigit [this message]
2024-09-12 13:18 ` Nandini Persad
2024-09-12 13:37 ` Ferruh Yigit
2024-09-12 13:40 ` Nandini Persad
2024-09-12 20:26 ` Stephen Hemminger
2024-09-13 4:19 ` WanRenyong
2024-09-13 9:07 ` Ferruh Yigit
2024-09-13 16:08 ` Stephen Hemminger
2024-09-16 16:28 ` [PATCH v4] " Stephen Hemminger
2024-09-27 0:19 ` Ferruh Yigit
2024-09-27 15:02 ` Thomas Monjalon
2024-10-04 16:39 ` [PATCH v5] " Nandini Persad
2024-10-04 18:33 ` Ferruh Yigit
2024-10-06 18:42 ` [PATCH v6] " Nandini Persad
2024-10-06 21:09 ` Ferruh Yigit
2024-10-18 17:04 ` Thomas Monjalon
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=1f0665f9-4fed-4880-bbea-51781a2d9710@amd.com \
--to=ferruh.yigit@amd.com \
--cc=dev@dpdk.org \
--cc=nandinipersad361@gmail.com \
--cc=stephen@networkplumber.org \
--cc=thomas@monjalon.net \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).