1# `stg` 2 3`stg` is used to extract and process ABI representations from libabigail XML, 4BTF and ELF/DWARF. 5 6## Synopsis 7 8``` 9stg 10 [-m|--metrics] 11 [-d|--keep-duplicates] 12 [-t|--types] 13 [-F|--files|--file-filter <filter>] 14 [-S|--symbols|--symbol-filter <filter>] 15 [-a|--abi|-b|--btf|-e|--elf|-s|--stg] [file] ... 16 [{-o|--output} {filename|-}] ... 17 [-A|--annotate] 18implicit defaults: --abi 19filter syntax: 20 <filter> ::= <term> | <expression> '|' <term> 21 <term> ::= <factor> | <term> '&' <factor> 22 <factor> ::= <atom> | '!' <factor> 23 <atom> ::= ':' <filename> | <glob> | '(' <expression> ')' 24 <filename> ::= <string> 25 <glob> ::= <string> 26``` 27 28## Input 29 30The tool can be passed any number of inputs to combine into a unified ABI. 31 32### Formats 33 34* `-a|--abi` 35 36 Read ABI XML representation generated by libabigail's `abidw`. Not all ABI 37 XML features are consumed. Some XML "tidying" is performed before parsing: 38 39 * types with naming typedefs are re-anonymised 40 * (rare) duplicate data members are removed 41 * (partial and entire) duplicate type definitions are removed 42 43 After parsing, function parameter and return type qualifiers are removed. 44 45* `-b|--btf` 46 47 Read ABI information from the `.BTF` ELF section. BTF only covers the C type 48 system and can be obtained in the following ways: 49 50 * `gcc -gbtf` generates BTF instead of DWARF 51 * `clang -c -g -target bpf` works similarly, but only for BPF targets 52 * `pahole -J` reads existing DWARF debug information and adds BTF 53 54* `-e|--elf` 55 56 Read ABI information from ELF symbols and DWARF types. 57 58* `-s|--stg` 59 60 Read ABI information from a `.stg` file. 61 62### Options 63 64* `--types` 65 66 Captures all named types found in ELF files as interface types, regardless 67 of whether those types are reachable by any symbol. 68 69## Merge 70 71If multiple (or zero) inputs are provided, then ABI roots from all inputs are 72merged. 73 74### Symbols 75 76Symbols must be disjoint across all inputs. 77 78### Types 79 80If duplicate type roots are found during merge, they are unified. If unification 81fails, the merge fails. 82 83Unification is a process which replaces references to forward declarations of 84types with references to full definitions, if that would result in equal types. 85 86## Filter 87 88There are two types of filters that can be applied to STG output: 89 90* `-F|--files|--file-filter <filter>` 91 92 Filter type definitions by source location. 93 94 DWARF information includes type declaration source locations. If a struct, 95 union, class or enum is defined in a file whose name does not match the 96 filter, then its definition (layout, members etc.) is dropped, leaving only 97 a declaration. 98 99 File filters are only applicable to ELF binary objects containing DWARF with 100 source location information; any other kind of input will be unaffected. 101 102* `-S|--symbols|--symbol-filter <filter>` 103 104 Filter ELF symbols by name (which may include a `@version` or `@@version` 105 suffix). 106 107 If a symbol filter is supplied, symbols not matching the filter are dropped. 108 Symbol filtering is universal across all input formats as it happens after 109 input processing. 110 111The basic syntactical elements are: 112 113* `glob` - a **glob**(7) pattern supporting `?`, `*` and `[ ... ]` wilcards 114* `:filename` - the name of a file containing a libabigail format filter list 115 116Filter expressions can be combined with infix disjuction (`|`) and conjunction 117(`&`) operators and negated with the prefix (`!`) operator; these obey the usual 118precedence rules. Parentheses (`( ... )`) can be used to enclose subexpressions. 119Whitespace is not significant, except as a string delimiter. 120 121### Examples 122 123Symbol filters: 124 125* `jiffies |panic` - keep just the symbols `jiffies` and `panic` 126* `str*` - keep symbols beginning with `str` such as `strncpy_from_user` 127* `!(*@* & ! *@@*`) - drop versioned symbols that are not the default versions 128* `!*@*|*@@*` - the same 129* `:include & !:exclude` - keep symbols that are in the symbol list file 130 `include` but not in the symbol list file `exclude` 131 132File filters: 133 134* `!*.cc` - exclude all type definitions found in source files named `*.cc` 135* `*.h` - include only type definitions found in source files named `*.h` 136 137## Deduplication 138 139ABI representations, particularly merged ones, almost always have some sets of 140nodes that are recursively equal. By default, duplicate nodes are eliminated. 141 142* `-d|--keep-duplicates` 143 144 Skip the deduplication pass. 145 146## Output 147 148* `-o|--output` 149 150 Zero or more outputs can be requested. The filename `-` is recognised as a 151 synonym for stdout. 152 153 The output will be an ABI representation in STG's native format. 154 155## Diagnostics 156 157* `-m|--metrics` 158 159 Print various internal timing and other metrics. 160 161## Annotations 162 163* `-A|--annotate` 164 165 Output node descriptions for edges in the graph as inline textual protobuf 166 comments. 167 168 Sample STG output: 169 170 ``` 171 root_id: 0x84ea5130 # interface 172 primitive { 173 id: 0x6720d32f 174 name: "int" 175 bytesize: 0x00000004 176 } 177 struct_union { 178 id: 0xf57dfbfc 179 kind: STRUCT 180 name: "S" 181 } 182 function { 183 id: 0x85d454a8 184 return_type_id: 0x6720d32f # int 185 parameter_id: 0x6720d32f # int 186 } 187 elf_symbol { 188 id: 0x8bf70937 189 name: "func" 190 symbol_type: FUNCTION 191 type_id: 0x85d454a8 # int(int) 192 } 193 elf_symbol { 194 id: 0x3e4f6c44 195 name: "s" 196 symbol_type: OBJECT 197 type_id: 0xf57dfbfc # struct S 198 } 199 interface { 200 id: 0x84ea5130 201 symbol_id: 0x8bf70937 # int func(int) 202 symbol_id: 0x3e4f6c44 # struct S s 203 } 204 ``` 205