Google Confidential - Do Not Distribute.
Expires on February 29, 2012 or when a new document is published.
Google Chrome OS Main Processor Firmware
Specification
Introduction
Main Processor Firmware
High-Level EEPROM Memory Map
High-Level Execution Flow
Boot Stub
Start initializing chipset
Check firmware write protect GPIO
Lock down EEPROM
Initialize TPM
S3 resume
Check debug reset mode flag
Lock TPM on S3 resume
Check recovery mode GPIO
Check recovery request field
Check try B count field
Check rewritable firmware signature
Lock TPM rewritable firmware key index
Jump to selected firmware
Recovery Mode Firmware
Continue initializing chipset
Clear RAM
Initialize display
Initialize SD card and USB interfaces
Check developer mode GPIO
Check for SD card or USB storage device
Attempt loading OS kernel from SD card
Attempt loading OS kernel from USB mass storage device
Display recovery instructions
Retry loading OS kernel
Rewritable Firmware
Continue initializing chipset
Check developer mode GPIO
Initialize display
Display developer mode warning screen
Attempt loading OS kernel from fixed drive
Loading an OS Kernel
Check GUID partition table
Check OS kernel partition signatures
Lock TPM OS kernel partition key index
Execute OS kernel image
Main Processor EEPROM Memory Map
Data Sections
Read-Only Firmware
Vital Product Data
Rewritable Slots
Rewritable Shared
Rewritable VPD
Other Sections
Data Subsections
Google Binary Block
Read-Only Firmware Data
Flashmap
Google Confidential - Do Not Distribute.
Expires on February 29, 2012 or when a new document is published.
Google Confidential - Do Not Distribute.
Expires on February 29, 2012 or when a new document is published.
Rewritable Data
Shared Data
Developer Configuration
Other Subsections
Interface to Chrome OS Software (x86 processors)
Battery
AC adapter
Power button
Lid switch
Ambient light sensor
Display
Display Adapter
Display Output Devices
Keyboard
Trackpad
Real-Time Clock
Embedded controller
Firmware version
EEPROM
Chrome OS ACPI Device
CHSW (Chrome OS switch positions)
HWID (Chrome OS hardware ID)
FWID (Chrome OS firmware version)
FRID (Chrome OS read-only firmware version)
BINF (Chrome OS boot information)
GPIO (Chrome OS GPIO assignments)
VBNV (Chrome OS NVRAM locations)
FMAP (Chrome OS flashmap address)
VDTA (Chrome OS verified boot data)
MLST (Chrome OS method list)
S3 Debug Data Area
Summary of Required ACPI Devices
Development Process
Hardware bring-up using existing (non-custom) firmware
Implement boot stub without signature checking
Implement rewritable firmware
Finish implementing boot stub
Implement recovery mode firmware
OEM / ODM / BIOS vendor bug fixing
Switch to Google-supplied keys
Introduction
This document is a high-level description of the components and organization of firmware for
Google Chrome OS devices.
It is intended for the following audiences:
●
●
Anyone interested in a high-level description of Google Chrome OS firmware.
OEMs and ODMs who are incorporating firmware from other parties.
It is not intended for development of Chromium OS on hardware which is not compliant with the
Google Chrome OS hardware requirements.
Google Confidential - Do Not Distribute.
Expires on February 29, 2012 or when a new document is published.
Google Confidential - Do Not Distribute.
Expires on February 29, 2012 or when a new document is published.
More detailed descriptions of design components, including the rationale for design decisions in
those components, can be found in the following design documents:
●
●
●
●
●
●
●
●
Firmware Boot & Recovery
Firmware Verified Boot Crypto Specs
Verified Boot
Developer Mode
Chromium OS Disk Format
Chrome OS Platform VPD Reporting Specification
Flashmap
NV Storage for Chrome OS Verified Boot
Main Processor Firmware
The main processor is the processor running the Google Chrome OS kernel.
On ARM processors, the main processor firmware is based on U-Boot. Google will compile and
release this firmware, using vendor-supplied drivers for hardware components, and Chromium
OS vendor independent verified boot and recovery mode code.
Speed is important. In the normal, fast boot path, the main processor firmware should take less
than 1.4 seconds from executing the first instruction of boot stub firmware to executing the first
instruction of the OS kernel.
High-Level EEPROM Memory Map
Main processor firmware and data is stored in an EEPROM with a write-protected (read-only)
region and a writable (R/W) region. At a high level, this looks like:
High-Level Execution Flow
Google Confidential - Do Not Distribute.
Expires on February 29, 2012 or when a new document is published.
Google Confidential - Do Not Distribute.
Expires on February 29, 2012 or when a new document is published.
Boot Stub
The boot stub is the first code executed on the main processor. It performs minimal system
initialization and determines whether to run one of the rewritable firmware copies or the
recovery mode firmware.
The boot stub, including the reset vector, must be stored in read-only memory; it is not field
upgradeable.
Google Confidential - Do Not Distribute.
Expires on February 29, 2012 or when a new document is published.
Google Confidential - Do Not Distribute.
Expires on February 29, 2012 or when a new document is published.
Start initializing chipset
The chipset is initialized to the minimum amount required to perform the tasks in the boot
stub. Full initialization shoud be deferred until the rewritable firmware.
Check firmware write protect GPIO
The firmware write protect GPIO is set to input mode, then checked to determine whether the
normally read-only portions of the firmware is write protected (GPIO asserted) or rewritable
(GPIO not asserted).
If firmware write protect is controlled entirely by hardware, this step is omitted.
Lock down EEPROM
If the EEPROM used to store the read-only portions of the firmware requires per-boot software
configuration to disable erase/write operations, this configuration step should be done
now. This minimizes the length of time where the EEPROM is writable.
If write protecting the EEPROM is done through hardware, or through a software state which
persists across reboots, with no per-boot software configuration necessary, this step does
nothing.
If the firmware write protect GPIO is not asserted, this step is skipped. This allows the entire
EEPROM to be reprogrammed in a manufacturing setting.
Google Confidential - Do Not Distribute.
Expires on February 29, 2012 or when a new document is published.
Google Confidential - Do Not Distribute.
Expires on February 29, 2012 or when a new document is published.
Initialize TPM
The Trusted Platform Module (TPM) is initialized so that the firmware can read and/or update the
key indexes for the keys used to sign the rewritable firmware and kernels. If this is a normal
boot and TPM initialization fails, the system reboots into recovery mode.
S3 resume
If this boot was triggered by a S3 resume event (resume from suspend-to-RAM), additional
steps are required to determine if this is a debug reset, and/or if the TPM requires locking
down.
Check debug reset mode flag
On systems where the contents of RAM are not maintained across a warm boot, Chrome OS
firmware uses a debug reset mode flag in NV Storage to assist in debugging system crashes.
If the debug reset mode flag is set during a S3 resume, then this S3 resume event was
triggered by the previously booted OS kernel to perform a debug reset. In this case, the
system should clear the debug reset mode flag, then continue booting the firmware without
resetting the contents of RAM, so the current boot of the OS kernel can attempt to log and/or
diagnose the crash in the previously booted OS kernel.
Lock TPM on S3 resume
If the TPM is powered down during suspend-to-RAM, the TPM must be initialized and locked
before jumping to the S3 resume pointer. This ensures the TPM is properly locked down before
resuming execution in the code in RAM.
If the TPM remains powered during S3 (suspend-to-RAM), it will still be locked from the previous
boot, so this step may be skipped.
Check recovery mode GPIO
The recovery mode GPIO is set to input mode, then checked to determine if the system should
boot into recovery mode (GPIO asserted) or continue with the normal boot flow (GPIO not
asserted). If the GPIO is asserted, select recovery mode firmware now.
This step ensures that the user can manually request recovery mode.
Check recovery request field
To enable the device to reboot itself into recovery mode, Chrome OS stores a recovery request
field in NV Storage. If this field is non-zero during a normal boot, the previous boot requested
that this boot be in recovery mode. In this case, clear the recovery request field back to 0, and
select recovery mode firmware now.
Check try B count field
Chrome OS firmware has the capability to test an updated version of the firmware and fall back
to a previous version if that updated version fails. This is implemented via the try B count field
in NV Storage.
If the try B count is non-zero, decrement the count and assign rewritable firmware B as
the primary firmware and rewritable firmware A as the secondary firmware. If the field is
zero, assign rewritable firmware A as the primary firmware and rewritable firmware B as the
secondary firmware.
Google Confidential - Do Not Distribute.
Expires on February 29, 2012 or when a new document is published.
Google Confidential - Do Not Distribute.
Expires on February 29, 2012 or when a new document is published.
Check rewritable firmware signature
See the Firmware Verified Boot document for details on the signature checking algorithm which
shall be implemented.
The signature header of the primary rewritable firmware is checked. If the header is valid and
the key index of the primary rewritable firmware header is greater or equal to the rewritable
firmware key index in the TPM, the key contained in the header is used to check the rest of the
primary rewritable firmware. If the signature of the primary rewritable firmware matches the
expected signature, select the primary rewritable firmware.
If the primary rewritable firmware was not selected, the signature header of the secondary
rewritable firmware is checked. If the header is valid and the key index of the secondary
rewritable firmware header is greater or equal to the rewritable firmware key index in the
TPM, the key contained in the header is used to check the rest of the secondary rewritable
firmware. If the signature of the secondary rewritable firmware matches the expected
signature, select the secondary rewritable firmware.
If neither primary or secondary rewritable firmware is selected, neither firmware is valid. Select
recovery mode firmware.
If the primary rewritable firmware is selected, and the key index of the primary rewritable
firmware is greater than the rewritable key index in the TPM, check the signature header of
the secondary rewritable firmware. If the header is valid, and the key index of the secondary
rewritable firmware header is greater than the rewritable key index in the TPM, then both
primary and secondary rewritable firmware headers are valid and have a key index greater
than the rewritable key index in the TPM. In this case, it is necessary to update the rewritable
firmware key index in the TPM to prevent rollback attacks. Replace the rewritable firmware key
index in the TPM with the lesser of the key indices from the primary and secondary rewritable
firmware.
Libraries to perform the firmware signature verification are available on the Chromium OS
website in the vboot_reference repository.
Lock TPM rewritable firmware key index
The TPM is set to prevent updating the rewritable firmware key index in the TPM during the
remainder of this boot.
Note: If the TPM has only a global lock bit for its entire NVRAM, and cannot lock the firmware
key index independently of the kernel key index, the firmware may skip this locking step. In
this case, the NVRAM should be locked when the kernel key index is determined (see "Lock TPM
OS kernel partition key index" below).
Note: Systems should leave global lock unlocked if and only if (1) the system is booting in
recovery mode and (2) the developer mode GPIO is asserted. This provides a path for Googlesigned recovery software to repair the TPM configuration. In this case, the Google-signed
recovery software will lock the rewritable firmware key index.
Jump to selected firmware
Jump to the firmware selected during the "Signature check rewritable firmware" step.
Recovery Mode Firmware
The recovery mode firmware is executed when the system boots in recovery mode - this is
caused by the recovery mode GPIO, recovery mode field check, or signature failures of the
rewritable firmware.
Google Confidential - Do Not Distribute.
Expires on February 29, 2012 or when a new document is published.
Google Confidential - Do Not Distribute.
Expires on February 29, 2012 or when a new document is published.
Recovery mode firmware must be stored in read-only memory; it is not field upgradeable.
Reliability is more important than boot speed in recovery mode. When choosing how to initialize
hardware in recovery mode, use the most reliable methods and/or settings.
Continue initializing chipset
The chipset is initialized sufficiently to perform the tasks required in the recovery firmware.
Clear RAM
RAM not currently in use by the recovery firmware is cleared (all bytes set to 0). This protects
against cold boot attacks.
Initialize display
The graphics hardware is initialized so that a bitmap can be displayed on the LCD panel.
Initialize SD card and USB interfaces
The SD card and USB interfaces are initialized. This should include sufficient settling time that a
storage device attached to either interface can be detected in the following steps.
Check developer mode GPIO
The developer mode GPIO is checked. If the device is in developer mode (GPIO is asserted),
firmware does not check for SD cards and USB storage devices which need to be removed, and
proceeds directly to attempting to load an OS kernel.
Check for SD card or USB storage device
The firmware checks to see if any SD cards or USB storage devices are inserted. If at least
one SD card or USB storage device is present, firmware displays a pre-rendered bitmap which
Google Confidential - Do Not Distribute.
Expires on February 29, 2012 or when a new document is published.
Google Confidential - Do Not Distribute.
Expires on February 29, 2012 or when a new document is published.
requests that the user should remove the device(s). It then rescans the SD and USB interfaces
to determine if all such devices have been removed. This check ensures that USB storage
devices or SD cards the user may have previously inserted into the system do not interfere with
loading an approved recovery OS image in the following steps.
When the firmware determines that no SD cards or USB storage devices are present, it proceeds
to attempting to load an OS kernel.
Attempt loading OS kernel from SD card
If a SD card is present, attempt to load the kernel from the SD card. See "Loading an OS
kernel" below.
The SD card is attempted before USB mass storage, since SD hardware usually requires less
software initialization/configuration than USB mass storage.
Attempt loading OS kernel from USB mass storage device
If a USB mass storage device is present, attempt to load the kernel from the USB mass storage
device. See "Loading an OS kernel" below.
Display recovery instructions
A pre-rendered bitmap containing recovery instructions is displayed on the LCD panel.
The firmware will display one of two pre-rendered bitmaps, depending on whether an external
storage device (USB or SD) is present.
● If no external storage device is present, bitmap 1 contains instructions to insert a
recovery storage device, and a URL linking to more information.
● If an external storage device is present, bitmap 2 contains an additional indication that
the current storage device(s) do not contain a valid recovery OS image.
Retry loading OS kernel
Continue checking SD card and USB mass storage interface to see if user inserts a card or mass
storage device containing a valid kernel. See "Loading an OS kernel" below.
Rewritable Firmware
The rewritable firmware is executed when the device boots in its normal (fast) boot path. It
initializes the fixed drive (eMMC, SSD, etc.) and attempts to load a kernel from that drive.
Speed is important for the rewritable firmware, since this is the normal boot path experienced
by users. Hardware components not required for the fast boot path (for example, USB) should
not be initialized in the rewritable firmware; they will be initialized in the OS kernel.
The rewritable firmware contains the key used to verify the signature of OS kernel headers.
Rewritable firmware is field updateable.
Google Confidential - Do Not Distribute.
Expires on February 29, 2012 or when a new document is published.
Google Confidential - Do Not Distribute.
Expires on February 29, 2012 or when a new document is published.
Continue initializing chipset
The chipset is initialized sufficiently to perform the tasks required in the rewritable firmware.
Check developer mode GPIO
The developer mode GPIO is checked to see what type of key may be used to sign the OS kernel
header.
If the device is in normal mode (GPIO is not asserted), the OS kernel header must be signed
with the key contained in the rewritable firmware.
If the device is in developer mode (GPIO is asserted), the OS kernel header does not need
to be signed. However, if the OS kernel header is NOT signed with the key contained in the
rewritable firmware, the developer warning screen must be shown.
Initialize display
The graphics hardware is initialized so that a bitmap can be displayed on the LCD panel.
Google Confidential - Do Not Distribute.
Expires on February 29, 2012 or when a new document is published.
Google Confidential - Do Not Distribute.
Expires on February 29, 2012 or when a new document is published.
Display developer mode warning screen
See the "Developer Mode" document for more details.
If the OS kernel partition header was signed by the key stored in the firmware, skip this step.
The graphics hardware and keyboard are initialized.
A pre-rendered developer mode warning bitmap, supplied by Google, is displayed on the
screen.
A 30-second timer is started. During this 30 second time period, the next step is determined by
the user's behavior:
● User presses Ctrl+D before the timer elapses: Expire the timer and attempt booting from
SSD
● User pressed Ctrl+U before the timer elapses: Attempt booting from USB/SD. If USB/SD
device is not present or attempt fails:
○ 1 beep is played over audio
○ Go back to waiting for the timer expiration or user key press.
● User presses Space bar, Enter, or Esc before the timer elapses: Store the recovery mode
cookie into the recovery mode field and perform a warm boot
● User presses any other key or combination of keys: No effect
● No button pressed & 20 seconds passes: Audio hardware is initialized and 2 beeps are
played over audio.
● No button pressed & 30 seconds passes: Attempt booting from SSD.
Attempt loading OS kernel from fixed drive
The fixed drive (eMMC, or SATA + SSD) is initialized.
Attempt loading the OS kernel from the fixed drive. See "Loading an OS kernel" below.
If unable to load an OS kernel from the fixed drive, store the recovery mode cookie into the
recovery mode field and perform a warm boot.
Loading an OS Kernel
This section describes the process for loading an OS kernel from a storage device.
This process is similar for rewritable and recovery mode firmwares. The differences are
described in the following table
Item
Rewritable Firmware
Recovery Mode Firmware
Location of OS kernel
Fixed drive only (normal firmware)
Any (developer mode)
SD card or USB mass storage
device
Unsigned OS kernel
header allowed
Only in developer mode
No, the OS kernel header
must be signed by recovery
key specified in modelspecific data area.
A summary of the process follows. More detail is available in the Chromium OS Disk Format
and Firmware Verified Boot documents. Libraries to perform these checks are available on the
Chromium OS website.
Check GUID partition table
Google Confidential - Do Not Distribute.
Expires on February 29, 2012 or when a new document is published.
Google Confidential - Do Not Distribute.
Expires on February 29, 2012 or when a new document is published.
The GUID partition table is loaded and its internal checksum is verified.
If the checksum does not match, the backup GUID partition table at the end of the drive is
loaded and its internal checksum is verified.
If neither GUID partition table is valid, store the recovery mode cookie into the recovery mode
field and perform a warm boot.
The GUID partition table is checked for sanity and scanned to locate OS kernel partitions. See
the "Chromium OS Disk Format" document for details.
Check OS kernel partition signatures
See the Firmware Verified Boot document for details on the signature checking algorithm, how
the OS kernel header key index is compared with the minimum OS kernel key index stored in
the TPM, and how/when to update the minimum OS kernel key index stored in the TPM.
Each OS kernel partition has a priority; see the "Chromium OS Disk Format" document for more
details.
Partitions are attempted in order of decreasing priority until an acceptable OS kernel is found.
The header for each attempted OS kernel partition is loaded and its signature is checked.
If this is recovery mode firmware, the header must be signed by the recovery key stored in the
model-specific data area. If not signed with this key, this kernel cannot be used; try the next
kernel partition.
If this is rewritable firmware, and developer mode is not enabled, the header must be signed
by the key stored in the rewritable firmware. If not signed with this key, this kernel cannot be
used; try the next kernel partition. If the header is signed by the key stored in the firmware,
and the key index in the OS kernel header is less than the minimum OS kernel key index stored
in the TPM, this kernel cannot be used; try the next kernel partition.
If this is rewritable firmware, and developer mode is enabled, the header is simply verified by
checking its internal hash.
The rest of the OS kernel partition is loaded into memory and its signature is verified against the
signature in the OS kernel partition header. If the signatures do not match, this kernel cannot
be used; try the next kernel partition.
If no valid kernel is found, store the recovery mode cookie into the recovery mode field and
perform a warm boot.
Lock TPM OS kernel partition key index
The TPM is set to prevent updating the OS kernel partition key index in the TPM during the
remainder of this boot.
Note: If the TPM has only a global lock bit for its entire NVRAM, this step should lock the entire
NVRAM, including the firmware key index. (See "Lock TPM rewritable firmware key index"
above).
Note: When booting from removable media in recovery mode, the firmware should not lock the
kernel partition key index in the TPM. This enables Google-signed recovery software to repair
the kernel key index before locking it. When booting from the fixed drive, the TPM is always
locked.
Execute OS kernel image
Google Confidential - Do Not Distribute.
Expires on February 29, 2012 or when a new document is published.
Google Confidential - Do Not Distribute.
Expires on February 29, 2012 or when a new document is published.
The OS kernel configuration data is parsed from the OS kernel data loaded into RAM.
The OS kernel stored in RAM is executed, using the configuration data.
Main Processor EEPROM Memory Map
The main processor EEPROM is divided into two main regions - a read-only region with the boot
stub and recovery firmware and associated data, and a writable region with the two copies of
rewritable firmware and associated data.
Here is a list of all required and optional sections. Note that in the table below, a region
consists of one or more contiguous sections. A section consists of one or more contiguous
subsections. Sections must be aligned on EEPROM sector boundaries; subsections should be
aligned when possible. The regions, sections, and subsections do not need to be in the order
specified below, as long as each region, section, and subsection is contiguous.
Optional (required=N) sections may be included with size=0, or may be omitted from the
EEPROM and FMAP.
Region
Section
Subsection
FMAP name
Notes
Read-only
Required?
Y
Read-only
firmware
RO_SECTION
Read-only firmware and
associated data.
Y
Boot stub
BOOT_STUB
Y
Recovery
firmware
RECOVERY
Y
Read-only data RO_DATA
On x86, includes RO_FRID N
and RO_BMP subregions.
Google binary
block (GBB)
GBB
Model-specific data, including Y
bitmaps, HWID, and root
keys.
Flashmap
FMAP
Flashmap (FMAP) data
structure itself. May be
inside RO_DATA.
Y
Read-only
firmware ID
RO_FRID
May be inside RO_DATA.
Y
Vital product
data (VPD)
RO_VPD
Device-specific data.
Y
See VPD spec for minimum
size.
Writable
Y
Rewritable
slot A
RW_SECTION_A
Verification
block A
VBLOCK_A
Rewritable
firmware A
FW_MAIN_A
Rewritable data DATA_A
A
Rewritable firmware and
Y
associated data, slot A.
A 2-stage firmware update
will replace all of this data
as a unit.
Must be at least 8KB
Y
Y
N
Rewritable
RW_FWID_A
firmware ID A
May be inside FW_MAIN_A or Y
DATA_A
Google Confidential - Do Not Distribute.
Expires on February 29, 2012 or when a new document is published.
Google Confidential - Do Not Distribute.
Expires on February 29, 2012 or when a new document is published.
Rewritable
slot B
RW_SECTION_B
Verification
block B
VBLOCK_B
Rewritable
firmware B
FW_MAIN_B
Rewritable firmware and
Y
associated data, slot B.
A 2-stage firmware update
will replace all of this data
as a unit.
Must be at least 8KB
Y
Rewritable data DATA_B
B
N
Rewritable
RW_FWID_B
firmware ID B
Rewritable
shared
Y
May be inside FW_MAIN_B or Y
DATA_B
RW_SHARED
N
Shared data
SHARED_DATA
Developer
configuration
DEV_CFG
User-configurable
N
parameters for developer
firmware.
RW_VPD
See VPD spec for minimum N
size
Rewritable
VPD
On x86, includes
NV_STORAGE and
NV_COMMON_STORE.
N
FMAP names for Chrome OS must use only the follow ing characters: [0-9A-Za-z.-_] That is:
numbers, letters, period, dash, and underscore.
Data Sections
Read-Only Firmware
Read-only firmware and associated data. This includes the boot stub and recovery firmware.
A read-only+rewritable firmware update (done during development) will replace this data.
Vital Product Data
The vital product data (VPD) region includes information such as the device serial number, MAC
addresses, etc., which varies on a device-to-device basis. This data is stored in read-only
EEPROM. Note that this is not part of RO_SECTION, so it will not be overwritten by a (readonly + rewritable) firmware update.
See the Chrome OS Platform VPD Reporting Specification for more details.
Rewritable Slots
The rewritable slots are used by 2-stage firmware update. Normally, slot A is attempted before
slot B.
A 2-stage firmware update will change one slot at a time.
Rewritable Shared
Some data, such as cached memory SPD information, is shared between the rewritable firmware
slots. Read-only firmware must not depend on the contents of this section, so that it can boot
even if this section is damaged.
Google Confidential - Do Not Distribute.
Expires on February 29, 2012 or when a new document is published.
Google Confidential - Do Not Distribute.
Expires on February 29, 2012 or when a new document is published.
A recovery firmware update will replace this data.
Rewritable VPD
Rewritable vital product data. Note that this is not part of RW_SHARED, so it will not be
overwritten by a recovery.
Other Sections
Other sections may be added as needed. Note that firmware update only knows about
RO_SECTION, RW_SECTION_A, RW_SECTION_B, and RW_SHARED, so any additional sections
will only be written by a full-chip write. If other data needs to be updated or recovered, it
should be placed as a subsection of one of those sections.
Data Subsections
Several types of data are stored in EEPROM along with the main firmware.
Google Binary Block
The Google binary block (GBB) subsection contains data used by the boot stub and recovery
mode firmware. This data must be stored in write-protected memory, so that it cannot be
altered on systems after they have shipped. This data is also referred to as Model Specific
Data.
Model-specific data includes:
● The root key used by the boot stub to verify the signature headers for the rewritable
firmware. For production firmware, this key is provided by Google.
● The root key used by recovery mode to verify the signature headers for the kernel, when
booting in recovery mode. For production firmware, this key is provided by Google.
●
●
●
A block of data with the Google-provided hardware ID string for the device. This is used
by autoupdate software to determine which update images to download, and by the
recovery boot image to ensure the correct recovery data is used.
The screen bitmaps displayed in recovery mode and developer mode.
The hardware ID (HWID) for the device, a null-terminated ASCII string up to 256
characters (counting the terminating NULL).
The GBB header is defined in this C header file.
Read-Only Firmware Data
Additional data required by the read-only firmware. On x86, this includes the RO_FRID and
RO_BMP regions.
Flashmap
The flashmap which describes the region layout. Note that this is part of the RO_SECTION, so
can be updated by a (read-only + rewritable) firmware update.
Rewritable Data
Additional data required by the rewritable firmware. There is one copy for each rewritable slot.
Shared Data
Additional data required by the rewritable firmware. On x86, this includes NV_STORAGE and
Google Confidential - Do Not Distribute.
Expires on February 29, 2012 or when a new document is published.
Google Confidential - Do Not Distribute.
Expires on February 29, 2012 or when a new document is published.
NV_COMMON_STORE, and cached SPD data from the SDRAM.
Firmware must be able to boot regardless of the contents of this data. This is essential because
this data is (1) shared between the two firmware slots and (2) not verified by the verified boot
process.
Developer Configuration
User-configurable parameters for developer firmware. This is not used by consumer
firmware. On ARM, this section holds the U-Boot environment variables for developer firmware.
Other Subsections
Firmware may declare other subsections as needed. As long as these are part of one of the
RO_SECTION, RW_SECTION_A, RW_SECTION_B, or RW_SHARED sections, these subsections
will be updated / recovered properly.
It is strongly recommended, though not required, that firmware describe the contents of its
subsections in as fine detail as possible, including adding sub-subsections to describe the
components of RO_DATA, SHARED_DATA, etc.
Interface to Chrome OS Software (x86
processors)
This section describes the interface between the firmware and Chrome OS software on x86
processors.
Firmware shall provide an ACPI interface to main processor and EC resources, complying with
the ACPI spec revision 3.0b or newer. References to the ACPI spec are to spec version 3.0b,
unless otherwise specified.
Firmware shall provide support for at least the following ACPI specification sections:
● Section 6 - Configuration
● Section 7 - Power and Performance Management
● Section 8 - Processor
● Section 11 - Thermal Management
See the detail sections below for specifically required devices and ACPI methods/objects. These
devices/methods/objects are required in addition to those required to comply with the ACPI
spec (for example, the ACPI spec requires all devices to supply a _HID object; this requirement
is not listed below) and sections listed above.
Battery
The battery shall be implemented as one of:
● a control method battery, as specified in the ACPI spec, section 10.2.
● a smart battery subsystem, as specified in the ACPI spec, section 10.1.
AC adapter
The AC adapter (external power) shall be implemented as an AC adapter device, as specified in
the ACPI spec, section 10.3.
Power button
Power button shall be implemented as a single power button device, as specified in the ACPI
spec, section 4.7.2.2.1, using the control method power button programming model.
Google Confidential - Do Not Distribute.
Expires on February 29, 2012 or when a new document is published.
Google Confidential - Do Not Distribute.
Expires on February 29, 2012 or when a new document is published.
Pressing the power button for >8 seconds shall trigger a soft off. Note that ACPI spec 4.7.2.2.1
specifies a 4-second delay; Chrome OS requires an 8-second delay.
Embedded controller shall implement the additional 4 seconds of delay by sending the following
signal on the PWRBTN# signal to the x86 chipset, in response to embedded controller's
PWRBTN# input:
● Asserted (low) for t0, where (32 msec < t0 < 100 msec)
● Unasserted (high) for t1, where t1 = (4000 msec - t0)
● Asserted for the t2, where t2 = remainder of time the power button is held down
● Unasserted after power button up
Power button shall generate wake (0x02) and button press (0x80) notifications, as specified in
the ACPI spec, section 9.3.
Power button shall generate keyboard events for key down (make) and key up (break). See the
Keyboard section below for a link to the keyboard specification which defines the keycodes for
the keyboard events.
Lid switch
Lid switch shall be implemented as a control method lid device, as specified in the ACPI spec,
section 9.4.
If system is in G1/(S1-S4) state, a lid-open event shall trigger a wake (0x02) notification.
In addition, if system is in G2/S5 (soft off) state, a lid-open event shall trigger a power-on as if
the power button was pressed.
Ambient light sensor
If ambient light sensor is connected to embedded controller, ambient light sensor shall be
implemented as a control method ambient light sensor device, as specified in the ACPI spec,
section 9.2.
This ACPI device must implement the _ALI and _ALR methods, and the 0x80 notification (lux
reading changed more than 10%).
If ambient light sensor is connected directly to processor, or to ICH/PCH, it will be controlled
directly by Chrome OS, and this ACPI interface is not present.
Display
Display Adapter
The display adapter device shall implement the ACPI extensions for display adapters, as
specified in the ACPI spec, appendix B.
Google Confidential - Do Not Distribute.
Expires on February 29, 2012 or when a new document is published.
Google Confidential - Do Not Distribute.
Expires on February 29, 2012 or when a new document is published.
The device must implement the _DOS and _DOD methods, and the 0x81 notification (output
device status change).
For the _DOS method, when bit 2 is 1:
● Neither the system BIOS nor EC shall automatically control the brightness level of the
LCD.
● Pressing the brightness up/down keys on the keyboard shall generate keycodes, but not
change the brightness level directly. (The OS will respond to the keycodes and call _BCM
to change the backlight level appropriately.)
The display adapter device does not need to implement _GPT, _SPD, or _VPO methods, since
the system will always POST to the built-in LCD panel.
If output control/switching is connected directly to processor, or to ICH/PCH, it will be controlled
directly by Chrome OS, and the _DOS and _DOD methods are not present.
Display Output Devices
The display adapter device shall have a child display output device for the internal LCD. It
must implement the _BCL, _BCM, _BQC, _DCS, _DGS, and _DSS methods.
In order to support smoothly varying screen brightness in response to ambient light, internal
LCD backlight control must support at least 30 distinct backlight levels, with adjacent values
differing by no more than 4% as returned by the _BCL method.
If the netbook has an external display port (HDMI, DVI, or VGA), the display adapter device
shall have a child display output device for each external display port. It must implement
the _DDC, _DCS, _DGS, and _DSS methods. For the _DCS method, it shall implement bit 4
(device is attached).
If backlight control is connected directly to processor, or to ICH/PCH, it will be controlled
directly by Chrome OS, and the _BCL, _BCM and _BQC methods are not present.
If output detect/control/switching is connected directly to processor, or to ICH/PCH, it will be
controlled directly by Chrome OS, and the _DCS, _DGS, and _DSS methods are not present.
Keyboard
Chrome OS will access the keyboard and keyboard indicator LEDs through a standard i8042 I/O
interface.
Keyboard shall support pulse output port commands for Gate A20 and System Reset (commands
0xFC-0xFE on port 0x64).
The ACPI device for the keyboard (PNP0303) shall generate wake (0x02) notifications.
Keyboard shall send scan codes as described in the Keyboard specification.
Trackpad
Chrome OS will access the trackpad through a standard i8042 I/O interface (AUX device).
The ACPI device for the trackpad (PNP0F13) shall generate wake (0x02) notifications.
Real-Time Clock
Real-time clock interface shall be implemented as described in section 9.16 of the ACPI spec.
Google Confidential - Do Not Distribute.
Expires on February 29, 2012 or when a new document is published.
Google Confidential - Do Not Distribute.
Expires on February 29, 2012 or when a new document is published.
Real-time clock shall be able to generate a wake notification (0x02).
Embedded controller
The embedded controller interface shall comply with the ACPI spec, section 12.
Firmware version
BIOS will report the current EC firmware version (that is, the version of EC code currently
running on the EC) via the following fields in the BIOS Information (Type 0) SMBIOS table:
● Embedded Controller Firmware Major Release
● Embedded Controller Firmware Minor Release
See the Chrome OS Platform VPD Reporting Specification for more information.
EEPROM
Chrome OS will read/write the embedded controller EEPROM using the flashrom tool. ODM is
responsible for providing flashrom support for the EC EEPROM. This support will be supplied
using the procedures from the Partner Sourcecode Development document. It is recommended
that ODM make their EC interface compatible with an existing flashrom programming interface.
Chrome OS ACPI Device
Hardware functionality specific to Chrome OS shall be exposed through a Chrome OS ACPI
device.
The plug and play ID of a Chrome OS ACPI device is GGL0001.
The following ACPI objects shall be supported:
Object
Description
CHSW
Chrome OS switch positions [Required]
HWID
Chrome OS hardware ID [Required]
FWID
Chrome OS firmware version [Required]
FRID
Chrome OS read-only firmware version
[Required]
BINF
Chrome OS boot information [Required]
GPIO
Chrome OS GPIO assignments [Required]
VBNV
Chrome OS NVRAM locations [Required]
VDTA
Chrome OS verified boot data [Required]
FMAP
Chrome OS flashmap base address [Required]
MLST
Chrome OS method list [Required]
CHSW (Chrome OS switch positions)
This control method returns the switch positions for Chrome OS specific hardware switches.
Arguments:
None
Result code:
An integer containing the switch positions as bitfields:
Google Confidential - Do Not Distribute.
Expires on February 29, 2012 or when a new document is published.
Google Confidential - Do Not Distribute.
Expires on February 29, 2012 or when a new document is published.
0x00000002 - Recovery button was pressed when x86 firmware booted.
0x00000004 - Recovery button was pressed when EC firmware booted. (required if EC
EEPROM is rewritable; otherwise optional)
0x00000020 - Developer switch was enabled when x86 firmware booted.
0x00000200 - Firmware write protect was disabled when x86 firmware booted. (required if
firmware write protect is controlled through x86 BIOS; otherwise optional)
All other bits are reserved and should be set to 0.
HWID (Chrome OS hardware ID)
This control method returns the hardware ID for the netbook.
Arguments:
None
Result code:
A null-terminated ASCII string containing the hardware ID from the Model-Specific Data area of
EEPROM.
Note that the hardware ID can be up to 256 characters long, including the terminating null.
FWID (Chrome OS firmware version)
This control method returns the firmware version for the rewritable portion of the main
processor firmware.
Arguments:
None
Result code:
A null-terminated ASCII string containing the complete firmware version for the rewritable
portion of the main processor firmware.
FRID (Chrome OS read-only firmware version)
This control method returns the firmware version for the read-only portion of the main processor
firmware.
Arguments:
None
Result code:
A null-terminated ASCII string containing the complete firmware version for the read-only
(bootstrap + recovery ) portion of the main processor firmware.
BINF (Chrome OS boot information)
This control method returns information about the current boot.
Arguments:
None
Result code:
Package {
Boot Reason
Active Main Firmware
Active EC Firmware
//DWORD
//DWORD
//DWORD
Google Confidential - Do Not Distribute.
Expires on February 29, 2012 or when a new document is published.
Google Confidential - Do Not Distribute.
Expires on February 29, 2012 or when a new document is published.
Active Main Firmware Type
Recovery Reason
}
//DWORD
//DWORD
Field
Format
Description
Boot Reason
DWORD
Reason for boot.
0 - Other
9 - OS-initiated S3 diagnostic path (debug mode
boot)
Other values are reserved.
Active Main Firmware
DWORD
The main (x86) firmware which was used during
boot.
0 - Recovery firmware
1 - Rewritable firmware A
2 - Rewritable firmware B
Other values are reserved.
Active EC firmware
DWORD
The EC firmware which was used during boot.
0 - Read-only (recovery) firmware,
1 - Rewritable firmware.
Set to 0 if EC firmware is always read-only.
Active Main Firmware Type
DWORD
The main firmware type which was used during
boot.
0 - Recovery
1 - Normal
2 - Developer
Other values are reserved.
Recovery Reason
DWORD
The recovery reason code for the current boot.
0 - Not in recovery mode
1-255 - Recovery reason from NV Storage API.
Other values are reserved.
GPIO (Chrome OS GPIO assignments)
This control method returns information about Chrome OS specific GPIO assignments for
Chrome OS hardware, so the kernel can directly control that hardware.
Arguments:
None
Result code:
Package {
Package {
// First GPIO assignment
Signal Type
Attributes
//DWORD
//DWORD
Google Confidential - Do Not Distribute.
Expires on February 29, 2012 or when a new document is published.
Google Confidential - Do Not Distribute.
Expires on February 29, 2012 or when a new document is published.
Controller Offset
Controller Name
//DWORD
//ASCIIZ
},
...
Package {
// Last GPIO assignment
Signal Type
Attributes
Controller Offset
Controller Name
}
//DWORD
//DWORD
//DWORD
//ASCIIZ
}
Where ASCIIZ means a null-terminated ASCII string.
Field
Format
Description
Signal Type
DWORD
Type of GPIO signal
0x00000001 - Recovery button
0x00000002 - Developer mode switch
0x00000003 - Firmware write protect switch
0x00000100 - Debug header GPIO 0
...
0x000001FF - Debug header GPIO 255
Other values are reserved.
Attributes
DWORD
Signal attributes as bitfields:
0x00000001 - Signal is active-high (for button, a GPIO value
of 1 means the button is pressed; for switches, a GPIO value
of 1 means the switch is enabled). If this bit is 0, the signal
is active low. Set to 0 for debug header GPIOs.
Controller Offset
DWORD
GPIO number on the specified controller.
Controller Name
ASCIIZ
Name of the controller for the GPIO.
Currently supported names:
● "NM10" - Intel NM10 chip
For example, the following package describes a device where the recovery button is on GPIO5 as
an active-low signal, the developer mode switch is on GPIO6 as an active-high signal, there is
a debug header with 4 GPIO lines on GPIO10 - GPIO13; in this example, all GPIOs are attached
to the NM10 chip:
Package {
Package {
1,
// Signal type = recovery button
0,
// Active low
5,
// GPIO line 5 on
"NM10"
// NM10 chip
},
Package {
2,
// Signal type = developer switch
0x00000001, // Active high
6,
// GPIO line 6 on
"NM10"
// NM10 chip
},
Package {
0x100,
// Signal type = debug header GPIO 0
0,
// Attributes
Google Confidential - Do Not Distribute.
Expires on February 29, 2012 or when a new document is published.
Google Confidential - Do Not Distribute.
Expires on February 29, 2012 or when a new document is published.
10,
"NM10"
},
Package {
0x101,
0,
11,
"NM10"
},
Package {
0x102,
0,
12,
"NM10"
},
Package {
0x103,
0,
13,
"NM10"
}
// GPIO line 10 on
// NM10 chip
// Signal type = debug header GPIO 1
// Attributes
// GPIO line 11 on
// NM10 chip
// Signal type = debug header GPIO 2
// Attributes
// GPIO line 12 on
// NM10 chip
// Signal type = debug header GPIO 3
// Attributes
// GPIO line 13 on
// NM10 chip
}
VBNV (Chrome OS NVRAM locations)
This control method returns information about the NVRAM (CMOS) locations used to
communicate with the BIOS.
Arguments:
None
Result code:
Package {
NV Storage Block Offset
NV Storage Block Size
}
Field
Format
NV Storage Block Offset DWORD
NV Storage Block Size
DWORD
//DWORD
//DWORD
Description
Offset in CMOS bank 0 of the verified boot non-volatile
storage block, counting from the first writable CMOS
byte (that is, offset=0 is the byte following the 14 bytes
of clock data).
Size in bytes of the verified boot non-volatile storage
block.
For example, the following package describes a device where the storage block is 16 bytes
starting at offset 0xF0 in bank 0:
Package {
0x000000F0,
// NV storage block starts at byte offset 0xF0 in CMOS
bank 0
0x00000010
// NV storage block is 16 bytes long
}
FMAP (Chrome OS flashmap address)
This control method returns the physical memory address of the start of the main processor
Google Confidential - Do Not Distribute.
Expires on February 29, 2012 or when a new document is published.
Google Confidential - Do Not Distribute.
Expires on February 29, 2012 or when a new document is published.
firmware flashmap.
Arguments:
None
Result code:
A DWORD containing the physical memory address of the start of the main processor firmware
flashmap.
VDTA (Chrome OS verified boot data)
This control method returns the verified boot data block shared between the firmware
verification step and the kernel verification step.
Arguments:
None
Result code:
A buffer containing the verified boot data block.
MLST (Chrome OS method list)
This control method returns a list of the other control methods supported by the Chrome OS
hardware device.
Arguments:
None
Result code:
A pakage containing a list of null-terminated ASCII strings, one for each control method
supported by the Chrome OS hardware device, not including the MLST method itself.
For this version of the specification, the result is:
Package {
"CHSW",
"FWID",
"HWID",
"FRID",
"BINF",
"GPIO",
"VBNV",
"FMAP",
"VDTA"
}
S3 Debug Data Area
On x86 processors, Chrome OS uses the 1MB memory region at physical memory addresses
0x00F00000 - 0x00FFFFFF to hold kernel diagnostic data for the S3 debug resume path. BIOS
shall mark this area as reserved and not access it during a S3 debug resume.
Summary of Required ACPI Devices
The following table summarizes the ACPI devices specifically required for Chrome OS firmware,
in addition to those required to support configuration, power management, processor, and
thermal management:
Component
ACPI Spec
Plug and Play ID Required Required
Notes
Google Confidential - Do Not Distribute.
Expires on February 29, 2012 or when a new document is published.
Google Confidential - Do Not Distribute.
Expires on February 29, 2012 or when a new document is published.
Sections
Methods
Notifications
_PSR
_PCL
0x80
Battery
9.3
10.1
10.2
PNP0C09
ACPI0002
AC adapter
10.3
ACPI0003
Power button
4.7.2.2.1
9.3
PNP0C0C
Lid switch
9.4
PNP0C0D
_LID
0x02
0x80
Ambient light
sensor
9.2
ACPI0008
_ALI
_ALR
0x80
Display
adapter
Appendix B SB/PCI/VGA
_DOS
_DOD
0x81
Display
internal LCD
Appendix B SB/PCI/VGA/LCD _BCL
_BCM
_BQC
_DCS
_DGS
_DSS
0x02
0x80
Required if sensor
is connected
to embedded
controller.
Display
Appendix B SB/PCI/VGA/CRT _DDC
external port
SB/PCI/VGA/DVI _DCS
_DGS
_DSS
Keyboard
n/a
PNP0303
n/a
0x02
Trackpad
n/a
PNP0F13
n/a
0x02
Real-Time
Clock
9.16
PNP0B00
PNP0B01
PNP0B02
Embedded
Controller
12
PNP0C09
Chrome OS
hardware
n/a
GGL0001
0x02
CHSW
HWID
FWID
FRID
BINF
GPIO
VBNV
FMAP
VDTA
MLST
Development Process
This section describes the expected process for developing Google Chrome OS firmware.
If resources permit, work on the boot stub, rewritable firmware, and recovery mode firmware
can occur in parallel.
Google Confidential - Do Not Distribute.
Expires on February 29, 2012 or when a new document is published.
Google Confidential - Do Not Distribute.
Expires on February 29, 2012 or when a new document is published.
Hardware bring-up using existing (non-custom) firmware
Initial hardware bring-up can be performed using existing / standard firmware, without the
Google Chrome OS customizations.
To enable rapid development, development systems should be modified to disable the firmware
write protect GPIO, so that all firmware is rewritable. See the Developer Mode design
document for more information.
Implement boot stub without signature checking
The following parts of the boot stub are implemented
● Start initializing chipset
● Check firmware write protect GPIO
● Lock down EEPROM
● Check recovery mode GPIO
● Check recovery mode field
● Jump to selected firmware
This enables development of the rewritable firmware, while maintaining an alternate boot path
to recovery mode firmware via the recovery button.
At this stage of development, the recovery mode firmware may be a copy of the existing /
standard firmware.
Implement rewritable firmware
All portions of the rewritable firmware are developed.
Signature checking may be initially implemented using manufacturer-created keys, to speed
development.
Finish implementing boot stub
The remaining features in the boot stub are implemented:
● Initialize TPM
● Check rewritable firmware signature
● Lock TPM rewritable firmware key index
Implement recovery mode firmware
All portions of the recovery mode firmware are developed.
OEM / ODM / BIOS vendor bug fixing
At this point, all firmware features are implemented. Remaining firmware development is
primarily for bug fixing.
In this stage, almost all production tests can be run on development devices.
Rapid firmware development is still possible. Devices can be modified to disable firmware write
protect so the entire EEPROM can be updated, and development firmware can be signed with
manufacturer-created keys.
Since firmware write protect is still disabled and signature checking is done using manufacturercreated keys, the following tests are expected to fail:
● Check that firmware write protect is enabled
● Check that main firmware uses only Google-supplied keys for signature checking
Google Confidential - Do Not Distribute.
Expires on February 29, 2012 or when a new document is published.
Google Confidential - Do Not Distribute.
Expires on February 29, 2012 or when a new document is published.
Switch to Google-supplied keys
Production devices will use Google-supplied keys for signature checking of the main firmware,
and will not have manufacturer mode enabled.
All production tests should pass on these devices.
If bugs are discovered or further development is necessary, firmware write protect can be
disabled on selected devices to enable more rapid development.
Google Confidential - Do Not Distribute.
Expires on February 29, 2012 or when a new document is published.