Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
Documentation/kbuild: Drop section numbers
Change the gendwarfksyms documentation to use proper chapter,
section, and subsection adornments instead of fragile section
numbers.
Suggested-by: Masahiro Yamada <masahiroy@kernel.org>
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
881bf900
c9083467
+22
-22
+22
-22
Documentation/kbuild/gendwarfksyms.rst
+22
-22
Documentation/kbuild/gendwarfksyms.rst
···
2
2
DWARF module versioning
3
3
=======================
4
4
5
-
1. Introduction
6
-
===============
5
+
Introduction
6
+
============
7
7
8
8
When CONFIG_MODVERSIONS is enabled, symbol versions for modules
9
9
are typically calculated from preprocessed source code using the
···
14
14
from the DWARF debugging information, which contains the necessary
15
15
details about the final module ABI.
16
16
17
-
1.1. Usage
18
-
==========
17
+
Usage
18
+
-----
19
19
20
20
gendwarfksyms accepts a list of object files on the command line, and a
21
21
list of symbol names (one per line) in standard input::
···
33
33
-h, --help Print this message
34
34
35
35
36
-
2. Type information availability
37
-
================================
36
+
Type information availability
37
+
=============================
38
38
39
39
While symbols are typically exported in the same translation unit (TU)
40
40
where they're defined, it's also perfectly fine for a TU to export
···
56
56
elsewhere. The name of the symbol pointer is expected to start with
57
57
`__gendwarfksyms_ptr_`, followed by the name of the exported symbol.
58
58
59
-
3. Symtypes output format
60
-
=========================
59
+
Symtypes output format
60
+
======================
61
61
62
62
Similarly to genksyms, gendwarfksyms supports writing a symtypes
63
63
file for each processed object that contain types for exported
···
85
85
DWARF format produced by **--dump-dies**, but with type references
86
86
instead of fully expanded strings.
87
87
88
-
4. Maintaining a stable kABI
89
-
============================
88
+
Maintaining a stable kABI
89
+
=========================
90
90
91
91
Distribution maintainers often need the ability to make ABI compatible
92
92
changes to kernel data structures due to LTS updates or backports. Using
···
104
104
transform the inputs for symbol versioning, the user is responsible for
105
105
ensuring that their changes actually won't break the ABI.
106
106
107
-
4.1. kABI rules
108
-
===============
107
+
kABI rules
108
+
----------
109
109
110
110
kABI rules allow distributions to fine-tune certain parts
111
111
of gendwarfksyms output and thus control how symbol
···
139
139
the format is extensible enough to allow further rules to be added as
140
140
need arises.
141
141
142
-
4.1.1. Managing definition visibility
143
-
=====================================
142
+
Managing definition visibility
143
+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
144
144
145
145
A declaration can change into a full definition when additional includes
146
146
are pulled into the translation unit. This changes the versions of any
···
168
168
169
169
KABI_DECLONLY(s);
170
170
171
-
4.1.2. Adding enumerators
172
-
=========================
171
+
Adding enumerators
172
+
~~~~~~~~~~~~~~~~~~
173
173
174
174
For enums, all enumerators and their values are included in calculating
175
175
symbol versions, which becomes a problem if we later need to add more
···
223
223
KABI_ENUMERATOR_IGNORE(e, C);
224
224
KABI_ENUMERATOR_VALUE(e, LAST, 2);
225
225
226
-
4.3. Adding structure members
227
-
=============================
226
+
Adding structure members
227
+
------------------------
228
228
229
229
Perhaps the most common ABI compatible change is adding a member to a
230
230
kernel data structure. When changes to a structure are anticipated,
···
237
237
reserved space in data structures and hiding members that don't change
238
238
the ABI when calculating symbol versions.
239
239
240
-
4.3.1. Reserving space and replacing members
241
-
============================================
240
+
Reserving space and replacing members
241
+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
242
242
243
243
Space is typically reserved for later use by appending integer types, or
244
244
arrays, to the end of the data structure, but any type can be used. Each
···
276
276
simplify the process and also ensure the replacement member is correctly
277
277
aligned and its size won't exceed the reserved space.
278
278
279
-
4.3.2. Hiding members
280
-
=====================
279
+
Hiding members
280
+
~~~~~~~~~~~~~~
281
281
282
282
Predicting which structures will require changes during the support
283
283
timeframe isn't always possible, in which case one might have to resort