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