Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
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>
authored by
Sami Tolvanen
and committed by
Masahiro Yamada
cf9d6926
881bf900
+92
-5
+92
-5
Documentation/kbuild/gendwarfksyms.rst
+92
-5
Documentation/kbuild/gendwarfksyms.rst
···
125
125
qualified name of the DWARF Debugging Information Entry (DIE).
126
126
- `value`: Provides rule-specific data.
127
127
128
-
The following helper macro, for example, can be used to specify rules
128
+
The following helper macros, for example, can be used to specify rules
129
129
in the source code::
130
130
131
-
#define __KABI_RULE(hint, target, value) \
132
-
static const char __PASTE(__gendwarfksyms_rule_, \
131
+
#define ___KABI_RULE(hint, target, value) \
132
+
static const char __PASTE(__gendwarfksyms_rule_, \
133
133
__COUNTER__)[] __used __aligned(1) \
134
134
__section(".discard.gendwarfksyms.kabi_rules") = \
135
-
"1\0" #hint "\0" #target "\0" #value
135
+
"1\0" #hint "\0" target "\0" value
136
+
137
+
#define __KABI_RULE(hint, target, value) \
138
+
___KABI_RULE(hint, #target, #value)
136
139
137
140
138
141
Currently, only the rules discussed in this section are supported, but
···
226
223
KABI_ENUMERATOR_IGNORE(e, C);
227
224
KABI_ENUMERATOR_VALUE(e, LAST, 2);
228
225
226
+
Managing structure size changes
227
+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
228
+
229
+
A data structure can be partially opaque to modules if its allocation is
230
+
handled by the core kernel, and modules only need to access some of its
231
+
members. In this situation, it's possible to append new members to the
232
+
structure without breaking the ABI, as long as the layout for the original
233
+
members remains unchanged.
234
+
235
+
To append new members, we can hide them from symbol versioning as
236
+
described in section :ref:`Hiding members <hiding_members>`, but we can't
237
+
hide the increase in structure size. The `byte_size` rule allows us to
238
+
override the structure size used for symbol versioning.
239
+
240
+
The rule fields are expected to be as follows:
241
+
242
+
- `type`: "byte_size"
243
+
- `target`: The fully qualified name of the target data structure
244
+
(as shown in **--dump-dies** output).
245
+
- `value`: A positive decimal number indicating the structure size
246
+
in bytes.
247
+
248
+
Using the `__KABI_RULE` macro, this rule can be defined as::
249
+
250
+
#define KABI_BYTE_SIZE(fqn, value) \
251
+
__KABI_RULE(byte_size, fqn, value)
252
+
253
+
Example usage::
254
+
255
+
struct s {
256
+
/* Unchanged original members */
257
+
unsigned long a;
258
+
void *p;
259
+
260
+
/* Appended new members */
261
+
KABI_IGNORE(0, unsigned long n);
262
+
};
263
+
264
+
KABI_BYTE_SIZE(s, 16);
265
+
266
+
Overriding type strings
267
+
~~~~~~~~~~~~~~~~~~~~~~~
268
+
269
+
In rare situations where distributions must make significant changes to
270
+
otherwise opaque data structures that have inadvertently been included
271
+
in the published ABI, keeping symbol versions stable using the more
272
+
targeted kABI rules can become tedious. The `type_string` rule allows us
273
+
to override the full type string for a type or a symbol, and even add
274
+
types for versioning that no longer exist in the kernel.
275
+
276
+
The rule fields are expected to be as follows:
277
+
278
+
- `type`: "type_string"
279
+
- `target`: The fully qualified name of the target data structure
280
+
(as shown in **--dump-dies** output) or symbol.
281
+
- `value`: A valid type string (as shown in **--symtypes**) output)
282
+
to use instead of the real type.
283
+
284
+
Using the `__KABI_RULE` macro, this rule can be defined as::
285
+
286
+
#define KABI_TYPE_STRING(type, str) \
287
+
___KABI_RULE("type_string", type, str)
288
+
289
+
Example usage::
290
+
291
+
/* Override type for a structure */
292
+
KABI_TYPE_STRING("s#s",
293
+
"structure_type s { "
294
+
"member base_type int byte_size(4) "
295
+
"encoding(5) n "
296
+
"data_member_location(0) "
297
+
"} byte_size(8)");
298
+
299
+
/* Override type for a symbol */
300
+
KABI_TYPE_STRING("my_symbol", "variable s#s");
301
+
302
+
The `type_string` rule should be used only as a last resort if maintaining
303
+
a stable symbol versions cannot be reasonably achieved using other
304
+
means. Overriding a type string increases the risk of actual ABI breakages
305
+
going unnoticed as it hides all changes to the type.
306
+
229
307
Adding structure members
230
308
------------------------
231
309
···
360
276
simplify the process and also ensure the replacement member is correctly
361
277
aligned and its size won't exceed the reserved space.
362
278
279
+
.. _hiding_members:
280
+
363
281
Hiding members
364
282
~~~~~~~~~~~~~~
365
283
···
391
305
unsigned long b;
392
306
};
393
307
394
-
With **--stable**, both versions produce the same symbol version.
308
+
With **--stable**, both versions produce the same symbol version. The
309
+
examples include a `KABI_IGNORE` macro to simplify the code.