linux-kernel - Re: [PATCH 8/9] bitfield: Add comment block for the host/fixed endian functions

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: <aThF_cYiyRjS38Ok@smile.fi.intel.com>
Date: Tue, 9 Dec 2025 17:53:33 +0200
From: Andy Shevchenko <andriy.shevchenko@...el.com>
To: david.laight.linux@...il.com
Cc: Yury Norov <yury.norov@...il.com>,
	Rasmus Villemoes <linux@...musvillemoes.dk>,
	linux-kernel@...r.kernel.org, linux-usb@...r.kernel.org,
	Geert Uytterhoeven <geert+renesas@...der.be>,
	Alexandre Belloni <alexandre.belloni@...tlin.com>,
	Jonathan Cameron <Jonathan.Cameron@...wei.com>,
	Crt Mori <cmo@...exis.com>,
	Richard Genoud <richard.genoud@...tlin.com>,
	Luo Jie <quic_luoj@...cinc.com>,
	Peter Zijlstra <peterz@...radead.org>,
	Jakub Kicinski <kuba@...nel.org>, netdev@...r.kernel.org,
	"David S . Miller" <davem@...emloft.net>,
	Simon Horman <simon.horman@...ronome.com>,
	Mika Westerberg <mika.westerberg@...ux.intel.com>,
	Andreas Noever <andreas.noever@...il.com>,
	Yehezkel Bernat <YehezkelShB@...il.com>,
	Nicolas Frattaroli <nicolas.frattaroli@...labora.com>
Subject: Re: [PATCH 8/9] bitfield: Add comment block for the host/fixed
 endian functions

On Tue, Dec 09, 2025 at 10:03:12AM +0000, david.laight.linux@...il.com wrote:

> Copied almost verbatim from the commit message that added the functions.

...

> +/*

Can it be a global DOC for being processed by kernel-doc?

> + * Primitives for manipulating bitfields both in host- and fixed-endian.
> + *
> + * * u32 le32_get_bits(__le32 val, u32 field) extracts the contents of the
> + *   bitfield specified by @field in little-endian 32bit object @val and
> + *   converts it to host-endian.
> + *
> + * * void le32p_replace_bits(__le32 *p, u32 v, u32 field) replaces
> + *   the contents of the bitfield specified by @field in little-endian
> + *   32bit object pointed to by @p with the value of @v.  New value is
> + *   given in host-endian and stored as little-endian.
> + *
> + * * __le32 le32_replace_bits(__le32 old, u32 v, u32 field) is equivalent to
> + *   ({__le32 tmp = old; le32p_replace_bits(&tmp, v, field); tmp;})
> + *   In other words, instead of modifying an object in memory, it takes
> + *   the initial value and returns the modified one.
> + *
> + * * __le32 le32_encode_bits(u32 v, u32 field) is equivalent to
> + *   le32_replace_bits(0, v, field).  In other words, it returns a little-endian
> + *   32bit object with the bitfield specified by @field containing the
> + *   value of @v and all bits outside that bitfield being zero.
> + *
> + * Such set of helpers is defined for each of little-, big- and host-endian
> + * types; e.g. u64_get_bits(val, field) will return the contents of the bitfield
> + * specified by @field in host-endian 64bit object @val, etc.  Of course, for
> + * host-endian no conversion is involved.
> + *
> + * Fields to access are specified as GENMASK() values - an N-bit field
> + * starting at bit #M is encoded as GENMASK(M + N - 1, M).  Note that
> + * bit numbers refer to endianness of the object we are working with -
> + * e.g. GENMASK(11, 0) in __be16 refers to the second byte and the lower
> + * 4 bits of the first byte.  In __le16 it would refer to the first byte
> + * and the lower 4 bits of the second byte, etc.
> + *
> + * Field specification must be a constant; __builtin_constant_p() doesn't
> + * have to be true for it, but compiler must be able to evaluate it at
> + * build time.  If it cannot or if the value does not encode any bitfield,
> + * the build will fail.
> + *
> + * If the value being stored in a bitfield is a constant that does not fit
> + * into that bitfield, a warning will be generated at compile time.
> + */

-- 
With Best Regards,
Andy Shevchenko