[PATCH][next] stddef: Document designated initializer semantics for __TRAILING_OVERLAP()

["Gustavo A. R. Silva" <gustavoars@kernel.org>]

Document the designated initializer behavior for overlapping storage
between NAME and MEMBERS, and clarify the implications for static
initialization to help avoid unintended overwrites.

Signed-off-by: Gustavo A. R. Silva <gustavoars@kernel.org>
---
 include/linux/stddef.h | 56 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 56 insertions(+)

diff --git a/include/linux/stddef.h b/include/linux/stddef.h
index 80b6bfb944f0..36c91c725546 100644
--- a/include/linux/stddef.h
+++ b/include/linux/stddef.h
@@ -100,6 +100,62 @@ enum {
  * Creates a union between a flexible-array member (FAM) in a struct and a set
  * of additional members that would otherwise follow it.
  *
+ * Beware that, as this helper encloses TYPE NAME and MEMBERS in the same
+ * union, designated initializers for MEMBERS may overwrite portions
+ * previously initialized through NAME.
+ *
+ * For example:
+ *
+ * struct flex {
+ *	size_t count;
+ *	u8 fam[];
+ * };
+ *
+ * struct composite {
+ *	...
+ *	__TRAILING_OVERLAP(struct flex, flex, fam, __packed,
+ *		u8 data;
+ *	);
+ * } __packed;
+ *
+ * static struct composite comp = {
+ *	.flex = {
+ *		.count = 1,
+ *	},
+ *	.data = 2,
+ * };
+ *
+ * In the example above, .flex and .data initialize different views of the same
+ * union storage. Since .data is initialized last, it _may_ overwrite portions
+ * previously initialized through .flex, leading to .flex.count being zeroed
+ * out.
+ *
+ * A couple of alternatives are show below.
+ *
+ * Initialize only one view of the overlapped storage and assign the rest
+ * at run time:
+ *
+ * static struct composite comp = {
+ *	.flex = {
+ *		.count = 1,
+ *	},
+ * };
+ *
+ * static void foo(void)
+ * {
+ *	comp.data = 2;
+ *	...
+ * }
+ *
+ * (Compiler Explorer test code: https://godbolt.org/z/zz4K1Ejvf)
+ *
+ * Alternatively, move the entire initialization to run time.
+ *
+ * For an example of stack-based inialization see commit 5e54510a9389
+ * ("acpi: nfit: intel: avoid multiple -Wflex-array-member-not-at-end warnings")
+ *
+ * Link: https://git.kernel.org/linus/5e54510a9389caa9
+ *
  * @TYPE: Flexible structure type name, including "struct" keyword.
  * @NAME: Name for a variable to define.
  * @FAM: The flexible-array member within @TYPE
-- 
2.51.0