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.
Items described in this section MUST be met for bindings to be considered conformant.
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.
Items described in this section SHOULD be met for bindings to be considered conformant.
TODO
Items described in this section MAY be met for bindings to be considered conformant.
It is RECOMMENDED to support the following operators over generated values:
&
|
^
~
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.:
<<
or >>
>>>
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/xunions 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.