symtypes − Linux-kernel ABI definition database
Symtypes files provide information about Application Binary Interface (ABI) in the Linux kernel. The ksymtypes utility recognizes two variants of this format, the base and its own consolidated variant.
The base format describes exported functions, variables and their dependent types as known in a single object file. The data is generated by genksyms utilities from the kernel tree.
The consolidated format extends the base format to efficiently describe types across multiple object files. This allows to have one file for the entire kernel ABI. The format is generated by the ksymtypes consolidate command.
A symtypes file consists of type records, one per a line. Each record is comprised of a type identifier and an associated type description, separated by a whitespace.
A type identifier can be one of the following:
|
• |
<exported-name> – an exported function or variable definition (no prefix), | ||
|
• |
t#<typedef-name> – a typedef definition, | ||
|
• |
e#<enum-name> – an enumeration definition, | ||
|
• |
s#<struct-name> – a structure definition, | ||
|
• |
u#<union-name> – a union definition, | ||
|
• |
E#<enum-constant-name> – an enumerator definition. |
A type description consists of a list of tokens, separated by a whitespace. A single token can be a literal value directly contributing to the type definition or a type reference. References are in the form "<x>#<type-name>" and point to another type defined in the file.
A type name can be optionally enclosed in single quotes, both when when definiting the type and when referencing it. This allows the type name to contain spaces.
The consolidated format extends the base format with variant suffixes and file records.
Each type definition can have additionally a suffix in the form "@<variant>". This allows to have different definitions of the same type in the consolidated file.
A file record is identified by "F#<file-name>". Its description lists types and exports found in a given file. The types must include their variant if multiple definitions of a specific type are present in the consolidated file. A type that has only one variant in the entire consolidated file can be omitted on the file record to save space. Its presence can be implicitly determined by recursively walking all exports in the specific file.
Type references found in other records do not use the variant suffix. An actual type must be determined based on the context in what file the reference is made.
The following example shows two files a.symtypes and .b.symtypes using the base format. The first file a.symtypes records an export of the function "baz" that takes as its parameters the structure "foo" and a pointer to the union "bar", with both types having a full definition. The second file b.symtypes records an export of the function "qux" that takes as its parameters the structure "foo" and a pointer to the union "bar", with the former having a full definition and the latter being an opaque declaration.
$ cat
example/a.symtypes
s#foo struct foo { int m ; }
u#bar union bar { int i; float f; }
baz void baz ( s#foo a1 , u#bar * a2 )
$ cat
example/b.symtypes
s#foo struct foo { int m ; }
u#bar union bar { UNKNOWN }
qux void qux ( s#foo a1 , u#bar * a2 )
The following example shows file c.symtypes that is produced by consolidating the previous two files a.symtypes and b.symtypes. The structure type "foo" which was same in both file is merged, the union type "bar" appears in two different variants. New "F#" records indicate which types are specific to each file.
$ ksymtypes
consolidate --output=example/c.kabi example/
$ cat example/c.kabi
s#foo struct foo { int m ; }
u#bar@0 union bar { int i; float f; }
u#bar@1 union bar { UNKNOWN }
baz void baz ( s#foo a1 , u#bar * a2 )
qux void qux ( s#foo a1 , u#bar * a2 )
F#example/a.symtypes u#bar@0 baz
F#example/b.symtypes u#bar@1 qux
ksymtypes(1)