Message-ID: <CAK7LNAS0Obe-ye1ba06EfZ+mgmc6ter+xMa+mKCw6aRM14L35Q@mail.gmail.com>
Date: Wed, 7 May 2025 21:27:46 +0900
From: Masahiro Yamada <masahiroy@...nel.org>
To: Sami Tolvanen <samitolvanen@...gle.com>
Cc: Luis Chamberlain <mcgrof@...nel.org>, Petr Pavlu <petr.pavlu@...e.com>, 
	Daniel Gomez <da.gomez@...sung.com>, linux-modules@...r.kernel.org, 
	linux-kbuild@...r.kernel.org, linux-kernel@...r.kernel.org
Subject: Re: [PATCH v2 4/4] Documentation/kbuild: Add new gendwarfksyms kABI rules

On Tue, May 6, 2025 at 6:24 AM Sami Tolvanen <samitolvanen@...gle.com> 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@...gle.com>
> ---
>  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

Powered by blists - more mailing lists