Document byte_size and type_string kABI stability rules. Also fix
the section numbers while we're at it.
Signed-off-by: Sami Tolvanen <samitolva...@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.906.g1f30a19c02-goog
