Peripheral Firmware Update via fwupd

Version: 2.4
Last Updated: 2024-07-23

Overview

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

fwupd flowchart

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

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

image

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

    1. Refer to the fwupd Integration Handbook (Second step - using fwupd).
    2. Plugin changes: example 1, example 2
    3. Matching VIDs:PIDs in .quirk file: example 3
      • As alternative for quirk file changes, if the USB peripheral is supported by the existing plugin, then you can follow the DS20 specification.
    4. Have resulting plugin and quirk changes merged by fwupd's maintainers.
    5. Wait for official point release of fwupd (i.e., 1.8.4), make a note of the version.

  2. fwupd releases are mirrored into ChromeOS regularly and will follow the Chromium release schedule.

  3. If you submit plugin changes, bug fixes, or quirk file changes after the feature freeze cut off date of a upcoming Chromium release, but the changes are high priority for the next ChromeOS release, then:

    1. Navigate to Partner Issue Tracker.
    2. Login with your Google Partner Domain Account.

    3. Click on the Create Issue button from the left side menu to create a bug in your component (ChromeOS > External > WWCB > PERIPHERAL OEM > fwupd). This alerts the ChromeOS team to uprev the fwupd version in ChromeOS.

      Provide the following information in the bug:

      1. Bug title:

        [PRODUCT NAME - fwupd]: New Plugin NAME OF THE PLUGIN requires fwupd X.Y.Z version uprev

      2. Bug description:

        1. fwupd version number which consists of plugin changes:
          • What features does it add?
          • What bugs are fixed?
          • What Hardware does it support?
        2. Make/Model of the Device
        3. VID, PID
        4. GUID (globally unique identifier)

      3. Example screenshot:

        screen shot of fwupd uprev bug

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

  5. 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.

  6. Validation results will be provided in the bug.

    • If validation fails due to bugs found during upgrade, the bug will be assigned back to Google Engineer.

  7. 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

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

image

  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.

      Make sure the device tests are added.

    3. If this is the first firmware upload, then make sure at least 2 firmwares, the base firmware (to test downgrade) and the new firmware (to test upgrade), are available in the stable remote of LVFS.

  3. Firmware upgrade should be tested on ChromeOS via a signed report.

    1. Upload certificates to LVFS to link the DUT with your account.
      1. Login to LVFS with your account.
      2. Click the “Person” icon on the top right, or click https://fwupd.org/lvfs/profile{:.external}.
      3. Click on Profile settings.
      4. Click the Upload Certificate button in the Client Certificates section.
        • Navigate to /var/lib/fwupd/pki and upload client.pem on each machine you're using for testing (you can upload multiple certificates for different computers).

    2. Test upgrade and upload signed reports via the DUT.

      1. To test and upload reports, run the following commands and authenticate when prompted.

        $ fwupdmgr refresh
$ fwupdmgr update
$ fwupdmgr report-history --sign

      2. Note: If you’ve already uploaded reports without the --sign flag, you can use fwupdmgr report-history --sign --force to re-upload the same report to the LVFS.

        $ fwupdmgr report-history --sign --force

        • You can pass --verbose to see the server response.

           $ fwupdmgr report-history --force --verbose
 ```
      1. Click on Yes in the confirmation dialog.
        • That should upload the signed report into your account.
        • To confirm, navigate to https://fwupd.org/lvfs/dashboard{:.external} and click on Signed Reports under the Home section on the top left.

    3. Verify the firmware version on LVFS has signed reports

      • Search for the peripheral on LVFS.
      • If the uploaded signed report was after successfully upgrading the firmware version on the peripheral using a Chromebook, then the Tested By section will show ChromeOS version, fwupd version, and the entity. See example.
      • Make sure Release Gating shows a green checkmark “Available to ChromOS users”.

    4. Starting M126, firmware updates will only be available to ChromeOS users if the firmware has signed reports (tested with ChromeOS) on LVFS.

      • After 24 hours, users can connect the peripheral to the chromebook and upgrade the firmware via ChromeOS UI. Navigate to Settings > About ChromeOS > Firmware updates.
      • Note: Firmware updates will be available assuming all the required plugin changes are available on ChromeOS for a given milestone.

More details on signed reports can be found on LVFS.

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 (M109 or later).
    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 long does the fwupd uprev process take?

fwupd uprev follows Chromium release schedule, ensure fwupd uprev request is submitted before branch feature freeze cut off date.

Q: Where can I get more information about the ChromeOS release schedule?

In the Chromium Release schedule.

Q: How to switch a chromebook to Developer mode?

  1. Turn off the Chromebook.
  2. Hold esc+Refresh and press the 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 delete the signed report via https://fwupd.org/lvfs/dashboard. 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. You can also use CL Finder to search build version in ChromeOS partner console (CPCon) (requires Google corp partner domain account—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 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—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

Revision History

Date Version Note
2024-07-23 2.4.1 Formatting updates.
2024-06-26 2.4 Update fwupd uprev workflow (use case 1).(published together with 2.4.1)
2024-06-17 2.3 Update Signed report workflow. (published together with 2.4.1)
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