From patchwork Thu Aug 29 15:20:25 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Jakub Kicinski X-Patchwork-Id: 13783377 X-Patchwork-Delegate: kuba@kernel.org Received: from smtp.kernel.org (aws-us-west-2-korg-mail-1.web.codeaurora.org [10.30.226.201]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 14F0718E373; Thu, 29 Aug 2024 15:20:28 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=10.30.226.201 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1724944829; cv=none; b=DR0zDNVFrxTrgMPSEjCh+svcc9GwJH5fH90MyZARJo0rHNOoPkE+Tg2EzCh8CV/Ga+AdEm+nlxqGaKO+dXRIoxaWNXb3No7wWz+nc4YklSo+UXTR6a2533PxjOlLNSnvTQLtNgdBRUBFX3spTbuk5tjI0ceEnn2HU3KXbZdmk6A= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1724944829; c=relaxed/simple; bh=IXYxlcYCp7DFF63JfA4Y1j/u8NAySHcOeG7Qwvedfv4=; h=From:To:Cc:Subject:Date:Message-ID:MIME-Version; b=suPfU07yfLSzLFS8Uc0oyXT2FjzLvTCgHIL87c3DJmUXgzs+8UwaWZ+qvyxoJ7JFuSColG0UaQ3zhXNJF+9WhBKf/1i5oMoanAPeFBO0UJsAxhJZvJU7HzXpsb/2DCuhv+P8HnOODl0BV8tp4BjnAioWOgokUER0TtxuUxTEb4U= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=OPm0P/Gw; arc=none smtp.client-ip=10.30.226.201 Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b="OPm0P/Gw" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 3DCFDC4CEC1; Thu, 29 Aug 2024 15:20:28 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1724944828; bh=IXYxlcYCp7DFF63JfA4Y1j/u8NAySHcOeG7Qwvedfv4=; h=From:To:Cc:Subject:Date:From; b=OPm0P/GwGyHHLwYBMTCsMWDq9rvYcsPWhkp0XWmZ/cneWUqNTUb9bk1UBMD8B/ctP 4OTKHXQRcVCZsbrqtNYxrPuIaIhGtxhVC+5CRya+SKoyA80zHTmVj5CYIU2ViXQAFv x5Qkfl1GEe52NAo+7QTOn0alqSpCtB60a5SGFOKHlYemxf2PKv/zpkhXF0GVs/PGWK PzCVCOr//rDHFLYTLiMHd36tPxxPFoD89w71uAsshRdC+xuLKQ084lXyWDB5Rv0HpN Lnj08vCIN6IelGvjQtKnibQUY2wYuH0Z7OBPkf6quGYkBRjx9FiNm7pfepdKgJ0TBA 2PxKyrca8CC5w== From: Jakub Kicinski To: davem@davemloft.net Cc: netdev@vger.kernel.org, edumazet@google.com, pabeni@redhat.com, Jakub Kicinski , andrew@lunn.ch, corbet@lwn.net, linux-doc@vger.kernel.org Subject: [PATCH net] docs: netdev: document guidance on cleanup.h Date: Thu, 29 Aug 2024 08:20:25 -0700 Message-ID: <20240829152025.3203577-1-kuba@kernel.org> X-Mailer: git-send-email 2.46.0 Precedence: bulk X-Mailing-List: netdev@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 X-Patchwork-Delegate: kuba@kernel.org Document what was discussed multiple times on list and various virtual / in-person conversations. guard() being okay in functions <= 20 LoC is my own invention. If the function is trivial it should be fine, but feel free to disagree :) Signed-off-by: Jakub Kicinski Reviewed-by: Eric Dumazet Reviewed-by: Nikolay Aleksandrov Reviewed-by: Andrew Lunn --- CC: andrew@lunn.ch CC: corbet@lwn.net CC: linux-doc@vger.kernel.org --- Documentation/process/maintainer-netdev.rst | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/Documentation/process/maintainer-netdev.rst b/Documentation/process/maintainer-netdev.rst index fe8616397d63..ccd6c96a169b 100644 --- a/Documentation/process/maintainer-netdev.rst +++ b/Documentation/process/maintainer-netdev.rst @@ -392,6 +392,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 interators. However, direct use of +``__free()`` within networking core and drivers is discouraged. +Similar guidance applies to declaring variables mid-function. + Resending after review ~~~~~~~~~~~~~~~~~~~~~~