diff mbox series

[net,v2] docs: netdev: document guidance on cleanup.h

Message ID 20240830171443.3532077-1-kuba@kernel.org (mailing list archive)
State Accepted
Commit c82299fbbccecf5866bdc3fa9cc46d5c6f5005ad
Delegated to: Netdev Maintainers
Headers show
Series [net,v2] docs: netdev: document guidance on cleanup.h | expand

Checks

Context Check Description
netdev/series_format success Single patches do not need cover letters
netdev/tree_selection success Clearly marked for net
netdev/ynl success Generated files up to date; no warnings/errors; no diff in generated;
netdev/fixes_present success No Fixes tags, but series doesn't touch code
netdev/header_inline success No static functions without inline keyword in header files
netdev/build_32bit success Errors and warnings before: 7 this patch: 7
netdev/build_tools success No tools touched, skip
netdev/cc_maintainers warning 1 maintainers not CCed: workflows@vger.kernel.org
netdev/build_clang success Errors and warnings before: 7 this patch: 7
netdev/verify_signedoff success Signed-off-by tag matches author and committer
netdev/deprecated_api success None detected
netdev/check_selftest success No net selftest shell script
netdev/verify_fixes success No Fixes tag
netdev/build_allmodconfig_warn success Errors and warnings before: 7 this patch: 7
netdev/checkpatch success total: 0 errors, 0 warnings, 0 checks, 22 lines checked
netdev/build_clang_rust success No Rust files in patch. Skipping build
netdev/kdoc success Errors and warnings before: 0 this patch: 0
netdev/source_inline success Was 0 now: 0
netdev/contest success net-next-2024-09-04--15-00 (tests: 718)

Commit Message

Jakub Kicinski Aug. 30, 2024, 5:14 p.m. UTC 
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.

Reviewed-by: Eric Dumazet <edumazet@google.com>
Reviewed-by: Nikolay Aleksandrov <razor@blackwall.org>
Reviewed-by: Andrew Lunn <andrew@lunn.ch>
Signed-off-by: Jakub Kicinski <kuba@kernel.org>
---
CC: horms@kernel.org
CC: corbet@lwn.net
CC: linux-doc@vger.kernel.org

v2:
 - add sentence about revisiting later to commit msg
 - fix spelling
v1: https://lore.kernel.org/20240829152025.3203577-1-kuba@kernel.org
---
 Documentation/process/maintainer-netdev.rst | 16 ++++++++++++++++
 1 file changed, 16 insertions(+)

Comments

Simon Horman Aug. 30, 2024, 8:31 p.m. UTC | #1 
On Fri, Aug 30, 2024 at 10:14:42AM -0700, Jakub Kicinski 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.
> 
> Reviewed-by: Eric Dumazet <edumazet@google.com>
> Reviewed-by: Nikolay Aleksandrov <razor@blackwall.org>
> Reviewed-by: Andrew Lunn <andrew@lunn.ch>
> Signed-off-by: Jakub Kicinski <kuba@kernel.org>
> ---
> CC: horms@kernel.org
> CC: corbet@lwn.net
> CC: linux-doc@vger.kernel.org
> 
> v2:
>  - add sentence about revisiting later to commit msg
>  - fix spelling
> v1: https://lore.kernel.org/20240829152025.3203577-1-kuba@kernel.org

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

...
patchwork-bot+netdevbpf@kernel.org Sept. 5, 2024, 9:10 a.m. UTC | #2 
Hello:

This patch was applied to netdev/net.git (main)
by Paolo Abeni <pabeni@redhat.com>:

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!
diff mbox series

Patch

diff --git a/Documentation/process/maintainer-netdev.rst b/Documentation/process/maintainer-netdev.rst
index 30d24eecdaaa..c9edf9e7362d 100644
--- a/Documentation/process/maintainer-netdev.rst
+++ b/Documentation/process/maintainer-netdev.rst
@@ -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
 ~~~~~~~~~~~~~~~~~~~~~~