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@google.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
============================================
Space is typically reserved for later use by appending integer types, or
@@ -276,7 +360,9 @@ The examples include `KABI_(RESERVE|USE|REPLACE)*` macros that help
simplify the process and also ensure the replacement member is correctly
aligned and its size won't exceed the reserved space.
-4.3.2. Hiding members
+.. _hiding_members:
+
+4.2.2. Hiding members
=====================
Predicting which structures will require changes during the support
@@ -305,4 +391,5 @@ member to a union where one of the fields has a name starting with
unsigned long b;
};
-With **--stable**, both versions produce the same symbol version.
+With **--stable**, both versions produce the same symbol version. The
+examples include a `KABI_IGNORE` macro to simplify the code.
--
2.49.0.967.g6a0df3ecc3-googOn Tue, May 6, 2025 at 6:24 AM Sami Tolvanen <samitolvanen@google.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@google.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
Hi Masahiro, On Wed, May 7, 2025 at 12:28 PM Masahiro Yamada <masahiroy@kernel.org> wrote: > > Hmm, renumbering is annoying. > > Maybe, better to stop managing section numbers? > > For example, see this commit > 1a4c1c9df72ec266f94631edc59f9f2a9dc5aa8c Agreed, that looks much better. I'll send v3 that drops the section numbers. Sami
© 2016 - 2025 Red Hat, Inc.