Excellent. Will send the update in accordingly. ________________________________ From: Ferruh Yigit Sent: Thursday, September 12, 2024 6:37:35 AM To: Nandini Persad Cc: dev@dpdk.org ; Thomas Mojalon ; Stephen Hemminger Subject: Re: [PATCH v3] doc: add new driver guidelines On 9/12/2024 2:18 PM, Nandini Persad wrote: > I like the separation. I can include it in V4 and see, it would be > helpful to know if it’s more or less confusing that way. > > For the prompt before each list, can we say something like “Avoid doing > the following” and “Suggested actions” or something a little better > grammatically. We could also just say “Avoid”. > Agree to have better header for the lists, what about: "Avoid doing the following" and "Remember to do the following" Or we can go with whatever you think more convenient. > ------------------------------------------------------------------------ > *From:* Ferruh Yigit > *Sent:* Thursday, September 12, 2024 1:13:33 AM > *To:* Nandini Persad > *Cc:* dev@dpdk.org ; Thomas Mojalon ; > Stephen Hemminger > *Subject:* Re: [PATCH v3] doc: add new driver guidelines > > 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 > >> 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. >> >