You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This is the homepage/documentation for chromeos-config which provides access to
the model configuration for Chrome OS.
[TOC]
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
coreboot
coreboot_target_name for boxster projects
coreboot for model.yaml based projects
This is applicable to every project.
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.
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.
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
{#project} 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).
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.
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:
sku
config (this is recursive ... any variable at any level can be
referenced)
device
product
This order allows shared anchors to define default variables that are then
optionally overridden by either the device or product scope.
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:
Defining local variables that are re-used in multiple places (e.g. file
paths).
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).
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.
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:
Order is important. If two files supply the same config, the last file wins.
Identity is important. Config is merged based on ONE OF the following:
name - If the name attribute matches, the config is merged
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:
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.
This file gets installed at /usr/share/chromeos-config/configfs.img, and is
used internally by the cros_configfs tool.
FRID identity combination generation
Some models may use multiple FRID match values in their identity configurations.
While only the configured combinations should be present in finalized production
devices, for devices in the factory process and for development devices, the
FRID may be set to another FRID used by that model until the firmware has been
updated to one with the final FRID. To support devices in this state, identity
configurations are generated to cover all FRID combinations. That is, for each
identity object with the FRID ignored, one config instance is generated for each
FRID value used within that model. For example, given the example input below:
In practice, this step takes place during the YAML transform step above, once
the configuration has been flattened.
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.
Start cros-workon on the ebuild where your source model.yaml lives:
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:
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.
Contains boolean flags or enums for hardware properties of this board, for example if it's convertible, has a touchscreen, has a camera, etc. This information is used to auto-generate C code that is consumed by the EC build process in order to do run-time configuration. If a value is defined within a config file, but not for a specific model, that value will be assumed to be false for that model. If a value is an enum and is not specified for a specific model, it will default to "none". All properties must be booleans or enums. If non-boolean properties are desired, the generation code in cros_config_schema.py must be updated to support them.
Override the HWID reported by crossystem. This property should only be used for devices supporting non-ChromeOS firmware, where we don't have the ability to set the HWID in GBB.
Google code name for the given model. While it is OK to use this string for human-display purposes (such as in a debug log or help dialog), or for a searchable-key in metrics collection, it is not recommended to use this property for creating model-specific behaviors. In this case, add a property to the schema which describes your behavior and use that instead.
Some projects store SKU ID, OEM ID and Board Revision in an EEPROM and only SKU ID can be updated in the factory and RMA flow but others should be pre-flashed in the chip level. In this case, we would like to validate whether oem-id here from the updated SKU ID matches the one in the EEPROM so we can prevent this device from being updated to another OEM's devices.
Defines settings that control power management functions. This mostly defines power_manager preferences, but there are a few other power related settings included. For details about each power_manager preference, see - src/platform2/power_manager/common/power_constants.h/cc For examples on setting these properties (including multiline examples), see the power config example in test_data/test.yaml
Sets limits on maximum WiFi transmit power for tablet and non-tablet device configurations. This config must contain properties for ath10k driver, rtw88 driver, rtw89 driver, mtk driver, or intel driver. Note that configs for the intel driver are delivered as encoded wifi sar hex files.
Defines media_profiles.xml file provided to ARC during initialization.
scale
integer
False
False
The screen density value in dpi that will be used for ARC apps. This value should be from the list of DPIs in android cdd.
build-properties
Attribute
Type
RegEx
Required
Oneof Group
Build-only
Description
device
string
True
False
Device name to report in 'ro.product.device'. This is often '{product}_cheets' but it can be something else if desired.
first-api-level
string
False
False
The first Android API level that this model shipped with. Deprecated since M94 (b/187778952).
marketing-name
string
False
False
Name of this model as it is called in the market, reported in 'ro.product.model'. This often starts with '{oem}'.
metrics-tag
string
True
False
Tag to use to track metrics for this model. The tag can be shared across many devices if desired, but this will result in larger granularity for metrics reporting. Ideally the metrics system should support collation of metrics with different tags into groups, but if this is not supported, this tag can be used to achieve the same end. This is reported in 'ro.product.metrics.tag'.
oem
string
False
False
Original Equipment Manufacturer for this model. This generally means the OEM name printed on the device.
pai-regions
string
(^([a-zA-Z0-9\.\-]+,)*[a-zA-Z0-9\.\-]+$)|(^\*$)
False
False
(Optional) Comma-separated allow list of region codes that can be appended to 'ro.oem.key1' for the purpose of targeting Play Auto Install applications by region. The value(s) should match the values that would be returned by cros_region_data region_code for the relevant region(s). If the device's region code is not in the allow list, or if there is no allow list, 'ro.oem.key1' will not include the region code. The allow list can also be a single '*' character to indicate that the region code should always be appended.
product
string
True
False
Product name to report in 'ro.product.name'. This may be the device name, or it can be something else, to allow several devices to be grouped into one product.
hardware-features
Attribute
Type
RegEx
Required
Oneof Group
Build-only
Description
build-path
string
True
True
Source of the file relative to the build system.
system-path
string
True
False
Installation path for the file on the system image.
media-codecs
Attribute
Type
RegEx
Required
Oneof Group
Build-only
Description
build-path
string
True
True
Source of the file relative to the build system.
system-path
string
True
False
Installation path for the file on the system image.
media-codecs-performance
Attribute
Type
RegEx
Required
Oneof Group
Build-only
Description
build-path
string
True
True
Source of the file relative to the build system.
system-path
string
True
False
Installation path for the file on the system image.
media-profiles
Attribute
Type
RegEx
Required
Oneof Group
Build-only
Description
build-path
string
True
True
Source of the file relative to the build system.
system-path
string
True
False
Installation path for the file on the system image.
Stop the bluetooth adapter on suspend and start it on resume.
branding
Attribute
Type
RegEx
Required
Oneof Group
Build-only
Description
marketing-name
string
False
False
Name of this model as it is called in the market, reported in 'ro.product.model'. This often starts with '{oem-name}'.
oem-name
string
False
False
Original Equipment Manufacturer for this model. Generally this means the OEM name printed on the device. This field can only be included after the product has been publicly announced AND should be filled by OEM. It is recommended not to use this field directly, and use cros_healthd Mojo interface instead as a general solution.
Bit flags representing camera capabilities of this device. A camera module can be mounted on this slot only if all the flags match.
has-privacy-switch
boolean
False
False
The camera has a privacy switch that can disable the output when enabled.
ids
array - string
False
False
An identifier string of camera module. For USB cameras this must be 4-digit hexadecimal VID and PID separated by a colon, e.g. 0123:abcd. For MIPI cameras it depends on vendor software usage.
interface
string
True
False
The interface type of the camera device.
orientation
integer
True
False
Clockwise angle through which the output image needs to be rotated to be upright on the device screen in its native orientation.
privacy-switch-is-delayed
boolean
False
False
The state of the privacy switch can be read only when the camera stream is active.
Upper bound for the battery's wear percentage. Battery health routine in cros_healthd uses this field as a threshold to determine whether the battery is in good condition. Minimum value: 0x0. Maximum value: 0x64.
Threshold number in percentage which NVMe wear level routine (only available to wilco devices) in cros_healthd examines wear level status against. Minimum value: 0x0. Maximum value: 0x63.
The Product ID of the detachable base. This value can be queried by command 'lsusb'. By taking this as an example: Bus 001 Device 032: ID 18d1:503c Google LLC the product-id is 20540(=0x503c).
touch-image-name
string
False
False
The touchpad binary name which is placed under /lib/firmware. This is only needed if the detachable base contains touchpad.
usb-path
string
False
False
Searches and finds the idVendor and idProduct under sysfs /sys/bus/usb/devices/* which matches the vendor-id and product-id. By taking this as an example: '/sys/bus/usb/devices/1-1.1' The usb-path is '1-1.1'.
vendor-id
integer
False
False
The Vendor ID of the detachable base. This value can be queried by command 'lsusb'. By taking this as an example: Bus 001 Device 032: ID 18d1:503c Google LLC the vendor-id is 6353(=0x18d1).
files
Attribute
Type
RegEx
Required
Oneof Group
Build-only
Description
destination
string
False
True
Installation path for the file on the system image.
source
string
False
True
Source of the file relative to the build system ${FILESDIR}
symlink
string
False
True
Symlink file that will be installed pointing to the destination.
dgpu
Attribute
Type
RegEx
Required
Oneof Group
Build-only
Description
dgpu-type
string
False
False
type of dGPU.
has-dgpu
boolean
False
False
Whether the model has discrete GPU.
displays
Attribute
Type
RegEx
Required
Oneof Group
Build-only
Description
connector-type
integer
False
False
The libdrm connector type that must match for the properties to apply to this display. For example, specify 14 for eDP. See drm_mode.h included with libdrm for all possible values. Minimum value: 0x0. Maximum value: 0x14.
The radius, in physical pixels, of the rounded corner. Minimum value: 0x0.
bottom-right
integer
False
False
The radius, in physical pixels, of the rounded corner. Minimum value: 0x0.
top-left
integer
False
False
The radius, in physical pixels, of the rounded corner. Minimum value: 0x0.
top-right
integer
False
False
The radius, in physical pixels, of the rounded corner. Minimum value: 0x0.
efi
Attribute
Type
RegEx
Required
Oneof Group
Build-only
Description
bootvar-name-override
string
[a-zA-Z0-9 ]+
False
False
Override the label/description of EFI boot entries managed by postinstall. The default is hard-coded in postinstall. This should be used by devices with non-ChromeOS firmware, in conjunction with the manage_efi_boot_entries USE flag.
fingerprint
Attribute
Type
RegEx
Required
Oneof Group
Build-only
Description
board
string
False
False
Specifies the fingerprint board in use.
fingerprint-sensor-type
string
False
False
Type of FP sensor. Currently describes whether FP is overlapped on the power button or not.
ro-version
string
False
True
RO version for the fingerprint firmware for the FPMCU specified by the "board" property. If not specified, the default RO version for the FPMCU is used.
sensor-location
string
False
False
Specifies the location of the fingerprint sensor.
firmware
Attribute
Type
RegEx
Required
Oneof Group
Build-only
Description
bcs-overlay
string
False
True
BCS overlay path used to determine BCS file path for binary firmware downloads.
Name of the file located in BCS under the respective bcs-overlay.
ec-rw-image
string
False
True
Name of the file located in BCS under the respective bcs-overlay.
firmware-config
integer
False
False
The firmware config bitmap to be flashed to the CBI. This field is used in the factory.
image-name
string
False
False
The name of the firmware image used by the firmware updater. Typically the device name, but can differ when a device may have two or more different firmware images.
key-id
string
False
True
Key ID from the signer key set that is used to sign the given firmware image.
main-ro-image
string
False
True
Name of the file located in BCS under the respective bcs-overlay.
main-rw-image
string
False
True
Name of the file located in BCS under the respective bcs-overlay.
name
string
False
True
This is a human-recognizable name used to refer to the firmware. It will be used when generating the shellball via firmware packer. Mainly, this is only for compatibility testing with device tree (since DT allowed firmwares to be named).
no-firmware
boolean
False
True
Set this flag to True to indicate the sku has no firmware bundle (bios+ec) and should be included in the firmware section even if build-targets is not specified.
pd-ro-image
string
False
True
Name of the file located in BCS under the respective bcs-overlay.
build-targets
Attribute
Type
RegEx
Required
Oneof Group
Build-only
Description
base
string
False
True
Build target of the base EC firmware for a detachable device, that will be considered dirty when building/testing
bmpblk
string
False
True
Build target that will be considered dirty when building/testing locally.
coreboot
string
False
True
Build target that will be considered dirty when building/testing locally.
depthcharge
string
False
True
Build target that will be considered dirty when building/testing locally.
ec
string
False
True
Build target that will be considered dirty when building/testing locally.
ec-extras
array - string
False
True
Extra EC build targets to build within chromeos-ec.
gsc
string
False
True
Build target that will be considered dirty when building/testing locally.
ish
string
False
True
Build target that will be considered dirty when building/testing locally.
libpayload
string
False
True
Build target that will be considered dirty when building/testing locally.
u-boot
string
False
True
Build target that will be considered dirty when building/testing locally.
zephyr-detachable-base
string
False
True
Specifies the detachable base of Zephyr-based firmware target to build.
zephyr-ec
string
False
True
Specifies the list of Zephyr-based firmware targets to build.
firmware-signing
Attribute
Type
RegEx
Required
Oneof Group
Build-only
Description
key-id
string
True
True
Key ID from the signer key set that is used to sign the given firmware image.
sig-id-in-customization-id
boolean
False
True
Indicates that this model cannot be decoded by the mapping table. Instead the model is stored in the VPD (Vital Product Data) region in the customization_id property. This allows us to determine the model to use in the factory during the finalization stage. Note that if the VPD is wiped then the model will be lost. This may mean that the device will revert back to a generic model, or may not work. It is not possible in general to test whether the model in the VPD is correct at run-time. We simply assume that it is. The advantage of using this property is that no hardware changes are needed to change one model into another. For example we can create 20 different whitelabel boards, all with the same hardware, just by changing the customization_id that is written into SPI flash.
signature-id
string
True
True
ID used to generate keys/keyblocks in the firmware signing output.
hardware-properties
Attribute
Type
RegEx
Required
Oneof Group
Build-only
Description
display-type
string
False
False
Denotes the type of display this device contains.
fan-count
integer
False
False
The number of fan in the device. Minimum value: 0x0. Maximum value: 0x7.
form-factor
string
False
False
Denotes the form factor of the device.
has-audio-jack
boolean
False
False
True if the device has an audio jack.
has-backlight
boolean
False
False
Does the device have a backlight.
has-base-accelerometer
boolean
False
False
Is there an accelerometer in the base of the device.
has-base-gyroscope
boolean
False
False
Is there a gyroscope in the base of the device.
has-base-light-sensor
boolean
False
False
Is there a light sensor in the base of the device.
has-base-magnetometer
boolean
False
False
Is there a magnetometer in the base of the device.
has-camera-light-sensor
boolean
False
False
Is there a light sensor in the camera of the device.
has-hdmi
boolean
False
False
True if the device has an HDMI port.
has-lid-accelerometer
boolean
False
False
Is there an accelerometer in the lid of the device.
has-lid-gyroscope
boolean
False
False
Is there a gyroscope in the lid of the device.
has-lid-light-sensor
boolean
False
False
Is there a light sensor in the lid of the device.
has-lid-magnetometer
boolean
False
False
Is there a magnetometer in the lid of the device.
has-poe-peripheral-support
boolean
False
False
Does the device have hardware for connecting PoE peripherals.
has-privacy-screen
boolean
False
False
Does the device have a privacy screen.
has-sd-reader
boolean
False
False
True if the device has an SD card reader.
has-side-volume-button
boolean
False
False
True if the device has a side volume button.
has-touchscreen
boolean
False
False
Does the device have a touchscreen.
is-lid-convertible
boolean
False
False
Can the lid be rotated 360 degrees.
psu-type
string
False
False
Type of PSU the device has: - battery: the device has a battery intended for primary use - AC_primary: the device has a battery, but it is not intended for primary use - AC_only: the device has no battery - no_power: the device does not receive power in any direct manner (e.g., it is virtualized)
recovery-input
string
False
False
Denotes the input method for entering device recovery.
storage-type
string
False
False
Type of the fixed storage device.
stylus-category
string
False
False
Denotes the category of stylus this device contains.
hdmi-cec
Attribute
Type
RegEx
Required
Oneof Group
Build-only
Description
power-off-displays-on-shutdown
boolean
False
False
Automatically power off all connected displays on shutdown.
power-on-displays-on-boot
boolean
False
False
Automatically power on all connected displays on boot.
hps
Attribute
Type
RegEx
Required
Oneof Group
Build-only
Description
has-hps
boolean
False
False
Whether the model has an hps device.
identity
Attribute
Type
RegEx
Required
Oneof Group
Build-only
Description
custom-label-tag
string
False
False
custom_label_tag value set in the VPD, to add branding over an unbranded base model. Note that whitelabel_tag is the historical name for this VPD value, and is accepted as well.
customization-id
string
False
False
'customization_id' value set in the VPD for non-unibuild Zergs and Whitelabels. Deprecated for use in new products since 2017/07/26.
feature-device-type
string
False
False
Type of feature enablement for this device
frid
string
False
False
String which must match the AP firmware FRID (first part before the period) in order for the config to match. Leaving this value unset will cause the config to match any FRID.
platform-name
string
False
False
Do not set or use this value. It is no longer used and is pending deletion.
sku-id
integer
False
False
SKU/Board strapping pins configured during board manufacturing. Leaving this value unset will cause the config to match any SKU ID. Minimum value: -0x1. Maximum value: 0x7fffffff.
keyboard
Attribute
Type
RegEx
Required
Oneof Group
Build-only
Description
backlight
boolean
False
False
Specifies the existence of backlight.
mcutype
string
False
False
Type of MCU firmware, if present.
numpad
boolean
False
False
Specifies the existence of numpad.
modem
Attribute
Type
RegEx
Required
Oneof Group
Build-only
Description
firmware-variant
string
False
False
Variant of the modem firmware to be used. This value is read by modemfwd to match against the variant field of a firmware entry in a firmware manifest. In most cases, we simply use the model name as the value.
modem-type
string
[0-9]+
False
False
The type of modem present on the device.
wedge-reboot-delay-ms
string
[0-9]+
False
False
Delay in milliseconds after which we pulse the modem reset GPIO if it hasn't appeared on the USB bus. This value is used by modemfwd and defaults to 5 minutes if not defined.
Enable (1) or disable (0) wake from touchpad. If not set, default to enable. When set to enable, on many devices, firmware is in charge of controlling whether to wake from touchpad. This flag is reserved for older devices without firmware support (Nami and Coral) and please do not set for new devices.
The policy to offline CPUs to reduce power consumption. Mainly used by battery-saver mode (battery-saver-power-preferences). Empty by default and CPU won't be offlined.
The policy to offline CPUs to reduce power consumption. Mainly used by battery-saver mode (battery-saver-power-preferences). Empty by default and CPU won't be offlined.
The policy to offline CPUs to reduce power consumption. Mainly used by battery-saver mode (battery-saver-power-preferences). Empty by default and CPU won't be offlined.
The policy to offline CPUs to reduce power consumption. Mainly used by battery-saver mode (battery-saver-power-preferences). Empty by default and CPU won't be offlined.
The policy to offline CPUs to reduce power consumption. Mainly used by battery-saver mode (battery-saver-power-preferences). Empty by default and CPU won't be offlined.
The policy to offline CPUs to reduce power consumption. Mainly used by battery-saver mode (battery-saver-power-preferences). Empty by default and CPU won't be offlined.
The policy to offline CPUs to reduce power consumption. Mainly used by battery-saver mode (battery-saver-power-preferences). Empty by default and CPU won't be offlined.
The policy to offline CPUs to reduce power consumption. Mainly used by battery-saver mode (battery-saver-power-preferences). Empty by default and CPU won't be offlined.
The policy to offline CPUs to reduce power consumption. Mainly used by battery-saver mode (battery-saver-power-preferences). Empty by default and CPU won't be offlined.
The policy to offline CPUs to reduce power consumption. Mainly used by battery-saver mode (battery-saver-power-preferences). Empty by default and CPU won't be offlined.
The policy to offline CPUs to reduce power consumption. Mainly used by battery-saver mode (battery-saver-power-preferences). Empty by default and CPU won't be offlined.
The policy to offline CPUs to reduce power consumption. Mainly used by battery-saver mode (battery-saver-power-preferences). Empty by default and CPU won't be offlined.
The policy to offline CPUs to reduce power consumption. Mainly used by battery-saver mode (battery-saver-power-preferences). Empty by default and CPU won't be offlined.
The policy to offline CPUs to reduce power consumption. Mainly used by battery-saver mode (battery-saver-power-preferences). Empty by default and CPU won't be offlined.
SSFC bitmap mask for bits that should be preserved after RMA, e.g. configs that can only be set by the factory but not the RMA center. Minimum value: 0x0. Maximum value: 0xffffffff.
Component name in the probe statement, e.g. gyroscope_1.
value
integer
False
False
SSFC value of the component. Minimum value: 0x0. Maximum value: 0xffffffff.
scheduler-tune
Attribute
Type
RegEx
Required
Oneof Group
Build-only
Description
boost-arcvm
number
False
False
(Optional) Global scheduler's boost factor of the ARCVM vcores and host services. For normal architectures, the boost-arcvm is directly converted to % boost value, where 1.0 is 100%. For the little.Big architecture, the ARCVM will be boosted by a % value, calculated from the formula little-core-freq / big-core-freq * boost-arcvm. Besides boosting the scheduler for the VM by a % value, the cgroup's uclamp.latency_sensitive attribute is enabled to further reduce the scheduling latency. Note - this is intended to be a temporary solution, which will be removed upon having the more appropriate scheduler improvements ready.
boost-top-app
integer
False
False
(Optional) Scheduler's boost value(%) for ARCVM topmost applications. When top-app class application is running, ARCVM applies this value to scheduler attribute. Tasks with higher boost value are more likely to have higher operating power point even when the system is low-utilized. If it is not set, the default value will be calculated by the performance ratio of the highest performance core and the lowest performance core. So the recommended value is higher than that. 0 means no boost and is not recommended. Minimum value: 0x0. Maximum value: 0x64.
boost-urgent
integer
False
False
(Optional) Scheduler's boost value(%) for urgent tasks. When an urgent thread is created, chrome applies this value to scheduler attribute. Tasks with higher boost value are more likely to have higher operating power point even when the system is low utilized. Minimum value: 0x0. Maximum value: 0x64.
cpuset-nonurgent
string
^[0-9]+(-[0-9]+|(,[0-9]+)+)$
False
False
(Optional) non-urgent task are only allowed to use given CPUs.
input-boost
integer
False
False
(Optional) chromium kernel has a cpu-boost feature, which boosts CPUs for a short duration when user intraction is detected from input devices. This value specifies how much CPUs will be boosted. Minimum value: 0x0. Maximum value: 0x64.
thermal
Attribute
Type
RegEx
Required
Oneof Group
Build-only
Description
dptf-dv
string
False
False
System image path to the .dv file containing DPTF (Dynamic Platform and Thermal Framework) settings.
Disabled features passed to the Ash window manager and system UI. Each entry should be a string of the form FeatureName. If this property is not set, features will be determined by other cros_config properties. Serialized to a null byte separated string when written to configfs.img
ash-enabled-features
array - string
False
True
Enabled features passed to the Ash window manager and system UI. Each entry should be a string of the form FeatureName. If this property is not set, features will be determined by other cros_config properties. Serialized to a null byte separated string when written to configfs.img
extra-ash-flags
array - string
False
True
Switches passed to the Ash window manager and system UI. Each entry should be a string of the form --=, or -- for boolean switches. If this property is not set, flags will be determined by other cros_config properties. Serialized to a null byte separated string when written to configfs.img
handwriting-recognition-web-platform-api
boolean
False
False
Whether the handwriting recognition web platform API is supported.
help-content-id
string
False
False
Identifier passed to the Showoff app to identify any device-specific help content to be displayed.
Defines the position of the side volume button. region indicates whether the button is at the side of the "screen" or "keyboard" of the device. side indicates which edge the button is anchored to while the device in landscape primary screen orientation. It can be "left", "right", "top", "bottom".
apps
Attribute
Type
RegEx
Required
Oneof Group
Build-only
Description
extra-web-apps-dir
string
False
True
Subdirectory of external web apps directory (/usr/share/google-chrome/extensions/web_apps) containing additional apps which should be installed on the device.
Offsets which are applied to WiFi power limits depending on the current regulatory domain. Offsets in units of 0.125 dBm. The sum of a geo offset and any power limit to which it applies cannot exceed 255. When the current regulatory domain is unknown or has yet to be determined, the base transmit power limits are used without any geo offsets applied. 'geo-offsets-fcc' is used for regulatory domains which follow FCC guidelines, 'geo-offsets-eu' is used for regulatory domains which follow ETSI guidelines, and 'geo-offsets-rest-of-world' is used for regulatory domains which don't follow FCC or ETSI guidelines.
Offsets which are applied to WiFi power limits depending on the current regulatory domain. Offsets in units of 0.125 dBm. The sum of a geo offset and any power limit to which it applies cannot exceed 255. When the current regulatory domain is unknown or has yet to be determined, the base transmit power limits are used without any geo offsets applied. 'geo-offsets-fcc' is used for regulatory domains which follow FCC guidelines, 'geo-offsets-eu' is used for regulatory domains which follow ETSI guidelines, and 'geo-offsets-rest-of-world' is used for regulatory domains which don't follow FCC or ETSI guidelines.
Offsets which are applied to WiFi power limits depending on the current regulatory domain. Offsets in units of 0.125 dBm. The sum of a geo offset and any power limit to which it applies cannot exceed 255. When the current regulatory domain is unknown or has yet to be determined, the base transmit power limits are used without any geo offsets applied. 'geo-offsets-fcc' is used for regulatory domains which follow FCC guidelines, 'geo-offsets-eu' is used for regulatory domains which follow ETSI guidelines, and 'geo-offsets-rest-of-world' is used for regulatory domains which don't follow FCC or ETSI guidelines.
[rtw] WiFi power chain for use with Realtek rtw88 or rtw89 drivers. Limits in units of 0.125 dBm for rtw88 and 0.25 dBm for rtw89. 5g band 2 (channels 5.35G-5.47G) power limit is not supported.
[rtw] WiFi power chain for use with Realtek rtw88 or rtw89 drivers. Limits in units of 0.125 dBm for rtw88 and 0.25 dBm for rtw89. 5g band 2 (channels 5.35G-5.47G) power limit is not supported.
2G band power limit (0.25dBm) Minimum value: 0x0. Maximum value: 0xff.
limit-5g
integer
False
False
5G band power limit (0.25dBm) Minimum value: 0x0. Maximum value: 0xff.
tablet-mode-power-table-ath10k
Attribute
Type
RegEx
Required
Oneof Group
Build-only
Description
limit-2g
integer
False
False
2G band power limit (0.25dBm) Minimum value: 0x0. Maximum value: 0xff.
limit-5g
integer
False
False
5G band power limit (0.25dBm) Minimum value: 0x0. Maximum value: 0xff.
geo-offsets-eu
Attribute
Type
RegEx
Required
Oneof Group
Build-only
Description
offset-2g
integer
False
False
Value to be added to the 2.4GHz WiFi band. (0.125 dBm) Minimum value: 0x0. Maximum value: 0xff.
offset-5g
integer
False
False
Value to be added to all 5GHz WiFi bands. (0.125 dBm) Minimum value: 0x0. Maximum value: 0xff.
offset-6g
integer
False
False
Value to be added to all 6GHz WiFi bands. (0.125 dBm) Minimum value: 0x0. Maximum value: 0xff.
geo-offsets-fcc
Attribute
Type
RegEx
Required
Oneof Group
Build-only
Description
offset-2g
integer
False
False
Value to be added to the 2.4GHz WiFi band. (0.125 dBm) Minimum value: 0x0. Maximum value: 0xff.
offset-5g
integer
False
False
Value to be added to all 5GHz WiFi bands. (0.125 dBm) Minimum value: 0x0. Maximum value: 0xff.
offset-6g
integer
False
False
Value to be added to all 6GHz WiFi bands. (0.125 dBm) Minimum value: 0x0. Maximum value: 0xff.
geo-offsets-rest-of-world
Attribute
Type
RegEx
Required
Oneof Group
Build-only
Description
offset-2g
integer
False
False
Value to be added to the 2.4GHz WiFi band. (0.125 dBm) Minimum value: 0x0. Maximum value: 0xff.
offset-5g
integer
False
False
Value to be added to all 5GHz WiFi bands. (0.125 dBm) Minimum value: 0x0. Maximum value: 0xff.
offset-6g
integer
False
False
Value to be added to all 6GHz WiFi bands. (0.125 dBm) Minimum value: 0x0. Maximum value: 0xff.
non-tablet-mode-power-table-rtw
Attribute
Type
RegEx
Required
Oneof Group
Build-only
Description
limit-2g
integer
False
False
2G band power limit: All 2G band channels. (0.125 dBm) Minimum value: 0x0. Maximum value: 0xff.
limit-5g-1
integer
False
False
5G band 1 power limit: 5.15G-5.35G channels. (0.125 dBm) Minimum value: 0x0. Maximum value: 0xff.
limit-5g-3
integer
False
False
5G band 3 power limit: 5.47G-5.725G channels. (0.125 dBm) Minimum value: 0x0. Maximum value: 0xff.
limit-5g-4
integer
False
False
5G band 4 power limit: 5.725G-5.95G channels. (0.125 dBm) Minimum value: 0x0. Maximum value: 0xff.
limit-6g-1
integer
False
False
6G band 1 power limit: 5.955G-6.155G channels. (0.125 dBm) Minimum value: 0x0. Maximum value: 0xff.
limit-6g-2
integer
False
False
6G band 1 power limit: 6.175G-6.415G channels. (0.125 dBm) Minimum value: 0x0. Maximum value: 0xff.
limit-6g-3
integer
False
False
6G band 1 power limit: 6.435G-6.515G channels. (0.125 dBm) Minimum value: 0x0. Maximum value: 0xff.
limit-6g-4
integer
False
False
6G band 1 power limit: 6.535G-6.695G channels. (0.125 dBm) Minimum value: 0x0. Maximum value: 0xff.
limit-6g-5
integer
False
False
6G band 1 power limit: 6.715G-6.855G channels. (0.125 dBm) Minimum value: 0x0. Maximum value: 0xff.
limit-6g-6
integer
False
False
6G band 1 power limit: 6.895G-7.115G channels. (0.125 dBm) Minimum value: 0x0. Maximum value: 0xff.
tablet-mode-power-table-rtw
Attribute
Type
RegEx
Required
Oneof Group
Build-only
Description
limit-2g
integer
False
False
2G band power limit: All 2G band channels. (0.125 dBm) Minimum value: 0x0. Maximum value: 0xff.
limit-5g-1
integer
False
False
5G band 1 power limit: 5.15G-5.35G channels. (0.125 dBm) Minimum value: 0x0. Maximum value: 0xff.
limit-5g-3
integer
False
False
5G band 3 power limit: 5.47G-5.725G channels. (0.125 dBm) Minimum value: 0x0. Maximum value: 0xff.
limit-5g-4
integer
False
False
5G band 4 power limit: 5.725G-5.95G channels. (0.125 dBm) Minimum value: 0x0. Maximum value: 0xff.
limit-6g-1
integer
False
False
6G band 1 power limit: 5.955G-6.155G channels. (0.125 dBm) Minimum value: 0x0. Maximum value: 0xff.
limit-6g-2
integer
False
False
6G band 1 power limit: 6.175G-6.415G channels. (0.125 dBm) Minimum value: 0x0. Maximum value: 0xff.
limit-6g-3
integer
False
False
6G band 1 power limit: 6.435G-6.515G channels. (0.125 dBm) Minimum value: 0x0. Maximum value: 0xff.
limit-6g-4
integer
False
False
6G band 1 power limit: 6.535G-6.695G channels. (0.125 dBm) Minimum value: 0x0. Maximum value: 0xff.
limit-6g-5
integer
False
False
6G band 1 power limit: 6.715G-6.855G channels. (0.125 dBm) Minimum value: 0x0. Maximum value: 0xff.
limit-6g-6
integer
False
False
6G band 1 power limit: 6.895G-7.115G channels. (0.125 dBm) Minimum value: 0x0. Maximum value: 0xff.
eu-power-table-mtk
Attribute
Type
RegEx
Required
Oneof Group
Build-only
Description
limit-2g
integer
False
False
2G band geo power limit. (0.25 dBm) Minimum value: 0x0. Maximum value: 0xff.
limit-5g
integer
False
False
5G band geo power limit. (0.25 dBm) Minimum value: 0x0. Maximum value: 0xff.
limit-6g
integer
False
False
6G band geo power limit. (0.25 dBm) Minimum value: 0x0. Maximum value: 0xff.
offset-2g
integer
False
False
Value to be added to the 2.4GHz WiFi band. (0.25 dBm) Minimum value: 0x0. Maximum value: 0xff.
offset-5g
integer
False
False
Value to be added to all 5GHz WiFi bands. (0.25 dBm) Minimum value: 0x0. Maximum value: 0xff.
offset-6g
integer
False
False
Value to be added to all 6GHz WiFi bands. (0.25 dBm) Minimum value: 0x0. Maximum value: 0xff.
fcc-power-table-mtk
Attribute
Type
RegEx
Required
Oneof Group
Build-only
Description
limit-2g
integer
False
False
2G band geo power limit. (0.25 dBm) Minimum value: 0x0. Maximum value: 0xff.
limit-5g
integer
False
False
5G band geo power limit. (0.25 dBm) Minimum value: 0x0. Maximum value: 0xff.
limit-6g
integer
False
False
6G band geo power limit. (0.25 dBm) Minimum value: 0x0. Maximum value: 0xff.
offset-2g
integer
False
False
Value to be added to the 2.4GHz WiFi band. (0.25 dBm) Minimum value: 0x0. Maximum value: 0xff.
offset-5g
integer
False
False
Value to be added to all 5GHz WiFi bands. (0.25 dBm) Minimum value: 0x0. Maximum value: 0xff.
offset-6g
integer
False
False
Value to be added to all 6GHz WiFi bands. (0.25 dBm) Minimum value: 0x0. Maximum value: 0xff.
non-tablet-mode-power-table-mtk
Attribute
Type
RegEx
Required
Oneof Group
Build-only
Description
limit-2g
integer
False
False
2G band power limit. (0.25 dBm) Minimum value: 0x0. Maximum value: 0xff.
limit-5g-1
integer
False
False
5G band 1 power limit: 5.15G-5.35G frequency. (0.25 dBm) Minimum value: 0x0. Maximum value: 0xff.
limit-5g-2
integer
False
False
5G band 2 power limit: 5.35G-5.47G frequency. (0.25 dBm) Minimum value: 0x0. Maximum value: 0xff.
limit-5g-3
integer
False
False
5G band 3 power limit: 5.47G-5.725G frequency. (0.25 dBm) Minimum value: 0x0. Maximum value: 0xff.
limit-5g-4
integer
False
False
5G band 4 power limit: 5.725G-5.95G frequency. (0.25 dBm) Minimum value: 0x0. Maximum value: 0xff.
limit-6g-1
integer
False
False
6G band 1 power limit: 5.945G-6.165G frequency. (0.25 dBm) Minimum value: 0x0. Maximum value: 0xff.
limit-6g-2
integer
False
False
6G band 2 power limit: 6.165G-6.405G frequency. (0.25 dBm) Minimum value: 0x0. Maximum value: 0xff.
limit-6g-3
integer
False
False
6G band 3 power limit: 6.405G-6.525G frequency. (0.25 dBm) Minimum value: 0x0. Maximum value: 0xff.
limit-6g-4
integer
False
False
6G band 4 power limit: 6.525G-6.705G frequency. (0.25 dBm) Minimum value: 0x0. Maximum value: 0xff.
limit-6g-5
integer
False
False
6G band 5 power limit: 6.705G-6.865G frequency. (0.25 dBm) Minimum value: 0x0. Maximum value: 0xff.
limit-6g-6
integer
False
False
6G band 6 power limit: 6.865G-7.125G frequency. (0.25 dBm) Minimum value: 0x0. Maximum value: 0xff.
rest-of-world-power-table-mtk
Attribute
Type
RegEx
Required
Oneof Group
Build-only
Description
limit-2g
integer
False
False
2G band geo power limit. (0.25 dBm) Minimum value: 0x0. Maximum value: 0xff.
limit-5g
integer
False
False
5G band geo power limit. (0.25 dBm) Minimum value: 0x0. Maximum value: 0xff.
limit-6g
integer
False
False
6G band geo power limit. (0.25 dBm) Minimum value: 0x0. Maximum value: 0xff.
offset-2g
integer
False
False
Value to be added to the 2.4GHz WiFi band. (0.25 dBm) Minimum value: 0x0. Maximum value: 0xff.
offset-5g
integer
False
False
Value to be added to all 5GHz WiFi bands. (0.25 dBm) Minimum value: 0x0. Maximum value: 0xff.
offset-6g
integer
False
False
Value to be added to all 6GHz WiFi bands. (0.25 dBm) Minimum value: 0x0. Maximum value: 0xff.
tablet-mode-power-table-mtk
Attribute
Type
RegEx
Required
Oneof Group
Build-only
Description
limit-2g
integer
False
False
2G band power limit. (0.25 dBm) Minimum value: 0x0. Maximum value: 0xff.
limit-5g-1
integer
False
False
5G band 1 power limit: 5.15G-5.35G frequency. (0.25 dBm) Minimum value: 0x0. Maximum value: 0xff.
limit-5g-2
integer
False
False
5G band 2 power limit: 5.35G-5.47G frequency. (0.25 dBm) Minimum value: 0x0. Maximum value: 0xff.
limit-5g-3
integer
False
False
5G band 3 power limit: 5.47G-5.725G frequency. (0.25 dBm) Minimum value: 0x0. Maximum value: 0xff.
limit-5g-4
integer
False
False
5G band 4 power limit: 5.725G-5.95G frequency. (0.25 dBm) Minimum value: 0x0. Maximum value: 0xff.
limit-6g-1
integer
False
False
6G band 1 power limit: 5.945G-6.165G frequency. (0.25 dBm) Minimum value: 0x0. Maximum value: 0xff.
limit-6g-2
integer
False
False
6G band 2 power limit: 6.165G-6.405G frequency. (0.25 dBm) Minimum value: 0x0. Maximum value: 0xff.
limit-6g-3
integer
False
False
6G band 3 power limit: 6.405G-6.525G frequency. (0.25 dBm) Minimum value: 0x0. Maximum value: 0xff.
limit-6g-4
integer
False
False
6G band 4 power limit: 6.525G-6.705G frequency. (0.25 dBm) Minimum value: 0x0. Maximum value: 0xff.
limit-6g-5
integer
False
False
6G band 5 power limit: 6.705G-6.865G frequency. (0.25 dBm) Minimum value: 0x0. Maximum value: 0xff.
limit-6g-6
integer
False
False
6G band 6 power limit: 6.865G-7.125G frequency. (0.25 dBm) Minimum value: 0x0. Maximum value: 0xff.
sar-file
Attribute
Type
RegEx
Required
Oneof Group
Build-only
Description
build-path
string
True
True
Source of the file relative to the build system.
system-path
string
True
False
Installation path for the file on the system image.
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. There is one exception, if there
is a custom_label_tag in VPD, the custom-label-tag in /identity
should be matched no matter is it a missing value or not.
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.
Property (from /identity)
x86 file
ARM file
frid
/sys/devices/platform/chromeos_acpi/FRID or /sys/devices/platform/GGL0001:00/FRID or /sys/devices/platform/GOOG0016:00/FRID
Note: Prior to 2022, the VPD key for custom-label-tag was called
whitelabel_tag. If /sys/firmware/vpd/ro/custom_label_tag does not
exist, /sys/firmware/vpd/ro/whitelabel_tag is checked instead.
Note: feature_device_type, being stored in RW VPD, is at greater risk of
corruption in shipped units. This is mitigated by enforcing that an
"off" configuration with an otherwise-equivalent identity match is present for
every identity with a non-"off" value, acting as a fallback configuration.
Additionally, libsegmentation will calculate the expected value and repopulate
it in RW VPD if necessary.
File Parsing Notes
All files are parsed as strings, except where mentioned below:
FRID files: Everything up to the first period (.) in the file is used.
/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.
Then update generated files and the README.md automatically via (unit tests
will check this):
src/platform2/chromeos-config/regen.sh
You'll want to run ./regen.sh when adding or changing the schema, power
management preferences, or anything which modifies the outputs of
cros_config_schema.