Documentation/kbuild: Add new gendwarfksyms kABI rules

Document the "byte_size" and "type_string" kABI stability rules.

Signed-off-by: Sami Tolvanen <samitolvanen@google.com>
Signed-off-by: Masahiro Yamada <masahiroy@kernel.org>

diff --git a/Documentation/kbuild/gendwarfksyms.rst b/Documentation/kbuild/gendwarfksyms.rst
index 9694ec99d190bf76f3262282312826a15af037c1..ed366250a54eac3a72c2f529da94a9e803704ae4 100644 (file)
--- 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,6 +226,87 @@ Example usage::
        KABI_ENUMERATOR_IGNORE(e, C);
        KABI_ENUMERATOR_VALUE(e, LAST, 2);
 
+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);
+
+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.
+
 Adding structure members
 ------------------------
 
@@ -276,6 +360,8 @@ 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.
 
+.. _hiding_members:
+
 Hiding members
 ~~~~~~~~~~~~~~
 
@@ -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.