xref: /aosp_15_r20/external/stg/doc/stg.md (revision 9e3b08ae94a55201065475453d799e8b1378bea6)

# `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: --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:

*   `-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 `[ ... ]` 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.

## 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
    }
    ```