1# FIDL: Overview 2 3This document is a description of the Fuchsia Interface Definition Language 4(FIDL) purpose, high-level goals, and requirements. 5 6## Related Documents 7 8* [FIDL: Wire Format Specification] 9* [FIDL: Language Specification] 10* [FIDL: Compiler Specification] 11* [FIDL: C Language Bindings] 12* [FIDL: C++ Language Bindings] 13* [FIDL Examples]: Some small example code used during development 14* [FIDL Tutorial]: A tutorial on using FIDL services in several languages 15 16<!-- Reference links because these are used again below. --> 17 18[FIDL: Wire Format Specification]: wire-format/index.md 19[FIDL: Language Specification]: language.md 20[FIDL: Compiler Specification]: compiler.md 21[FIDL: C Language Bindings]: https://fuchsia.googlesource.com/docs/+/master/development/languages/fidl/c.md 22[FIDL: C++ Language Bindings]: https://fuchsia.googlesource.com/docs/+/master/development/languages/fidl/cpp.md 23[FIDL Examples]: ../../system/host/fidl/examples 24[FIDL Tutorial]: https://fuchsia.googlesource.com/docs/+/master/development/languages/fidl/tutorial.md 25 26[TOC] 27 28## Overview 29 30The Fuchsia Interface Definition Language (FIDL) is the language used to 31describe interprocess communication (IPC) protocols used by programs running on 32the Fuchsia Operating System. FIDL is supported by a toolchain (compiler) and 33runtime support libraries (bindings) to help developers use IPC effectively. 34 35Goals 36 37Fuchsia extensively relies on IPC since it has a microkernel architecture 38wherein most functionality is implemented in user space outside of the kernel, 39including privileged components such as device drivers. Consequently the IPC 40mechanism must be efficient, deterministic, robust, and easy to use. 41 42**IPC efficiency** pertains to the computational overhead required to generate, 43transfer, and consume messages between processes. IPC will be involved in all 44aspects of system operation so it must be efficient. The FIDL compiler must 45generate tight code without excess indirection or hidden costs. It should be at 46least as good as hand-rolled code would be where it matters most. 47 48**IPC determinism** pertains to the ability to perform transactions within a 49known resource envelope. IPC will be used extensively by critical system 50services such as filesystems which serve many clients and which must perform in 51predictable ways. The FIDL wire format must offer strong static guarantees such 52as ensuring that structure size and layout is invariant thereby alleviating the 53need for dynamic memory allocation or complex validation rules. 54 55**IPC robustness** pertains to the need to consider IPC as an essential part of 56the operating system's ABI. Maintaining binary stability is crucial. Mechanisms 57for protocol evolution must be designed conservatively so as not to violate the 58invariants of existing services and their clients, particularly when the need 59for determinism is also considered. The FIDL bindings must perform effective, 60lightweight, and strict validation. 61 62**IPC ease of use** pertains to the fact that IPC protocols are an essential 63part of the operating system's API. It is important to provide good developer 64ergonomics for accessing services via IPC. The FIDL code generator removes the 65burden of writing IPC bindings by hand. Moreover, the FIDL code generator can 66produce different bindings to suit the needs of different audiences and their 67idioms. 68 69TODO: express goal of meeting the needs of different audiences using 70appropriately tailored bindings, eg. system programming native vs. event-driven 71dispatch vs. async calls, etc... say more things about FIDL as our system API, 72SDK concerns, etc. 73 74Requirements 75 76# Purpose 77 78* Describe data structures and interfaces used by IPC protocols on Zircon. 79* Optimized for interprocess communication only; FIDL must not be persisted to 80 disk or used for network transfer across device boundaries. 81* Efficiently transport messages consisting of data (bytes) and capabilities 82 (handles) over Zircon channels between processes running on the same 83 device. 84* Designed specifically to facilitate effective use of Zircon primitives; not 85 intended for use on other platforms; not portable. 86* Offers convenient APIs for creating, sending, receiving, and consuming 87 messages. 88* Perform sufficient validation to maintain protocol invariants (but no more 89 than that). 90 91# Efficiency 92 93* Just as efficient (speed and memory) as using hand-rolled data structures 94 would be. 95* Wire format uses uncompressed native datatypes with host-endianness and 96 correct alignment to support in-place access of message contents. 97* No dynamic memory allocation is required to produce or to consume messages 98 when their size is statically known or bounded. 99* Explicitly handle ownership with move-only semantics. 100* Data structure packing order is canonical, unambiguous, and has minimum 101 padding. 102* Avoid back-patching pointers. 103* Avoid expensive validation. 104* Avoid calculations which may overflow. 105* Leverage pipelining of interface requests for asynchronous operation. 106* Structures are fixed size; variable-size data is stored out-of-line. 107* Structures are not self-described; FIDL files describe their contents. 108* No versioning of structures, but interfaces can be extended with new methods 109 for protocol evolution. 110 111# Ergonomics 112 113* Programming language bindings maintained by Fuchsia team: 114 * C, C++ (native), C++ (idiomatic), Dart, Go, Rust 115* Keeping in mind we might want to support other languages in the future, such 116 as: 117 * Java, Javascript, etc. 118* The bindings and generated code are available in native or idiomatic flavors 119 depending on the intended application. 120* Use compile-time code generation to optimize message serialization, 121 deserialization, and validation. 122* FIDL syntax is familiar, easily accessible, and programming language 123 agnostic. 124* FIDL provides a library system to simplify deployment and use by other 125 developers. 126* FIDL expresses the most common data types needed for system APIs; it does 127 not seek to provide a comprehensive one-to-one mapping of all types offered 128 by all programming languages. 129 130# Implementation 131 132* Compiler is written in C++ to be usable by components built in Zircon. 133 134* Compiler is portable and can be built with a host toolchain. 135 136* We will not support FIDL bindings for any platform other than Fuchsia. 137 138## Where to Find the Code 139 140- [The compiler](../../system/host/fidl) 141- [C bindings](../../system/ulib/fidl) 142- [C++ bindings](https://fuchsia.googlesource.com/garnet/+/master/public/lib/fidl/cpp) 143- [Go bindings](https://fuchsia.googlesource.com/garnet/+/master/public/lib/fidl/go) 144- [Rust bindings](https://fuchsia.googlesource.com/garnet/+/master/public/lib/fidl/rust) 145 146## Constituent Parts of Specification 147 148### FIDL Wire Format 149 150The FIDL wire format specified how FIDL messages are represented in memory for 151transmission over IPC. 152 153The fidl wire format is documented [FIDL: Wire Format Specification]. 154 155### FIDL Language 156 157The FIDL language is the syntax by which interfaces are described in ***.fidl** 158files. 159 160The fidl language is documented [FIDL: Language Specification]. 161 162### FIDL Compiler 163 164The FIDL compiler generates code for programs to use and implement interfaces 165described by the FIDL language. 166 167The fidl compiler is documented [FIDL: Compiler Specification]. 168 169### FIDL Bindings 170 171FIDL bindings are language-specific runtime support libraries and code 172generators which provide APIs for manipulating FIDL data structures and 173interfaces. 174 175Languages-specific topics: 176 177* [FIDL: C Language Bindings] 178* [FIDL: C++ Language Bindings] 179 180Bindings are available in various flavors depending on the language: 181 182* **Native bindings**: designed for highly sensitive contexts such as device 183 drivers and high-throughput servers, leverage in-place access, avoid memory 184 allocation, but may require somewhat more awareness of the constraints of 185 the protocol on the part of the developer. 186* **Idiomatic bindings**: designed to be more developer-friendly by copying 187 data from the wire format into easier to use data types (such as heap-backed 188 strings or vectors), but correspondingly somewhat less efficient as a 189 result. 190 191Bindings offer several various ways of invoking interface methods depending on 192the language: 193 194* **Send/receive**: read or write messages directly to a channel, no built-in 195 wait loop (C) 196* **Callback-based**: received messages are dispatched asynchronously as 197 callbacks on an event loop (C++, Dart) 198* **Port-based**: received messages are delivered to a port or future (Rust) 199* **Synchronous call**: waits for reply and return it (Go, C++ unit tests) 200 201Bindings provide some or all of the following principal operations: 202 203* **Encode**: in-place transform native data structures into the wire format 204 (coupled with validation) 205* **Decode**: in-place transform wire format data into native data structures 206 (coupled with validation) 207* **Copy/Move To Idiomatic Form**: copy contents of native data structures 208 into idiomatic data structures, handles are moved 209* **Copy/Move To Native Form**: copy contents of idiomatic data structures 210 into native data structures, handles are moved 211* **Clone**: copy native or idiomatic data structures (that do not contain 212 move-only types) 213* **Call**: invoke interface method 214 215## Workflow 216 217This section describes the workflow of authors, publishers, and consumers of IPC 218protocols described using FIDL. 219 220# Authoring FIDL 221 222The author of a FIDL based protocol creates one or more ***.fidl files** to 223describe their data structures and interfaces. 224 225FIDL files are grouped into one or more **FIDL libraries** by the author. Each 226library represents a group of logically related functionality with a unique 227library name. FIDL files within the same library implicitly have access to all 228other declarations within the same library. The order of declarations within the 229FIDL files that make up a library is not significant. 230 231FIDL files of one library can access declarations within another FIDL library by 232**importing** the other FIDL module. Importing other FIDL libraries makes their 233symbols available for use thereby enabling the construction of protocols derived 234from them. Imported symbols must be qualified by the library name or by an alias 235to prevent namespace collisions. 236 237# Publishing FIDL 238 239The publisher of a FIDL based protocol is responsible for making FIDL libraries 240available to consumers. For example, the author may disseminate FIDL libraries in 241a public source repository or distribute them as part of an SDK. 242 243Consumers need only point the FIDL compiler at the directory which contains the 244FIDL files for a library (and its dependencies) to generate code for that 245library. The precise details for how this is done will generally be addressed by 246the consumer's build system. 247 248# Consuming FIDL 249 250The consumer of a FIDL based protocol uses the FIDL compiler to generate code 251suitable for use with their language runtime specific bindings. For certain 252language runtimes, the consumer may have a choice of a few different flavors of 253generated code all of which are interoperable at the wire format level but 254perhaps not at the source level. 255 256In the Fuchsia world build environment, generating code from FIDL libraries will 257be done automatically for all relevant languages by individual FIDL build 258targets for each library. 259 260In the Fuchsia SDK environment, generating code from FIDL libraries will be done 261as part of compiling the applications which use them. 262