Google is committed to advancing racial equity for Black communities. See how.

Platform evolution next steps

Fuchsia is designed to evolve. However it's also a work in progress. This section highlights some of the work that is ongoing or hasn’t started yet that will promote Fuchsia’s ability to evolve. This document will be updated over time to reflect Fuchsia’s progress.

Last updated: September 2021

Versioning and compatibility metadata throughout the surface

  • FIDL availability annotations are not yet implemented. Once this is implemented, the next step is to apply these annotations to FIDL files.
  • Availability annotations are not yet implemented for C/C++ headers in the Fuchsia IDK. Once this is implemented, the next step is to apply these annotations to SDK header files.
  • FIDL API summaries are useful for detecting API-breaking changes. Currently we have no equivalent for C/C++ APIs. Potentially-breaking changes are detected by comparing content hashes to a known reference, which produces false detections. For instance reformatting a header has no bearing on APIs or ABIs, but will falsely trigger the change detector.
  • Support for vDSO backward compatibility. For instance if a component is known to target an older ABI revision then Fuchsia could load a vDSO shim into its address space that exports the old ABI and calls into the most recent vDSO ABI.
  • There is no mechanism yet for indicating what Fuchsia SDK version was used to build a given package or component. Introducing such a mechanism and using it to annotate prebuilt packages is useful for instance to detect incompatibility.

Complete Fuchsia ABI migrations to FIDL

While Fuchsia ABIs are largely defined in FIDL, there are still some legacy ABIs that are defined in other terms that don’t have the same affordances for evolution.

  • While syscalls are defined in FIDL, some of their input and output types are still defined as C structures in Zircon headers. For instance zx_object_get_info is defined in FIDL, but its output type (the buffer parameter) is a byte buffer that’s opaque to the FIDL definition and is formatted in terms of a zx_info_*_t C struct.
  • The processargs protocol is used to bootstrap newly-created processes with startup capabilities. The format of the bootstrap message is defined as C structs, and should be converted to FIDL.

Complete the Fuchsia SDK

The Fuchsia IDK and SDKs built on top of it can be used to develop Fuchsia components without checking out Fuchsia’s source code or using Fuchsia’s own build system. However there remain developer use cases that are not yet possible out-of-tree.

Finish the Component Framework migration

The new Component Framework (aka CFv2) has full control over the sandbox of component instances, and expresses sandboxes in terms of capabilities that decouple contracts from implementation details.

The legacy Component Framework (appmgr) supported sandbox features that allowed access to certain global namespaces and would expose components to platform implementation details that had no affordances for evolution such as versioning or transition support. The new Component Framework either enforces isolation or forbids access to these namespaces entirely. For instance the hub becomes hierarchically contained, only offering information about the component’s realm and its children but never of its parent, since a global hub is a form of ambient authority.

The components v2 migration is an ongoing multi-year effort. Currently the team is focused on migrating system components.

Deprecate unlisted platform ABIs

The fullness of the platform surface should be strictly defined, and expressed in terms such as FIDL that afford for evolution via such mechanisms as versioning and support for transitions. Currently there exist some aspects of the platform surface that don’t meet these requirements.

  • Retrieving build information uses a modern FIDL protocol. Previously this was done using a now-deprecated appmgr sandbox feature, which offered this information to components using raw file access that did not afford for evolution. This is now deprecated, new usage is discouraged, but there are still a few allowlisted legacy usages remaining.
  • Some out-of-tree component testing frameworks launch test doubles for platform components by specifying their fuchsia-pkg:// launch URLs. These URLs don’t have evolution affordances. Instead out-of-tree components find themselves exposed to platform implementation details such as the names of specific packages containing specific components that implement certain platform capabilities. These tests often break between Fuchsia platform and SDK revisions, even though no API or ABI breaking change is registered in the SDK or platform surface. Beyond deprecating existing usages, we should take steps to prevent these issues from reoccurring.
  • Scripting Layer for Fuchsia (SL4F) is a system automation framework for testing. SL4F is driven by a host-side test using a JSON-RPC/HTTPS protocol that is implemented to the specification of a pre-existing system. This decision accelerated porting a large inventory of connectivity tests. However the JSON-RPC/HTTPS protocol doesn’t have the same affordances for evolution as those found in FIDL and that benefit ffx plugins, nor does it have a schema. Therefore moving forward we should not support SL4F for system automation by out-of-tree tests, and introduce an alternative solution.

Formalize diagnostics contracts

Fuchsia supports multiple diagnostics tools for understanding the system’s internal state and for troubleshooting problems. Internal diagnostics exposes implementation details by its nature, surfacing such information as process names and hierarchies.

This information is useful for instance when troubleshooting a defective system or when collecting a snapshot such as after a crash. In such instances, internal implementation details are of interest. However, diagnostics don’t make for good public contracts.

  • Runtime diagnostics information, such as a particular component’s log or an Inspect property, can be read at runtime using the fuchsia.diagnostics.ArchiveAccessor capability, as specified by a selector. The selector consists of a component moniker, a diagnostics hierarchy path selector, and a property selector. Monikers may expose platform implementation details such as the topology and names of platform components. Hierarchy and property selectors may also be considered implementation details, and in addition don’t have evolution mechanisms. These are known instances of out-of-tree components in Fuchsia-based products that use diagnostics selectors to read system diagnostics information at runtime. These components are exposed to platform implementation details and often break when these details change. Clients of Fuchsia diagnostics that are outside of the platform itself should be ported to using strictly-defined FIDL protocols to read precisely the information that they need, and the open-ended ArchiveAccessor capability should be restricted for further use by out-of-tree components.
  • Components generate diagnostics information in different ways, such as an internal hierarchy of Inspect properties or as unstructured text in logs. Most platform components that do this don’t promise a particular schema for this information. Even Inspect which has structure and types doesn’t have all the evolution affordances found in FIDL for instance. Therefore processing platform diagnostics offline, such as in a tool that’s not provided by the SDK or in a product-specific dashboard, is bound to break.
  • Performance tools such as tracing, CPU performance monitoring, ,and mem collect and expose performance information in such terms as the names of processes and their interrelationships. This information is useful to investigate the performance of some systems, but it reflects private implementation details, not public contracts.

Deprecate legacy developer tools

Several SDK tools are offered to Fuchsia developers, most importantly ffx and its many commands. The new ffx tool interacts between the host and a Fuchsia target in terms defined in FIDL, which affords for evolution. However some legacy tools are still offered to out-of-tree developers that don’t have the same evolution affordances.

  • SSH is supported (such as with the fssh tool and provides the host with a developer experience similar to a remote root shell on a target Fuchsia device. The client may circumvent the intended platform surface such as by directly observing, starting, and killing system processes.
  • SCP (file copy over SSH) is similarly supported, and offers unrestricted access to global namespaces and to mutable filesystems, again circumventing the intended platform surface.
  • Certain developer features (example) are exposed to developers as legacy shell components rather than as ffx commands. This exposes developers to platform implementation details that can’t easily evolve such as the names of packages and components, and expresses inputs and outputs as human-readable text rather than typed and structured data.
  • Some ffx commands, for instance ffx component, expose internal implementation details such as component monikers and topologies. These are meant for diagnostics and troubleshooting, not as an API.

Compatibility testing

API and ABI compatibility can be checked using continuous integration with static analysis tools and build systems. In addition, the Fuchsia Compatibility Test Suite (CTS) can test different supported combinations of platform and SDK versions. These tests can extend the notion of compatibility from APIs and ABIs to also ensure that expected behaviors that are important are preserved.

The CTS project is new and coverage is fairly low. CTS is a form of defense in depth, so increasing coverage helps ensure that compatibility is as intended, even if CTS coverage never reaches 100% of the platform surface.