Skip to content

Latest commit

 

History

History
276 lines (223 loc) · 7.63 KB

fidl.md

File metadata and controls

276 lines (223 loc) · 7.63 KB

Fuchsia Interface Definition Language

<<../../_common/fidl/_fidl_intro.md>>

Creating a FIDL library

FIDL libraries group FIDL source files together. A library acts as a namespace for the protocols it contains, and FIDL source files can implicitly access all other declarations within the same library. FIDL source files must import any declarations from another library.

The Fuchsia build system provides the fidl() build target to compile FIDL source files into a library. The name of the library target must match the library declarations in each source file. See the following BUILD.gn example for the fuchsia.examples library:

# Import the fidl GN template.
import("//build/fidl/fidl.gni")

# Define a FIDL library target.
fidl("fuchsia.examples") {
  # FIDL source files contained in library
  sources = [
    "echo.fidl",
  ]
}
By default, the build system uses the fidl() GN target name as the library name. You can override this behavior with the name parameter.

At build time, the FIDL Compiler (fidlc) frontend tool validates and compiles the library source files into a JSON Intermediate Representation (IR). This JSON IR format is the basis for the FIDL bindings.

Generating FIDL bindings

Components consume FIDL protocols through generated code called FIDL bindings. Bindings encode and decode requests and responses as FIDL messages and transfer them over the underlying IPC channel. The language-specific binding libraries provide wrappers around these structures to align interactions with familiar programming idioms.

The client interface (sometimes referred to as a proxy) performs translation between higher-level function calls and FIDL messages. On the server side, bindings process incoming request messages and deliver them through an abstract interface for components to implement.

![Diagram showing how FIDL bindings provide generated library code to translate function calls into FIDL messages for transport across process boundaries.] (/get-started/images/fidl/fidl-bindings.png){: width="574"}

Note: For more details on the bindings specification and supported programming languages, see the Bindings Reference.

At build time, the fidlgen backend tools generate bindings for supported programming languages from the JSON IR library produced by fidlc. For example, fidlgen_rust generates Rust bindings from the JSON IR.

The fidl() library target creates individual binding targets for each supported language. Due to the nature of GN, these bindings are not generated at build time unless they are included as a dependency.

See the following example BUILD.gn snippet that includes the generated bindings target for the fuchsia.examples library:

  • {Rust}

    deps = [
  "fidl/fuchsia.examples:fuchsia.examples-rustc",
  ...
]

  • {C++}

    deps = [
  "fidl/fuchsia.examples:fuchsia.examples",
  ...
]

Exercise: Echo FIDL Library

In this section, you'll define a new FIDL library with a protocol called Echo containing a single method that returns string values back to the caller.

Start by creating a new directory for the FIDL library target:

mkdir -p vendor/fuchsia-codelab/echo-fidl

Add a new FIDL interface file called echo.fidl with the following contents:

{% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/components/routing/fidl/echo.fidl" region_tag="fidl_echo" adjust_indentation="auto" %}

EchoString is a two-way method that accepts an optional (nullable) string value and returns the same value.

Add a BUILD.gn file with the following contents to declare the library target:

{% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/components/routing/fidl/BUILD.gn" region_tag="fidl_echo" adjust_indentation="auto" %}

Add the library target to the build configuration:

fx set workstation_eng.qemu-x64 --with //vendor/fuchsia-codelab/echo-fidl:echo

Run fx build to compile the FIDL interface:

fx build vendor/fuchsia-codelab/echo-fidl:echo

Examine the FIDL bindings

The fidl() GN target compiles the FIDL interface and generates additional build targets to provide the bindings in various languages. To examine the bindings, you must compile the individual targets.

Compile the fidl.examples.routing.echo bindings:

  • {Rust}

    fx build vendor/fuchsia-codelab/echo-fidl:echo-rustc

  • {C++}

    fx build vendor/fuchsia-codelab/echo-fidl:echo

Use GN to locate the generated source files for the target and open them in an editor:

  • {Rust}

    fx gn desc out/default/ vendor/fuchsia-codelab/echo-fidl:echo-rustc sources

  • {C++}

    fx gn desc out/default/ vendor/fuchsia-codelab/echo-fidl:echo_hlcpp sources

Explore the contents of these files. Below is a summary of some of the key generated interfaces:

  • {Rust}

    Interface Description
    EchoMarker Used to open a proxy and request stream for a given protocol.
    EchoProxy Asynchronous client that transforms protocol methods into FIDL request messages sent over the IPC channel.
    EchoSynchronousProxy Synchronous client that transforms protocol methods into FIDL request messages sent over the IPC channel.
    EchoRequest Structured types for handling incoming requests for each protocol method.
    EchoRequestStream Stream to handle incoming FIDL request messages over the IPC channel.
    EchoEchoStringResponder Callback to send a return value for each proxy request as a FIDL response message.

  • {C++}

    Interface Description
    EchoPtr Asynchronous client that transforms protocol methods into FIDL request messages sent over the IPC channel.
    EchoSyncPtr Synchronous client that transforms protocol methods into FIDL request messages sent over the IPC channel.
    Echo Abstract class for a server component to override and handle incoming FIDL requests.
    EchoStringCallback Callback to send a return value for each request as a FIDL response message.
Asynchronous vs. synchronous clients

The FIDL toolchain generates client bindings that are asynchronous by default. This means the client methods return immediately to the caller and responses are delivered using a callback or future. Synchronous clients provide a simplified API that guarantees responses are delivered before the client method returns.

Synchronous clients are not available in all supported languages. For more details, see the specifications for your chosen language in the Bindings Reference.