SUSE-KABI-TOOLS(5)

🌸 NAME 🌸

suse-kabi-tools — Linux-kernel Application Binary Interface (ABI) definition files. This is the whole SUSE-KABI-TOOLS(5) page, bestie, from the File Formats Manual. 🫶

💖 DESCRIPTION 💖

Okay so suse-kabi-tools operates on several data formats, and they are:

• symbol types (symtypes)
• symbol versions (symvers)
• consolidated symtypes
• kABI severity rules

The symtypes and symvers data files are generated by the Linux kernel build, and their format is effectively defined by the Linux project. The consolidated symtypes and kABI severity rules are custom formats defined specifically by suse-kabi-tools.

Bestie, this document describes these formats. Periodt. 💅

🧚 SYMBOL TYPES 🧚

✨ DESCRIPTION ✨

Symtypes files give you 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. Ngl, that's the whole point. 💅

📝 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. Cute, right? 🎀

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 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 defining the type and when referencing it. This allows the type name to contain spaces. Iconic. 🦋

🧪 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. No cap. 🧢

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

🔥 SYMBOL VERSIONS 🔥

✨ DESCRIPTION ✨

A symvers file gives you the 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. Slay. 💅

📝 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. Lowkey straightforward. ✨

🧪 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

🌈 CONSOLIDATED SYMBOL TYPES 🌈

✨ DESCRIPTION ✨

The consolidated symtypes format extends the base symtypes format to efficiently describe types across multiple object files. This allows you to have one file for the entire kernel ABI — main character energy. 👑 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 the 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 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. Periodt. 💅

🧪 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. Obsessed. 🦋

$ 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 )

💀 KABI SEVERITY RULES 💀

✨ DESCRIPTION ✨

A kABI severity file provides rules to be used in the comparison of symvers data. It’s literally the vibe check for changes. 💅

📝 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:

• <module-name> — a module name, indicated by the presence of the character "/" in the name, or by the name being literally "vmlinux"
• <namespace-identifier> — a namespace identifier, indicated by all letters being capital
• <symbol-name> — a symbol name, the default case

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

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. So order matters, bestie — no cap. 🔥

🧪 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. Iconic. 🌸

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

🫶 SEE ALSO 🫶

Go check out ksymtypes(1) and ksymvers(1), bestie. They’re right there. 💖

---

Sign-off time, bestie: source/version is SUSE-KABI-TOOLS(5) / File Formats Manual, and the footer has no date printed — so I’m not making one up. Bye! 💖✨