This page provides detailed information about Structured Configuration's behavior and implementation. For guides on using Structured Configuration, see:
- Structured Configuration introductory guide
- Assembling Structured Configuration from product configuration
- Evolving Structured Configuration schemas
- Verifying configuration values
Lifecycle
Configuration values are resolved when a component is created.
Resolution precedence
Component configuration "tailors the behavior of a component instance to the context it's running in," which implies that the most authoritative configuration values should be those which encode the most knowledge of the component instance's context.
Component Manager will resolve a value for each configuration field, preferring each source in this order:
- values from a developer override service (WIP)
- values from a component's parent
- values from the component's own package
A component developer working on an engineering build can have knowledge about everything running on the system, which makes those overrides the most authoritative. A parent can understand the context it provides to its children. Finally, because the values in the component's own package can only encode an understanding of how the component was packaged, all other information must be provided from an outside source.
Generated client libraries
Component authors are expected to access their configuration values using
client libraries generated by the configc tool. These libraries consume
the resolved VMO through an API provided by the component's runner (like
procargs for the ELF runner), verify that the checksum is correct, and return
the parsed configuration values to the caller.
Client libraries return local, non-static values with the configuration to give users the option of either passing values down their stack as arguments or explicitly placing configuration values in a globally-accessible location.
Because Component Manager will only start a component if it has valid configuration values, client libraries appear to the caller to be infallible and crash the component instance if they are unable to retrieve or parse configuration values.
Configuration value files
Component resolvers that return a component manifest that includes a config
schema must also return a configuration value file.
A configuration value files is a persisted FIDL message of the
type fuchsia.component.decl/ConfigValuesData.
Where compiled component manifests are conventionally stored in a package as
meta/*.cm, configuration value files are conventionally stored in a package
as meta/*.cvf.
Resolved VMO
Once component manager has resolved a component's configuration values from the
combination of values from the component resolver and any runtime overrides,
it encodes the configuration into a VMO which is provided to the runner in
fuchsia.component.runner/ComponentStartInfo.encoded_config.
The first 2 bytes of the VMO should be interpreted as an unsigned 16-bit little-endian integer which denotes the number of bytes following it that contain the configuration checksum. After the checksum, all the remaining bytes are a persistent FIDL message of a top-level struct, matching the layout used by the generated client library. The struct's fields match the configuration fields of the component's compiled manifest in the same order.
Checksum validation
As a guard rail against accidental misconfiguration from errors in packaging
configured components, cmc computes a hash of a component's config schema
when compiling its CML and includes that as a checksum in the compiled manifest
(*.cm). This checksum is also included in the configuration value file, the generated client library and the resolved VMO.
At build-time and component-creation-time, the compiled manifest's checksum is validated to match the checksum in the configuration value file. Component Manager then places the checksum in the resolved VMO when starting the component. The generated client libraries check that the value in the resolved VMO matches at runtime before parsing the actual configuration values.