1# `stgdiff` 2 3`stgdiff` is used to compare ABI representations from various sources, like 4libabigail XML, BTF and ELF/DWARF. 5 6## Usage 7 8``` 9stgdiff 10 [-m|--metrics] 11 [-a|--abi|-b|--btf|-e|--elf|-s|--stg] file1 12 [-a|--abi|-b|--btf|-e|--elf|-s|--stg] file2 13 [-x|--exact] 14 [-t|--types] 15 [{-i|--ignore} <ignore-option>] ... 16 [{-f|--format} <output-format>] ... 17 [{-o|--output} {filename|-}] ... 18 [{-F|--fidelity} {filename|-}] 19implicit defaults: --abi --format plain 20--exact (node equality) cannot be combined with --output 21output formats: plain flat small short viz 22ignore options: type_declaration_status symbol_type_presence primitive_type_encoding member_size enum_underlying_type qualifier linux_symbol_crc interface_addition type_definition_addition 23``` 24 25## Input 26 27### Formats 28 29* `-a|--abi` 30 31 Read ABI XML representation generated by libabigail's `abidw`. Not all ABI 32 XML features are consumed. Some XML "tidying" is performed before parsing: 33 34 * types with naming typedefs are re-anonymised 35 * (rare) duplicate data members are removed 36 * (partial and entire) duplicate type definitions are removed 37 38 After parsing, function parameter and return type qualifiers are removed. 39 40* `-b|--btf` 41 42 Read ABI information from the `.BTF` ELF section. BTF only covers the C type 43 system and can be obtained in the following ways: 44 45 * `gcc -gbtf` generates BTF instead of DWARF 46 * `clang -c -g -target bpf` works similarly, but only for BPF targets 47 * `pahole -J` reads existing DWARF debug information and adds BTF 48 49* `-e|--elf` 50 51 Read ABI information from ELF symbols and DWARF types. 52 53* `-s|--stg` 54 55 Read ABI information from a `.stg` file. 56 57### Options 58 59* `--types` 60 61 Captures all named types found in ELF files as interface types, regardless 62 of whether those types are reachable by any symbol. 63 64## Comparison 65 66The default behaviour is to compare two ABIs for equivalence. 67 68### Options 69 70* `-i|--ignore` 71 72The following two ignore options suppress noisy diffs that are inevitable when 73consuming ABI XML output from `abidw`. 74 75* `symbol_type_presence` 76 77 Ignore changes in symbol type presence, thus `stgdiff` does not report loss 78 or gain of symbol type information. 79 80* `type_declaration_status` 81 82 Ignore changes in type declaration status, thus `stgdiff` does not report 83 loss or gain of user-defined type definitions. 84 85The following options are useful when comparing ABI representations that differ 86in how much (DWARF) information they preserve. 87 88* `primitive_type_encoding` 89 90 Ignore primitve type encodings during comparison. BTF provides a subset of 91 encoding information. libabigail XML lacks encoding information. 92 93* `member_size` 94 95 Ignore member sizes during comparison. libabigail XML does not model them. 96 97* `enum_underlying_type` 98 99 Ignore enum-underlying types during comparison. BTF doesn't model them. 100 libabigail provides incomplete information. 101 102* `qualifier` 103 104 Ignore qualifiers during comparison. Both libabigail and STG interpret and 105 adjust type qualifiers but sometimes do so differently. 106 107* `linux_symbol_crc` 108 109 Ignore Linux kernel symbol CRC changes during comparison. This can be 110 useful for ABI comparisons across different toolchains, where CRC changes 111 are often large and not useful. 112 113These two options can be used for ABI compatibility testing where the first ABI 114is expected to be a subset of the second. 115 116* `interface_addition` 117 118 Ignore interface (symbol and type root) additions during comparison. 119 120* `type_definition_addition` 121 122 Ignore type definition additions during comparison. Any extra symbol and 123 type roots may reach extra definitions of existing types. 124 125### Fidelity Reporting 126 127* `-F|--fidelity` 128 129Compares ABI representations for fidelity of symbol and type information. It 130reports the following kinds of fidelity changes: 131 132* Addition or removal of types (fully defined or declaration only) 133* Loss or gain of type definitions 134* Loss or gain of type information for symbols 135 136## Output formats 137 138All outputs are based on a diff graph which is rooted at the comparison of two 139symbol table nodes. 140 141* `plain` 142 143 Serialise the diff graph via depth first search, avoiding revisiting nodes 144 that have been visited or are being visited. The report mirrors the search 145 tree. 146 147 This format is only suitable for small inputs because the indentation level 148 is proportional to recursion depth and the resulting output may be 149 unreadable. 150 151 Example: 152 153 ``` 154 function symbol 'unsigned int fun(enum A, enum B)' changed 155 type 'unsigned int(enum A, enum B)' changed 156 parameter 1 type 'enum A' changed 157 enumerator 'Ae' value changed from 0 to 1 158 parameter 2 type 'enum B' changed 159 enumerator 'Be' value changed from 1 to 2 160 ``` 161 162* `flat` 163 164 Serialise the diff graph being broken into smaller pieces, each rooted at a 165 symbol, a user-defined type or a primitive type. Each piece is serialised as 166 a tree at the top level. 167 168 Example: 169 170 ``` 171 function symbol 'unsigned int fun(enum A, enum B)' changed 172 type 'unsigned int(enum A, enum B)' changed 173 parameter 1 type 'enum A' changed 174 parameter 2 type 'enum B' changed 175 176 type 'enum A' changed 177 enumerator 'Ae' value changed from 0 to 1 178 179 type 'enum B' changed 180 enumerator 'Be' value changed from 1 to 2 181 ``` 182 183* `small` 184 185 Like the `flat` output, but any subtrees that contain no diffs are pruned. 186 This report excludes symbols and types that have changed only due to some 187 other type change. 188 189 Example: 190 191 ``` 192 type 'enum A' changed 193 enumerator 'Ae' value changed from 0 to 1 194 195 type 'enum B' changed 196 enumerator 'Be' value changed from 1 to 2 197 ``` 198 199* `short` 200 201 The `short` report is a result of the following post-processing 202 transformations on the `small` report: 203 204 * Changes in symbols where only the CRC value has changed are collapsed 205 and the total number of changes is reported. 206 * Runs of member offset changes are collapsed and the amount by which the 207 offsets have shifted is reported. 208 * Added and removed symbols are reported in a compact manner with variable 209 and function symbols separated. 210 211* `viz` 212 213 Print the difference graph in Graphviz format. 214 215 Example: 216 217 ``` 218 digraph "ABI diff" { 219 "0" [shape=rectangle, label="'symbols'"] 220 "1" [label="'unsigned int fun(enum A, enum B)'"] 221 "2" [label="'unsigned int(enum A, enum B)'"] 222 "3" [color=red, shape=rectangle, label="'enum A'"] 223 "3" -> "3:0" 224 "3:0" [color=red, label="enumerator 'Ae' value changed from 0 to 1"] 225 "2" -> "3" [label="parameter 1"] 226 "4" [color=red, shape=rectangle, label="'enum B'"] 227 "4" -> "4:0" 228 "4:0" [color=red, label="enumerator 'Be' value changed from 1 to 2"] 229 "2" -> "4" [label="parameter 2"] 230 "1" -> "2" [label=""] 231 "0" -> "1" [label=""] 232 } 233 ``` 234 235## Exact Node Equality 236 237* `-x|--exact`: perform exact node equality (ignoring node identity) instead 238 of generating an ABI equivalence diff graph; no outputs may be specified. 239 240## Other options: 241 242* `-m|--metrics`: print duration of ABI parsing, comparison and reporting. 243 244## Return code 245 246If input files' ABIs are equivalent (or equal with `--exact`), `stgdiff` will 247return 0. Otherwise: 248 249* Return code 1: there was an exception during comparison, see `stderr` for 250 the exception reason. 251* Return code 4: ABIs differ. 252 253## Examples 254 255* Compare two ABI XML files, and print a short report to stdout: 256 257 ``` 258 stgdiff -a abi.0.xml abi.1.xml -f short -o - 259 ``` 260 261* Compare two ABI XML files **without printing anything**: 262 263 ``` 264 stgdiff -a abi.0.xml abi.1.xml && echo "Equivalent" || echo "Not equivalent, return code: $?" 265 ``` 266 267* Compare two ABI XML files, print short report to stdout and also print diff 268 graph visualisation to the file: 269 270 ``` 271 stgdiff -a abi.0.xml abi.1.xml -f short -o - -f viz -o graph.viz 272 ``` 273 274* Compare two ABI XML files, ignoring type presence and type declaration 275 status changes, and print short report to stdout: 276 277 ``` 278 stgdiff -i symbol_type_presence -i type_declaration_status -a abi.0.xml abi.1.xml -f short -o - 279 ``` 280 281* Compare ABI XML to ABI from ELF and print a short report to file: 282 283 ``` 284 stgdiff -a abi.xml -e example.o -f short -o example.diff 285 ``` 286 287* Compare two STG files and print fidelity report to stdout: 288 289 ``` 290 stgdiff -s abi.0.stg abi.1.stg -F - 291 ``` 292 293* Compare symbols and named types in two ELF files and print a short report to 294 stdout: 295 296 ``` 297 stgdiff -t -e example1.o example2.o -f short -o - 298 ``` 299