FIDL bindings specification

This document is a specification of requirements on the Fuchsia Interface Definition Language (FIDL) bindings.

In this document, the following keywords are to be interpreted as described in RFC2119: MAY, MUST, MUST NOT, OPTIONAL, RECOMMENDED, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT.

Requirements

Items described in this section MUST be met for bindings to be considered conformant.

Generated Code Indication

A comment must be placed at the top of machine-generated code to indicate it is machine generated. For languages with a standard on how to indicate generated sources (as opposed to human-written code), that standard must be followed..

In Go for instance, generated sources must be marked with a comment following the pattern

// Code generated by <tool>; DO NOT EDIT.

Recommendations

Items described in this section SHOULD be met for bindings to be considered conformant.

TODO

Best Practices

Items described in this section MAY be met for bindings to be considered conformant.

Bits Support

It is RECOMMENDED to support the following operators over generated values:

bitwise and, i.e &
bitwise or, i.e |
bitwise exclusive-or, i.e ^
bitwise not, i.e ~

To provide bitwise operations which always result in valid bits values, implementations of bitwise not should further mask the resulting value with the mask of all values. In pseudo code:

~value1   means   mask & ~bits_of(value1)

This mask value is provided in the JSON IR for convenience.

Bindings SHOULD NOT support other operators since they could result in invalid bits value (or risk a non-obvious translation of their meaning), e.g.:

bitwise shifts, i.e << or >>
bitwise unsigned shift, i.e >>>

Union Support

This section applies to flexible unions as well as the soon to be deprecated unions

For languages without union types and literals for these, it is RECOMMENDED to support factory methods for constructing new unions given a value for one of the possible variants. For example, in a C like language, this would allow replacing code like:

my_union_t foo;
foo.set_variant(bar);
do_stuff(foo);

with something like:

do_stuff(my_union_with_variant(bar));

Examples of this for the HLCPP and Go bindings.