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 <[email protected]> --- 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
