9sphinx.addnodesdocument)}( rawsourcechildren]( translations LanguagesNode)}(hhh](h pending_xref)}(hhh]docutils.nodesTextChinese (Simplified)}parenthsba attributes}(ids]classes]names]dupnames]backrefs] refdomainstdreftypedoc reftarget(/translations/zh_CN/kbuild/gendwarfksymsmodnameN classnameN refexplicitutagnamehhh ubh)}(hhh]hChinese (Traditional)}hh2sbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget(/translations/zh_TW/kbuild/gendwarfksymsmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hItalian}hhFsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget(/translations/it_IT/kbuild/gendwarfksymsmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hJapanese}hhZsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget(/translations/ja_JP/kbuild/gendwarfksymsmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hKorean}hhnsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget(/translations/ko_KR/kbuild/gendwarfksymsmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hSpanish}hhsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget(/translations/sp_SP/kbuild/gendwarfksymsmodnameN classnameN refexplicituh1hhh ubeh}(h]h ]h"]h$]h&]current_languageEnglishuh1h hh _documenthsourceNlineNubhsection)}(hhh](htitle)}(hDWARF module versioningh]hDWARF module versioning}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhhhB/var/lib/git/docbuild/linux/Documentation/kbuild/gendwarfksyms.rsthKubh)}(hhh](h)}(h1. Introductionh]h1. Introduction}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhhhhhKubh paragraph)}(hXWhen CONFIG_MODVERSIONS is enabled, symbol versions for modules are typically calculated from preprocessed source code using the **genksyms** tool. However, this is incompatible with languages such as Rust, where the source code has insufficient information about the resulting ABI. With CONFIG_GENDWARFKSYMS (and CONFIG_DEBUG_INFO) selected, **gendwarfksyms** is used instead to calculate symbol versions from the DWARF debugging information, which contains the necessary details about the final module ABI.h](hWhen CONFIG_MODVERSIONS is enabled, symbol versions for modules are typically calculated from preprocessed source code using the }(hhhhhNhNubhstrong)}(h **genksyms**h]hgenksyms}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhubh tool. However, this is incompatible with languages such as Rust, where the source code has insufficient information about the resulting ABI. With CONFIG_GENDWARFKSYMS (and CONFIG_DEBUG_INFO) selected, }(hhhhhNhNubh)}(h**gendwarfksyms**h]h gendwarfksyms}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhubh is used instead to calculate symbol versions from the DWARF debugging information, which contains the necessary details about the final module ABI.}(hhhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhhhhubeh}(h] introductionah ]h"]1. introductionah$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(h 1.1. Usageh]h 1.1. Usage}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKubh)}(hgendwarfksyms accepts a list of object files on the command line, and a list of symbol names (one per line) in standard input::h]h~gendwarfksyms accepts a list of object files on the command line, and a list of symbol names (one per line) in standard input:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh literal_block)}(hXUsage: gendwarfksyms [options] elf-object-file ... < symbol-list Options: -d, --debug Print debugging information --dump-dies Dump DWARF DIE contents --dump-die-map Print debugging information about die_map changes --dump-types Dump type strings --dump-versions Dump expanded type strings used for symbol versions -s, --stable Support kABI stability features -T, --symtypes file Write a symtypes file -h, --help Print this messageh]hXUsage: gendwarfksyms [options] elf-object-file ... < symbol-list Options: -d, --debug Print debugging information --dump-dies Dump DWARF DIE contents --dump-die-map Print debugging information about die_map changes --dump-types Dump type strings --dump-versions Dump expanded type strings used for symbol versions -s, --stable Support kABI stability features -T, --symtypes file Write a symtypes file -h, --help Print this message}hj'sbah}(h]h ]h"]h$]h&] xml:spacepreserveuh1j%hhhKhjhhubeh}(h]usageah ]h"] 1.1. usageah$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(h 2. Type information availabilityh]h 2. Type information availability}(hjBhhhNhNubah}(h]h ]h"]h$]h&]uh1hhj?hhhhhK%ubh)}(hXWhile symbols are typically exported in the same translation unit (TU) where they're defined, it's also perfectly fine for a TU to export external symbols. For example, this is done when calculating symbol versions for exports in stand-alone assembly code.h]hXWhile symbols are typically exported in the same translation unit (TU) where they’re defined, it’s also perfectly fine for a TU to export external symbols. For example, this is done when calculating symbol versions for exports in stand-alone assembly code.}(hjPhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK'hj?hhubh)}(hTo ensure the compiler emits the necessary DWARF type information in the TU where symbols are actually exported, gendwarfksyms adds a pointer to exported symbols in the `EXPORT_SYMBOL()` macro using the following macro::h](hTo ensure the compiler emits the necessary DWARF type information in the TU where symbols are actually exported, gendwarfksyms adds a pointer to exported symbols in the }(hj^hhhNhNubhtitle_reference)}(h`EXPORT_SYMBOL()`h]hEXPORT_SYMBOL()}(hjhhhhNhNubah}(h]h ]h"]h$]h&]uh1jfhj^ubh! macro using the following macro:}(hj^hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK,hj?hhubj&)}(h#define __GENDWARFKSYMS_EXPORT(sym) \ static typeof(sym) *__gendwarfksyms_ptr_##sym __used \ __section(".discard.gendwarfksyms") = &sym;h]h#define __GENDWARFKSYMS_EXPORT(sym) \ static typeof(sym) *__gendwarfksyms_ptr_##sym __used \ __section(".discard.gendwarfksyms") = &sym;}hjsbah}(h]h ]h"]h$]h&]j5j6uh1j%hhhK1hj?hhubh)}(hXWhen a symbol pointer is found in DWARF, gendwarfksyms can use its type for calculating symbol versions even if the symbol is defined elsewhere. The name of the symbol pointer is expected to start with `__gendwarfksyms_ptr_`, followed by the name of the exported symbol.h](hWhen a symbol pointer is found in DWARF, gendwarfksyms can use its type for calculating symbol versions even if the symbol is defined elsewhere. The name of the symbol pointer is expected to start with }(hjhhhNhNubjg)}(h`__gendwarfksyms_ptr_`h]h__gendwarfksyms_ptr_}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jfhjubh., followed by the name of the exported symbol.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK6hj?hhubeh}(h]type-information-availabilityah ]h"] 2. type information availabilityah$]h&]uh1hhhhhhhhK%ubh)}(hhh](h)}(h3. Symtypes output formath]h3. Symtypes output format}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKhjhhubh)}(hMatching the existing format, the first column of each line contains either a type reference or a symbol name. Type references have a one-letter prefix followed by "#" and the name of the type. Four reference types are supported::h]hMatching the existing format, the first column of each line contains either a type reference or a symbol name. Type references have a one-letter prefix followed by “#” and the name of the type. Four reference types are supported:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKEhjhhubj&)}(hEe# = enum s# = struct t# = typedef u# = unionh]hEe# = enum s# = struct t# = typedef u# = union}hjsbah}(h]h ]h"]h$]h&]j5j6uh1j%hhhKJhjhhubh)}(hCType names with spaces in them are wrapped in single quotes, e.g.::h]hBType names with spaces in them are wrapped in single quotes, e.g.:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKOhjhhubj&)}(h=s#'core::result::Result'h]h=s#'core::result::Result'}hjsbah}(h]h ]h"]h$]h&]j5j6uh1j%hhhKQhjhhubh)}(hThe rest of the line contains a type string. Unlike with genksyms that produces C-style type strings, gendwarfksyms uses the same simple parsed DWARF format produced by **--dump-dies**, but with type references instead of fully expanded strings.h](hThe rest of the line contains a type string. Unlike with genksyms that produces C-style type strings, gendwarfksyms uses the same simple parsed DWARF format produced by }(hjhhhNhNubh)}(h**--dump-dies**h]h --dump-dies}(hj'hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh=, but with type references instead of fully expanded strings.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKShjhhubeh}(h]symtypes-output-formatah ]h"]3. symtypes output formatah$]h&]uh1hhhhhhhhKubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubj)}(h~`target`: Specifies the target of the rule, typically the fully qualified name of the DWARF Debugging Information Entry (DIE).h]h)}(h~`target`: Specifies the target of the rule, typically the fully qualified name of the DWARF Debugging Information Entry (DIE).h](jg)}(h`target`h]htarget}(hjkhhhNhNubah}(h]h ]h"]h$]h&]uh1jfhjgubhv: Specifies the target of the rule, typically the fully qualified name of the DWARF Debugging Information Entry (DIE).}(hjghhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK|hjcubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubj)}(h&`value`: Provides rule-specific data. h]h)}(h%`value`: Provides rule-specific data.h](jg)}(h`value`h]hvalue}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jfhjubh: Provides rule-specific data.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK~hjubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubeh}(h]h ]h"]h$]h&]bullet-uh1jhhhKyhjhhubh)}(hZThe following helper macro, for example, can be used to specify rules in the source code::h]hYThe following helper macro, for example, can be used to specify rules in the source code:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubj&)}(hXX#define __KABI_RULE(hint, target, value) \ static const char __PASTE(__gendwarfksyms_rule_, \ __COUNTER__)[] __used __aligned(1) \ __section(".discard.gendwarfksyms.kabi_rules") = \ "1\0" #hint "\0" #target "\0" #valueh]hXX#define __KABI_RULE(hint, target, value) \ static const char __PASTE(__gendwarfksyms_rule_, \ __COUNTER__)[] __used __aligned(1) \ __section(".discard.gendwarfksyms.kabi_rules") = \ "1\0" #hint "\0" #target "\0" #value}hjsbah}(h]h ]h"]h$]h&]j5j6uh1j%hhhKhjhhubh)}(hCurrently, only the rules discussed in this section are supported, but the format is extensible enough to allow further rules to be added as need arises.h]hCurrently, only the rules discussed in this section are supported, but the format is extensible enough to allow further rules to be added as need arises.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubeh}(h] kabi-rulesah ]h"]4.1. kabi rulesah$]h&]uh1hhhhhhhhKlubh)}(hhh](h)}(h%4.1.1. Managing definition visibilityh]h%4.1.1. Managing definition visibility}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKubh)}(hXA declaration can change into a full definition when additional includes are pulled into the translation unit. This changes the versions of any symbol that references the type even if the ABI remains unchanged. As it may not be possible to drop includes without breaking the build, the `declonly` rule can be used to specify a type as declaration-only, even if the debugging information contains the full definition.h](hXA declaration can change into a full definition when additional includes are pulled into the translation unit. This changes the versions of any symbol that references the type even if the ABI remains unchanged. As it may not be possible to drop includes without breaking the build, the }(hjhhhNhNubjg)}(h `declonly`h]hdeclonly}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jfhjubhx rule can be used to specify a type as declaration-only, even if the debugging information contains the full definition.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(h.The rule fields are expected to be as follows:h]h.The rule fields are expected to be as follows:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubj)}(hhh](j)}(h`type`: "declonly"h]h)}(hj-h](jg)}(h`type`h]htype}(hj2hhhNhNubah}(h]h ]h"]h$]h&]uh1jfhj/ubh: “declonly”}(hj/hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhj+ubah}(h]h ]h"]h$]h&]uh1jhj(hhhhhNubj)}(he`target`: The fully qualified name of the target data structure (as shown in **--dump-dies** output).h]h)}(he`target`: The fully qualified name of the target data structure (as shown in **--dump-dies** output).h](jg)}(h`target`h]htarget}(hjXhhhNhNubah}(h]h ]h"]h$]h&]uh1jfhjTubhE: The fully qualified name of the target data structure (as shown in }(hjThhhNhNubh)}(h**--dump-dies**h]h --dump-dies}(hjjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjTubh output).}(hjThhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjPubah}(h]h ]h"]h$]h&]uh1jhj(hhhhhNubj)}(h `value`: This field is ignored. h]h)}(h`value`: This field is ignored.h](jg)}(h`value`h]hvalue}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jfhjubh: This field is ignored.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhj(hhhhhNubeh}(h]h ]h"]h$]h&]jjuh1jhhhKhjhhubh)}(hubah}(h]h ]h"]h$]h&]uh1jhj;hhhhhNubj)}(h`target`: The fully qualified name of the target enum (as shown in **--dump-dies** output) and the name of the enumerator field separated by a space.h]h)}(h`target`: The fully qualified name of the target enum (as shown in **--dump-dies** output) and the name of the enumerator field separated by a space.h](jg)}(h`target`h]htarget}(hjkhhhNhNubah}(h]h ]h"]h$]h&]uh1jfhjgubh;: The fully qualified name of the target enum (as shown in }(hjghhhNhNubh)}(h**--dump-dies**h]h --dump-dies}(hj}hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjgubhC output) and the name of the enumerator field separated by a space.}(hjghhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjcubah}(h]h ]h"]h$]h&]uh1jhj;hhhhhNubj)}(h+`value`: Integer value used for the field. h]h)}(h*`value`: Integer value used for the field.h](jg)}(h`value`h]hvalue}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jfhjubh#: Integer value used for the field.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhj;hhhhhNubeh}(h]h ]h"]h$]h&]jjuh1jhhhKhjhhubh)}(h