DESCRIPTION¶

Symtypes files provide detailed information about the ABI in the Linux kernel. The format describes exported functions, variables and their dependent types as known in a single object file. The data is generated by the genksyms utility from the kernel tree. It records the type information that was used by the tool to calculate a signature (CRC) of each symbol.

FORMAT¶

A symtypes file consists of type records, one per line. Each record is comprised of a type identifier and an associated type description, separated by whitespace.

A type identifier can be one of the following:

A type description consists of a list of tokens, separated by 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 defining the type and when referencing it. This allows the type name to contain spaces.

EXAMPLES¶

The following example shows the file a.symtypes. The data records the exported function "baz", which takes as its parameters the structure "foo" and a pointer to the union "bar". The structure "foo" has a complete definition in the file, while the union "bar" is an opaque declaration.

$ cat a.symtypes
s#foo struct foo { int m ; }
u#bar union bar { UNKNOWN }
baz void baz ( s#foo a1 , u#bar * a2 )
    

DESCRIPTION¶

A symvers file provides final information about the ABI in the Linux kernel. The file summarizes data that was embedded during the Linux kernel build into the main kernel binary and loadable modules to detect compatibility between symbol references and associated definitions. The data is generated by the modpost utility from the kernel tree.

FORMAT¶

A symvers file consists of symbol records, one per line. Each record is comprised of a 32-bit symbol CRC, a symbol name, a module name, an export type and optionally a namespace identifier, all separated by whitespace.

EXAMPLES¶

The following example shows the file Module.symvers. The data records two exported functions "baz" and "qux". The symbol "baz" has a CRC of 0x12345678, originates from the main kernel binary and is a regular export. The symbol "qux" has a CRC of 0x90abcdef, originates from the lib/test module, is a GPL-only export and is defined in the BAR_NS namespace.

$ cat Module.symvers
0x12345678 baz vmlinux  EXPORT_SYMBOL
0x90abcdef qux lib/test EXPORT_SYMBOL_GPL BAR_NS
    

DESCRIPTION¶

The consolidated symtypes format extends the base symtypes 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.

FORMAT¶

The format introduces the concept of file sections, with each section starting with a special record in the form "/* <file-name> */". The content of each section can be trivially same as in the case of the base symtypes format. However, two extensions are present to save storage space.

A file section can omit a type definition if it is the same as its last definition previously encountered in the consolidated file. A reader can implicitly determine its presence be by recursively walking all exports in the specific file.

A file section can transform opaque declarations in the form "<short-type>#<name> <type> <name> { UNKNOWN }" to "<short-type>##<name>". For instance, "s#task_struct struct task_struct { UNKNOWN }" becomes "s##task_struct". Such definitions apply only to the current file section and do not override the last definition of the symbol.

EXAMPLES¶

The following example shows two files a.symtypes and .b.symtypes using the base format. The first file a.symtypes records the exported function "baz", which takes as its parameters the structure "foo" and a pointer to the union "bar", with the former having a complete definition and the latter being an opaque declaration. The second file b.symtypes records the exported function "qux", which takes as its parameters the structure "foo" and a pointer to the union "bar", with both types having a complete definition.

$ cat example/a.symtypes
s#foo struct foo { int m ; }
u#bar union bar { UNKNOWN }
baz void baz ( s#foo a1 , u#bar * a2 )
    

$ cat example/b.symtypes
s#foo struct foo { int m ; }
u#bar union bar { int i; float f; }
qux void qux ( s#foo a1 , u#bar * a2 )
    

The following example shows the file c.symtypes, which is produced by consolidating the previous two files a.symtypes and b.symtypes. The structure type "foo", which was the same in both files, is merged; the union type "bar" appears in two different variants.

$ ksymtypes consolidate --output=example/c.kabi example/
$ cat example/c.kabi
/* a.symtypes */
s#foo struct foo { int m ; }
u##bar
baz void baz ( s#foo a1 , u#bar * a2 )
/* b.symtypes */
u#bar union bar { int i; float f; }
qux void qux ( s#foo a1 , u#bar * a2 )
    

DESCRIPTION¶

A kABI severity file provides rules to be used in the comparison of symvers data.

FORMAT¶

A kABI severity file consists of rules, one per line. Each rule is comprised of a pattern and an associated verdict, separated by whitespace.

A pattern can be one of the following:

A pattern can contain the shell wildcards "*" and "?", with their usual meaning.

A verdict can be either "PASS" or "FAIL".

The file can contain comments beginning with "#", which extend to the end of the line. Rules are ordered, and the first match takes effect.

EXAMPLES¶

The following example shows the file severity.rules, which defines three rules. The first rule is a module rule that indicates all changes in modules matching "lib/important*" should result in a failure. The second rule is a namespace rule that indicates all changes in the namespace "TEST_IMPORTANT" should result in a failure. The last rule is a symbol rule that indicates all changes to symbols matching "*not_stable*" can be ignored.

$ cat severity.rules
lib/important* FAIL
TEST_IMPORTANT FAIL
*not_stable*   PASS