The Fuchsia device interfaces are expressed as FIDL interfaces. 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 an interface 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 interfaces must use the [Layout = "Simple"] attribute. This restriction exists to allow ease of implementing interfaces 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 interface 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 interface has a bitfield, represent its values using const values. They should be grouped together in the FIDL file and have a common prefix. For example:
// Bit definitions for Info.features field // If present, this device represents WLAN hardware. const uint32 INFO_FEATURE_WLAN = 0x00000001; // If present, this device is synthetic (i.e. not backed by hardware). const uint32 INFO_FEATURE_SYNTH = 0x00000002; // If present, this device will receive all messages it sends. const uint32 INFO_FEATURE_LOOPBACK = 0x00000004;
If FIDL gains bitfield support, this guidance will be updated.
Some interfaces 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.
