ChromiumOS Vital Product Data (VPD) tooling for firmware images

Clone this repo:
  1. 12a4095 dump_vpd_log: Add oem_name to filter list by Michal Mazur · 8 days ago main release-R124-15823.B
  2. 0ce44ef BUILD: Install vpd_provider_interface.h by Brian Norris · 3 months ago release-R122-15753.B release-R123-15786.B stabilize-15756.B stabilize-15793.B
  3. 0bfa1fa Revert "encoder: Drop EPS support" by Brian Norris · 3 months ago
  4. 1dd93cb Revert "Drop dead C code" by Brian Norris · 3 months ago
  5. 1c903ae Revert "vpd.cc: Drop stale EPS-related logic" by Brian Norris · 3 months ago

ChromeOS Vital Product Data (VPD) Binary Blob 2.0

Overview

The Chrome OS Platform VPD Reporting Specification describes how a firmware image complies with the Chrome OS SMBIOS requirement. That document defines the required fields of type 0/1/127 tables and type 241 binary blob pointers. However, the format of type 241 is left for each ODM to define. In most cases this is acceptable because Google is not involved in manufacturing and RMA processes.

The type 241 data often consists of component IDs and other items that affect the OEM software setup. Component IDs include network device IDs, IDs for removable devices (storage, RAM, etc), and other arbitrary ID types. OEM software information includes the default country code, language code, and so on.

Occasionally, modifying the vendor product data is required. Each OEM uses a proprietary format, which varies from model to model. To minimize variations, Google defined a standard format for the Vital Product Database (VPD) that is common, simple, and extensible.

This document describes the standard format for the VPD on Chrome devices. The format provides:

  • An universal vendor product data format for all ODMs and OEMs
  • A method for tracking serial numbers for all removable or replaceable components on a machine
  • A more efficient, usable approach for both manufacturing and Return Materials Authorization (RMA) processes

The format design principles were:

  • Simple encoding implementation (no XML)
  • Flexible enough for different hardware configurations

Syntax

The basic syntax for database entries is {type, key, value} * n. Instead of using a null-terminated ASCII string for key and value, we prefix a length for binary-safe. The string size varies according to the length value that precedes it. Every byte is contiguous and back-to-back. Padding the value is field allowed. To avoid parsing the VPD structure, the hardcoded fixed address can be used to read VPD values directly.

The following diagram illustrates the structure of the blob: blob 2.0 diagram

The entire binary blob is an array of {key, value} pairs. At the end, a 0x00 (VPD_TYPE_TERMINATOR) or a 0xFF (VPD_TYPE_IMPLICIT_TERMINATOR) indicates the end of the array and the binary blob.

The combination of key and value can exceed 127 bytes. Setting the More bit to 1 indicates the next byte has lower significant 7 bits in length.

Encoding example

The following example shows how to encode strings of normal length:

<01> <04> "UUID"          <10> "0123456789ABCDEF"
<01> <07> "3G_IMEI"       <0E> "AABBBBBB-CC-DD"
<01> <0C> "ethernet_mac"  <06> <2A><02><03><B3><D5><7C>
<00>   // the terminator

The following example shows how to encode longer strings, like “any=Very long long long...”:

<01> <03> "any"     <84><82><01> "Very long long long"...(65793 bytes)
<00>

The VPD supports 4 types:

TypeNameDescription
0x00VPD_TYPE_TERMINATORTerminates VPD data.
0x01VPD_TYPE_STRINGEncoded string length-value pair.
0xFEVPD_TYPE_INFOKey-value pair VPD info header.
0xFFVPD_TYPE_IMPLICIT_TERMINATORSame as VPD_TYPE_TERMINATOR.

Additional information:

VPD_TYPE_STRING is made up of a key pair and a value pair.

VPD_TYPE_INFO is a key-value pair the AP Firmware (sometimes referred as BIOS) uses to parse the VPD. The search pattern is,“gVpdInfo”,(see VPD_INFO_MAGIC in the code) and the 4-byte size of VPD data follows.

For details of each type, search for VPD_TYPE_* in the code.

Utility command examples

Chrome OS includes a utility for manipulating VPD data. The examples below show how to use the VPD utility to perform common tasks. Each task is described in the comment line preceding the example:

  # Dump all key-pairs in RO_VPD partition on the flash
  % vpd -l
    "serial_number"="20100915SKU0015566"
    "SKU"="SKU0001"
    "UUID"="0001-0203_04050607"
    "ethernet_mac"="2A:45:29_66:D4:57"

  # Dump RW_VPD partition
  % vpd -l -i "RW_VPD"

  # Rather using access flash each time (usually slow), instead
  # dump a cached image to access.
  % futility read bios.bin
  % vpd -f bios.bin -l

  # Add a new key-value pair, which value is a string (-s)
  % vpd -f vpd.bin -s "SKU"="0123456789ABCDEF"

  # Add tons of key-value pairs at one time.
  % vpd -f vpd.bin -s "serial_number"="20101214_MARIO_1122" \
                   -s "ethernet_mac"="11:22:33:44:55:66" \
                   -s "mlb_serial_number"="2037291738734" \
                   -s "UUID"="2323-3524-2344364-133456" \
                   ...

  # By default, utility accesses "RO_VPD" on flash. You can specify -i
  # parameter to access particular partition.
  # PS. -O means overwriting any garbage in partition.
  vpd -i "RW_VPD" -O -s "ActivateDate=2011/03/02 11:22:33"

  # Read a specific key-value pair. Specially useful in shell script.
  % vpd -g "mlb_serial_number"
    MB20100914_012345
  # no key string and no quotes in output.

  # Delete a key-value pair
  % vpd -f vpd.bin -d "3G_IMEI"

Partition names

The AP firmware image for Chrome OS has two VPD partitions. Each stores a specific type of data:

  • RO_VPD partition in the read-only area. Stores machine-specific information, like the mainboard serial number and MAC address.
  • RW_VPD partition in the writeable area. Stores all data that will be updated after a device leaves the factory.

Note that the naming convention includes the underscore ( _ ) character.

VPD fields

Although VPD 2.0 doesn't define a fixed data structure, Google requires partners to include specific VPD fields in the AP firmware image, for example serial_number. The list of VPD fields are available in the ChromeOS Partner Site document “VPD Field Requirements”.

In theory the VPD name can be arbitrary string, but in order to simplify processing, the utility only accepts names in CamelCase or lower_underline, i.e., in regular expression [a-zA-Z0-9_]+.

Appendix A

This information is intended for a developer audience.

Type enumerates used in ‘type’ field.

ValueType
0x00The terminator
0x01String
0xFEInfo header
0xFFThe implicit terminator.

On the flash media, a non-programmed byte is 0xFF. When decoder reads this type, it should assume no more pairs are present after this byte.

Values in Binary Blob Pointer (Type 241)

OffsetNameLengthValue
00hTypeBYTE241
01hLengthBYTEVaries
02hHandleWORDVaries
04hStructure Major VersionBYTE01h
05hStructure Minor VersionBYTE00h
06hBlob VendorBYTE1 “Google”
07hBlob DescriptionBYTE2 “VPD 2.0”
08hBlob Major VersionBYTE2
09hBlob Minor VersionBYTE0
0AhBlob VariantBYTE3 ""
0Bh-0FhReserved
10h-1FhBlob UUID16 BYTES0a7c23d3-8a27-4252-99bf-7868a2e26b61
20h-23hOffsetDWORDVaries
24h-27hSizeDWORDVaries

Change Log

VersionDateChanges
0.172014/02/27Added VPD_TYPE_INFO
0.122011/04/20Reorganized content, updated available options
0.72011/03/11Added VPD partition names and required field
0.62011/03/08Made small refinement to Binary Blob Pointer values
0.52011/03/02Added RW VPD example
0.42010/12/13Fixed the command style
0.32010/12/14Added the implicit terminator (0xFF)
0.22010/12/08Added type field. Allowed padding.
0.12010/09/14Draft version.