Platform Surface Area Manifest

Design document

Motivation

Provide an exhaustive list of platform surface elements for computing platform surface test coverage for the CTF effort.

Glossary

(References to already defined glossary items are typeset in cursive type.)

Platform surface element.

A named smallest component of Fuchsia's public API or ABI.

Platform surface area.

An exhaustive collection of platform surface elements.

Platform surface fragment.

A subset of the platform surface area.

Platform surface area manifest.

A file containing pointers to the platform surface fragment files.

Requirements

1. Uniquely identify and enumerate useful platform surface elements in a given platform surface view.

2. Efficiently generate and traverse potentially many surface elements based on a platform surface view.

3. Allow reuse of already existing platform surface fragments across different platform surface kinds.

4. Allow incremental inclusion of platform surface fragments as they are defined and built.

5. Cooperate with our build system.

Why now?

For the CTF test coverage dashboard to be universally useful, it should show the covered and uncovered parts of the platform surface.

1. The covered parts of the platform surface allow us to make certain correctness and safety guarantees about the underlying platform.

2. The uncovered parts of the platform surface guide CTF test authors to the parts of the API surface that are not adequately covered by CTF tests.

The platform surface area manifest complements (1) and fulfills (2).

Stakeholders

• CTF maintainers
• CTF test authors

Design

The platform surface area is described in a collection of platform surface area fragment files, with a platform surface manifest file which in turn lists the location of all such files in Fuchsia's build output directory ($FUCHSIA_DIR/out/default or similar). By convention, the manifest file is called manifest.plasa.json, while the fragment files have names matching the file path pattern *.fragment.plasa.json, as seen in the diagram below.

A number of reasons influenced the choice of this hub-and-spoke manifest layout:

1. Allows different subsystems to evolve their own custom platform surface area formats.

2. Allows generating the platform surface area fragments concurrently. This avoids platform-wide build bottlenecks from large file merges.

3. Allows generating the platform surface area manifest file using a lightweight metadata propagation mechanism inherent in our build system.

4. Allows easy extension of the platform surface area metadata if needed.

The tooling needs to be cognizant of this file layout and ensure that all files are properly handled. For those tools that require single files, it should be easy to write a script that will be able to merge the files.

Manifest file format

The manifest file format is a sequence of JSON-formatted objects. Each object contains a reference to a fragment file, and a declaration of the type the fragment is expected to be. The manifest is a sequence of items as this is a format that is particularly easy to generate by our build system, while still being able to describe the content in sufficient detail.

• Sequence of...

  • kind (Enum): The kind of the fragment in question. Each distinct kind may be interpreted differently. At the time of this writing, the possible values are:

  • api_cc: denotes the fragment in question is following the C++ API fragment format

  • api_fidl: denotes the fragment in question is following the FIDL API summary format (per RFC-0076)

  • file (String): The fully qualified label of the fragment.

Sample

[
  {
    "file": "//out/workstation_eng.x64/gen/sdk/lib/fdio/fdio.fragment.plasa.json",
    "kind": "api_cc",
  },
  {
    "file": "//out/workstation_eng.x64/gen/sdk/lib/stdcompat/stdcompat.fragment.plasa.json",
    "kind": "api_cc",
  },
  {
    "file": "//out/workstation_eng.x64/gen/sdk/lib/fit/fit.fragment.plasa.json",
    "kind": "api_cc",
  }
]

C++ API fragment file format

The fragment file format is currently a sequence of platform element items. The format may be expanded as need arises.

• JSON object of...

  • items (Sequence) of...

  • name (String): The name of the platform surface element.

  • file (optional[String]): The file path to the file where the element is located.

  • line (optional[Integer]): The line of file where the element is defined.

Sample

{
  "items": [
        {
            "name": "fit::deferred_action::deferred_action<T>",
            "file": "gen/sdk/lib/fit/../../../../../../sdk/lib/fit/include/lib/fit/defer.h",
            "line": 81
        },
        {
            "name": "fit::deferred_action::operator bool",
            "file": "gen/sdk/lib/fit/../../../../../../sdk/lib/fit/include/lib/fit/defer.h",
            "line": 43
        }
  ]
}

Documentation & examples

We may want to update the CTF documentation to include the existence of the platform surface manifests.

• The rule that generates the manifest.
• The template plasa_artifacts.gni that generates the fragment files.
• Usage of the template plasa_artifacts.gni throughout the source tree.

Backwards compatibility

This is new functionality which does not have a compatibility baseline to maintain.

Security & privacy

This design is neutral with respect to security and privacy as follows:

1. All platform surface fragments that are public knowledge are likely not subject to security and privacy constraints, by the nature of their public visibility.

2. Any private platform surface fragments can be defined in a manifest that is outside of the public view. An overall platform surface manifest can be formed by including both the privately and the publicly accessible fragments into a single manifest, if it becomes needed.

Future work

Future work will see more elements of the platform surface covered by the platform surface area manifest:

1. Represent command line utilities and flags in the manifest.

2. Represent other Plasa elements in the manifest.