Chrome OS Model Configuration tools / library

This is the homepage/documentation for chromeos-config which provides access to the model configuration for Chrome OS.

Design Documentation

See the design doc for information about the design. This is accessible from the public page too (‘Unified Builds’).

Important classes

See CrosConfig for the class to use to access configuration strings on a target. See cros_config_host.py for access to the config on a host or during a build.

CLI Usage

There are two CLIs built for Chrome OS configuration access, cros_config for use on the target, and cros_config_host for use on the host/during building. See the --help for each tool respectively for help on usage.

Chrome OS Firmware Build Targets

As Chrome OS firmware continues to evolve, this document is intended to provide guidance for developers on best practices for managing build targets for a given project.

There are currently 6 firmware build targets that may be applicable to any given project.

AP Firmware

1. coreboot

• coreboot_target_name for boxster projects
• coreboot for model.yaml based projects

This is applicable to every project.

2. depthcharge

• depthcharge_target_name for boxster projects
• depthcharge for model.yaml based projects

If depthcharge is required to use FW_CONFIG to probe for peripherals that depthcharge uses (such as storage, audio, etc.), then each coreboot build target will require a matching depthcharge target. There are two approaches to this:

• Organize the board.c file such that most setup code is shared and the defconfig board file and a ${VARIANT}.c setup file provide the differences.
• Each build target has its own board.c setup file If FW_CONFIG is not used by the program, then a single build target may be appropriate for an entire program.

3. bmpblk

• bmpblk_target_name for boxster projects
• bmpblk for model.yaml based projects

This project used to typically be built once per-program, but given the desire more flexibility (e.g., matching firmware screen resolution to native device resolution), many programs are supporting building this on a pre-project basis.

4. libpayload

• libpayload_target_name for boxster projects
• libpayload for model.yaml projects

This project is typically built to support one target per-program. The Kconfig options and the linker do a fine job of removing unused code from the resulting binary.

EC Firmware

Only 1 of the 2 is used for each program

• ChromiumOS EC

  This is the custom RTOS used by previous generations of Chrome OS devices.

• Zephyr Google recently joined Zephyr OS, therefore the EC team is rapidly moving towards using it as the primary EC choice for new platforms. This should become the default choice beginning with programs where lead devices ship after 2H '22.

Notes

1. A project here means all mainboards supported by a single logical config.star file (including the public and private parts).

NB. Projects which share a coreboot target must also share all other firmware build targets (including EC).

Debugging

libcros_config will emit a lot of debugging log messages if you set the CROS_CONFIG_DEBUG environment variable to a non-empty value before calling into the library.

Config Schema

Chrome OS config is schema validated YAML. New projects define their configuration via Starlark code generating protocol buffer outputs. These outputs are translated back into the config schema compatible YAML format by the cros_config_proto_converter.py. This allows the tooling described above to be compatible with the new approach. These configurations are generated by and stored in configuration projects that can be found in src/project/${program}/${project} locations of your chromiumos checkout. These config files are installed by chromeos-config-bsp ebuilds. Profiles within the overlay allow builds to target a specific project. For more details on the new approach see the documentation at ChromeOS Project Configuration. Some of the following details, such as YAML source location and YAML templating, do not apply to the new approach.

The following components make up the YAML based chromeos-config support:

YAML Source

The YAML source is designed for human maintainability. It allows for easy config sharing across many different devices (via anchors).

For background on YAML, see: Learn YAML in 10 minutes

The source is generally located at:

ls src/overlay-${BOARD}/chromeos-base/chromeos-config-bsp/files/model.yaml

Beyond the normal features of YAML, there are a few custom features supported that allow for even better re-use and expressiveness in the YAML config.

1. Templating - Templating allows config to be shared by letting callers reference variables in the config, which are then evaluated on a per device/sku/product basis.

   The basic syntax is:

   some-element: "{{some-template-variable}}"
   

   Valid template variables are any YAML elements that are currently in scope. When generating config, scope is evaluated in the following order:

   1. sku
   2. config (this is recursive ... any variable at any level can be referenced)
   3. device
   4. product

   This order allows shared anchors to define default variables that are then optionally overridden by either the device or product scope.

2. Local Variables - These are variables that are only used for templating and are dropped in the final JSON output. Variables starting with ‘$’ are considered local and are ignored after template evaluation. The basic syntax is:

   config:
     $some-local-variable: "some-value"
     some-element: "{{$some-local-variable}}"
   

   This supports the following:

   1. Defining local variables that are re-used in multiple places (e.g. file paths).
   2. Re-using common config (e.g. ‘identity’) where the variable value isn't known until the device/product/sku variables come into scope (e.g. $sku-id).

3. File Imports - File imports allow common snippets of YAML to be shared across multiple different implementations. File importing works the same as if the YAML files were cat'd together and then evaluated. File importing is recursive also, so it will support importing files that import other files. Import paths must be relative to the file that specifies the import.

   imports:
     - "some_common_import_file.yaml"
     - "../common/some_other_common_import_file.yaml"
   

The following provides a simple example of a config using both core YAML features and the custom features described above.

common_config: &common_config
  name: "{{$device-name}}"
  brand-code: "{{$brand-code}}"
  identity:
    platform-name: "SomePlatform"
    smbios-name-match: "SomePlatform"
    sku-id: "{{$sku-id}}"
  firmware-signing:
    key-id: "{{$key-id}}"
    signature-id: "{{name}}"
chromeos:
  devices:
    - $device-name: "SomeDevice"
      products:
        - $brand-code: "YYYY"
          $key-id: "SOME-KEY-ID"
      skus:
        - $sku-id: 0
          config:
            <<: *common_config
            wallpaper: "some-wallpaper"
        - $sku-id: 1
          config: *common_config

When this YAML is evaluated, it will fully expand out as the following:

chromeos:
  models:
    - name: "SomeDevice"
      brand-code: "YYYY"
      identity:
        platform-name: "SomePlatform"
        smbios-name-match: "SomePlatform"
        sku-id: 0
      firmware-signing:
        key-id: "SOME-KEY-ID"
        signature-id: "SomeDevice"
      wallpaper: "some-wallpaper"
    - name: "SomeDevice"
      brand-code: "YYYY"
      identity:
        platform-name: "SomePlatform"
        smbios-name-match: "SomePlatform"
        sku-id: 1
      firmware-signing:
        key-id: "SOME-KEY-ID"
        signature-id: "SomeDevice"

YAML Merging (multiple source YAML files)

There are various cases where it makes sense to manage YAML config across multiple different repos in separate YAML files.

E.g.

• Permissions based control via git repo access to specific config
• Extending overlays for device customization (e.g. Moblab)

This is supported through cros_config_schema tool and is invoked as part of the chromeos-config ebuild.

Using normal portage ebuilds/config, users can install as many YAML files as they wish to be merged together into: /usr/share/chromeos-config/yaml

E.g.

• models.yaml
• models-private.yaml (private config overlaid on the public config)

These files are then merged together based on their lexicographic name order.

Merging of YAML files applies the following characteristics:

1. Order is important. If two files supply the same config, the last file wins.

2. Identity is important. Config is merged based on ONE OF the following:

   1. name - If the name attribute matches, the config is merged
   2. identity - all fields of identity must match explicitly for code generation purposes. The fields are documented in identity. All fields that are present in the second file must be present in the first file. Note that a null value (the field is not present) and an empty string (the field is assigned the value of "") are not considered a match for code generation purposes.

For a detailed example of how merging works, see the following test files:

1. test_merge_base.yaml - First file passed to the merge routine.
2. test_merge_overlay.yaml - Second file passed (winner of any conflicts).
3. test_merge.json - Result generated from the merge.

YAML Transform (to SquashFS)

Before the config gets used on the device, it's translated to a flattened filesystem view of the configuration, and stored as a SquashFS image. This keeps the runtime code on the device very simple.

First, the configuration is flattened using the following algorithm:

• FOREACH device in chromeos/devices
  • FOREACH product in device/products
    • FOREACH sku in device/skus
      • sku varibles are put into scope
      • config variables are put into scope
      • device variables are put into scope
      • product variables are put into scope
      • with sku/config
        • config template variables are evaluated

After this, the configuration is stored in a SquashFS, with paths representing directories, and properties representing files.

/
├── identity.bin        # "Table of contents" to efficiently lookup device identity.
└── v1
    └── chromeos
        └── configs
            ├── 0
            │   ├── ...
            │   ├── power
            │   │   └── ...
            │   ├── wallpaper
            │   └── ...
            ├── 1
            │   ├── ...
            │   ├── power
            │   │   └── ...
            │   ├── wallpaper
            │   └── ...
            └── ...

This file gets installed at /usr/share/chromeos-config/configfs.img, and is used internally by the cros_configfs tool.

Making changes to a YAML model file

When modifying a model.yaml file there are few steps that need to be taken to manifest the change in a board target. Since the actual work to combine and process the YAML files is done in the chromeos-config ebuild, it needs to be remerged after the input YAML has been modified.

1. Start cros-workon on the ebuild where your source model.yaml lives:

   (chroot) $ cros-workon-${BOARD} start chromeos-base/chromeos-config-bsp
   

   Note: If you have access to the private overlays for a board, you‘ll notice there’s an additional package containing private configuration data, chromeos-base/chromeos-config-bsp-private. To cros-workon this package:

   (chroot) $ cros-workon-${BOARD} start chromeos-base/chromeos-config-bsp-private
   

2. After making your changes, emerge all affected ebuilds and the chromeos-config ebuild:

   (chroot) $ emerge-${BOARD} chromeos-config-bsp chromeos-config
   

   Alternatively, if you made changes in the private package:

   (chroot) $ emerge-${BOARD} chromeos-config-bsp chromeos-config-bsp-private chromeos-config
   

Schema Validation

The config is evaluated against a http://json-schema.org/ schema located at: chromeos-config/cros_config_host/cros_config_schema.yaml

NOTE: The schema is managed in YAML because it's easier to edit than JSON.

Only the transformed JSON is actually evaluated against the schema. Authors can do whatever makes sense in the YAML (from a sharing perspective) as long as it generates compliant JSON that passes the schema validation.

The schema documentation is auto-generated (and put into this README.md file) via: python -m cros_config_host.generate_schema_doc -o README.md

The schema definition is below:

CrOS Config Type Definitions (v2)

Definitions

In the tables below,

• Build-only attributes get automatically stripped from the platform JSON as part of the build.

model

arc

build-properties

hardware-features

media-profiles

audio

main

files

bluetooth

flags

camera

config-file

devices

flags

cros-healthd

battery

cached-vpd

cross-device

instant-tethering

demo-mode

detachable-base

files

fingerprint

firmware

build-targets

firmware-signing

hardware-properties

identity

keyboard

modem

nnpalm

power

autobrightness

config-file

proximity-sensor

lte

wifi

wifi-lte

scheduler-tune

thermal

files

touch

files

ui

apps

power-button

side-volume-button

wifi

non-tablet-mode-power-table-ath10k

tablet-mode-power-table-ath10k

geo-offsets-eu

geo-offsets-fcc

geo-offsets-rest-of-world

non-tablet-mode-power-table-rtw

tablet-mode-power-table-rtw

eu-power-table-mtk

fcc-power-table-mtk

non-tablet-mode-power-table-mtk

rest-of-world-power-table-mtk

tablet-mode-power-table-mtk

sar-file

On the Device

At bootup, cros_configfs is executed to mount /usr/share/chromeos-config/configfs.img at /run/chromeos-config/private. The table of contents is scanned to match the device's identity to a matching configuration, and the corresponding directory then gets mounted (via a bind mount) to /run/chromeos-config/v1.

Identity Matching

Identity matching is done by comparing properties which come from /identity to the corresponding values from firmware. If properties are left unspecified in /identity, they will match any value from firmware, or even a missing value.

The first config with a matching identity is selected.

The files in the table below, exposed from firmware by the kernel, are used to compare the values from firmware. Strings are compared case-insensitive.

File Parsing Notes

All files are parsed as strings, except where mentioned below:

/proc/device-tree/compatible: This file contains a list of null-terminated strings. If any of the strings in the list match device-tree-compatible-match, it is considered to be a match.

/sys/class/dmi/id/product_sku: This file is parsed as scanf("sku%u", &sku_id).

/proc/device-tree/firmware/coreboot/sku-id: 4 bytes, parsed as a 32-bit network-endian integer.

Accessing the Config

The configuration can be read by any language or library simply by reading the corresponding file to the property. For example, to read /ui/power-button:edge from the configuration, you can simply read the contents of /run/chromeos-config/v1/ui/power-button/edge.

There is also the cros_config command line tool, which can cat these files for you, or libcros_config, which provides C++ bindings used widely across platform2 to read these files.

Usage Instructions

Adding and testing new properties

Before starting, cros_workon the following:

(chroot) $ cros_workon --host start chromeos-config-host
(chroot) $ cros_workon --board=BOARD start chromeos-config-bsp chromeos-config

To introduce a new property, first add its definition to the schema:

chromeos-config/cros_config_host/cros_config_schema.yaml

Then update the README.md automatically via (unit tests will check this):

(chroot) $ python -m cros_config_host.generate_schema_doc -o README.md

To install the updated schema, run:

(chroot) $ FEATURES=test sudo -E emerge chromeos-config-host

To use the new property, update your respective YAML source file. e.g. overlay-${BOARD}-private/chromeos-base/chromeos-config-bsp/files/model.yaml

To install the changes, run:

(chroot) $ emerge-${BOARD} chromeos-config-bsp chromeos-config

At this point the updated config is located at:

/build/${BOARD}/usr/share/chromeos-config/yaml/config.yaml

To query your new item run the test command in the chroot:

(chroot) $  cros_config_host -c /build/${BOARD}/usr/share/chromeos-config/yaml/config.yaml -m <MODEL> get </path/to/property> <property name>

For instance:

(chroot) $ cros_config_host -c /build/coral/usr/share/chromeos-config/yaml /config.yaml -m robo360 get /firmware key-id
(chroot) $ cros_config_host -c /build/coral/usr/share/chromeos-config/yaml /config.yaml list-models

Device Testing

To test configuration changes on actual devices use the platform.CrosConfig Tast test. This will run cros_config tests for unibuilds and mosys for all devices. See HOWTO.