On Tue, May 6, 2025 at 6:24 AM Sami Tolvanen <samitolvanen@xxxxxxxxxx> wrote:
>
> Document byte_size and type_string kABI stability rules. Also fix
> the section numbers while we're at it.
>
> Signed-off-by: Sami Tolvanen <samitolvanen@xxxxxxxxxx>
> ---
> Documentation/kbuild/gendwarfksyms.rst | 103 +++++++++++++++++++++++--
> 1 file changed, 95 insertions(+), 8 deletions(-)
>
> diff --git a/Documentation/kbuild/gendwarfksyms.rst b/Documentation/kbuild/gendwarfksyms.rst
> index e4beaae7e456..8b0d7ebbb084 100644
> --- a/Documentation/kbuild/gendwarfksyms.rst
> +++ b/Documentation/kbuild/gendwarfksyms.rst
> @@ -125,14 +125,17 @@ the rules. The fields are as follows:
> qualified name of the DWARF Debugging Information Entry (DIE).
> - `value`: Provides rule-specific data.
>
> -The following helper macro, for example, can be used to specify rules
> +The following helper macros, for example, can be used to specify rules
> in the source code::
>
> - #define __KABI_RULE(hint, target, value) \
> - static const char __PASTE(__gendwarfksyms_rule_, \
> + #define ___KABI_RULE(hint, target, value) \
> + static const char __PASTE(__gendwarfksyms_rule_, \
> __COUNTER__)[] __used __aligned(1) \
> __section(".discard.gendwarfksyms.kabi_rules") = \
> - "1\0" #hint "\0" #target "\0" #value
> + "1\0" #hint "\0" target "\0" value
> +
> + #define __KABI_RULE(hint, target, value) \
> + ___KABI_RULE(hint, #target, #value)
>
>
> Currently, only the rules discussed in this section are supported, but
> @@ -223,7 +226,88 @@ Example usage::
> KABI_ENUMERATOR_IGNORE(e, C);
> KABI_ENUMERATOR_VALUE(e, LAST, 2);
>
> -4.3. Adding structure members
> +4.1.3. Managing structure size changes
> +======================================
> +
> +A data structure can be partially opaque to modules if its allocation is
> +handled by the core kernel, and modules only need to access some of its
> +members. In this situation, it's possible to append new members to the
> +structure without breaking the ABI, as long as the layout for the original
> +members remains unchanged.
> +
> +To append new members, we can hide them from symbol versioning as
> +described in section :ref:`Hiding members <hiding_members>`, but we can't
> +hide the increase in structure size. The `byte_size` rule allows us to
> +override the structure size used for symbol versioning.
> +
> +The rule fields are expected to be as follows:
> +
> +- `type`: "byte_size"
> +- `target`: The fully qualified name of the target data structure
> + (as shown in **--dump-dies** output).
> +- `value`: A positive decimal number indicating the structure size
> + in bytes.
> +
> +Using the `__KABI_RULE` macro, this rule can be defined as::
> +
> + #define KABI_BYTE_SIZE(fqn, value) \
> + __KABI_RULE(byte_size, fqn, value)
> +
> +Example usage::
> +
> + struct s {
> + /* Unchanged original members */
> + unsigned long a;
> + void *p;
> +
> + /* Appended new members */
> + KABI_IGNORE(0, unsigned long n);
> + };
> +
> + KABI_BYTE_SIZE(s, 16);
> +
> +4.1.4. Overriding type strings
> +==============================
> +
> +In rare situations where distributions must make significant changes to
> +otherwise opaque data structures that have inadvertently been included
> +in the published ABI, keeping symbol versions stable using the more
> +targeted kABI rules can become tedious. The `type_string` rule allows us
> +to override the full type string for a type or a symbol, and even add
> +types for versioning that no longer exist in the kernel.
> +
> +The rule fields are expected to be as follows:
> +
> +- `type`: "type_string"
> +- `target`: The fully qualified name of the target data structure
> + (as shown in **--dump-dies** output) or symbol.
> +- `value`: A valid type string (as shown in **--symtypes**) output)
> + to use instead of the real type.
> +
> +Using the `__KABI_RULE` macro, this rule can be defined as::
> +
> + #define KABI_TYPE_STRING(type, str) \
> + ___KABI_RULE("type_string", type, str)
> +
> +Example usage::
> +
> + /* Override type for a structure */
> + KABI_TYPE_STRING("s#s",
> + "structure_type s { "
> + "member base_type int byte_size(4) "
> + "encoding(5) n "
> + "data_member_location(0) "
> + "} byte_size(8)");
> +
> + /* Override type for a symbol */
> + KABI_TYPE_STRING("my_symbol", "variable s#s");
> +
> +The `type_string` rule should be used only as a last resort if maintaining
> +a stable symbol versions cannot be reasonably achieved using other
> +means. Overriding a type string increases the risk of actual ABI breakages
> +going unnoticed as it hides all changes to the type.
> +
> +4.2. Adding structure members
> =============================
>
> Perhaps the most common ABI compatible change is adding a member to a
> @@ -237,7 +321,7 @@ natural method. This section describes gendwarfksyms support for using
> reserved space in data structures and hiding members that don't change
> the ABI when calculating symbol versions.
>
> -4.3.1. Reserving space and replacing members
> +4.2.1. Reserving space and replacing members
> ============================================
Hmm, renumbering is annoying.
Maybe, better to stop managing section numbers?
For example, see this commit
1a4c1c9df72ec266f94631edc59f9f2a9dc5aa8c
--
Best Regards
Masahiro Yamada
