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|-}] ...
  [-A|--annotate]
implicit defaults: --elf
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:

• -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.

• -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 [ ... ] wildcards
• :filename - the name of a file containing a libabigail format filter list

Filter expressions can be combined with infix disjunction (|) 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.

Annotations

• -A|--annotate

  Output node descriptions for edges in the graph as inline textual protobuf comments.

  Sample STG output:

  root_id: 0x84ea5130  # interface
  primitive {
    id: 0x6720d32f
    name: "int"
    bytesize: 0x00000004
  }
  struct_union {
    id: 0xf57dfbfc
    kind: STRUCT
    name: "S"
  }
  function {
    id: 0x85d454a8
    return_type_id: 0x6720d32f  # int
    parameter_id: 0x6720d32f  # int
  }
  elf_symbol {
    id: 0x8bf70937
    name: "func"
    symbol_type: FUNCTION
    type_id: 0x85d454a8  # int(int)
  }
  elf_symbol {
    id: 0x3e4f6c44
    name: "s"
    symbol_type: OBJECT
    type_id: 0xf57dfbfc  # struct S
  }
  interface {
    id: 0x84ea5130
    symbol_id: 0x8bf70937  # int func(int)
    symbol_id: 0x3e4f6c44  # struct S s
  }