Entities

The IR is a set of pydantic models. A yace.ir.model.Model is the root; its entities are declarations, in yace.ir.decls, and the types they use are in yace.ir.types.

Model

The root of the yace IR: the Meta describing the API and the declarations, its entities, in the order the header declares them

The IR is stored as YAML. load() and Model.save() read and write it, and schema() is its JSON Schema, for tools that read the IR without yace.

class yace.ir.model.Meta(*, name: str, prefix: str, version: str = '0.0.1', brief: str = '', description: str = '', author: str = '', license: str = '', headers: List[str] = [], prelude: List[str] = [], pkg: str = '', crate: str = '', errmsg: str = '', abi: str = '')

What the API is called, its prefix, and who it is by and under what license

model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

source() → str

What the IR was parsed from, as generated code says it

class yace.ir.model.Model(*, meta: Meta, entities: List[Annotated[Include | Define | Enum | Struct | Union | Typedef | Function, FieldInfo(annotation=NoneType, required=True, discriminator='key')]] = [])
enums() → dict

The enums by name

errmsg() → Function | None

The function that returns the message of the call that failed last, or None where the meta names none, or one that errmsg_unfit() rejects

errmsg_unfit() → str | None

Why the function that the meta names as ‘errmsg’ cannot give the message of a failed call, or None where the function can, or the meta names no function

find(name: str, kind: Type[T]) → T | None
find(name: str, kind: Tuple[Type[T], Type[U]]) → T | U | None
find(name: str, kind: None = None) → Any | None

The entity named ‘name’, of ‘kind’ where given, as C has records and functions of the same name

model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

records() → dict

The structs and unions by name

save(path: Path)

Write the IR to ‘path’ as YAML

typedefs() → dict

The typedefs by name

yace.ir.model.host_abi() → str

The platform layout recorded in the IR is valid for, such as ‘Linux-x86_64’

yace.ir.model.load(path: Path) → Model

Read the IR from the YAML at ‘path’

yace.ir.model.schema() → dict

The JSON Schema of the IR

Declarations

Declarations in the yace IR, the entities of a yace.ir.model.Model

Each is one top-level declaration of the header, in the order they appear:

Struct and union carry their layout, size and alignment in bytes and the offset of each field in bits, as the compiler that parsed the header laid them out. Targets check what they generate against that layout. A record declared with __attribute__((packed)), or under #pragma pack(1), is ‘packed’: its fields are not aligned, and nor is the record.

class yace.ir.decls.Define(*, key: Literal['define'] = 'define', name: str, value: IntLiteral | StrLiteral, doc: Doc = Doc(brief='', description='', params={}, directions={}, returns='', records=[], arrays=[], references={}, stray=[], repeated=[], twice=[], tags={}))
model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class yace.ir.decls.Enum(*, key: Literal['enum_decl'] = 'enum_decl', name: str, members: List[EnumMember], underlying: Builtin | None = None, spelled: str = '', doc: Doc = Doc(brief='', description='', params={}, directions={}, returns='', records=[], arrays=[], references={}, stray=[], repeated=[], twice=[], tags={}))
model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class yace.ir.decls.EnumMember(*, name: str, value: int, doc: Doc = Doc(brief='', description='', params={}, directions={}, returns='', records=[], arrays=[], references={}, stray=[], repeated=[], twice=[], tags={}))
model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class yace.ir.decls.Field(*, name: str, typ: Builtin | Pointer | Array | Record | EnumRef | TypedefRef | FunctionType, bits: int | None = None, offset: int | None = None, masks: List[Mask] = [], doc: Doc = Doc(brief='', description='', params={}, directions={}, returns='', records=[], arrays=[], references={}, stray=[], repeated=[], twice=[], tags={}))
model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class yace.ir.decls.Function(*, key: Literal['function_decl'] = 'function_decl', name: str, ret: Builtin | Pointer | Array | Record | EnumRef | TypedefRef | FunctionType, params: List[Param] = [], variadic: bool = False, errno: bool = False, partial: bool = False, destroys: str | None = None, nullable: bool = False, memory: Memory | None = None, doc: Doc = Doc(brief='', description='', params={}, directions={}, returns='', records=[], arrays=[], references={}, stray=[], repeated=[], twice=[], tags={}))

A function, with what C cannot say about it, from its documentation: whether it returns a negative errno on failure, and whether it writes its [out] parameters also then, which parameter’s handle it destroys, whether the pointer it returns may be NULL, and what it does with a buffer of memory

model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class yace.ir.decls.Include(*, key: Literal['include'] = 'include', name: str, system: bool = True)
model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class yace.ir.decls.IntLiteral(*, key: Literal['int'] = 'int', value: int, base: Literal[10, 16] = 10)
model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class yace.ir.decls.Mask(*, name: str, define: str, lo: int, width: int, doc: Doc = Doc(brief='', description='', params={}, directions={}, returns='', records=[], arrays=[], references={}, stray=[], repeated=[], twice=[], tags={}))

A named part of an integer field: the bits the #define named ‘define’ masks, ‘width’ of them from bit ‘lo’; see yace.ir.masks

property largest: int

The largest value of the part

model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

property value: int

The mask, the bits in their place

class yace.ir.decls.Memory(*, role: Literal['alloc', 'free', 'realloc', 'register', 'unregister'], stem: str, ptr: str | None = None, nbytes: str | None = None)

What a function does with a buffer of memory, by the names of the buffer pattern: <stem>_alloc returns a buffer of nbytes bytes, which <stem>_free frees and <stem>_realloc resizes, and <stem>_register registers nbytes bytes of the caller’s at ptr, until <stem>_unregister

model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class yace.ir.decls.Param(*, name: str = '', typ: Builtin | Pointer | Array | Record | EnumRef | TypedefRef | FunctionType, direction: Literal['in', 'out', 'inout'] = 'in', nullable: bool = False, length: str | None = None, count: str | None = None, size: str | None = None, context: str | None = None, lifetime: Literal['call', 'once', 'handle'] | None = None)

A parameter, with what C cannot say about it, from its documentation: whether the function reads it, writes it, or both, whether it may be NULL, which parameter holds its length, or the size of the record it points to, which [out] parameter the function writes the number of elements it wrote to, which callback a void * is the context of, and how long a callback may be invoked

model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class yace.ir.decls.StrLiteral(*, key: Literal['str'] = 'str', value: str)
model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class yace.ir.decls.Struct(*, key: Literal['struct_decl'] = 'struct_decl', name: str, fields: List[Field], size: int | None = None, align: int | None = None, packed: bool = False, spelled: str = '', doc: Doc = Doc(brief='', description='', params={}, directions={}, returns='', records=[], arrays=[], references={}, stray=[], repeated=[], twice=[], tags={}))
model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class yace.ir.decls.Typedef(*, key: Literal['typedef_decl'] = 'typedef_decl', name: str, typ: Builtin | Pointer | Array | Record | EnumRef | TypedefRef | FunctionType, doc: Doc = Doc(brief='', description='', params={}, directions={}, returns='', records=[], arrays=[], references={}, stray=[], repeated=[], twice=[], tags={}))
model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class yace.ir.decls.Union(*, key: Literal['union_decl'] = 'union_decl', name: str, fields: List[Field], size: int | None = None, align: int | None = None, packed: bool = False, spelled: str = '', doc: Doc = Doc(brief='', description='', params={}, directions={}, returns='', records=[], arrays=[], references={}, stray=[], repeated=[], twice=[], tags={}))
model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

Types

Types in the yace IR

A type is a tree of nodes, each one kind of type, told apart by key:

  • Builtin, a type C provides, such as int or uint32_t

  • Pointer, a pointer to another type

  • Array, a fixed-length array of another type

  • Record, a reference to a struct or union by its tag

  • EnumRef, a reference to an enum by its tag

  • TypedefRef, a reference to a typedef by its name

  • FunctionType, the signature of a function, the pointee of a function pointer

So const char * is a Pointer to a const Builtin named char, and int (*)(void *, size_t) is a Pointer to a FunctionType.

class yace.ir.types.Array(*, key: Literal['array'] = 'array', of: Builtin | Pointer | Array | Record | EnumRef | TypedefRef | FunctionType, length: int | None)
model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class yace.ir.types.Builtin(*, key: Literal['builtin'] = 'builtin', name: Literal['void', 'bool', 'char', 'signed char', 'unsigned char', 'short', 'unsigned short', 'int', 'unsigned int', 'long', 'unsigned long', 'long long', 'unsigned long long', 'float', 'double', 'int8_t', 'int16_t', 'int32_t', 'int64_t', 'uint8_t', 'uint16_t', 'uint32_t', 'uint64_t', 'intptr_t', 'uintptr_t', 'size_t', 'ssize_t', 'ptrdiff_t'], const: bool = False)
model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class yace.ir.types.EnumRef(*, key: Literal['enum'] = 'enum', name: str, const: bool = False)
model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class yace.ir.types.FunctionType(*, key: Literal['function'] = 'function', ret: Builtin | Pointer | Array | Record | EnumRef | TypedefRef | FunctionType, params: List[TypeParam] = [], variadic: bool = False)
model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class yace.ir.types.Node

Base of the IR models; unknown attributes are an error, not ignored

model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class yace.ir.types.Pointer(*, key: Literal['pointer'] = 'pointer', to: Builtin | Pointer | Array | Record | EnumRef | TypedefRef | FunctionType, const: bool = False)
model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class yace.ir.types.Record(*, key: Literal['record'] = 'record', tag: Literal['struct', 'union'], name: str, const: bool = False)
model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class yace.ir.types.TypeParam(*, name: str = '', typ: Builtin | Pointer | Array | Record | EnumRef | TypedefRef | FunctionType)

A parameter of a FunctionType; the name may be empty

model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class yace.ir.types.TypedefRef(*, key: Literal['typedef'] = 'typedef', name: str, const: bool = False)
model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

yace.ir.types.is_string(typ) → bool

Whether ‘typ’ is a const char *, a C string the callee does not change

yace.ir.types.walk(typ)

Yield ‘typ’ and every type nested in it, outermost first

Fields of bits

Fields of bits: an integer field of a record and the masks naming its parts

The C subset has no bit-fields. A field of bits is an unsigned integer, and each of its parts is named by a mask, an object-like #define of the part’s bits in their place. Both ends of the link are written in the header, in the doc comments, and yace checks that they agree:

  • the integer names the prefix of its masks: ///< <what>, see <PREFIX>_<STRUCT>_<FIELD>_*

  • each mask is named by that prefix and the part, and says which bits of which field it is: /** <what>; bits <hi>:<lo> of '<field>' */, or bit <n> for one bit

For example:

struct foo_status {
  uint16_t code; ///< Status code, see FOO_STATUS_CODE_*
};

/** Generic, command specific or media error; bits 2:0 of 'code' */
#define FOO_STATUS_CODE_TYPE 0x7
/** Whether more is in the log; bit 15 of 'code' */
#define FOO_STATUS_CODE_MORE 0x8000

links the parts type and more to code of struct foo_status, as yace.ir.decls.Mask on the field. Nothing is inferred from a name alone: a #define is a mask when its doc says which bits it is, and it belongs to the field whose doc names its prefix. Every disagreement is reported by the bit-mask rule, and the mask is not linked. A field whose see <PREFIX>_* names no masks, such as one naming the constants of its values, is not a field of bits.

Link each mask among the #defines of ‘entities’ to its field

Documentation

Documentation attached to an entity in the yace IR, parsed from the Doxygen style comment above, or trailing (‘///<’), the declaration in the header

class yace.ir.doc.Doc(*, brief: str = '', description: str = '', params: Dict[str, str] = {}, directions: Dict[str, str] = {}, returns: str = '', records: List[str] = [], arrays: List[str] = [], references: Dict[str, Dict[str, str]] = {}, stray: List[str] = [], repeated: List[Tuple[str, str]] = [], twice: List[str] = [], tags: Dict[str, str] = {})

The brief, the description after it, as paragraphs separated by a blank line, with each item of a list on a line of its own, the parameters by name, the direction of those documented with one, as @param[out], those documented with @recparam and @arrparam, the parameters that their @nbytes_at, @len_at and @nwritten_at name, what is returned, and any other tag, by tag name, with its text. The commands of those three that are not in the text of a parameter, or name no parameter in braces, are stray, and a command given twice for one parameter is repeated. A parameter documented by two tags, one of them @arrparam or @recparam, is documented twice

model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

prose() → List[str]

The tags of PROSE_TAGS it has, each as its label and text, or its label alone, as a bare ‘@deprecated’ says

yace.ir.doc.joined(line: str) → str

What joins ‘line’ to the text before it: a newline, where it starts an item of a list, else a space, as the line continues a sentence

yace.ir.doc.joint(tag: str, text: str) → str

What joins another of the repeated prose ‘tag’ to its ‘text’: references are listed, and the rest are sentences. parse() joins yace’s own tags by a space instead, as their text is read word by word

yace.ir.doc.parse(raw) → Doc

Parse the raw comment text, as libclang gives it, into a Doc

yace.ir.doc.strip_markers(raw: str) → str

The text of a comment, without its markers, such as /** and */

Diagnostics

Diagnostics: where a header steps outside the C subset that yace describes an FFI boundary with

A header outside the subset is still parsed, and everything that can be represented is; every place it steps outside is reported as a Diagnostic, naming the rule it breaks. Nothing is dropped or changed without one. A diagnostic fails the run, unless --lenient.

The rules, by name, with why each exists, are RULES. A note, by a name in NOTES, reports what is skipped without the header breaking a rule: what only the C compiler uses, with no symbol for other languages to bind. A note does not fail the run.

class yace.ir.diagnostics.Diagnostic(*, rule: str, message: str, file: str = '', line: int = 0, column: int = 0)

Where a header breaks a rule of the C subset, and how, or a note

model_config = {'extra': 'forbid'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

property note: bool

Whether this reports what is skipped without breaking a rule