Peripheral Firmware Update via fwupd

Version: 2.2
Last Updated: 2024-02-01

Overview

The purpose of this guide is to describe how to configure fwupd firmware updates supported by ChromeOS UI.

Background

fwupd is an open-source daemon that performs peripheral and other system firmware updates on Linux-based systems. fwupd is the mechanism by which ChromeOS updates peripheral firmware.

fwupd update payloads consist of .cab files that are stored in Linux Vendor Firmware Service (LVFS). In Linux, fwupd updates can be made widely available once they are uploaded to LVFS. However, for the updates to be made available in ChromeOS, the ChromeOS team will separately verify and allowlist new updates to ensure optimal user experience.

fwupd Process

The following is only applicable to WWCB-certified peripherals where samples have been sent to Allion.

If the current version of fwupd in ChromeOS does not already support the peripheral then follow instructions provided in use case 1 and use case 2. If the current version of fwupd in ChromeOS already supports the peripheral then skip to use case 2.

Use Case 1: ChromeOS current version of fwupd does not support the peripheral

image

If the current version of fwupd in ChromeOS does not already support the peripheral.

  1. ODM and OEMs to directly work with chipset vendors to submit plugin changes into the fwupd codebase.

  2. Navigate to Partner Issue Tracker, login with your Google Partner Domain Account and click on the Create Issue button from the left side menu to create a bug in your component (ChromeOS \> External \> WWCB \> [Peripheral OEM] \> fwupd), alerting us to uprev the fwupd version in ChromeOS.

    1. Bug title:

      [Product Name - fwupd]: New Plugin [name of the plugin] requires fwupd [x.y.z] version uprev
      
    2. Include the following information in the bug:

    3. fwupd version number which consists of plugin changes: - What features does it add? - What bugs are fixed? - What Hardware does it support?

    4. Make/Model of the Device

    5. VID, PID

    6. GUID (globally unique identifier)

    7. Example screenshot:

      image

  3. The bug will be triaged, and the selective version of fwupd will be incorporated to test image of ChromeOS by Google Engineers.

  4. The bug will then be assigned to qualify uprev'd version of fwupd in chromeOS, this ensures the uprev does not break fwupd.

    • Testing team will pick 5 products and upgrade/downgrade firmware using the test image of ChromeOS that consists of uprev'd fwupd.
  5. Validation results will be made available in the bug.

    • If validation fails due to bugs found during upgrade, the bug will be assigned back to Google Engineer.
  6. Once testing is complete, the uprev'd version of fwupd will be promoted to canary channel as the changelist is approved.

    • Leave a comment on the bug to know which build version of ChromeOS consists of the uprev'd version of fwupd. You can also use CL Finder to search build version in ChromeOS partner console (CPCon) (requires Google corp partner domain account, please contact TAMs for access to CPCon).

Use Case 2: ChromeOS current version of fwupd supports the peripheral

image

The current version of fwupd in ChromeOS already supports the peripheral and a new firmware is available.

  1. Create a cab file
    • All firmware is uploaded as a cabinet archive. Along with the firmware binary, the LVFS expects the archive to contain at least one .metainfo.xml file that describes the target device and firmware. You can create a cabinet archives using gcab (a library to create cabinet files) on Linux.
  2. Upload the tested and final firmware update (.cab file) to LVFS.

    1. Ensure the update is available on the stable remote
      • If it is available on the private, embargo, or testing remote, it will not be added to the ChromeOS mirror
    2. Updates marked as validated in LVFS via a signed report 1. Make sure the device tests are added - Example json file, supported by the test framework for device testing
    3. If this is the first firmware upload then make sure 2 firmwares, the base firmware (to test downgrade) and the new firmware (to test upgrade) are available in the stable remote of LVFS
  3. Navigate to Partner Issue Tracker, login with your Google Partner Domain Account and click on the Create Issue button from the left side menu to create a bug in your component (ChromeOS \> External \> WWCB \> [Peripheral OEM] > fwupd), alerting us of the update you wish to have added to the next milestone of ChromeOS.

    1. Bug title:

      [Product Name - fwupd]: New firmware upgrade
      
    2. Include the following information in the bug:

    3. Link to the fwupd update of interest on LVFS - NOTE: If the firmware has a hard requirement, mentioned in the requires metadata section of .metainfo.xml file, list the hard requirements in the issuetracker. - For example:

          ```
          <requires>
          <id compare="ge" version="0.4.3">org.freedesktop.gusb</id>
          …
          </requires>
          ```
      
      -   Google Engineers will accordingly uprev ([example uprev]).
      
    4. Make/Model of the Device

    5. VID, PID

    6. GUID

    7. The initial version of fwupd that supports device (i.e. plugin support landed in fwupd 1.8.4) - Bug link to uprev'd fwupd version

          ![image](images/fwupd-guide02.png)
      
    8. If a prior version of peripheral firmware is supported in ChromeOS, provide a link to the last bug that tracked the prior firmware payload.

  4. The bug will be triaged, and the update file will then be validated by the ChromeOS team.

    1. Testing via test Framework
      1. Detect peripheral
      2. Detect LVFS link
      3. Update firmware
      4. Downgrade firmware
    2. Post-Update Functional Testing
      1. Functional testing will be conducted to ensure that the firmware update did not break any functionality of the peripheral
  5. Validation results will be made available in the bug.

    1. If validation fails due to the framework not detecting the peripheral / LVFS link, you will be notified via the bug
      1. The peripheral does not support fwupd or
      2. The peripheral VID/PID does not match or
      3. The .cab file is not available/visible on LVFS
    2. If validation fails due to bugs found during upgrade or in functional testing, you will be notified via the bug
      1. A new, revised .cab file will need to be uploaded to LVFS and the process will begin from step 1.
  6. Upon successful validation, submit a changelist via the Chromium Gerrit

    1. How to get started
      1. Developers guide
      2. Developer Support
    2. Changelist should consist of two changes

      1. Add another line to the manifest: sys-firmware/fwupd-peripherals/Manifest
      2. Add another line to the ebuild with the appropriate file name: sys-firmware/fwupd-peripherals/fwupd-peripherals-9999.ebuild
      3. See Example Changelist 2.

        • To generate Manifest calculations, after editing fwupd-peripherals-9999.ebuild, from inside Chroot:

          $ ebuild fwupd-peripherals-9999.ebuild manifest
          
    3. This is a necessary step to have the update appear in the ChromeOS fwupd UI. Without this step, the user will not see any update available, regardless of the urgency of the update.

    4. In order to make it into the next version of ChromeOS, the changelist needs to be submitted two weeks prior to the branch cut-off date. Release schedule can be found in Schedule.

    5. Ensure the changelist has the bug number created in step 3. In the commit message of the changelist, BUG=b:<bug number> line is required to be added. This will ensure that the CL is properly linked to the bug, and that Google reviewers can find your CL to review.

  7. Once the changelist is approved, the Changelist will be merged to a specific version of ChromeOS Image that the firmware update will go live in.

    1. Leave a comment on the bug to know which build version of ChromeOS consists of the firmware updates. You can also use CL Finder to search build version in ChromeOS partner console (CPCon) (requires Google corp partner domain account, please contact TAMs for access to CPCon).

FAQs

Q: Which Chromebook supports fwupd?

All ChromeOS devices on M101 or later.

Q: How to find which version of fwupd is integrated with ChromeOS?

  1. Open chrome://system via browser
    1. Navigate to fwupd_version
  2. Or via Developer mode, root console,
    1. Type fwupdmgr --version
    2. Look for runtime org.freedesktop.fwupd

Q: How to switch a chromebook to Developer mode?

  1. Turn off the Chromebook
  2. Hold esc+Refresh and press Power button
    • Note: On some chromebooks it is esc+> (right arrow key) and press Power button
  3. Device turns on and you should see Recovery screen / mode
  4. Then press ctrl+d, followed by Enter to accept.
    • Note: If you press any keys before ctrl+d the device will not transition into developer mode.
  5. The device will reboot, beep and you will see ‘Your system is transitioning to Developer mode'
  6. After about 30 seconds you will see ‘Preparing system for Developer mode'
  7. Eventually (this can be 10 minutes to 1+ hours depending on the disk size) the device will reboot into the regular welcome screen
  8. Get the Command Prompt press ctrl+alt+> (right arrow key)
    • Note: On some chromebooks it is ctrl+alt+refresh key
    • To get back to browser view, press ctrl+alt+< (left arrow key)
  9. More details can be found in [Developer Mode]

Q: How to switch a chromebook to Normal mode (i.e., disable Developer mode)?

Reboot your device and press the Spacebar at the firmware screen.

More details can be found in [Developer Mode]

Q: Does ChromeOS support downgrades via fwupd?

No, if the Production version of fwupd or the firmware breaks, you will have to revert the Changelist. It is important to test whenever you submit plugin changes and/or have a new firmware available. Ensure a base version of firmware is always available on a stable remote of LVFS.

Q: How can one know which versions of ChromeOS will support which fwupd updates?

You can leave a comment on the bug asking for which build version are the changes incorporated into and the Google Engineers should be able to provide you with that information or you can also use CL Finder to search build version in ChromeOS partner console (CPCon) (requires Google corp partner domain account, please contact TAMs for access to CPCon). One may cross reference the build version on ChromeOS Partner Frontend (CPFE) to see which milestone it corresponds to.

Q: How long does the new update upload process take?

Follow Chromium schedule, ensure above changes are submitted at least 2 weeks prior to branch cut off date.

Q: How to create a LVFS account?

Refer to Getting an Account LVFS documentation.

Q: How to upload cab files to LVFS?

Refer to Uploading Firmware LVFS documentation.

Q: How to ensure a firmware is for a specific peripheral?

This is possible via the best known configuration file. Refer to fwupd Best Known Configuration for more information.

Q: How can I test my fwupd update before uploading to LVFS?

Once the plugin changes are submitted and the selective version of fwupd is incorporated to ChromeOS test image, you can access the test image via ChromeOS Partner Frontend (CPFE) (requires Google corp partner domain account, please contact TAMs for access to CPFE).

Refer to LVFS documentation Firmware testing on ChromeOS. Alternatively you can also run fwupd tests with Moblab.

Q: How will a user be notified that a firmware update is available for their peripheral?

The user will receive a notification that an update is available based on the urgency the update was assigned in LVFS. Behavior is as follows:

Urgency Notification Behavior
Low User will not be notified, will have to manually check for updates
Medium
High
Critical Notification will show every boot until update is complete

Q: Do fwupd updates happen automatically?

No. All fwupd updates are initiated by the user, and will not happen during boot or automatically.

Q: What is the advantage of DS20 Specification?

Currently verified for USB peripherals only, if you use the same protocol you did on your other hardware, it'll just work with a DS20 descriptor.

Vendors can put the quirk file data into the USB descriptor rather than into the fwupd project. That way the USB device is inserted, fwupd reads the descriptor data, matches the plugin, enumerates the device without having to get the vendor to submit a patch to fwupd and waiting for fwupd uprev.

Q: Is DS20 an alternate option to quirk file changes only?

Yes; most of the time future hardware just needs VID&PIDs added to an existing plugin, rather than actual code changes. If code changes are required then the vendor has to submit plugin changes to fwupd.

Appendices

  1. Developers guide
  2. Developer Support
  3. [Introduction to Git & Gerrit for CrOS contributors]
  4. [Making changes to source code]
  5. [Gerrit review/approval process]
  6. fwupd Integration Handbook
  7. fwupd flow

    image

Revision History

Date Version Note
2024-02-01 2.2 Republication on new platform; minor wording updates.
2023-10-12 2.1 Added Images in Case 1 and Case 2, fwupd Integration Handbook hosted in Partner Site
2022-08-14 2.0 Initial partner site publication