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 small 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 useful 110 for ABI comparisons across different toolchains, where CRC changes are often 111 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 137 138All outputs are based on a diff graph which is rooted at the comparison of two 139symbol table nodes. 140 141The `--format` and `--output` options may be repeated to obtain outputs of 142different formats. 143 144### Formats 145 146* `plain` 147 148 Serialise the diff graph via depth first search, avoiding revisiting nodes 149 that have been visited or are being visited. The report mirrors the search 150 tree. 151 152 This format is only suitable for small inputs because the indentation level 153 is proportional to recursion depth and the resulting output may be 154 unreadable. 155 156 Example: 157 158 ``` 159 function symbol 'unsigned int fun(enum A, enum B)' changed 160 type 'unsigned int(enum A, enum B)' changed 161 parameter 1 type 'enum A' changed 162 enumerator 'Ae' value changed from 0 to 1 163 parameter 2 type 'enum B' changed 164 enumerator 'Be' value changed from 1 to 2 165 ``` 166 167* `flat` 168 169 Serialise the diff graph being broken into smaller pieces, each rooted at a 170 symbol, a user-defined type or a primitive type. Each piece is serialised as 171 a tree at the top level. 172 173 Example: 174 175 ``` 176 function symbol 'unsigned int fun(enum A, enum B)' changed 177 type 'unsigned int(enum A, enum B)' changed 178 parameter 1 type 'enum A' changed 179 parameter 2 type 'enum B' changed 180 181 type 'enum A' changed 182 enumerator 'Ae' value changed from 0 to 1 183 184 type 'enum B' changed 185 enumerator 'Be' value changed from 1 to 2 186 ``` 187 188* `small` 189 190 Like the `flat` output, but any subtrees that contain no diffs are pruned. 191 This report excludes symbols and types that have changed only due to some 192 other type change. 193 194 Example: 195 196 ``` 197 type 'enum A' changed 198 enumerator 'Ae' value changed from 0 to 1 199 200 type 'enum B' changed 201 enumerator 'Be' value changed from 1 to 2 202 ``` 203 204* `short` 205 206 The `short` report is a result of the following post-processing 207 transformations on the `small` report: 208 209 * Changes in symbols where only the CRC value has changed are collapsed 210 and the total number of changes is reported. 211 * Runs of member offset changes are collapsed and the amount by which the 212 offsets have shifted is reported. 213 * Added and removed symbols are reported in a compact manner with variable 214 and function symbols separated. 215 216* `viz` 217 218 Print the difference graph in Graphviz format. 219 220 Example: 221 222 ``` 223 digraph "ABI diff" { 224 "0" [shape=rectangle, label="'symbols'"] 225 "1" [label="'unsigned int fun(enum A, enum B)'"] 226 "2" [label="'unsigned int(enum A, enum B)'"] 227 "3" [color=red, shape=rectangle, label="'enum A'"] 228 "3" -> "3:0" 229 "3:0" [color=red, label="enumerator 'Ae' value changed from 0 to 1"] 230 "2" -> "3" [label="parameter 1"] 231 "4" [color=red, shape=rectangle, label="'enum B'"] 232 "4" -> "4:0" 233 "4:0" [color=red, label="enumerator 'Be' value changed from 1 to 2"] 234 "2" -> "4" [label="parameter 2"] 235 "1" -> "2" [label=""] 236 "0" -> "1" [label=""] 237 } 238 ``` 239 240## Exact Node Equality 241 242* `-x|--exact`: perform exact node equality (ignoring node identity) instead 243 of generating an ABI equivalence diff graph; no outputs may be specified. 244 245## Other options: 246 247* `-m|--metrics`: print duration of ABI parsing, comparison and reporting. 248 249## Return code 250 251If input files' ABIs are equivalent (or equal with `--exact`), `stgdiff` will 252return 0. Otherwise: 253 254* Return code 1: there was an exception during comparison, see `stderr` for 255 the exception reason. 256* Return code 4: ABIs differ. 257 258## Examples 259 260* Compare two ABI XML files, and print a short report to stdout: 261 262 ``` 263 stgdiff -a abi.0.xml abi.1.xml -f short -o - 264 ``` 265 266* Compare two ABI XML files **without printing anything**: 267 268 ``` 269 stgdiff -a abi.0.xml abi.1.xml && echo "Equivalent" || echo "Not equivalent, return code: $?" 270 ``` 271 272* Compare two ABI XML files, print short report to stdout and also print diff 273 graph visualisation to the file: 274 275 ``` 276 stgdiff -a abi.0.xml abi.1.xml -f short -o - -f viz -o graph.viz 277 ``` 278 279* Compare two ABI XML files, ignoring type presence and type declaration 280 status changes, and print short report to stdout: 281 282 ``` 283 stgdiff -i symbol_type_presence -i type_declaration_status -a abi.0.xml abi.1.xml -f short -o - 284 ``` 285 286* Compare ABI XML to ABI from ELF and print a short report to file: 287 288 ``` 289 stgdiff -a abi.xml -e example.o -f short -o example.diff 290 ``` 291 292* Compare two STG files and print fidelity report to stdout: 293 294 ``` 295 stgdiff -s abi.0.stg abi.1.stg -F - 296 ``` 297 298* Compare symbols and named types in two ELF files and print a short report to 299 stdout: 300 301 ``` 302 stgdiff -t -e example1.o example2.o -f short -o - 303 ``` 304