1======================= 2DWARF module versioning 3======================= 4 5Introduction 6============ 7 8When CONFIG_MODVERSIONS is enabled, symbol versions for modules 9are typically calculated from preprocessed source code using the 10**genksyms** tool. However, this is incompatible with languages such 11as Rust, where the source code has insufficient information about 12the resulting ABI. With CONFIG_GENDWARFKSYMS (and CONFIG_DEBUG_INFO) 13selected, **gendwarfksyms** is used instead to calculate symbol versions 14from the DWARF debugging information, which contains the necessary 15details about the final module ABI. 16 17Usage 18----- 19 20gendwarfksyms accepts a list of object files on the command line, and a 21list of symbol names (one per line) in standard input:: 22 23 Usage: gendwarfksyms [options] elf-object-file ... < symbol-list 24 25 Options: 26 -d, --debug Print debugging information 27 --dump-dies Dump DWARF DIE contents 28 --dump-die-map Print debugging information about die_map changes 29 --dump-types Dump type strings 30 --dump-versions Dump expanded type strings used for symbol versions 31 -s, --stable Support kABI stability features 32 -T, --symtypes file Write a symtypes file 33 -h, --help Print this message 34 35 36Type information availability 37============================= 38 39While symbols are typically exported in the same translation unit (TU) 40where they're defined, it's also perfectly fine for a TU to export 41external symbols. For example, this is done when calculating symbol 42versions for exports in stand-alone assembly code. 43 44To ensure the compiler emits the necessary DWARF type information in the 45TU where symbols are actually exported, gendwarfksyms adds a pointer 46to exported symbols in the `EXPORT_SYMBOL()` macro using the following 47macro:: 48 49 #define __GENDWARFKSYMS_EXPORT(sym) \ 50 static typeof(sym) *__gendwarfksyms_ptr_##sym __used \ 51 __section(".discard.gendwarfksyms") = &sym; 52 53 54When a symbol pointer is found in DWARF, gendwarfksyms can use its 55type for calculating symbol versions even if the symbol is defined 56elsewhere. The name of the symbol pointer is expected to start with 57`__gendwarfksyms_ptr_`, followed by the name of the exported symbol. 58 59Symtypes output format 60====================== 61 62Similarly to genksyms, gendwarfksyms supports writing a symtypes 63file for each processed object that contain types for exported 64symbols and each referenced type that was used in calculating symbol 65versions. These files can be useful when trying to determine what 66exactly caused symbol versions to change between builds. To generate 67symtypes files during a kernel build, set `KBUILD_SYMTYPES=1`. 68 69Matching the existing format, the first column of each line contains 70either a type reference or a symbol name. Type references have a 71one-letter prefix followed by "#" and the name of the type. Four 72reference types are supported:: 73 74 e#<type> = enum 75 s#<type> = struct 76 t#<type> = typedef 77 u#<type> = union 78 79Type names with spaces in them are wrapped in single quotes, e.g.:: 80 81 s#'core::result::Result<u8, core::num::error::ParseIntError>' 82 83The rest of the line contains a type string. Unlike with genksyms that 84produces C-style type strings, gendwarfksyms uses the same simple parsed 85DWARF format produced by **--dump-dies**, but with type references 86instead of fully expanded strings. 87 88Maintaining a stable kABI 89========================= 90 91Distribution maintainers often need the ability to make ABI compatible 92changes to kernel data structures due to LTS updates or backports. Using 93the traditional `#ifndef __GENKSYMS__` to hide these changes from symbol 94versioning won't work when processing object files. To support this 95use case, gendwarfksyms provides kABI stability features designed to 96hide changes that won't affect the ABI when calculating versions. These 97features are all gated behind the **--stable** command line flag and are 98not used in the mainline kernel. To use stable features during a kernel 99build, set `KBUILD_GENDWARFKSYMS_STABLE=1`. 100 101Examples for using these features are provided in the 102**scripts/gendwarfksyms/examples** directory, including helper macros 103for source code annotation. Note that as these features are only used to 104transform the inputs for symbol versioning, the user is responsible for 105ensuring that their changes actually won't break the ABI. 106 107kABI rules 108---------- 109 110kABI rules allow distributions to fine-tune certain parts 111of gendwarfksyms output and thus control how symbol 112versions are calculated. These rules are defined in the 113`.discard.gendwarfksyms.kabi_rules` section of the object file and 114consist of simple null-terminated strings with the following structure:: 115 116 version\0type\0target\0value\0 117 118This string sequence is repeated as many times as needed to express all 119the rules. The fields are as follows: 120 121- `version`: Ensures backward compatibility for future changes to the 122 structure. Currently expected to be "1". 123- `type`: Indicates the type of rule being applied. 124- `target`: Specifies the target of the rule, typically the fully 125 qualified name of the DWARF Debugging Information Entry (DIE). 126- `value`: Provides rule-specific data. 127 128The following helper macros, for example, can be used to specify rules 129in the source code:: 130 131 #define ___KABI_RULE(hint, target, value) \ 132 static const char __PASTE(__gendwarfksyms_rule_, \ 133 __COUNTER__)[] __used __aligned(1) \ 134 __section(".discard.gendwarfksyms.kabi_rules") = \ 135 "1\0" #hint "\0" target "\0" value 136 137 #define __KABI_RULE(hint, target, value) \ 138 ___KABI_RULE(hint, #target, #value) 139 140 141Currently, only the rules discussed in this section are supported, but 142the format is extensible enough to allow further rules to be added as 143need arises. 144 145Managing definition visibility 146~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 147 148A declaration can change into a full definition when additional includes 149are pulled into the translation unit. This changes the versions of any 150symbol that references the type even if the ABI remains unchanged. As 151it may not be possible to drop includes without breaking the build, the 152`declonly` rule can be used to specify a type as declaration-only, even 153if the debugging information contains the full definition. 154 155The rule fields are expected to be as follows: 156 157- `type`: "declonly" 158- `target`: The fully qualified name of the target data structure 159 (as shown in **--dump-dies** output). 160- `value`: This field is ignored. 161 162Using the `__KABI_RULE` macro, this rule can be defined as:: 163 164 #define KABI_DECLONLY(fqn) __KABI_RULE(declonly, fqn, ) 165 166Example usage:: 167 168 struct s { 169 /* definition */ 170 }; 171 172 KABI_DECLONLY(s); 173 174Adding enumerators 175~~~~~~~~~~~~~~~~~~ 176 177For enums, all enumerators and their values are included in calculating 178symbol versions, which becomes a problem if we later need to add more 179enumerators without changing symbol versions. The `enumerator_ignore` 180rule allows us to hide named enumerators from the input. 181 182The rule fields are expected to be as follows: 183 184- `type`: "enumerator_ignore" 185- `target`: The fully qualified name of the target enum 186 (as shown in **--dump-dies** output) and the name of the 187 enumerator field separated by a space. 188- `value`: This field is ignored. 189 190Using the `__KABI_RULE` macro, this rule can be defined as:: 191 192 #define KABI_ENUMERATOR_IGNORE(fqn, field) \ 193 __KABI_RULE(enumerator_ignore, fqn field, ) 194 195Example usage:: 196 197 enum e { 198 A, B, C, D, 199 }; 200 201 KABI_ENUMERATOR_IGNORE(e, B); 202 KABI_ENUMERATOR_IGNORE(e, C); 203 204If the enum additionally includes an end marker and new values must 205be added in the middle, we may need to use the old value for the last 206enumerator when calculating versions. The `enumerator_value` rule allows 207us to override the value of an enumerator for version calculation: 208 209- `type`: "enumerator_value" 210- `target`: The fully qualified name of the target enum 211 (as shown in **--dump-dies** output) and the name of the 212 enumerator field separated by a space. 213- `value`: Integer value used for the field. 214 215Using the `__KABI_RULE` macro, this rule can be defined as:: 216 217 #define KABI_ENUMERATOR_VALUE(fqn, field, value) \ 218 __KABI_RULE(enumerator_value, fqn field, value) 219 220Example usage:: 221 222 enum e { 223 A, B, C, LAST, 224 }; 225 226 KABI_ENUMERATOR_IGNORE(e, C); 227 KABI_ENUMERATOR_VALUE(e, LAST, 2); 228 229Managing structure size changes 230~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 231 232A data structure can be partially opaque to modules if its allocation is 233handled by the core kernel, and modules only need to access some of its 234members. In this situation, it's possible to append new members to the 235structure without breaking the ABI, as long as the layout for the original 236members remains unchanged. 237 238To append new members, we can hide them from symbol versioning as 239described in section :ref:`Hiding members <hiding_members>`, but we can't 240hide the increase in structure size. The `byte_size` rule allows us to 241override the structure size used for symbol versioning. 242 243The rule fields are expected to be as follows: 244 245- `type`: "byte_size" 246- `target`: The fully qualified name of the target data structure 247 (as shown in **--dump-dies** output). 248- `value`: A positive decimal number indicating the structure size 249 in bytes. 250 251Using the `__KABI_RULE` macro, this rule can be defined as:: 252 253 #define KABI_BYTE_SIZE(fqn, value) \ 254 __KABI_RULE(byte_size, fqn, value) 255 256Example usage:: 257 258 struct s { 259 /* Unchanged original members */ 260 unsigned long a; 261 void *p; 262 263 /* Appended new members */ 264 KABI_IGNORE(0, unsigned long n); 265 }; 266 267 KABI_BYTE_SIZE(s, 16); 268 269Overriding type strings 270~~~~~~~~~~~~~~~~~~~~~~~ 271 272In rare situations where distributions must make significant changes to 273otherwise opaque data structures that have inadvertently been included 274in the published ABI, keeping symbol versions stable using the more 275targeted kABI rules can become tedious. The `type_string` rule allows us 276to override the full type string for a type or a symbol, and even add 277types for versioning that no longer exist in the kernel. 278 279The rule fields are expected to be as follows: 280 281- `type`: "type_string" 282- `target`: The fully qualified name of the target data structure 283 (as shown in **--dump-dies** output) or symbol. 284- `value`: A valid type string (as shown in **--symtypes**) output) 285 to use instead of the real type. 286 287Using the `__KABI_RULE` macro, this rule can be defined as:: 288 289 #define KABI_TYPE_STRING(type, str) \ 290 ___KABI_RULE("type_string", type, str) 291 292Example usage:: 293 294 /* Override type for a structure */ 295 KABI_TYPE_STRING("s#s", 296 "structure_type s { " 297 "member base_type int byte_size(4) " 298 "encoding(5) n " 299 "data_member_location(0) " 300 "} byte_size(8)"); 301 302 /* Override type for a symbol */ 303 KABI_TYPE_STRING("my_symbol", "variable s#s"); 304 305The `type_string` rule should be used only as a last resort if maintaining 306a stable symbol versions cannot be reasonably achieved using other 307means. Overriding a type string increases the risk of actual ABI breakages 308going unnoticed as it hides all changes to the type. 309 310Adding structure members 311------------------------ 312 313Perhaps the most common ABI compatible change is adding a member to a 314kernel data structure. When changes to a structure are anticipated, 315distribution maintainers can pre-emptively reserve space in the 316structure and take it into use later without breaking the ABI. If 317changes are needed to data structures without reserved space, existing 318alignment holes can potentially be used instead. While kABI rules could 319be added for these type of changes, using unions is typically a more 320natural method. This section describes gendwarfksyms support for using 321reserved space in data structures and hiding members that don't change 322the ABI when calculating symbol versions. 323 324Reserving space and replacing members 325~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 326 327Space is typically reserved for later use by appending integer types, or 328arrays, to the end of the data structure, but any type can be used. Each 329reserved member needs a unique name, but as the actual purpose is usually 330not known at the time the space is reserved, for convenience, names that 331start with `__kabi_` are left out when calculating symbol versions:: 332 333 struct s { 334 long a; 335 long __kabi_reserved_0; /* reserved for future use */ 336 }; 337 338The reserved space can be taken into use by wrapping the member in a 339union, which includes the original type and the replacement member:: 340 341 struct s { 342 long a; 343 union { 344 long __kabi_reserved_0; /* original type */ 345 struct b b; /* replaced field */ 346 }; 347 }; 348 349If the `__kabi_` naming scheme was used when reserving space, the name 350of the first member of the union must start with `__kabi_reserved`. This 351ensures the original type is used when calculating versions, but the name 352is again left out. The rest of the union is ignored. 353 354If we're replacing a member that doesn't follow this naming convention, 355we also need to preserve the original name to avoid changing versions, 356which we can do by changing the first union member's name to start with 357`__kabi_renamed` followed by the original name. 358 359The examples include `KABI_(RESERVE|USE|REPLACE)*` macros that help 360simplify the process and also ensure the replacement member is correctly 361aligned and its size won't exceed the reserved space. 362 363.. _hiding_members: 364 365Hiding members 366~~~~~~~~~~~~~~ 367 368Predicting which structures will require changes during the support 369timeframe isn't always possible, in which case one might have to resort 370to placing new members into existing alignment holes:: 371 372 struct s { 373 int a; 374 /* a 4-byte alignment hole */ 375 unsigned long b; 376 }; 377 378 379While this won't change the size of the data structure, one needs to 380be able to hide the added members from symbol versioning. Similarly 381to reserved fields, this can be accomplished by wrapping the added 382member to a union where one of the fields has a name starting with 383`__kabi_ignored`:: 384 385 struct s { 386 int a; 387 union { 388 char __kabi_ignored_0; 389 int n; 390 }; 391 unsigned long b; 392 }; 393 394With **--stable**, both versions produce the same symbol version. The 395examples include a `KABI_IGNORE` macro to simplify the code. 396