CABIR

C ABI Representation

Binary format to describe a C ABI and associated metadata.

This is a design document. All described features are currently vaporware and subject to change.

Features

• CABIR files contain at a minimum the necessary function signature/struct layout/etc. information required to call a function from C for all functions on the ABI boundary.

• CABIR files may include metadata that goes beyond the minimum necessary information. For example:

  • Pointer nullability
  • Function parameter names
  • Documentation comments
  • Valid enum values/non-exhaustiveness

• Converting a header file or equivalent in any language to a CABIR file should not lose any metadata.

• Converting a CABIR file to a header file or equivalent for a given language may be lossy depending on the metadata features supported by the language and its type system.

• CABIR files are target-specific. Converting the same C header file into a CABIR file for x86_64 and aarch64 may give different results. This is due to features like comptime and macros.

• It is not expected that a language X -> CABIR -> language X conversion gives the exact same source code. Features like comptime and macros make this impossible.

• Two CABIR files may be compared for compatibility

  • There is no error if one file is missing metadata that the other file specifies. For example one file specifies unknown pointer nullability and the other specifies that the pointer is non-null.
  • There is an error if the files specify conflicting metadata. the types. For example, one file specifies a non-null pointer and the other file specifies a nullable pointer.
  • Errors for conflicting documentation comments/parameter names may be optional.

• To give good error messages on incompatibility, CABIR files may store source information linking function signatures/type declarations in the CABIR file back to the source code in the original language.

Goal

The goal is to close https://github.com/ziglang/zig/issues/20654.

I wrote this design document from first principles after having not read that issue for at least a year. I think it's promising that the proposed design has quite a few parallels with Andrew's original idea.

Nominal Types

A tricky case is nominal types, where we want to allow increased type safety on one side of the ABI than the other. For example, libwayland's struct wl_listener type is represented in zig-wayland by a generic wl.Listener(T) type. Cabir does not have any knowledge of generics however, it sees every concrete wl.Listener(Foo) or wl.Listener(Bar) instance as a distinct type.

Let X and Y be the sets of nominal types on opposite sides of the ABI boundary. The sides are compatible when the relation R ∈ X⨯Y defined by the usage of nominal types in corresponding locations (e.g. as function arguments) has the following properties:

1. R = R1∪R2 where R1∈ X1→Y1, R2∈ Y2→X2
2. X1∩X2=∅, X1⊆X, X2⊆X
3. Y1∩Y2=∅, Y1⊆Y, Y2⊆Y

In prose, a nominal type on side X of the ABI boundary may map to multiple nominal types on side Y. However in that case no other type on side X map to any of the multiple types on side Y. The same property holds in the opposite direction.