FIDL grammar

Modified BNF rules

This is the grammar for FIDL source files. The grammar is expressed in a modified BNF format.

A nonterminal symbol matches a sequence of other symbols, delimited by commas.

  1. nonterminal = list , of , symbols ;

Some symbols are terminals, which are either in all caps or are in double quotes.

  1. another-nonterminal = THESE , ARE , TERMINALS , AND , SO , IS , "this" ;

Alternation is expressed with a pipe.

  1. choice = this | that | the-other ;

An option (zero or one) is expressed with parentheses.

  1. optional = ( maybe , these ) , but , definitely , these ;

Repetition (zero or more) is expressed with parentheses and a star.

  1. zero-or-more = ( list-part )* ;

Repetition (one or more) is expressed with parentheses and a plus.

  1. one-or-more = ( list-part )+ ;

Tokens

Whitespace and comments are ignored during lexing, and thus not present in the following grammar.

Comments can start with two slashes (‘//‘) or three slashes (‘///‘), or they can be embodied within a [Doc] attribute. The three-slash variant and the [Doc] attribute behave the same way, propagating the comments to the generated target.

The fidldoc tool processes comments propagated into the JSON-based Intermediate Representation (IR) to generate reference documentation pages for FIDL files.

See the FIDL style guide for more details on comments.

Grammar {#grammar}

file is the starting symbol.

  1. file = library-header , ( using-list ) , declaration-list ;
  3. library-header = ( attribute-list ) , "library" , compound-identifier , ";" ;
  5. using-list = ( using , ";" )* ;
  7. using = "using" , compound-identifier , ( "as" , IDENTIFIER ) ;
  9. declaration-list = ( declaration , ";" )* ;
  11. compound-identifier = IDENTIFIER ( "." , IDENTIFIER )* ;
  13. declaration = bits-declaration | const-declaration | enum-declaration | protocol-declaration
  14.             | struct-declaration | table-declaration | union-declaration
  15.             | type-alias-declaration | resource-declaration | service-declaration ;
  17. declaration-modifiers = "flexible" | "strict" | "resource"; [NOTE 1]
  19. const-declaration = ( attribute-list ) , "const" , type-constructor , IDENTIFIER , "=" , constant ;
  21. enum-declaration = ( attribute-list ) , ( declaration-modifiers )* , "enum" , IDENTIFIER ,
  22.                    ( ":" , type-constructor ) , "{" , ( bits-or-enum-member , ";" )+ ,
  23.                    "}" ; [NOTE 2]
  25. bits-declaration = ( attribute-list ) , ( declaration-modifiers )* , "bits" , IDENTIFIER ,
  26.                    ( ":" , type-constructor ) , "{" , ( bits-or-enum-member , ";" )+ ,
  27.                    "}" ; [NOTE 3]
  29. bits-or-enum-member = ( attribute-list ) , IDENTIFIER , "=" , bits-or-enum-member-value ;
  31. bits-or-enum-member-value = IDENTIFIER | literal ; [NOTE 4]
  33. protocol-declaration = ( attribute-list ) , "protocol" , IDENTIFIER ,
  34.                        "{" , ( protocol-member , ";" )*  , "}" ;
  36. protocol-member = protocol-method | protocol-event | protocol-compose ;
  38. protocol-method = ( attribute-list ) , IDENTIFIER , parameter-list,
  39.                   ( "->" , parameter-list , ( "error" type-constructor ) ) ; [NOTE 5]
  41. protocol-event = ( attribute-list ) , "->" , IDENTIFIER , parameter-list ;
  43. parameter-list = "(" , ( parameter ( "," , parameter )+ ) , ")" ;
  45. parameter = ( attribute-list ) , type-constructor , IDENTIFIER ;
  47. protocol-compose = "compose" , compound-identifier ;
  49. struct-declaration = ( attribute-list ) , "struct" , IDENTIFIER , "{" , ( member-field , ";" )* ,
  50.                      "}" ;
  52. union-declaration = ( attribute-list ) , ( declaration-modifiers )* , "union" , IDENTIFIER , "{" ,
  53.                     ( ordinal-member-field , ";" )+ , "}" ;
  55. table-declaration = ( attribute-list ) , ( declaration-modifiers )* , "table" , IDENTIFIER , "{" ,
  56.                     ( ordinal-member-field , ";" )* , "}" ;
  58. member-field = ( attribute-list ) , type-constructor , IDENTIFIER , ( "=" , constant ) ;
  60. ordinal-member-field = ( attribute-list ) , ordinal , ":" , ordinal-member-field-body ; [NOTE 6]
  62. ordinal-member-field-body = member-field | "reserved";
  64. type-alias-declaration = ( attribute-list ) , "alias" , IDENTIFIER ,  "=" , type-constructor ;
  66. resource-declaration = ( attribute-list ) , "resource_definition" , IDENTIFIER , ":",
  67.                        "uint32" , "{" , resource-properties ,  "}" ;
  69. resource-properties = "properties" , "{" , ( type-constructor , IDENTIFIER  , ";" )* , "}" , ";"
  71. service-declaration = ( attribute-list ) , "service" , IDENTIFIER , "{" ,
  72.                       ( service-member , ";" )* , "}" ;
  74. service-member = ( attribute-list ) , type-constructor , IDENTIFIER ; [NOTE 7]
  76. attribute-list = "[" , attributes , "]" ;
  78. attributes = attribute | attribute , "," , attributes ;
  80. attribute = IDENTIFIER , ( "=" , STRING-LITERAL ) ;
  82. type-constructor = compound-identifier ( "<" type-constructor ">" ) , (  type-constraint ) , ( "?" )
  83.                  | handle-type ;
  85. handle-type = "handle" , ( "<" , handle-subtype , ">" ) , ( "?" ) ;
  87. handle-subtype = "bti" | "channel" | "clock" | "debuglog" | "event" | "eventpair" | "exception"
  88.                | "fifo" | "guest" | "interrupt" | "iommu" | "job" | "pager" | "pcidevice"
  89.                | "pmt" | "port" | "process" | "profile" | "resource" | "socket" | "suspendtoken"
  90.                | "thread" | "timer" | "vcpu" | "vmar" | "vmo" ;
  92. type-constraint = ":" , constant ;
  94. constant = compound-identifier | literal ;
  96. ordinal = NUMERIC-LITERAL ;
  98. literal = STRING-LITERAL | NUMERIC-LITERAL | "true" | "false" ;

NOTE 1

The grammar allows ( declaration-modifiers )* on all declarations, but the compiler limits this as follows:

  • A modifier cannot occur twice on the same declaration.
  • The flexible and strict modifiers cannot be used together.
  • The flexible and strict modifiers can only be used on bits, enum, and union.
  • The resource modifier can only be used on struct, table, and union.

NOTE 2

The enum-declaration allows the more liberal type-constructor in the grammar, but the compiler limits this to signed or unsigned integer types, see primitives.

NOTE 3

The bits-declaration allows the more liberal type-constructor in the grammar, but the compiler limits this to unsigned integer types, see primitives.

NOTE 4

The bits-or-enum-member-value allows the more liberal literal in the grammar, but the compiler limits this to:

  • A NUMERIC-LITERAL in the context of an enum;
  • A NUMERIC-LITERAL, which must be a power of two, in the context of a bits.

NOTE 5

The protocol-method error stanza allows the more liberal type-constructor in the grammar, but the compiler limits this to an int32, uint32, or an enum thereof.

NOTE 6

Attributes cannot be placed on a reserved member.

NOTE 7

The service-member allows the more liberal type-constructor in the grammar, but the compiler limits this to protocols.