The Fuchsia device interfaces are expressed as FIDL protocols. These FIDL definitions should conform to the FIDL Readability Rubric.
Prefer descriptive identifiers. If you are using domain-specific abbreviations, document the expansion or provide a reference for further information.
Every identifier that is defined as part of a protocol must be documented with a comment explaining its interpretation (in the case of fields, types, and parameters) or behavior (in the case of methods).
All device interface protocols must use the [Layout = "Simple"] attribute. This restriction exists to allow ease of implementing protocols in any of our supported languages for driver development.
Use a zx.status return to represent success and failure. If a method should not be able to fail, do not provide a zx.status return. If the method returns multiple values, the zx.status should come first.
All arrays, strings, and vectors must be of bounded length. For arbitrarily selected bounds, prefer to use a const identifier as the length so that protocol consumers can programmatically inspect the length.
Prefer enums with explicit sizes (e.g. enum Foo : uint32 { ... }) to plain integer types when a field has a constrained set of non-arithmetic values.
If your protocol has a bitfield, represent its values using bits values. For details, see the “bits” topic in the readability rubric.
Some interface protocols may negotiate a non-channel protocol as a performance optimization (e.g. the zircon.ethernet.Device's GetFifos/SetIOBuffer methods). FIDL does not currently support expressing these protocols. For now, represent any shared data structures with struct definitions and provide detailed documentation about participation in the protocol. Packed structures are not currently supported.
