Linux kernel mirror (for testing) git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel os linux
1
fork

Configure Feed

Select the types of activity you want to include in your feed.

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
··· 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