1# FIDL: Language Specification 2 3This document is a specification of the Fuchsia Interface Definition Language 4(FIDL) syntax. 5 6See [FIDL: Overview](index.md) for more information about FIDL's overall 7purpose, goals, and requirements, as well as links to related documents. 8 9[TOC] 10 11## Syntax 12 13The Fuchsia Interface Definition Language provides a syntax for declaring named 14constants, enums, structs, unions, and interfaces. These declarations are 15collected into libraries for distribution. 16 17FIDL declarations are stored in plain text UTF-8 files. Each file consists of a 18sequence of semicolon delimited declarations. The order of declarations within a 19FIDL file or among FIDL files within a library is irrelevant. FIDL does not 20require (or support) forward declarations of any kind. 21 22### Tokens 23 24#### Comments 25 26FIDL supports C++-style comments. These go from `//` to the end of the 27line. They may contain UTF-8 content (which is of course ignored). 28 29``` 30// this is a comment 31struct Foo { // so is this 32 int32 f; // and this 33}; // last one! 34``` 35 36#### Document Comments 37 38TODO(TO-504): We will generate online documentation from FIDL 39files. Perhaps the compiler can emit document contents together with 40the declarations in a machine-readable FIDL IR format that could be 41consumed by other tools. 42 43#### Reserved Words 44 45The following keywords are reserved in FIDL. 46 47``` 48array, as, bool, const, enum, float32, float64, handle, int8, int16, 49int32, int64, interface, library, request, string, struct, uint8, uint16, 50uint32, uint64, union, using, vector 51``` 52 53To use these words as identifiers, they must be escaped by prepending an "@". 54For example "interface" is a reserved word but "@interface" is an identifier 55whose name is "interface". 56 57#### Identifiers 58 59FIDL identifiers must match the regex "@?[a-zA-Z_][0-9a-zA-Z]\*". The "@" prefix, 60if present, serves to distinguish identifiers from reserved words in the FIDL 61language. The "@" prefix itself is ignored for the purposes of naming the 62identifier. This allows reserved words in the FIDL language to nevertheless be 63used as identifiers (when escaped with "@"). 64 65Identifiers are case-sensitive. 66 67``` 68// a library named "foo" 69library foo; 70 71// a struct named "Foo" 72struct Foo { }; 73 74// a struct named "struct" 75struct @struct { }; 76``` 77 78#### Qualified Identifiers 79 80FIDL always looks for unqualified symbols within the scope of the current 81library. To reference symbols in other libraries, they must be qualified by 82prefixing the identifier with the library name or alias. 83 84**objects.fidl:** 85 86``` 87 library objects; 88 using textures as tex; 89 90 interface Frob { 91 // "Thing" refers to "Thing" in the "objects" library 92 // "tex.Color" refers to "Color" in the "textures" library 93 Paint(Thing thing, tex.Color color); 94 }; 95 96 struct Thing { 97 string name; 98 }; 99``` 100 101**textures.fidl:** 102 103``` 104 library textures; 105 106 struct Color { 107 uint32 rgba; 108 }; 109``` 110 111#### Literals 112 113FIDL supports the following literal types using C-like syntax: bools, signed 114integers, unsigned integers, floats, strings. 115 116``` 117 const bool BOOL = true; 118 const int32 INT = -333; 119 const uint32 UINT = 42; 120 const uint64 DIAMOND = 0x183c7effff7e3c18; 121 const string STRING = "a string"; 122 const float32 FLOAT = 1.0; 123``` 124 125#### Declaration Separator 126 127FIDL uses the semi-colon **';'** to separate adjacent declarations within the 128file, much like C. 129 130### Libraries 131 132Libraries are named containers of FIDL declarations. 133 134Each library has a name consisting of a dot-delimited identifier. Library names 135appear in [Qualified Identifiers](#qualified-identifiers). 136 137Libraries may declare that they use other libraries with a "using" declaration. 138This allows the library to refer to symbols defined in other libraries upon which 139they depend. Symbols which are imported this way may be accessed either by 140qualifying them with the library name as in _"mozart.geometry.Rect"_ or by 141qualifying them with the library alias as in _"geo.Rect"_. 142 143``` 144 library mozart.composition; 145 using mozart.geometry as geo; 146 using mozart.buffers; 147 148 interface Compositor { ��� }; 149``` 150 151In the source tree, each library consists of a directory with some number of 152**.fidl** files. The name of the directory is irrelevant to the FIDL compiler 153but by convention it should resemble the library name itself. A directory should 154not contain FIDL files for more than one library. 155 156The scope of "library" and "using" declarations is limited to a single file. 157Each individual file within a FIDL library must restate the "library" 158declaration together with any "using" declarations needed by that file. 159 160The library's name may be used by certain language bindings to provide scoping 161for symbols emitted by the code generator. 162 163For example, the C++ bindings generator places declarations for the 164FIDL library "fuchsia.ui" within the C++ namespace 165"fuchsia::ui". Similarly, for languages such as Dart and Rust which 166have their own module system, each FIDL library is compiled as a 167module for that language. 168 169### Types and Type Declarations 170 171#### Primitives 172 173* Simple value types. 174* Not nullable. 175 176The following primitive types are supported: 177 178* Boolean **`bool`** 179* Signed integer **`int8 int16 int32 int64`** 180* Unsigned integer **`uint8 uint16 uint32 uint64`** 181* IEEE 754 Floating-point **`float32 float64`** 182 183Numbers are suffixed with their size in bits, **`bool`** is 1 184byte. 185 186##### Use 187 188``` 189// A record which contains fields of a few primitive types. 190struct Sprite { 191 float32 x; 192 float32 y; 193 uint32 index; 194 uint32 color; 195 bool visible; 196}; 197``` 198 199#### Enums 200 201* Proper enumerated types; bit fields are not valid enums. 202* Discrete subset of named values chosen from an underlying integer primitive 203 type. 204* Not nullable. 205* Enums must have at least one member. 206 207##### Declaration 208 209The ordinal index is **required** for each enum element. The underlying type of 210an enum must be one of: **int8, uint8, int16, uint16, int32, uint32, int64, 211uint64**. If omitted, the underlying type is assumed to be **uint32**. 212 213``` 214// An enum declared at library scope. 215enum Beverage : uint8 { 216 WATER = 0; 217 COFFEE = 1; 218 TEA = 2; 219 WHISKEY = 3; 220}; 221 222// An enum declared at library scope. 223// Underlying type is assumed to be uint32. 224enum Vessel { 225 CUP = 0; 226 BOWL = 1; 227 TUREEN = 2; 228 JUG = 3; 229}; 230``` 231 232##### Use 233 234Enum types are denoted by their identifier, which may be qualified if needed. 235 236``` 237// A record which contains two enum fields. 238struct Order { 239 Beverage beverage; 240 Vessel vessel; 241}; 242``` 243 244#### Arrays 245 246* Fixed-length sequences of homogeneous elements. 247* Elements can be of any type including: primitives, enums, arrays, strings, 248 vectors, handles, structs, unions. 249* Not nullable themselves; may contain nullable types. 250 251##### Use 252 253Arrays are denoted **`array<T>:n`** where _T_ can 254be any FIDL type (including an array) and _n_ is a positive 255integer constant expression which specified the number of elements in 256the array. 257 258``` 259// A record which contains some arrays. 260struct Record { 261 // array of exactly 16 floating point numbers 262 array<float32>:16 matrix; 263 264 // array of exactly 10 arrays of 4 strings each 265 array<array<string>:4>:10 form; 266}; 267``` 268 269#### Strings 270 271* Variable-length sequence of UTF-8 encoded characters representing text. 272* Nullable; null strings and empty strings are distinct. 273* Can specify a maximum size, eg. **`string:40`** for a 274 maximum 40 byte string. 275 276##### Use 277 278Strings are denoted as follows: 279 280* **`string`** : non-nullable string (validation error 281 occurs if null is encountered) 282* **`string?`** : nullable string 283* **`string:N, string:N?`** : string with maximum 284 length of _N_ bytes 285 286``` 287// A record which contains some strings. 288struct Record { 289 // title string, maximum of 40 bytes long 290 string:40 title; 291 292 // description string, may be null, no upper bound on size 293 string? description; 294}; 295``` 296 297#### Vectors 298 299* Variable-length sequence of homogeneous elements. 300* Nullable; null vectors and empty vectors are distinct. 301* Can specify a maximum size, eg. **`vector<T>:40`** for a 302 maximum 40 element vector. 303* There is no special case for vectors of bools. Each bool element takes one 304 byte as usual. 305 306##### Use 307 308Vectors are denoted as follows: 309 310* **`vector<T>`** : non-nullable vector of element type 311 _T_ (validation error occurs if null is encountered) 312* **`vector<T>?`** : nullable vector of element type 313 _T_ 314* **`vector<T>:N, vector<T>:N?`** : vector with 315 maximum length of _N_ elements 316 317_T_ can be any FIDL type. 318 319``` 320// A record which contains some vectors. 321struct Record { 322 // a vector of up to 10 integers 323 vector<int32>:10 params; 324 325 // a vector of bytes, no upper bound on size 326 vector<uint8> blob; 327 328 // a nullable vector of up to 24 strings 329 vector<string>:24? nullable_vector_of_strings; 330 331 // a vector of nullable strings 332 vector<string?> vector_of_nullable_strings; 333 334 // a vector of vectors of arrays of floating point numbers 335 vector<vector<array<float32>:16>> complex; 336}; 337``` 338 339#### Handles 340 341* Transfers a Zircon capability by handle value. 342* Stored as a 32-bit unsigned integer. 343* Nullable by encoding as a zero-valued handle. 344 345##### Use 346 347Handles are denoted: 348 349* **`handle`** : non-nullable Zircon handle of 350 unspecified type 351* **`handle?`** : nullable Zircon handle of 352 unspecified type 353* **`handle<H>`** : non-nullable Zircon handle 354 of type _H_ 355* **`handle<H>?`** : nullable Zircon handle of 356 type _H_ 357 358_H_ can be one of: `channel, event, eventpair, fifo, job, 359process, port, resource, socket, thread, vmo`. New types will 360be added to the fidl language as they are added to Zircon. 361 362``` 363// A record which contains some handles. 364struct Record { 365 // a handle of unspecified type 366 handle h; 367 368 // an optional channel 369 handle<channel>? c; 370}; 371``` 372 373#### Structs 374 375* Record type consisting of a sequence of typed fields. 376* Declaration is not intended to be modified once deployed; use interface 377 extension instead. 378* Reference may be nullable. 379* Structs contain one or more members. A struct with no members is 380 difficult to represent in C and C++ as a zero-sized type. Fidl 381 therefore chooses to require all structs to have nonzero size. 382 383##### Declaration 384 385``` 386struct Point { 387 float32 x; 388 float32 y; 389}; 390struct Color { 391 float32 r; 392 float32 g; 393 float32 b; 394}; 395``` 396 397#### Use 398 399Structs are denoted by their declared name (eg. **Circle**) and nullability: 400 401* **`Circle`** : non-nullable Circle 402* **`Circle?`** : nullable Circle 403 404``` 405struct Circle { 406 bool filled; 407 Point center; // Point will be stored in-line 408 float32 radius; 409 Color? color; // Color will be stored out-of-line 410 bool dashed; 411}; 412``` 413 414#### Unions 415 416* Tagged option type consisting of tag field and variadic contents. 417* Declaration is not intended to be modified once deployed; use interface 418 extension instead. 419* Reference may be nullable. 420* Unions contain one or more members. A union with no members would have 421 no inhabitants and make little sense in a wire format. 422 423##### Declaration 424 425``` 426union Pattern { 427 Color color; 428 Texture texture; 429}; 430struct Color { 431 float32 r; 432 float32 g; 433 float32 b; 434}; 435struct Texture { string name; }; 436``` 437 438##### Use 439 440Union are denoted by their declared name (eg. **Pattern**) and nullability: 441 442* **`Pattern`** : non-nullable Shape 443* **`Pattern?`** : nullable Shape 444 445``` 446struct Paint { 447 Pattern fg; 448 Pattern? bg; 449}; 450``` 451 452#### Interfaces 453 454* Describe methods which can be invoked by sending messages over a channel. 455* Methods are identified by their ordinal index. Ordinals must be stated 456 explicitly to reduce the chance that developers might break interfaces by 457 reordering methods and to help with interface extension and derivation. 458 * Method ordinals are unsigned values in the range **0x00000001** to 459 **0x7fffffff**. 460 * The FIDL wire format internally represents ordinals as 32-bit values but 461 reserves the range **0x80000000** to **0xffffffff** for protocol control 462 messages, so these values cannot be associated with methods. 463* Each method declaration states its arguments and results. 464 * If no results are declared, then the method is one-way: no response will 465 be generated by the server. 466 * If results are declared (even if empty), then the method is two-way: 467 each invocation of the method generates a response from the server. 468 * If only results are declared, the method is referred to as an 469 *event*. It then defines an unsolicited message from the server. 470* When a client or server of an interface is about to close its side of the 471 channel, it may elect to send an **epitaph** message to its peer to indicate 472 the disposition of the connection. If sent, the epitaph must be the last 473 message delivered through the channel. An epitaph message includes: 474 * 32-bit generic status: one of the **ZX_status_t** constants 475 * 32-bit protocol-specific code: meaning is left up to the interface in 476 question 477 * a string: a human-readable message explaining the disposition 478* **Interface extension:** New methods can be added to existing interfaces as 479 long as they do not collide with existing methods. 480* **Interface derivation:** New interfaces can be derived from any number of 481 existing interfaces as long as none of their methods use the same ordinals. 482 (This is purely a FIDL language feature, does not affect the wire format.) 483 484##### Declaration 485 486``` 487interface Calculator { 488 1: Add(int32 a, int32 b) -> (int32 sum); 489 2: Divide(int32 dividend, int32 divisor) 490 -> (int32 quotient, int32 remainder); 491 3: Clear(); 492 4: -> OnClear(); 493}; 494 495interface RealCalculator : Calculator { 496 1001: AddFloats(float32 a, float32 b) -> (float32 sum); 497}; 498 499interface Science { 500 2001: Hypothesize(); 501 2002: Investigate(); 502 2003: Explode(); 503 2004: Reproduce(); 504}; 505 506interface ScientificCalculator : RealCalculator, Science { 507 3001: Sin(float32 x) -> (float32 result); 508}; 509``` 510 511##### Use 512 513Interfaces are denoted by their name, directionality of the channel, and 514optionality: 515 516* **`Interface`** : non-nullable FIDL interface (client 517 endpoint of channel) 518* **`Interface?`** : nullable FIDL interface (client 519 endpoint of channel) 520* **`request<Interface>`** : non-nullable FIDL interface 521 request (server endpoint of channel) 522* **`request<Interface>?`** : nullable FIDL interface request 523 (server endpoint of channel) 524 525``` 526// A record which contains interface-bound channels. 527struct Record { 528 // client endpoint of a channel bound to the Calculator interface 529 Calculator c; 530 531 // server endpoint of a channel bound to the Science interface 532 request<Science> s; 533 534 // optional client endpoint of a channel bound to the 535 // RealCalculator interface 536 RealCalculator? r; 537}; 538``` 539 540### Constant Declarations 541 542Constant declarations introduce a name within their scope. The constant's type 543must be either a primitive or an enum. 544 545``` 546// a constant declared at library scope 547const int32 FAVORITE_NUMBER = 42; 548``` 549 550### Constant Expressions 551 552Constant expressions are either literals or the names of other 553constant expressions. 554 555## Grammar 556 557A modified [EBNF description of the fidl grammar is here](grammar.md). 558