Glossary

The purpose of this document is to provide short definitions for a collection of technical terms used in Fuchsia.

When adding new definitions, follow these guidelines:

  • A definition should provide a high-level description of a term and in most cases should not be longer than two or three sentences.
  • When another non-trivial technical term needs to be employed as part of the description, consider adding a definition for that term and linking to it from the original definition.
  • A definition should be complemented by a list of links to more detailed documentation and related topics.

Terms

ABI

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.

ABR

Fuchsia uses a bootloader A/B/R slot logic. This logic is not required to boot Zircon or run a basic Fuchsia system, but it is required to take full advantage of Fuchsia's over-the-air (OTA) update features.

The term slot is used to refer to a set of partitions that update together. If an update fails, the partitions fall back together. This works because there are two copies of each partition on disk. By convention, the slots used for normal updates are denoted A and B, and the corresponding partitions are labeled with a suffix of “_a” or “_b”. The slot used for recovery is denoted R which is chosen when neither A nor B is bootable.

Agent

A Modular concept that is being deprecated.

An agent is a role a component can play to execute in the background in the context of a session. Agents are always a singleton within a session, and provide services to other components.

See Agent concept docs for more.

AppMgr

The Application Manager (AppMgr) is responsible for launching v1 components and managing the namespaces in which those components run. It is run by component manager as a v2 component.

Banjo

Banjo is a language for defining protocols that are used to communicate between drivers. It is different from FIDL in that it specifies an ABI for drivers to use to call into each other, rather than an IPC protocol.

Binding

In Components v2, a component instance binds to another component instance when it connects to a capability provided by the other component instance. This is the most common reason for a component to start.

bootfs

The bootfs RAM disk contains the files needed early in the boot process when no other filesystems are available. It is part of the ZBI, and is decompressed and served by bootsvc. After the early boot process is complete, the bootfs is mounted at /boot.

bootsvc

bootsvc is the second process started in Fuchsia. It provides a filesystem service for the bootfs and a loader service that loads programs from the same bootfs. After starting these services, it loads the third program, which defaults to component_manager.

Bus Driver

A driver for a device that has multiple children. For example, hardware interfaces like PCI specify a topology in which a single controller is used to interface with multiple devices connected to it. In that situation, the driver for the controller would be a bus driver.

Cache directory

Similar to a data directory, except that the contents of a cache directory may be cleared by the system at any time, such as when the device is under storage pressure. Canonically mapped to /cache in the component instance’s namespace.

Capability

A capability is a value that combines an object reference and a set of rights. When a program has a capability it is conferred the privilege to perform certain actions using that capability. A handle is a common example for a capability.

Capability routing

A way for one component to give capabilities to another instance over the component instance tree. Component manifests define how routing takes place, with syntax for service capabilities, directory capabilities, and storage capabilities.

Capability routing is a components v2 concept.

expose

A component instance may use the expose manifest keyword to indicate that it is making a capability available to its parent to route. Parents may offer a capability exposed by any of their children to their other children or to their parent, but they cannot use it themselves in order to avoid dependency cycles.

offer

A component instance may use the offer manifest keyword to route a capability that was exposed to it to one of its children (other than the child that exposed it).

use

A component instance may use the use manifest keyword to consume a capability that was offered to it by its parent.

Channel

A channel is an IPC primitive provided by Zircon. It is a bidirectional, datagram-like transport that can transfer small messages including Handles. FIDL protocols typically use channels as their underlying transport.

Component

A component is a unit of executable software on Fuchsia. Components support capability routing, software composition, isolation boundaries, continuity between executions, and introspection.

Component collection

A node in the component instance tree whose children are dynamically instantiated rather than statically defined in a component manifest.

Component collection is a components v2 concept.

Component declaration

A component declaration is a FIDL table (fuchsia.sys2.ComponentDecl) that includes information about a component’s runtime configuration, capabilities it exposes, offers, and uses, and facets.

Component declaration is a components v2 concept.

Component Framework

An application framework for declaring and managing components, consisting of build tools, APIs, conventions, and system services.

Component instance

One of possibly many instances of a particular component at runtime. A component instance has its own environment and lifecycle independent of other instances.

Component instance tree

A tree structure that represents the runtime state of parent-child relationships between component instances. If instance A launches instance B then in the tree A will be the parent of B. The component instance tree is used to route capabilities such that parents can offer capabilities to their children to use, and children can expose capabilities for their parents to expose to their parents or offer to other children.

Component instance tree is a components v2 concept.

Component Manager

A system service that lets component instances manage their children and routes capabilities between them, thus implementing the component instance tree. Component Manager is the system service that implements the components v2 runtime.

Component Manifest

In Components v1, a component manifest is a JSON file with a .cmx extension that contains information about a component’s runtime configuration, services and directories it receives in its namespace, and facets.

In Components v2, a component manifest is a file with a .cm extension, that encodes a component declaration.

Component Manifest Facet

Additional metadata that is carried in a component manifest. This is an extension point to the component framework.

Component Instance Identifier

A unique, stable identifer for a component instance. The instance id is the canonical identifier for a component instance. The component runtime uses this to key a component‘s persistent resources, if it has any. While a component instance’s moniker may change, its instance ID remains the same.

Instance IDs are assigned to component instances using a component ID index.

Component URL

A URL that identifies a component, most often used when instantiating a component, for example fuchsia-pkg://fuchsia.com/stash#meta/stash_secure.cm.

See also: fuchsia-pkg URL

Components v1

A shorthand for the Component Architecture as first implemented on Fuchsia. Includes a runtime as implemented by appmgr and sysmgr, protocols and types as defined in fuchsia.sys, build-time tools such as cmc, and IDK libraries such as libsys and libsvc.

See also: Components v2

Components v2

A shorthand for the Component Architecture in its modern implementation. Includes a runtime as implemented by component_manager, protocols and types as defined in fuchsia.sys2, and build-time tools such as cmc.

See also: Components v1

Concurrent Device Driver

A concurrent device driver is a hardware driver that supports multiple concurrent operations. This may be, for example, through a hardware command queue or multiple device channels. From the perspective of the core driver, the device has multiple pending operations, each of which completes or fails independently. If the driven device can internally parallelize an operation, but can only have one operation outstanding at a time, it may be better implemented with a sequential device driver.

Core Driver

A core driver is a driver that implements the application-facing RPC interface for a class of drivers (e.g. block drivers, ethernet drivers). It is hardware-agnostic. It communicates with a hardware driver through banjo to service its requests.

Data directory

A private directory within which a component instance may store data local to the device, canonically mapped to /data in the component instance’s namespace.

Directory capability

A capability that permits access to a filesystem directory by adding it to the namespace of the component instance that uses it. If multiple component instances are offered the same directory capability then they will have access to the same underlying filesystem directory.

Directory capability is a components v2 concept.

Driver

A driver is a dynamic shared library that Driver Manager can load into a Driver Host and that enables, and controls one or more devices.

Driver Host

A Driver Host is a process containing one or more device drivers. They are created by the Driver Manager, as needed, to provide isolation between drivers for stability and security.

Driver Manager

The Driver Manager (formerly devmgr or devcoordinator) is responsible for enumerating, loading, and managing the life cycle of device drivers.

Element

A component added to a session dynamically through the FIDL protocol ElementManager. In addition to the properties common to all components, Elements are also annotated by Element Proposers. Those annotations are shared with other components within the session.

It is the session's responsibility to manage the lifecycle of elements.

Elements are a Session Framework concept.

Element Annotation

A FIDL struct (see fuchsia.session.Annotation).

A collection of named attributes associated with an element. Annotations are specified at element creation time by element proposers and remain mutable for the lifetime of the element.

Element annotations are a Session Framework concept.

Element Manager

A FIDL protocol (see fuchsia.session.ElementManager).

A protocol used to grant session sub-components the capability to ask for elements to be added to the product experience at runtime.

Element manager is a Session Framework concept.

Element Proposer

A way to refer to any component that invokes the ProposeElement() method on ElementManager to launch a specific element in a session.

Element Proposer is a Session Framework concept.

Environment

A container for a set of components, which provides a way to manage their lifecycle and provision services for them. All components in an environment receive access to (a subset of) the environment's services.

Escher

Graphics library for compositing user interface content. Its design is inspired by modern real-time and physically based rendering techniques though we anticipate most of the content it renders to have non-realistic or stylized qualities suitable for user interfaces.

FAR

The Fuchsia Archive Format is a container for files to be used by Zircon and Fuchsia.

FBL

FBL is the Fuchsia Base Library, which is shared between kernel and userspace.

FDF

The Fuchsia Driver Framework is the documentation, APIs, and ABIs necessary to build Zircon Device Drivers. Device drivers are implemented as ELF shared libraries loaded by Zircon's Driver Manager.

fdio

fdio is the Zircon IO Library. It provides the implementation of posix-style open(), close(), read(), write(), select(), poll(), etc, against the RemoteIO RPC protocol. These APIs are return- not-supported stubs in libc, and linking against libfdio overrides these stubs with functional implementations.

FIDL

The Fuchsia Interface Definition Language (FIDL) is a language for defining protocols that are typically used over channels. FIDL is programming language agnostic and has bindings for many popular languages, including C, C++, Dart, Go, and Rust. This approach lets system components written in a variety of languages interact seamlessly.

Flutter

Flutter is a functional-reactive user interface framework optimized for Fuchsia and is used by many system components. Flutter also runs on a variety of other platforms, including Android and iOS. Fuchsia itself does not require you to use any particular language or user interface framework.

FTP

FIDL Tuning Proposal. An FTP is the way developers can suggest changes to FIDL. After being written, an FTP goes through a formal review process where it is either accepted or rejected.

Fuchsia API Surface

The Fuchsia API Surface is the combination of the Fuchsia System Interface and the client libraries included in the Fuchsia IDK.

Fuchsia emulator (FEMU)

The Fuchsia emulator (FEMU) is the default emulator for Fuchsia. It allows you to test Fuchsia components and applications without needing a Fuchsia device. FEMU is based on the Android Emulator (AEMU), which is a fork of QEMU.

Fuchsia Package

A Fuchsia Package is a unit of software distribution. It is a collection of files, such as manifests, metadata, zero or more executables (e.g. Components), and assets. Individual Fuchsia Packages can be identified using fuchsia-pkg URLs.

fuchsia-pkg URL

The fuchsia-pkg URL scheme is a means for referring to a repository, a package, or a package resource. The syntax is fuchsia-pkg://<repo-hostname>[/<pkg-name>][#<path>]]. E.g., for the component echo_client_dart.cmx published under the package echo_dart's meta directory, from the fuchsia.com repository, its URL is fuchsia-pkg://fuchsia.com/echo_dart#meta/echo_client_dart.cmx.

Fuchsia Integrator Development Kit (IDK)

The Fuchsia IDK is a collection of libraries and tools that the Fuchsia project provides to Fuchsia developers. Among other things, the Fuchsia IDK contains a definition of the Fuchsia System Interface as well as a number of client libraries. The IDK is targeted at development environment integrators that add environment specific tooling specific to the build environment to form a full SDK.

Fuchsia System Interface

The Fuchsia System Interface is the binary interface that the Fuchsia operating system presents to software it runs. For example, the entry points into the vDSO as well as all the FIDL protocols are part of the Fuchsia System Interface.

Fuchsia Volume Manager

Fuchsia Volume Manager (FVM) is a partition manager providing dynamically allocated groups of blocks known as slices into a virtual block address space. The FVM partitions provide a block interface enabling filesystems to interact with it in a manner largely consistent with a regular block device.

GN

GN is a meta-build system that generates build files so that Fuchsia can be built with Ninja. GN is fast and comes with solid tools to manage and explore dependencies. GN files, named BUILD.gn, are located all over the repository.

GraphicalPresenter

A FIDL protocol (see fuchsia.element.GraphicalPresenter).

A GraphicalPresenter organizes and presents graphical views.

The presented views can be annotated with Element Annotations to communicate presentation properties to the GraphicalPresenter. This protocol is used, for example, when a session component written in Rust wants to delegate presentation logic to a child component written in Flutter, or when a session component that manages the lifecycle of elements delegates the presentation of element views to a child component that implements GraphicalPresenter.

For more information, see the GraphicalPresenter concept documentation.

GraphicalPresenter is a Session Framework concept.

Handle

A Handle is how a userspace process refers to a kernel object. They can be passed to other processes over Channels.

Hardware Driver

A hardware driver is a driver that controls a device. It receives requests from its core driver and translates them into hardware-specific operations. Hardware drivers strive to be as thin as possible. They do not support RPC interfaces, ideally have no local worker threads (though that is not a strict requirement), and some will have interrupt handling threads. They may be further classified into sequential device drivers and concurrent device drivers.

Hub

The hub is a portal for tools to access detailed structural information about component instances at runtime, such as their names, job and process ids, and exposed capabilities.

Input pipeline client library

A client library available to session authors to simplify the consumption and routing of input events from physical hardware.

Input pipeline is a Session Framework concept.

Input pipeline InputDeviceBinding

A Rust trait in the input pipeline client library.

An InputDeviceBinding represents a connection to a physical input device (e.g. mouse, keyboard) in an input pipeline. An InputDeviceBinding does the following:

  1. Connects to an InputReport file located at /dev/class/input-report/XXX.
  2. Generates InputEvents from the DeviceDescriptor and incoming InputReports.

The input pipeline creates and owns InputDeviceBindings as new input peripherals are connected to a device.

InputDeviceBinding is a Session Framework concept.

Input pipeline DeviceDescriptor

A property of the Rust struct InputEvent of type enum InputDeviceDescriptor and a FIDL table (see fuchsia.input.report.DeviceDescriptor).

An InputDeviceDescriptor describes the ranges of values a particular input device can generate. For example, a InputDeviceDescriptor::Keyboard contains the keys available on the keyboard, and a InputDeviceDescriptor::Touch contains the maximum number of touch contacts and the range of x- and y-values each contact can take on.

InputDeviceDescriptor is a Session Framework concept.

Input pipeline InputDeviceEvent

A property of the Rust struct InputEvent.

An InputDeviceEvent represents an input event from an input device. InputDeviceEvents contain more context than the raw InputReports they are parsed from. For example, InputDeviceEvent::Keyboard contains all the pressed keys, as well as the key's phase (pressed, released, etc.).

InputDeviceEvent is a Session Framework concept.

Input pipeline InputEvent

A Rust struct in the input pipeline client library.

An event from an input device containing context (a InputDeviceDescriptor) and state (e.g. phase and location of a button press). The input pipeline generates InputEvents from hardware signals.

InputEvent is a Session Framework concept.

Input pipeline InputHandler

A Rust trait in the input pipeline client library.

An InputHandler represents a client of InputEvents in an input pipeline. When an InputHandler receives an InputEvent, it does at least one of the following:

  1. Forwards the InputEvent to the relevant client component.
  2. Outputs a vector of InputEvents for the next InputHandler to process.

InputHandler is a Session Framework concept.

InputReport

A FIDL struct (see fuchsia.ui.InputReport).

A stateless representation of an event from a physical input device. Zircon generates InputReports from HID Reports.

Jiri

Jiri is a tool for multi-repo development. It is used to checkout the Fuchsia codebase. It supports various subcommands, which makes it easy for developers to manage their local checkouts.

Job

A Job is a kernel object that groups a set of related processes, their child processes, and their jobs (if any). Every process in the system belongs to a job and all jobs form a single rooted tree.

Kernel Object

A kernel object is a kernel data structure that is used to regulate access to system resources such as memory, i/o, processor time and access to other processes. Userspace can only reference kernel objects via Handles.

KOID

A Kernel Object Identifier.

LK

Little Kernel (LK) is the embedded kernel that formed the core of the Zircon Kernel. LK is more microcontroller-centric and lacks support for MMUs, userspace, system calls -- features that Zircon added.

Module

A Modular concept that is being deprecated.

A module is a role a component can play to contribute UI to a user experience container (story) within a Modular session. Any component that exports a Scenic ViewProvider can be be used as a module.

See Module concept docs for more.

Moniker

A moniker identifies a specific component instance in the component tree using a topological path.

A v1 component‘s moniker is defined as a tuple of (path to the component’s realm, component URL).

A v2 component's moniker is defined as a path to the component instance in the component instance tree.

Musl

Fuchsia's standard C library (libc) is based on Musl Libc.

Namespace

A namespace is the composite hierarchy of files, directories, sockets, services, and other named objects offered to components by their environment.

Netstack

An implementation of TCP, UDP, IP, and related networking protocols for Fuchsia.

Ninja

Ninja is the build system executing Fuchsia builds. It is a small build system with a strong emphasis on speed. Unlike other systems, Ninja files are not supposed to be manually written but should be generated by other systems, such as GN in Fuchsia.

OpaqueTest

OpaqueTest is a Rust client-side library that sets up hermetic tests for a v2 component.

Outgoing directory

A file system directory where a component may expose capabilities for others to use.

Paver

A tool in Zircon that installs partition images to internal storage of a device.

Platform Source Tree

The Platform Source Tree is the open source code hosted on fuchsia.googlesource.com, which comprises the source code for Fuchsia. A given Fuchsia system can include additional software from outside the Platform Source Tree by adding the appropriate Fuchsia Package.

Process

A Process is a kernel object that represents an instance of a program as a set of instructions that are executed by one or more threads together with a collection of capabilities. Every process is contained in a job.

Protocol

In FIDL, a protocol groups methods and events to describe how one process interacts with another.

In components v1, a component may access a protocol (called a “service” in v1) from its environment through its namespace by naming the protocol in its services whitelist.

In components v2, a protocol is used and routed to other components as a protocol capability.

Protocol capability

A capability that permits communicating with a protocol over a channel using a specified FIDL protocol. The server end of the channel is held by the component instance that provides the capability. The client end of the channel is given to the component instance that uses the capability.

Protocol capability is a components v2 concept.

Realm

In components v1, realm is synonymous to environment.

In components v2, a realm is a subtree of component instances in the component instance tree. It acts as a container for component instances and capabilities in the subtree.

Runner

A component that provides a runtime environment for other components, e.g. the ELF runner, the Dart AOT runner, the Chromium web runner.

Every component needs a runner in order to launch. Components express their dependency on a runner in the component's declaration.

When the component framework starts a component, it first determines the capabilities that the component should receive, then asks the component‘s runner to launch the component. The runner is responsible for creating any necessary processes, loading executable code, initializing language runtimes, handing control to the component’s entry points, and terminating the component when requested by the component framework.

Scenic

Scenic is a system service that composes graphical objects from multiple processes into a shared scene graph. Scenic includes views, input, compositor, and GPU services.

Sequential Device Driver

A sequential device driver is a hardware driver that will only service a single request at a time. The core driver synchronizes and serializes all requests.

Service

In FIDL, a service groups protocols to describe how one process interacts with another.

Services can be used and provided to other components by routing service capabilities.

Service capability

A capability that permits communicating with a service over a channel using a specified FIDL service. The server end of the channel is held by the component instance that provides the capability. The client end of the channel is given to the component instance that uses the capability.

Service capability is a components v2 concept.

Session

A session is a component that encapsulates a product’s user experience. It is the first product-specific component started on boot after the Session Manager. Sessions typically utilize aspects of the Session Framework during their development, in automated testing, and at runtime. At runtime, there is only one session component, but it can be composed of many sub-components. For example, the session for a graphical product instantiates Scenic (graphics) as a child component.

Session is a Session Framework concept.

Session Framework

The session framework is a framework for building products on Fuchsia. The framework provides software libraries, FIDL protocols, developer tools, and standards that are composed to create a particular product’s user experience.

See the session framework conceptual documentation.

Session Launcher

A FIDL protocol (see fuchsia.session.Launcher).

A protocol, exposed by the Session Manager, used to start or restart sessions. It is available to developer tools such as session_control to control session components at runtime.

Session Launcher is a Session Framework concept.

Session Manager

The platform component, started late in the Fuchsia boot sequence, that manages the lifecycle of the session. The session manager defines the set of system capabilities provided to sessions at runtime.

Session Manager is a Session Framework concept.

Storage capability

A storage capability is a capability that allocates per-component isolated storage for a designated purpose within a filesystem directory. Multiple component instances may be given the same storage capability, but underlying directories that are isolated from each other will be allocated for each individual use. This is different from directory capabilities, where a specific filesystem directory is routed to a specific component instance.

Isolation is achieved because Fuchsia does not support dotdot.

There are three types of storage capabilities:

Storage capability is a components v2 concept.

Thread

A Thread is a kernel object that represents a time-shared CPU execution context. Each thread is contained in a process.

userboot

userboot is the first process started by the Zircon kernel. It is loaded from the kernel image in the same way as the vDSO, instead of being loaded from a filesystem. Its primary purpose is to load the second process, bootsvc, from the bootfs.

ViewController

A FIDL protocol (see fuchsia.element.ViewController).

A ViewController represents a handle to a remote View that was launched by calling PresentView() on a GraphicalPresenter. With this handle, the caller (often, the session) can control the View's lifecycle. Closing the ViewController should close the presented view, and allow the system to reclaim its resources.

ViewHolderToken

A FIDL struct (see fuchsia.ui.views.ViewHolderToken).

A ViewHolderToken uniquely identifies an attachment point for a View in the global scene graph. Each ViewHolderToken has exactly one corresponding ViewToken.

ViewRef

A FIDL struct (see fuchsia.ui.views.ViewRef).

A ViewRef is a handle to a kernel object that identifies a unique View across the system. Two ViewRefs to the same View have the same KOID.

ViewSpec

A FIDL table (see fuchsia.element.ViewSpec).

A ViewSpec is a description of a view to be presented by a GraphicalPresenter.

ViewToken

A FIDL struct (see fuchsia.ui.views.ViewToken).

A ViewToken uniquely identifies a View, which is the root point for a subgraph in the global scene graph. Each ViewToken has exactly one corresponding ViewHolderToken.

Virtual Dynamic Shared Object

The Virtual Dynamic Shared Object (vDSO) is a Virtual Shared Library -- it is provided by the Zircon kernel and does not appear in the filesystem or a package. It provides the Zircon System Call API/ABI to userspace processes in the form of an ELF library that's “always there.” In the Fuchsia IDK and Fuchsia Driver Framework it exists as libzircon.so for the purpose of having something to pass to the linker representing the vDSO.

Virtual Memory Address Range

A Virtual Memory Address Range (VMAR) is a Zircon kernel object that controls where and how Virtual Memory Objects may be mapped into the address space of a process.

Virtual Memory Object

A Virtual Memory Object (VMO) is a Zircon kernel object that represents a collection of pages (or the potential for pages) that may be read, written, mapped into the address space of a process, or shared with another process by passing a Handle over a Channel.

Zircon Boot Image

A Zircon Boot Image (ZBI) contains everything needed during the boot process before any drivers are working. This includes the kernel image and a RAM disk for the boot filesystem.

Zedboot

Zedboot is a recovery image that is used to install and boot a full Fuchsia system. Zedboot is actually an instance of the Zircon kernel with a minimal set of drivers and services running used to bootstrap a complete Fuchsia system on a target device. Upon startup, Zedboot listens on the network for instructions from a bootserver that may instruct Zedboot to install a new OS. Upon completing the installation Zedboot will reboot into the newly installed system.

Zircon

Zircon is the microkernel and lowest level userspace components (driver runtime environment, core drivers, libc, etc) at the core of Fuchsia. In a traditional monolithic kernel, many of the userspace components of Zircon would be part of the kernel itself.

ZX

ZX is an abbreviation of “Zircon” used in Zircon C APIs/ABIs (zx_channel_create(), zx_handle_t, ZX_EVENT_SIGNALED, etc) and libraries (libzx in particular).

ZXDB

The native low-level system debugger.