Design document
Provide an exhaustive list of platform surface elements for computing platform surface test coverage for the CTS effort.
(References to already defined glossary items are typeset in cursive type.)
Platform surface element.
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.
Uniquely identify and enumerate useful platform surface elements in a given platform surface view.
Efficiently generate and traverse potentially many surface elements based on a platform surface view.
Allow reuse of already existing platform surface fragments across different platform surface kinds.
Allow incremental inclusion of platform surface fragments as they are defined and built.
Cooperate with our build system.
For the CTS test coverage dashboard to be universally useful, it should show the covered and uncovered parts of the platform surface.
The covered parts of the platform surface allow us to make certain correctness and safety guarantees about the underlying platform.
The uncovered parts of the platform surface guide CTS test authors to the parts of the API surface that are not adequately covered by CTS tests.
The platform surface area manifest complements (1) and fulfills (2).
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:
Allows different subsystems to evolve their own custom platform surface area formats.
Allows generating the platform surface area fragments concurrently. This avoids platform-wide build bottlenecks from large file merges.
Allows generating the platform surface area manifest file using a lightweight metadata propagation mechanism inherent in our build system.
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.
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.
[ { "file": "//out/workstation.qemu-x64/gen/sdk/lib/fdio/fdio.fragment.plasa.json", "kind": "api_cc", }, { "file": "//out/workstation.qemu-x64/gen/sdk/lib/stdcompat/stdcompat.fragment.plasa.json", "kind": "api_cc", }, { "file": "//out/workstation.qemu-x64/gen/sdk/lib/fit/fit.fragment.plasa.json", "kind": "api_cc", } ]
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.
{ "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 } ] }
We may want to update the CTS documentation to include the existence of the platform surface manifests.
plasa_artifacts.gni
that generates the fragment files.plasa_artifacts.gni
throughout the source tree.This is new functionality which does not have a compatibility baseline to maintain.
This design is neutral with respect to security and privacy as follows:
All platform surface fragments that are public knowledge are likely not subject to security and privacy constraints, by the nature of their public visibility.
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 will see more elements of the platform surface covered by the platform surface area manifest:
Represent command line utilities and flags in the manifest.
Represent other Plasa elements in the manifest.