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.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:
Include,#include <stdint.h>Define,#define FOO_MAX 42Enum,enum foo_opt { ... };Typedef,typedef int (*foo_cb)(void *arg);Function,int foo_open(const char *path);
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
#definenamed ‘define’ masks, ‘width’ of them from bit ‘lo’; seeyace.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>_allocreturns a buffer ofnbytesbytes, which<stem>_freefrees and<stem>_reallocresizes, and<stem>_registerregistersnbytesbytes of the caller’s atptr, 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 asintoruint32_tPointer, a pointer to another typeArray, a fixed-length array of another typeRecord, a reference to astructorunionby its tagEnumRef, a reference to anenumby its tagTypedefRef, a reference to atypedefby its nameFunctionType, 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>' */, orbit <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.
- yace.ir.masks.link(entities: list, report: Callable[[str, str, object], None], cursors: dict)¶
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@recparamand@arrparam, the parameters that their@nbytes_at,@len_atand@nwritten_atname, 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@arrparamor@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_TAGSit 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.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