Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
Documentation/kbuild: gendwarfksyms: Style cleanup
The indentation in gendwarfksyms.rst currently uses a mix of tabs and
spaces. Convert all indentation to tabs, and match the usage output and
code examples with theirs references.
Suggested-by: Miguel Ojeda <ojeda@kernel.org>
Signed-off-by: Jihan LIN <linjh22s@gmail.com>
Reviewed-by: Petr Pavlu <petr.pavlu@suse.com>
Link: https://patch.msgid.link/20260114-documents_gendwarfksyms-v2-2-297c98bd62c6@gmail.com
[nathan: Minor commit message formatting adjustment]
Signed-off-by: Nathan Chancellor <nathan@kernel.org>
authored by
Jihan LIN
and committed by
Nathan Chancellor
301a02d4
983233ac
+50
-50
+50
-50
Documentation/kbuild/gendwarfksyms.rst
+50
-50
Documentation/kbuild/gendwarfksyms.rst
···
43
43
gendwarfksyms accepts a list of object files on the command line, and a
44
44
list of symbol names (one per line) in standard input::
45
45
46
-
Usage: gendwarfksyms [options] elf-object-file ... < symbol-list
46
+
Usage: gendwarfksyms [options] elf-object-file ... < symbol-list
47
47
48
-
Options:
49
-
-d, --debug Print debugging information
50
-
--dump-dies Dump DWARF DIE contents
51
-
--dump-die-map Print debugging information about die_map changes
52
-
--dump-types Dump type strings
53
-
--dump-versions Dump expanded type strings used for symbol versions
54
-
-s, --stable Support kABI stability features
55
-
-T, --symtypes file Write a symtypes file
56
-
-h, --help Print this message
48
+
Options:
49
+
-d, --debug Print debugging information
50
+
--dump-dies Dump DWARF DIE contents
51
+
--dump-die-map Print debugging information about die_map changes
52
+
--dump-types Dump type strings
53
+
--dump-versions Dump expanded type strings used for symbol versions
54
+
-s, --stable Support kABI stability features
55
+
-T, --symtypes file Write a symtypes file
56
+
-h, --help Print this message
57
57
58
58
59
59
Type information availability
···
69
69
to exported symbols in the `EXPORT_SYMBOL()` macro using the following
70
70
macro::
71
71
72
-
#define __GENDWARFKSYMS_EXPORT(sym) \
73
-
static typeof(sym) *__gendwarfksyms_ptr_##sym __used \
74
-
__section(".discard.gendwarfksyms") = &sym;
72
+
#define __GENDWARFKSYMS_EXPORT(sym) \
73
+
static typeof(sym) *__gendwarfksyms_ptr_##sym __used \
74
+
__section(".discard.gendwarfksyms") = &sym;
75
75
76
76
77
77
When a symbol pointer is found in DWARF, gendwarfksyms can use its
···
94
94
one-letter prefix followed by "#" and the name of the type. Four
95
95
reference types are supported::
96
96
97
-
e#<type> = enum
98
-
s#<type> = struct
99
-
t#<type> = typedef
100
-
u#<type> = union
97
+
e#<type> = enum
98
+
s#<type> = struct
99
+
t#<type> = typedef
100
+
u#<type> = union
101
101
102
102
Type names with spaces in them are wrapped in single quotes, e.g.::
103
103
104
-
s#'core::result::Result<u8, core::num::error::ParseIntError>'
104
+
s#'core::result::Result<u8, core::num::error::ParseIntError>'
105
105
106
106
The rest of the line contains a type string. Unlike with genksyms that
107
107
produces C-style type strings, gendwarfksyms uses the same simple parsed
···
151
151
The following helper macros, for example, can be used to specify rules
152
152
in the source code::
153
153
154
-
#define ___KABI_RULE(hint, target, value) \
155
-
static const char __PASTE(__gendwarfksyms_rule_, \
154
+
#define ___KABI_RULE(hint, target, value) \
155
+
static const char __PASTE(__gendwarfksyms_rule_, \
156
156
__COUNTER__)[] __used __aligned(1) \
157
157
__section(".discard.gendwarfksyms.kabi_rules") = \
158
158
"1\0" #hint "\0" target "\0" value
···
273
273
274
274
Using the `__KABI_RULE` macro, this rule can be defined as::
275
275
276
-
#define KABI_BYTE_SIZE(fqn, value) \
277
-
__KABI_RULE(byte_size, fqn, value)
276
+
#define KABI_BYTE_SIZE(fqn, value) \
277
+
__KABI_RULE(byte_size, fqn, value)
278
278
279
279
Example usage::
280
280
281
281
struct s {
282
-
/* Unchanged original members */
282
+
/* Unchanged original members */
283
283
unsigned long a;
284
-
void *p;
284
+
void *p;
285
285
286
-
/* Appended new members */
287
-
KABI_IGNORE(0, unsigned long n);
286
+
/* Appended new members */
287
+
KABI_IGNORE(0, unsigned long n);
288
288
};
289
289
290
290
KABI_BYTE_SIZE(s, 16);
···
353
353
not known at the time the space is reserved, for convenience, names that
354
354
start with `__kabi_` are left out when calculating symbol versions::
355
355
356
-
struct s {
357
-
long a;
358
-
long __kabi_reserved_0; /* reserved for future use */
359
-
};
356
+
struct s {
357
+
long a;
358
+
long __kabi_reserved_0; /* reserved for future use */
359
+
};
360
360
361
361
The reserved space can be taken into use by wrapping the member in a
362
362
union, which includes the original type and the replacement member::
363
363
364
-
struct s {
365
-
long a;
366
-
union {
367
-
long __kabi_reserved_0; /* original type */
368
-
struct b b; /* replaced field */
369
-
};
370
-
};
364
+
struct s {
365
+
long a;
366
+
union {
367
+
long __kabi_reserved_0; /* original type */
368
+
struct b b; /* replaced field */
369
+
};
370
+
};
371
371
372
372
If the `__kabi_` naming scheme was used when reserving space, the name
373
373
of the first member of the union must start with `__kabi_reserved`. This
···
392
392
timeframe isn't always possible, in which case one might have to resort
393
393
to placing new members into existing alignment holes::
394
394
395
-
struct s {
396
-
int a;
397
-
/* a 4-byte alignment hole */
398
-
unsigned long b;
399
-
};
395
+
struct s {
396
+
int a;
397
+
/* a 4-byte alignment hole */
398
+
unsigned long b;
399
+
};
400
400
401
401
402
402
While this won't change the size of the data structure, one needs to
···
405
405
member to a union where one of the fields has a name starting with
406
406
`__kabi_ignored`::
407
407
408
-
struct s {
409
-
int a;
410
-
union {
411
-
char __kabi_ignored_0;
412
-
int n;
413
-
};
414
-
unsigned long b;
415
-
};
408
+
struct s {
409
+
int a;
410
+
union {
411
+
char __kabi_ignored_0;
412
+
int n;
413
+
};
414
+
unsigned long b;
415
+
};
416
416
417
417
With **--stable**, both versions produce the same symbol version. The
418
418
examples include a `KABI_IGNORE` macro to simplify the code.