Skip to contentSkip to conversation

docs: netdev: document guidance on cleanup.h

PATCH Applied Jakub Kicinski 3 participants 3 messages Aug 30, 2024 – Sep 5, 2024

Subsystems (4)
lore
Share & tools
lore

Jakub Kicinski

author maintainer
#0 lore raw

PATCH v2 1/1 docs: netdev: document guidance on cleanup.h

Document what was discussed multiple times on list and various virtual / in-person conversations. guard() being okay in functions <= 20 LoC is a bit of my own invention. If the function is trivial it should be fine, but feel free to disagree :)

We'll obviously revisit this guidance as time passes and we and other subsystems get more experience.

---
CC: [email protected]
CC: [email protected]
CC: [email protected]

v2:
- add sentence about revisiting later to commit msg
- fix spelling
v1: https://lore.kernel.org/[email protected]

---
 Documentation/process/maintainer-netdev.rst | 16 ++++++++++++++++
 1 file changed, 16 insertions(+)
Documentation/process/maintainer-netdev.rst +16 -0
index 30d24eecdaaa..c9edf9e7362d 100644
@@ -375,6 +375,22 @@ When working in existing code which uses nonstandard formatting make
 your code follow the most recent guidelines, so that eventually all code
 in the domain of netdev is in the preferred format.
 
+Using device-managed and cleanup.h constructs
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Netdev remains skeptical about promises of all "auto-cleanup" APIs,
+including even ``devm_`` helpers, historically. They are not the preferred
+style of implementation, merely an acceptable one.
+
+Use of ``guard()`` is discouraged within any function longer than 20 lines,
+``scoped_guard()`` is considered more readable. Using normal lock/unlock is
+still (weakly) preferred.
+
+Low level cleanup constructs (such as ``__free()``) can be used when building
+APIs and helpers, especially scoped iterators. However, direct use of
+``__free()`` within networking core and drivers is discouraged.
+Similar guidance applies to declaring variables mid-function.
+
 Resending after review
 ~~~~~~~~~~~~~~~~~~~~~~
 
Signature · 1 line
2.46.0
reviewer
#1 lore raw
Quoted 17 lines · Jakub Kicinski

Document what was discussed multiple times on list and various virtual / in-person conversations. guard() being okay in functions <= 20 LoC is a bit of my own invention. If the function is trivial it should be fine, but feel free to disagree :)

We'll obviously revisit this guidance as time passes and we and other subsystems get more experience.

---
CC: [email protected]
CC: [email protected]
CC: [email protected]

Quoted 4 lines

v2:
- add sentence about revisiting later to commit msg
- fix spelling
v1: https://lore.kernel.org/[email protected]

Thanks. I think this patch has enough tags, so I won't add another. But, FTR, this version looks good to me.

...

#2 lore raw
In reply to Jakub Kicinski
This patch was applied to netdev/net.git (main) by Paolo Abeni <[email protected]>:

Hello:

This patch was applied to netdev/net.git (main)
by Paolo Abeni <[email protected]>:

Quoted 9 lines · On Fri, 30 Aug 2024 10:14:42 -0700 you wrote:

Document what was discussed multiple times on list and various virtual / in-person conversations. guard() being okay in functions <= 20 LoC is a bit of my own invention. If the function is trivial it should be fine, but feel free to disagree :)

We'll obviously revisit this guidance as time passes and we and other subsystems get more experience.

[...]

Here is the summary with links:
- [net,v2] docs: netdev: document guidance on cleanup.h

    https://git.kernel.org/netdev/net/c/c82299fbbcce

You are awesome, thank you!

Signature · 2 lines
Deet-doot-dot, I am a bot.
https://korg.docs.kernel.org/patchwork/pwbot.html