C Parser¶
Given a C header, yace parses it into the IR with libclang. Any header can
be parsed; everything that can be represented is, and every place the header
steps outside the C subset is reported as a diagnostic, naming the rule, see
Rules. Nothing is dropped or changed without one.
Invoking it on the example library:
yace examples/libfoo/include/foo.h --meta examples/libfoo/meta.yaml --output output
C Header¶
/**
* An example library, using every construct of the C subset of yace
*
* It is the fixture the targets are checked against: each target's check calls
* it through the bindings generated from this header and prints what it got
* back, which must be what 'expected.yaml' says.
*/
#ifndef FOO_H
#define FOO_H
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#include <sys/types.h>
#define FOO_NAME "foo" ///< Name of the library
#define FOO_MAGIC 0xACDC ///< A hexadecimal constant
#define FOO_VERSION_MAJOR 1 ///< Major version
#define FOO_VERSION_MINOR 2 ///< Minor version
#define FOO_VERSION_PATCH 3 ///< Patch version
#define FOO_POINTS_MAX (1 << 3) ///< Points a handle holds at most
#define FOO_DEFAULT_SHAPE_SIDES FOO_POINTS_MAX ///< A constant, by name
/**
* Kinds of figure
*/
enum foo_shape {
FOO_SHAPE_NONE = -1, ///< No figure
FOO_SHAPE_POINT = 0, ///< A single point
FOO_SHAPE_LINE = 1, ///< Two points
FOO_SHAPE_POLYGON = 2, ///< Three points or more
};
/**
* Options of a figure, combined as bits
*/
enum foo_option {
FOO_OPTION_CLOSED = 0x1, ///< The last corner connects to the first
FOO_OPTION_FILLED = 0x2, ///< The inside is filled
};
/**
* A collection of points, opened with foo_open() and closed with foo_close()
*/
struct foo_handle;
/**
* A point on the plane
*/
struct foo_point {
int32_t x; ///< Horizontal position
int32_t y; ///< Vertical position
};
/**
* Called back with each point visited
*
* @param arg The argument given along with the callback
* @param point The point visited
*
* @return 0 to go on, anything else to stop
*/
typedef int (*foo_visit_cb)(void *arg, const struct foo_point *point);
/**
* Called back when a count submitted completes
*
* @param arg The argument given along with the callback
* @param count The number of points when it completed
*/
typedef void (*foo_done_cb)(void *arg, size_t count);
/**
* Called back with each point added to a handle watched
*
* @param arg The argument given along with the callback
* @param point The point added
*/
typedef void (*foo_added_cb)(void *arg, const struct foo_point *point);
/**
* A callback and its argument
*/
struct foo_visitor {
foo_visit_cb visit; ///< Called for each point
void *arg; ///< Given to 'visit'
};
/**
* A value of every kind of scalar
*/
struct foo_scalars {
bool flag; ///< bool
char letter; ///< char
signed char schar; ///< signed char
unsigned char uchar; ///< unsigned char
short s; ///< short
unsigned short us; ///< unsigned short
int i; ///< int
unsigned int ui; ///< unsigned int
long l; ///< long
unsigned long ul; ///< unsigned long
long long ll; ///< long long
unsigned long long ull; ///< unsigned long long
float f; ///< float
double d; ///< double
int8_t i8; ///< int8_t
int16_t i16; ///< int16_t
int32_t i32; ///< int32_t
int64_t i64; ///< int64_t
uint8_t u8; ///< uint8_t
uint16_t u16; ///< uint16_t
uint32_t u32; ///< uint32_t
uint64_t u64; ///< uint64_t
intptr_t iptr; ///< intptr_t
uintptr_t uptr; ///< uintptr_t
size_t size; ///< size_t
ssize_t ssize; ///< ssize_t
ptrdiff_t diff; ///< ptrdiff_t
};
/**
* A figure: its kind, where it is, and its corners
*/
struct foo_figure {
uint32_t shape; ///< One of enum foo_shape
uint32_t options; ///< Bits of enum foo_option
struct foo_point origin; ///< Where the figure is
struct foo_point corners[4]; ///< The corners, relative to 'origin'
uint8_t ncorners; ///< How many of 'corners' are used
char name[16]; ///< Name of the figure
int16_t grid[2][3]; ///< A two-dimensional array
const char *label; ///< A string, NULL when there is none
float scale; ///< Scale of the figure
double area; ///< Area of the figure
};
/**
* A 32-bit value, read as signed, as unsigned, or as the 'x' of a point
*/
union foo_value {
int32_t i; ///< Signed
uint32_t u; ///< Unsigned
struct foo_point point; ///< A point, its 'x' sharing the bits of 'i'
};
/**
* A record laid out without padding, as a wire format is: no field after the
* first is aligned
*/
struct __attribute__((packed)) foo_wire {
uint8_t kind; ///< One of enum foo_shape
uint32_t length; ///< At offset 1
struct foo_point at; ///< A point, at offset 5
uint16_t pair[2]; ///< An array, at offset 13
};
/**
* The status of a handle, its code a field of bits
*/
struct foo_status {
uint16_t code; ///< Status code, see FOO_STATUS_CODE_*
uint16_t max; ///< Points the handle holds at most
};
/** A count is submitted and not yet completed; bit 0 of 'code' */
#define FOO_STATUS_CODE_PENDING 0x1
/** Points held; bits 11:4 of 'code' */
#define FOO_STATUS_CODE_POINTS 0xff0
/** The handle holds FOO_POINTS_MAX points; bit 15 of 'code' */
#define FOO_STATUS_CODE_FULL 0x8000
/**
* The version of the library
*
* @return The version, as "MAJOR.MINOR.PATCH"
*/
const char *
foo_version(void);
/**
* Why the call that failed last on the calling thread failed
*
* A function that returns a negative errno keeps a message saying what the
* errno does not, such as the name of the handle that is full. The meta names
* this function as 'errmsg', so that the error of a binding holds the message.
*
* @return The message, owned by the library and valid until the next call
* fails on the calling thread; "" when no call has failed
*/
const char *
foo_errmsg(void);
/**
* Open a handle holding no points
*
* @param[in] name Name of the handle, copied
* @param[out] handle Set to the handle opened
*
* @return 0 on success, -EINVAL when 'name' or 'handle' is NULL, -ENOMEM when
* memory ran out
*
* @errno
*/
int
foo_open(const char *name, struct foo_handle **handle);
/**
* Close a handle
*
* @param handle The handle to close, NULL is ignored
*
* @nullable handle
* @destroys handle
*/
void
foo_close(struct foo_handle *handle);
/**
* The name the handle was opened with
*
* @param handle The handle
*
* @return The name, owned by the handle
*/
const char *
foo_name(const struct foo_handle *handle);
/**
* Add a point to the handle
*
* @param handle The handle
* @param[in] point The point to add, copied
*
* @return 0 on success, -ENOSPC when the handle holds FOO_POINTS_MAX points
*
* @errno
*/
int
foo_point_add(struct foo_handle *handle, const struct foo_point *point);
/**
* Add points to the handle, as many as it has room for
*
* @param handle The handle
* @arrparam[in] points The points to add, copied
* @param points_len The number of points
*
* @return The number of points added, -ENOSPC when there was room for none
*
* @errno
*/
ssize_t
foo_point_add_many(struct foo_handle *handle, const struct foo_point *points, size_t points_len);
/**
* The number of points held
*
* @param handle The handle
*
* @return The number of points
*/
size_t
foo_point_count(const struct foo_handle *handle);
/**
* A point held by the handle
*
* @param handle The handle
* @param idx Index of the point
*
* @return The point, NULL when 'idx' is past the last one
*
* @nullable return
*/
const struct foo_point *
foo_point_get(const struct foo_handle *handle, size_t idx);
/**
* Copy the points held, as many as fit
*
* @param handle The handle
* @arrparam[out] points Where to copy the points to
* @param points_len The number of points that fit
*
* @return The number of points copied
*
* @errno
*/
ssize_t
foo_point_copy(const struct foo_handle *handle, struct foo_point *points, size_t points_len);
/**
* Watch the points added to the handle, from now until it is closed
*
* @param handle The handle
* @param added Called with each point added, until the handle is closed
* @param arg Given to 'added'
*
* @return 0 on success, -EBUSY when the handle is watched already
*
* @nullable arg
* @lifetime added handle
* @errno
*/
int
foo_point_watch(struct foo_handle *handle, foo_added_cb added, void *arg);
/**
* Visit the points in the order they were added
*
* @param handle The handle
* @param visit Called for each point, until it returns non-zero
* @param arg Given to 'visit'
*
* @return The number of points visited, -EINVAL when 'visit' is NULL
*
* @nullable arg
* @lifetime visit call
* @errno
*/
ssize_t
foo_point_visit(struct foo_handle *handle, foo_visit_cb visit, void *arg);
/**
* Visit the points with a visitor; as foo_point_visit()
*
* @param handle The handle
* @param[in] visitor The callback and its argument
*
* @return The number of points visited, -EINVAL when the callback is NULL
*
* @errno
*/
ssize_t
foo_point_visit_with(struct foo_handle *handle, const struct foo_visitor *visitor);
/**
* Submit a count of the points, completed by foo_count_complete()
*
* @param handle The handle
* @param done Called once, by foo_count_complete(), with the number of points
* @param arg Given to 'done'
*
* @return 0, -EBUSY when a count is submitted and not yet completed
*
* @nullable arg
* @lifetime done once
* @errno
*/
int
foo_count_submit(struct foo_handle *handle, foo_done_cb done, void *arg);
/**
* Complete the count submitted, if any, calling its callback
*
* @param handle The handle
*
* @return The number of counts completed, 0 or 1
*/
size_t
foo_count_complete(struct foo_handle *handle);
/**
* The status of the handle
*
* @param handle The handle
* @param[out] status The status to fill in
*/
void
foo_status_get(const struct foo_handle *handle, struct foo_status *status);
/**
* Fill in a value of every kind of scalar, the limits of the fixed-width ones
*
* @param[out] scalars The values to fill in
*/
void
foo_scalars_fill(struct foo_scalars *scalars);
/**
* Fill in a figure of the given shape
*
* @param[out] figure The figure to fill in
* @param shape One of enum foo_shape
*
* @return 0 on success, -EINVAL when 'shape' is none of enum foo_shape
*
* @errno
*/
int
foo_figure_fill(struct foo_figure *figure, uint32_t shape);
/**
* Set a value, clearing the bits it does not use
*
* @param[out] value The value to set
* @param i What to set it to
*/
void
foo_value_set(union foo_value *value, int32_t i);
/**
* Fill in a packed record
*
* @param[out] wire The record to fill in
*/
void
foo_wire_fill(struct foo_wire *wire);
#endif /* FOO_H */
IR¶
meta:
name: libfoo
prefix: foo
version: 0.0.1
brief: An example library described in the C subset of yace
description: ''
author: Simon A. F. Lund <os@safl.dk>
license: GPL-2.0-only
headers:
- foo.h
prelude: []
pkg: foo
crate: ''
errmsg: foo_errmsg
abi: Linux-x86_64
entities:
- key: include
name: stdbool.h
- key: include
name: stddef.h
- key: include
name: stdint.h
- key: include
name: sys/types.h
- key: define
name: FOO_NAME
value:
key: str
value: foo
doc:
brief: Name of the library
- key: define
name: FOO_MAGIC
value:
key: int
value: 44252
base: 16
doc:
brief: A hexadecimal constant
- key: define
name: FOO_VERSION_MAJOR
value:
key: int
value: 1
doc:
brief: Major version
- key: define
name: FOO_VERSION_MINOR
value:
key: int
value: 2
doc:
brief: Minor version
- key: define
name: FOO_VERSION_PATCH
value:
key: int
value: 3
doc:
brief: Patch version
- key: define
name: FOO_POINTS_MAX
value:
key: int
value: 8
doc:
brief: Points a handle holds at most
- key: define
name: FOO_DEFAULT_SHAPE_SIDES
value:
key: int
value: 8
doc:
brief: A constant, by name
- key: define
name: FOO_STATUS_CODE_PENDING
value:
key: int
value: 1
base: 16
doc:
brief: A count is submitted and not yet completed; bit 0 of 'code'
- key: define
name: FOO_STATUS_CODE_POINTS
value:
key: int
value: 4080
base: 16
doc:
brief: Points held; bits 11:4 of 'code'
- key: define
name: FOO_STATUS_CODE_FULL
value:
key: int
value: 32768
base: 16
doc:
brief: The handle holds FOO_POINTS_MAX points; bit 15 of 'code'
- key: enum_decl
name: foo_shape
members:
- name: FOO_SHAPE_NONE
value: -1
doc:
brief: No figure
- name: FOO_SHAPE_POINT
value: 0
doc:
brief: A single point
- name: FOO_SHAPE_LINE
value: 1
doc:
brief: Two points
- name: FOO_SHAPE_POLYGON
value: 2
doc:
brief: Three points or more
underlying:
key: builtin
name: int
doc:
brief: Kinds of figure
- key: enum_decl
name: foo_option
members:
- name: FOO_OPTION_CLOSED
value: 1
doc:
brief: The last corner connects to the first
- name: FOO_OPTION_FILLED
value: 2
doc:
brief: The inside is filled
underlying:
key: builtin
name: unsigned int
doc:
brief: Options of a figure, combined as bits
- key: struct_decl
name: foo_handle
fields: []
doc:
brief: A collection of points, opened with foo_open() and closed with foo_close()
- key: struct_decl
name: foo_point
fields:
- name: x
typ:
key: builtin
name: int32_t
offset: 0
doc:
brief: Horizontal position
- name: y
typ:
key: builtin
name: int32_t
offset: 32
doc:
brief: Vertical position
size: 8
align: 4
doc:
brief: A point on the plane
- key: typedef_decl
name: foo_visit_cb
typ:
key: pointer
to:
key: function
ret:
key: builtin
name: int
params:
- name: arg
typ:
key: pointer
to:
key: builtin
name: void
- name: point
typ:
key: pointer
to:
key: record
tag: struct
name: foo_point
const: true
doc:
brief: Called back with each point visited
params:
arg: The argument given along with the callback
point: The point visited
returns: 0 to go on, anything else to stop
- key: typedef_decl
name: foo_done_cb
typ:
key: pointer
to:
key: function
ret:
key: builtin
name: void
params:
- name: arg
typ:
key: pointer
to:
key: builtin
name: void
- name: count
typ:
key: builtin
name: size_t
doc:
brief: Called back when a count submitted completes
params:
arg: The argument given along with the callback
count: The number of points when it completed
- key: typedef_decl
name: foo_added_cb
typ:
key: pointer
to:
key: function
ret:
key: builtin
name: void
params:
- name: arg
typ:
key: pointer
to:
key: builtin
name: void
- name: point
typ:
key: pointer
to:
key: record
tag: struct
name: foo_point
const: true
doc:
brief: Called back with each point added to a handle watched
params:
arg: The argument given along with the callback
point: The point added
- key: struct_decl
name: foo_visitor
fields:
- name: visit
typ:
key: typedef
name: foo_visit_cb
offset: 0
doc:
brief: Called for each point
- name: arg
typ:
key: pointer
to:
key: builtin
name: void
offset: 64
doc:
brief: Given to 'visit'
size: 16
align: 8
doc:
brief: A callback and its argument
- key: struct_decl
name: foo_scalars
fields:
- name: flag
typ:
key: builtin
name: bool
offset: 0
doc:
brief: bool
- name: letter
typ:
key: builtin
name: char
offset: 8
doc:
brief: char
- name: schar
typ:
key: builtin
name: signed char
offset: 16
doc:
brief: signed char
- name: uchar
typ:
key: builtin
name: unsigned char
offset: 24
doc:
brief: unsigned char
- name: s
typ:
key: builtin
name: short
offset: 32
doc:
brief: short
- name: us
typ:
key: builtin
name: unsigned short
offset: 48
doc:
brief: unsigned short
- name: i
typ:
key: builtin
name: int
offset: 64
doc:
brief: int
- name: ui
typ:
key: builtin
name: unsigned int
offset: 96
doc:
brief: unsigned int
- name: l
typ:
key: builtin
name: long
offset: 128
doc:
brief: long
- name: ul
typ:
key: builtin
name: unsigned long
offset: 192
doc:
brief: unsigned long
- name: ll
typ:
key: builtin
name: long long
offset: 256
doc:
brief: long long
- name: ull
typ:
key: builtin
name: unsigned long long
offset: 320
doc:
brief: unsigned long long
- name: f
typ:
key: builtin
name: float
offset: 384
doc:
brief: float
- name: d
typ:
key: builtin
name: double
offset: 448
doc:
brief: double
- name: i8
typ:
key: builtin
name: int8_t
offset: 512
doc:
brief: int8_t
- name: i16
typ:
key: builtin
name: int16_t
offset: 528
doc:
brief: int16_t
- name: i32
typ:
key: builtin
name: int32_t
offset: 544
doc:
brief: int32_t
- name: i64
typ:
key: builtin
name: int64_t
offset: 576
doc:
brief: int64_t
- name: u8
typ:
key: builtin
name: uint8_t
offset: 640
doc:
brief: uint8_t
- name: u16
typ:
key: builtin
name: uint16_t
offset: 656
doc:
brief: uint16_t
- name: u32
typ:
key: builtin
name: uint32_t
offset: 672
doc:
brief: uint32_t
- name: u64
typ:
key: builtin
name: uint64_t
offset: 704
doc:
brief: uint64_t
- name: iptr
typ:
key: builtin
name: intptr_t
offset: 768
doc:
brief: intptr_t
- name: uptr
typ:
key: builtin
name: uintptr_t
offset: 832
doc:
brief: uintptr_t
- name: size
typ:
key: builtin
name: size_t
offset: 896
doc:
brief: size_t
- name: ssize
typ:
key: builtin
name: ssize_t
offset: 960
doc:
brief: ssize_t
- name: diff
typ:
key: builtin
name: ptrdiff_t
offset: 1024
doc:
brief: ptrdiff_t
size: 136
align: 8
doc:
brief: A value of every kind of scalar
- key: struct_decl
name: foo_figure
fields:
- name: shape
typ:
key: builtin
name: uint32_t
offset: 0
doc:
brief: One of enum foo_shape
- name: options
typ:
key: builtin
name: uint32_t
offset: 32
doc:
brief: Bits of enum foo_option
- name: origin
typ:
key: record
tag: struct
name: foo_point
offset: 64
doc:
brief: Where the figure is
- name: corners
typ:
key: array
of:
key: record
tag: struct
name: foo_point
length: 4
offset: 128
doc:
brief: The corners, relative to 'origin'
- name: ncorners
typ:
key: builtin
name: uint8_t
offset: 384
doc:
brief: How many of 'corners' are used
- name: name
typ:
key: array
of:
key: builtin
name: char
length: 16
offset: 392
doc:
brief: Name of the figure
- name: grid
typ:
key: array
of:
key: array
of:
key: builtin
name: int16_t
length: 3
length: 2
offset: 528
doc:
brief: A two-dimensional array
- name: label
typ:
key: pointer
to:
key: builtin
name: char
const: true
offset: 640
doc:
brief: A string, NULL when there is none
- name: scale
typ:
key: builtin
name: float
offset: 704
doc:
brief: Scale of the figure
- name: area
typ:
key: builtin
name: double
offset: 768
doc:
brief: Area of the figure
size: 104
align: 8
doc:
brief: 'A figure: its kind, where it is, and its corners'
- key: union_decl
name: foo_value
fields:
- name: i
typ:
key: builtin
name: int32_t
offset: 0
doc:
brief: Signed
- name: u
typ:
key: builtin
name: uint32_t
offset: 0
doc:
brief: Unsigned
- name: point
typ:
key: record
tag: struct
name: foo_point
offset: 0
doc:
brief: A point, its 'x' sharing the bits of 'i'
size: 8
align: 4
doc:
brief: A 32-bit value, read as signed, as unsigned, or as the 'x' of a point
- key: struct_decl
name: foo_wire
fields:
- name: kind
typ:
key: builtin
name: uint8_t
offset: 0
doc:
brief: One of enum foo_shape
- name: length
typ:
key: builtin
name: uint32_t
offset: 8
doc:
brief: At offset 1
- name: at
typ:
key: record
tag: struct
name: foo_point
offset: 40
doc:
brief: A point, at offset 5
- name: pair
typ:
key: array
of:
key: builtin
name: uint16_t
length: 2
offset: 104
doc:
brief: An array, at offset 13
size: 17
align: 1
packed: true
doc:
brief: 'A record laid out without padding, as a wire format is: no field after the first
is aligned'
- key: struct_decl
name: foo_status
fields:
- name: code
typ:
key: builtin
name: uint16_t
offset: 0
masks:
- name: pending
define: FOO_STATUS_CODE_PENDING
lo: 0
width: 1
doc:
brief: A count is submitted and not yet completed; bit 0 of 'code'
- name: points
define: FOO_STATUS_CODE_POINTS
lo: 4
width: 8
doc:
brief: Points held; bits 11:4 of 'code'
- name: full
define: FOO_STATUS_CODE_FULL
lo: 15
width: 1
doc:
brief: The handle holds FOO_POINTS_MAX points; bit 15 of 'code'
doc:
brief: Status code, see FOO_STATUS_CODE_*
- name: max
typ:
key: builtin
name: uint16_t
offset: 16
doc:
brief: Points the handle holds at most
size: 4
align: 2
doc:
brief: The status of a handle, its code a field of bits
- key: function_decl
name: foo_version
ret:
key: pointer
to:
key: builtin
name: char
const: true
doc:
brief: The version of the library
returns: The version, as "MAJOR.MINOR.PATCH"
- key: function_decl
name: foo_errmsg
ret:
key: pointer
to:
key: builtin
name: char
const: true
doc:
brief: Why the call that failed last on the calling thread failed
description: A function that returns a negative errno keeps a message saying what the
errno does not, such as the name of the handle that is full. The meta names this function
as 'errmsg', so that the error of a binding holds the message.
returns: The message, owned by the library and valid until the next call fails on the
calling thread; "" when no call has failed
- key: function_decl
name: foo_open
ret:
key: builtin
name: int
params:
- name: name
typ:
key: pointer
to:
key: builtin
name: char
const: true
- name: handle
typ:
key: pointer
to:
key: pointer
to:
key: record
tag: struct
name: foo_handle
direction: out
errno: true
doc:
brief: Open a handle holding no points
params:
name: Name of the handle, copied
handle: Set to the handle opened
directions:
name: in
handle: out
returns: 0 on success, -EINVAL when 'name' or 'handle' is NULL, -ENOMEM when memory ran
out
tags:
errno: ''
- key: function_decl
name: foo_close
ret:
key: builtin
name: void
params:
- name: handle
typ:
key: pointer
to:
key: record
tag: struct
name: foo_handle
nullable: true
destroys: handle
doc:
brief: Close a handle
params:
handle: The handle to close, NULL is ignored
tags:
nullable: handle
destroys: handle
- key: function_decl
name: foo_name
ret:
key: pointer
to:
key: builtin
name: char
const: true
params:
- name: handle
typ:
key: pointer
to:
key: record
tag: struct
name: foo_handle
const: true
doc:
brief: The name the handle was opened with
params:
handle: The handle
returns: The name, owned by the handle
- key: function_decl
name: foo_point_add
ret:
key: builtin
name: int
params:
- name: handle
typ:
key: pointer
to:
key: record
tag: struct
name: foo_handle
- name: point
typ:
key: pointer
to:
key: record
tag: struct
name: foo_point
const: true
errno: true
doc:
brief: Add a point to the handle
params:
handle: The handle
point: The point to add, copied
directions:
point: in
returns: 0 on success, -ENOSPC when the handle holds FOO_POINTS_MAX points
tags:
errno: ''
- key: function_decl
name: foo_point_add_many
ret:
key: builtin
name: ssize_t
params:
- name: handle
typ:
key: pointer
to:
key: record
tag: struct
name: foo_handle
- name: points
typ:
key: pointer
to:
key: record
tag: struct
name: foo_point
const: true
length: points_len
- name: points_len
typ:
key: builtin
name: size_t
errno: true
doc:
brief: Add points to the handle, as many as it has room for
params:
handle: The handle
points: The points to add, copied
points_len: The number of points
directions:
points: in
returns: The number of points added, -ENOSPC when there was room for none
arrays:
- points
tags:
errno: ''
- key: function_decl
name: foo_point_count
ret:
key: builtin
name: size_t
params:
- name: handle
typ:
key: pointer
to:
key: record
tag: struct
name: foo_handle
const: true
doc:
brief: The number of points held
params:
handle: The handle
returns: The number of points
- key: function_decl
name: foo_point_get
ret:
key: pointer
to:
key: record
tag: struct
name: foo_point
const: true
params:
- name: handle
typ:
key: pointer
to:
key: record
tag: struct
name: foo_handle
const: true
- name: idx
typ:
key: builtin
name: size_t
nullable: true
doc:
brief: A point held by the handle
params:
handle: The handle
idx: Index of the point
returns: The point, NULL when 'idx' is past the last one
tags:
nullable: return
- key: function_decl
name: foo_point_copy
ret:
key: builtin
name: ssize_t
params:
- name: handle
typ:
key: pointer
to:
key: record
tag: struct
name: foo_handle
const: true
- name: points
typ:
key: pointer
to:
key: record
tag: struct
name: foo_point
direction: out
length: points_len
- name: points_len
typ:
key: builtin
name: size_t
errno: true
doc:
brief: Copy the points held, as many as fit
params:
handle: The handle
points: Where to copy the points to
points_len: The number of points that fit
directions:
points: out
returns: The number of points copied
arrays:
- points
tags:
errno: ''
- key: function_decl
name: foo_point_watch
ret:
key: builtin
name: int
params:
- name: handle
typ:
key: pointer
to:
key: record
tag: struct
name: foo_handle
- name: added
typ:
key: typedef
name: foo_added_cb
lifetime: handle
- name: arg
typ:
key: pointer
to:
key: builtin
name: void
nullable: true
context: added
errno: true
doc:
brief: Watch the points added to the handle, from now until it is closed
params:
handle: The handle
added: Called with each point added, until the handle is closed
arg: Given to 'added'
returns: 0 on success, -EBUSY when the handle is watched already
tags:
nullable: arg
lifetime: added handle
errno: ''
- key: function_decl
name: foo_point_visit
ret:
key: builtin
name: ssize_t
params:
- name: handle
typ:
key: pointer
to:
key: record
tag: struct
name: foo_handle
- name: visit
typ:
key: typedef
name: foo_visit_cb
lifetime: call
- name: arg
typ:
key: pointer
to:
key: builtin
name: void
nullable: true
context: visit
errno: true
doc:
brief: Visit the points in the order they were added
params:
handle: The handle
visit: Called for each point, until it returns non-zero
arg: Given to 'visit'
returns: The number of points visited, -EINVAL when 'visit' is NULL
tags:
nullable: arg
lifetime: visit call
errno: ''
- key: function_decl
name: foo_point_visit_with
ret:
key: builtin
name: ssize_t
params:
- name: handle
typ:
key: pointer
to:
key: record
tag: struct
name: foo_handle
- name: visitor
typ:
key: pointer
to:
key: record
tag: struct
name: foo_visitor
const: true
errno: true
doc:
brief: Visit the points with a visitor; as foo_point_visit()
params:
handle: The handle
visitor: The callback and its argument
directions:
visitor: in
returns: The number of points visited, -EINVAL when the callback is NULL
tags:
errno: ''
- key: function_decl
name: foo_count_submit
ret:
key: builtin
name: int
params:
- name: handle
typ:
key: pointer
to:
key: record
tag: struct
name: foo_handle
- name: done
typ:
key: typedef
name: foo_done_cb
lifetime: once
- name: arg
typ:
key: pointer
to:
key: builtin
name: void
nullable: true
context: done
errno: true
doc:
brief: Submit a count of the points, completed by foo_count_complete()
params:
handle: The handle
done: Called once, by foo_count_complete(), with the number of points
arg: Given to 'done'
returns: 0, -EBUSY when a count is submitted and not yet completed
tags:
nullable: arg
lifetime: done once
errno: ''
- key: function_decl
name: foo_count_complete
ret:
key: builtin
name: size_t
params:
- name: handle
typ:
key: pointer
to:
key: record
tag: struct
name: foo_handle
doc:
brief: Complete the count submitted, if any, calling its callback
params:
handle: The handle
returns: The number of counts completed, 0 or 1
- key: function_decl
name: foo_status_get
ret:
key: builtin
name: void
params:
- name: handle
typ:
key: pointer
to:
key: record
tag: struct
name: foo_handle
const: true
- name: status
typ:
key: pointer
to:
key: record
tag: struct
name: foo_status
direction: out
doc:
brief: The status of the handle
params:
handle: The handle
status: The status to fill in
directions:
status: out
- key: function_decl
name: foo_scalars_fill
ret:
key: builtin
name: void
params:
- name: scalars
typ:
key: pointer
to:
key: record
tag: struct
name: foo_scalars
direction: out
doc:
brief: Fill in a value of every kind of scalar, the limits of the fixed-width ones
params:
scalars: The values to fill in
directions:
scalars: out
- key: function_decl
name: foo_figure_fill
ret:
key: builtin
name: int
params:
- name: figure
typ:
key: pointer
to:
key: record
tag: struct
name: foo_figure
direction: out
- name: shape
typ:
key: builtin
name: uint32_t
errno: true
doc:
brief: Fill in a figure of the given shape
params:
figure: The figure to fill in
shape: One of enum foo_shape
directions:
figure: out
returns: 0 on success, -EINVAL when 'shape' is none of enum foo_shape
tags:
errno: ''
- key: function_decl
name: foo_value_set
ret:
key: builtin
name: void
params:
- name: value
typ:
key: pointer
to:
key: record
tag: union
name: foo_value
direction: out
- name: i
typ:
key: builtin
name: int32_t
doc:
brief: Set a value, clearing the bits it does not use
params:
value: The value to set
i: What to set it to
directions:
value: out
- key: function_decl
name: foo_wire_fill
ret:
key: builtin
name: void
params:
- name: wire
typ:
key: pointer
to:
key: record
tag: struct
name: foo_wire
direction: out
doc:
brief: Fill in a packed record
params:
wire: The record to fill in
directions:
wire: out
Implementation¶
Parse a C header into the yace IR
The header describes an FFI boundary in a subset of C99. Any header is parsed,
also one outside the subset: everything that can be represented is, and every
place the header steps outside the subset is reported as a
yace.ir.diagnostics.Diagnostic. Nothing is dropped or changed without
one, so the IR of a header outside the subset is usable, and the diagnostics say
what to change for it to be within.
CParserparses a header into ayace.ir.model.Modelc_to_yace()writes the IR and the diagnostics of headers to files
- class yace.ir.cparser.CParser(args: List[str] | None = None)¶
Wraps libclang; parse a header with
parse()- parse(paths, meta: dict | None = None, prelude: List[str] | None = None)¶
Parse the header, or the headers, at ‘paths’ as one API; returns the (Model, [Diagnostic]). What the headers declare is in the model, and what any other header declares is external. The system headers named in ‘prelude’, such as ‘stdio.h’, are included ahead of them.
- exception yace.ir.cparser.MissingHeader¶
A header yace includes itself, of the C library or of the compiler, is not found; every layout would then be guessed, so nothing is parsed
- exception yace.ir.cparser.Unsupported¶
A type that the IR cannot represent; the message says which
- yace.ir.cparser.actual_layout(cursor) tuple¶
The size, alignment and field offsets, in bytes, of the record
- yace.ir.cparser.attribute(cursor) str¶
The name of an attribute, from its tokens where libclang has none
- yace.ir.cparser.c_to_yace(paths: List[Path], output: Path, meta: dict | None = None, args=None, prelude: List[str] | None = None) Tuple[Model, List[Diagnostic]]¶
Parse the headers in ‘paths’ as one API, after the system headers named in ‘prelude’, writing its IR to ‘<output>/<prefix>.yaml’ and its diagnostics to ‘<output>/<prefix>.status’. The prefix is that of the meta, or else the name of the first header.
- yace.ir.cparser.calling_convention(ctype) int¶
The calling convention of the function type ‘ctype’, by libclang’s clang_getFunctionTypeCallingConv(), which its Python bindings do not wrap
- yace.ir.cparser.comment_before(lines: List[str], lineno: int) str | None¶
The Doxygen comment ending on the line above ‘lineno’, or trailing on it; libclang does not attach comments to macros, so they are found in the source
- yace.ir.cparser.decl_key(cursor) Tuple[str, int]¶
Identifies a declaration, also an anonymous one, within a translation unit
- yace.ir.cparser.element(ctype)¶
The type ‘ctype’ is made of, through pointers and arrays
- yace.ir.cparser.has_flexible(ctype) bool¶
Whether ‘ctype’ is a struct ending in a flexible array member, or a union holding one, which ISO C allows neither in an array nor in a struct
- yace.ir.cparser.is_unnamed(cursor) bool¶
Whether the record or enum has no tag; libclang spells such a one ‘’ or ‘(anonymous …)’ / ‘(unnamed …)’, and is_anonymous() misses typedef’d ones
- yace.ir.cparser.natural_layout(cursor) tuple | None¶
The layout that the types of the record’s fields give it, as C lays them out without attributes or ‘#pragma pack’, as actual_layout() gives one; None where it is not computed: of a record of bit-fields, or with a field whose size or alignment libclang does not give
- yace.ir.cparser.qualify(typ: Annotated[Builtin | Pointer | Array | Record | EnumRef | TypedefRef | FunctionType, FieldInfo(annotation=NoneType, required=True, discriminator='key')])¶
Make ‘typ’ const; C qualifies an array by its elements
- yace.ir.cparser.unescape(text: str) str¶
The value of the body of a C string literal, its escapes decoded; bytes that are not UTF-8 are kept as the surrogates of ‘surrogateescape’
Semantics¶
What C cannot say about an FFI boundary, taken from the documentation of its
functions, and checked: which way each pointer goes, which may be NULL, which
integer is the length of which pointer, which pointer is to a record of
arguments, which void * is the context of which callback, which functions
report errors as a negative errno, and which destroy the handles others create.
The targets need this to bind the API idiomatically rather than only as raw calls: to return what a function writes through an [out] pointer, to raise or return an error, to release a handle when it goes out of scope, and to pass a closure as a callback. Each is a rule of the C subset, or a tag in the Doxygen comment of the function:
@param[in],@param[out],@param[in,out]Doxygen’s own: whether the function reads what the pointer points to, writes it, or both. A pointer documented with neither is read,
[in].@recparam name textAs
@param, of a record of arguments:nameis a pointer to a const struct, and its size is thesize_t<name>_nbytes, or the parameter that@nbytes_at{size}in the text names. The function’s name ends in_sized, and a static inline function of the name without it passessizeof.@arrparam name textAs
@param, of an array: its length is the unsigned integer<name>_len, or the parameter that@len_at{length}in the text names. Of an [out] array, the length is the capacity, and an [out] pointer to an unsigned integer<name>_nwritten, or the one@nwritten_at{count}names, is the number of elements the function wrote. Where<name>_lenor<name>_nwrittenis a parameter, no reference names another.@nullable name ...The named pointer parameters may be NULL;
returnnames what the function returns. Every other pointer must not be NULL.@errnoThe function returns a negative errno on failure, and zero or more on success. It returns a signed integer.
@errno partialsays that the function writes its [out] parameters also when it fails, so that what it wrote is not lost. It returnsint, has an [out] parameter, and none is a handle.@destroys nameThe function releases the handle given as
name, its only parameter; after it, the handle is not used again. An opaque record created through an [out] pointer must have one.@lifetime callback call|once|handle ...How long the library may invoke the callback, a promise only the author of the header can make:
call, only during the call;once, at most once, after the call, and not at all when it fails;handle, any number of times, until the handle the function is a method of is destroyed, and not at all when the call fails. The tag takes pairs, one for every callback. A callback is invoked during a call into the library, on its thread:call, during the call itself; the others, of a method, during a later call given the same handle, or of a function, during any later call.@nobindThe function is not bound: the parser leaves it out of the IR, before reading its types, which may be outside the C subset, such as the
FILE *of a printer. It takes nothing.
A void * parameter right after a callback is the callback’s context, as the
callback-context rule requires; a returned const char * is borrowed, as the
string-return rule requires.
Buffers of memory follow names, as the buffer-lifecycle rule requires:
<stem>_alloc returns a void * buffer of size_t nbytes bytes;
<stem>_free frees it, taking it as its one void *; and
<stem>_realloc, where it exists, resizes it, taking it and nbytes.
<stem>_register, documented @errno, registers size_t nbytes bytes of
the caller’s at its one void *, until <stem>_unregister takes that
address. The other parameters of <stem>_free, <stem>_realloc and
<stem>_unregister are named, and typed, as parameters of
<stem>_alloc or <stem>_register, which the bindings pass them again.
- class yace.ir.semantics.Semantics(entities: list, report: Callable[[str, str, object], None], inlines: Iterable[str] = ())¶
Applies the tags of the functions to the IR, reporting what is wrong
- arrparam(func: Function, name: str, annotation, counted: set)¶
Apply the @arrparam ‘name’ of ‘func’: a pointer, and its length, an unsigned integer, by @len_at{} or ‘<name>_len’. An [out] one may have a count written, an [out] pointer to an unsigned integer, by @nwritten_at{} or ‘<name>_nwritten’; ‘counted’ holds those already taken
- buffers(cursors: Dict[str, object])¶
Apply the buffer pattern: mark what each function of it does with a buffer, and report the allocations and registrations nothing releases
- callback(typ) FunctionType | None¶
The function type of ‘typ’, when it is a pointer to a function
- is_pointer(typ) bool¶
Whether ‘typ’ is a pointer, also one by a typedef of a callback
- lifecycle(cursors: Dict[str, object])¶
Report the records created through an [out] pointer, never destroyed
- misplaced(entity, cursor)¶
Report the @arrparam, @recparam and references in the comments of ‘entity’, and of its fields or members, which is no function
- paired(func: Function, name: str, command: str, suffix: str, annotation, required: bool = True) Param | None¶
The parameter that the @<command>{} in the text of ‘name’ names, or else the one named ‘<name><suffix>’; None, reported where ‘required’, when there is neither, and reported when both are parameters and differ, as the name of the one would mislead
- partial(func: Function, annotation) bool¶
Whether ‘func’ can write its [out] parameters when it fails: ‘func’ has an [out] parameter, none of them is a handle, as the owner of a handle written by a failed call is undefined, and ‘func’ returns int, as a failure returns no count
- points_to_struct(typ) bool¶
Whether ‘typ’ is a pointer to a const struct the headers define, which has a size, also by a typedef
- recparam(func: Function, name: str, annotation, sized: set)¶
Apply the @recparam ‘name’ of ‘func’, a function taking its arguments as a record: ‘name’ is an [in] pointer to a const struct the headers define, and its size is a size_t, by @nbytes_at{} or ‘<name>_nbytes’; ‘sized’ holds the sizes already taken. The record’s parameter then holds the size’s name
- renamed_record(typ) bool¶
Whether ‘typ’ reaches a record only through a typedef of another name, such as
foo_t *fortypedef struct foo_s foo_t;