| # Fuchsia System Interface |
| |
| ## Overview |
| |
| The *Fuchsia System Interface* is the binary interface that the Fuchsia |
| operating system presents to software it runs. The foundation of the interface |
| is the vDSO, which provides access to the system calls. Programs are not allowed |
| to issue system calls directly (e.g., by trapping into the kernel). Instead, |
| programs use the vDSO to interface with the kernel. |
| |
| The bulk of the system interface is provided through inter-process |
| communication protocols, typically defined using FIDL. These protocols are |
| spoken over various kernel primitives, including channels and sockets. |
| |
| The `fuchsia.io` FIDL library provides protocols for file and directory |
| operations. Fuchsia uses the `fuchsia.io` protocols to provide a namespace to |
| components through which components can access system services and resources. |
| The names in these namespaces follow certain conventions, which are part of the |
| system ABI. See [namespaces](/docs/concepts/process/namespaces.md) for more details. |
| |
| Packages themselves also provide an interface to the system in terms of |
| directory structure and file formats. The system uses this information to |
| initialize processes in which components stored in these packages execute. |
| |
| ## Terminology |
| |
| The *Application Programming Interface* (API) for a system is the source-level |
| interface to the system. You typically write software that uses this |
| interface directly. Changes to the system API might require you to update |
| your source code to account for the changes to the API. |
| |
| The *Application Binary Interface* (ABI) for a system is the binary-level interface |
| to the system. Typically you don't write software that uses the system ABI |
| directly. Instead, you write software against the system API. When the software |
| is compiled, the binary artifact created by the compiler interfaces with the system |
| through the ABI. Changes to the system ABI may require you to recompile |
| your source code to account for the changes in the ABI. |
| |
| ## ABI Surfaces |
| |
| This section describes the various ABI surfaces for Fuchsia components. |
| |
| ### vDSO |
| |
| The vDSO is a virtual shared library that provides access to the kernel. |
| Concretely, the vDSO is an ELF shared library, called `libzircon.so`, that |
| exports a number of symbols with a C calling convention. The source of truth for |
| these symbols is [//zircon/vdso](/zircon/vdso/). Their semantics are |
| described in [the documentation](/docs/reference/syscalls/). |
| |
| ### FIDL protocols |
| |
| The bulk of the system interfaces are defined in the Fuchsia Interface |
| Definition Language (FIDL). The FIDL compiler produce language specific APIs and |
| runtime libraries, referred to as FIDL bindings, for a variety of target |
| languages. These bindings provide an idiomatic interface for sending and |
| receiving interprocess communication messages over Zircon channels (and other |
| primitives). |
| |
| #### Wire format |
| |
| The FIDL protocol definitions themselves and the language-specific bindings |
| generated by the compiler are part of the system *API* but not part of the |
| system *ABI*. Instead, the format of the serialized messages, called the *wire |
| format*, comprises the ABI. The FIDL wire format is defined by the |
| [specification](/docs/reference/fidl/language/wire-format/README.md). |
| |
| #### User signals |
| |
| In addition to the messages sent, some FIDL protocols make use of user signals |
| on the underlying kernel objects. Currently, these signals are not declared in |
| FIDL. Typically, the semantics of any associated user signals are documented |
| in prose in comments in the FIDL definitions. |
| |
| ### Namespace conventions |
| |
| When run, components are given a [namespace][glossary.namespace] and serve an |
| [outgoing directory][glossary.outgoing-directory]. |
| The names in the namespace and outgoing directory follow certain conventions, |
| which are are part of the system ABI. |
| |
| #### Namespace |
| |
| A component's [namespace][glossary.namespace] is provided during startup and |
| lets the component interact with capabilities published by the rest of the |
| system. |
| |
| For example, components can discover implementations of FIDL |
| [protocols][glossary.protocol] and [services][glossary.service] through the |
| `/svc` entry in this namespace, which lists them under well-known names. |
| Similarly, by convention, the `pkg` namespace entry is mapped to the package |
| from which the component was resolved. |
| |
| #### Outgoing directory {#outgoing_directory} |
| |
| A component serves an [outgoing directory][glossary.outgoing-directory] to |
| publish capabilities to the rest of the system. |
| |
| For example, components expose FIDL [protocols][glossary.protocol] and |
| [services][glossary.service] to other components using the `/svc` entry in this |
| directory, which lists them under well-known names. |
| |
| #### Data formats |
| |
| Some namespaces include files with data. The data format used by these files is |
| also part of the system ABI. |
| For example, components access the root certificates through a namespace entry |
| that contains a `certs.pem` file. The `pem` data format is therefore part of the |
| system ABI. |
| |
| ### Package conventions |
| |
| Fuchsia packages have a directory structure that follows certain naming |
| conventions. These conventions are also part of the system ABI. This section |
| gives two examples of important packaging conventions. |
| |
| #### meta |
| |
| By convention, the `meta` directory in a package contains metadata files that |
| describe the package. The structure of this metadata, including the data formats |
| used by these files such as [component manifests][glossary.component-manifest], |
| is part of the system ABI. |
| |
| #### lib |
| |
| By convention, the `lib` directory in a package contains the shared libraries |
| used by components in the package. When the system runs an executable from the |
| package, requests for shared libraries are resolved relative to this `lib` |
| directory. |
| |
| One important difference between Fuchsia and other operating systems is that the |
| shared libraries themselves are provided by the package creator rather than the |
| system itself. For that reason, the shared libraries themselves (including |
| `libc`) are not part of the system ABI. |
| |
| The system does provide two shared libraries: the [vDSO](#vdso) and the |
| [Vulkan ICD](#vulkan-icd). See those sections for details. |
| |
| ### Process structure |
| |
| Processes on Fuchsia are fairly flexible and largely under the control of the |
| executable running in the process, but some of the initial structure of the |
| process is controlled by the system and part of the system ABI. |
| |
| For additional details, see |
| [Program Loading](/docs/concepts/process/program_loading.md). |
| |
| #### ELF loader |
| |
| Fuchsia uses the ELF data format for executables. When loading an executable |
| into a process, the loader parses contents of the executable as ELF. The loader |
| reads the `INTERP` directive from the executable and resolves that name as a |
| file in the `lib` directory of the package that contained the executable. The |
| loader then parses the contents of the `INTERP` file as an ELF shared library, |
| relocates the library, and maps the library into the newly created process. |
| |
| #### Startup message |
| |
| As part of starting a process, the creator of the process supplies the process |
| with a message that contains, for example, the command line arguments, the |
| `environ`, the initial handles, and the namespace for the process. |
| (The outgoing directory is included in the set of initial handles for the |
| process.) |
| |
| The format of this message, including length limitations on fields such as the |
| command line arguments and the `environ`, are part of the system ABI, as are |
| the conventions around the contents of the message. For example, by convention, |
| the `PWD` environment variable is the name the creator suggests the process use |
| as its current working directory. |
| |
| The initial handles are associated with numerical identifiers. The conventions |
| around these identifiers are part of the system ABI. For example, by convention, |
| the `PA_PROC_SELF` handle is a handle to the process object for the newly |
| created process. In addition to the types of these handles, the rights |
| associated with these handles are also part of the system ABI. |
| |
| #### VMAR structure |
| |
| Before starting a process, the creator modifies the root VMAR for the process. |
| For example, the creator maps the vDSO and allocates a stack for the initial |
| thread. The structure of the VMAR when the process is started is part of the |
| system ABI. |
| |
| #### Job policy |
| |
| Processes are run in jobs, which can apply policy to the processes and jobs they |
| contain. The job policy applied to processes is part of the system ABI. For |
| example, components run in processes with `ZX_POL_NEW_PROCESS` set to |
| `ZX_POL_ACTION_DENY`. This enforces that the component use the |
| `fuchsia.process.Launcher` protocol to create processes rather than issuing the |
| `zx_process_create` system call directly. |
| |
| ### Vulkan ICD {#vulkan-icd} |
| |
| Components that use the Vulkan API for hardware accelerated graphics link |
| against `libvulkan.so` and specify the `vulkan` feature in their manifests. This |
| library is provided by the package that contains the component and therefore is |
| not part of the system ABI. However, `libvulkan.so` loads another shared |
| library, called the *Vulkan Installable Client Driver* (Vulkan ICD). The Vulkan |
| ICD is loaded using `fuchsia.vulkan.loader.Loader`, which means the library is |
| provided by the system itself rather than the package that contains the |
| component. For this reason, the Vulkan ICD is part of the system ABI. |
| |
| The Vulkan ICD is an ELF shared library that exports exactly three symbols. |
| These symbols are reserved for use by the Vulkan ICD and should not be used |
| directly. |
| |
| * `vk_icdGetInstanceProcAddr` |
| * `vk_icdNegotiateLoaderICDInterfaceVersion` |
| * `vk_icdInitializeOpenInNamespaceCallback` |
| |
| In addition, the Vulkan ICD shared library has a `NEEDED` section that lists |
| several shared libraries upon which the Vulkan ICD depends. The package |
| containing the component is required to provide these shared libraries. |
| |
| The Vulkan ICD also imports a number of symbols. The conventions around these |
| imported symbols, for example their parameters and semantics, are part of the |
| system ABI. |
| |
| Currently, the `NEEDED` section and the list of imported symbols for the Vulkan |
| ICD are both larger than we desire. Hopefully we will be able to minimize these |
| aspects of the system ABI. |
| |
| ### Sockets |
| |
| #### Datagram framing |
| |
| Datagram sockets used for networking include a frame that specifies the network |
| address associated with the datagram. This frame is also part of the system ABI. |
| |
| ### Terminal protocol |
| |
| Programs that run in the terminal communicate with the terminal using the |
| Fuchsia Terminal Protocol, which is a text-based protocol similar to `vt100`. |
| This protocol is also exposed over the network through `ssh`, both by clients |
| that expect incoming `ssh` connections to support this protocol and by servers |
| that expect outgoing `ssh` connections to support this protocol. |
| |
| [glossary.component-manifest]: /docs/glossary/README.md#component-manifest |
| [glossary.namespace]: /docs/glossary/README.md#namespace |
| [glossary.outgoing-directory]: /docs/glossary/README.md#outgoing-directory |
| [glossary.protocol]: /docs/glossary/README.md#protocol |
| [glossary.service]: /docs/glossary/README.md#service |