netdev - Re: [PATCH net-next v8 04/10] lib: packing: document recently added APIs

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <20241204232650.67xald6yfbhtz6a4@skbuf>
Date: Thu, 5 Dec 2024 01:26:50 +0200
From: Vladimir Oltean <vladimir.oltean@....com>
To: Jacob Keller <jacob.e.keller@...el.com>
Cc: Andrew Morton <akpm@...ux-foundation.org>,
	Eric Dumazet <edumazet@...gle.com>,
	Jakub Kicinski <kuba@...nel.org>, Paolo Abeni <pabeni@...hat.com>,
	Tony Nguyen <anthony.l.nguyen@...el.com>,
	Przemek Kitszel <przemyslaw.kitszel@...el.com>,
	Masahiro Yamada <masahiroy@...nel.org>,
	netdev <netdev@...r.kernel.org>
Subject: Re: [PATCH net-next v8 04/10] lib: packing: document recently added
 APIs

On Tue, Dec 03, 2024 at 03:53:50PM -0800, Jacob Keller wrote:
> Extend the documentation for the packing library, covering the intended use
> for the recently added APIs. This includes the pack() and unpack() macros,
> as well as the pack_fields() and unpack_fields() macros.
> 
> Add a note that the packing() API is now deprecated in favor of pack() and
> unpack().
> 
> For the pack_fields() and unpack_fields() APIs, explain the rationale for
> when a driver may want to select this API. Provide an example which shows
> how to define the fields and call the pack_fields() and unpack_fields()
> macros.
> 
> Signed-off-by: Vladimir Oltean <vladimir.oltean@....com>
> Signed-off-by: Jacob Keller <jacob.e.keller@...el.com>
> ---
>  Documentation/core-api/packing.rst | 118 +++++++++++++++++++++++++++++++++++--
>  1 file changed, 113 insertions(+), 5 deletions(-)
> 
> diff --git a/Documentation/core-api/packing.rst b/Documentation/core-api/packing.rst
> index 821691f23c541cee27995bb1d77e23ff04f82433..30fc2328f789920e27a1bcf3945a6793894ef1d4 100644
> --- a/Documentation/core-api/packing.rst
> +++ b/Documentation/core-api/packing.rst
> @@ -227,11 +227,119 @@ Intended use
>  
>  Drivers that opt to use this API first need to identify which of the above 3
>  quirk combinations (for a total of 8) match what the hardware documentation
> -describes. Then they should wrap the packing() function, creating a new
> -xxx_packing() that calls it using the proper QUIRK_* one-hot bits set.
> +describes.
> +
> +There are 3 supported usage patterns, detailed below.
> +
> +packing()
> +^^^^^^^^^
> +
> +This API function is deprecated.
>  
>  The packing() function returns an int-encoded error code, which protects the
>  programmer against incorrect API use.  The errors are not expected to occur
> -during runtime, therefore it is reasonable for xxx_packing() to return void
> -and simply swallow those errors. Optionally it can dump stack or print the
> -error description.
> +during runtime, therefore it is reasonable to wrap packing() into a custom
> +function which returns void and simply swallow those errors. Optionally it can

returns (...) and swallows

> +dump stack or print the error description.