Fwupd Firmware Updates Integration Handbook

Version: 1.0.2
Last updated: 2025-03-12

TL;DR

This doc is intended to be a walkthrough of how vendors can implement fwupd for future projects. It includes insight directly quoted from LVFS maintainers as well. Fwupd is an open source firmware update framework that can help centralize the way we perform firmware updates in partnership with external vendors.

First Step - Gather Information & Provide Guidance

For Vendors - First Ask:

  • Questions on updatable component (s)

    • Update size

    • Update time

    • Existing update type (A/B or bootloader/runtime model)

    • What happens to the component’s functionality during an update?

    • What has to happen to the system to start using a successful update?

    • Do multiple components need to be installed in a particular order?

  • Familiarity in working with LVFS/fwupd, or knowledge of it

  • Ability to commit eng resource to help implement plugin (see below for further details)

  • Commitment on open sourcing plugin to LGPLv2+ (code that writes the firmware to component) and allowing firmware to be redistributable by LVFS

For Vendors - Initial Guidance:

  • Update must minimize time that the peripheral or internal component functionality is impacted, ideally to a couple of seconds. The longer part of the update should occur silently in the background without disrupting the user

    • If this peripheral impacts the user experience in an obvious way (e.g. display stops working) this requirement becomes even more stringent

  • To enable this type of silent update, A/B updates are strongly encouraged

    • A/B updates that can activate at peripheral unplug are ideal to minimize user disruption

  • Update must be recoverable - if you power off, unplug peripheral, etc the update should not brick the device or peripheral. It should be robust to recover without user action.

    • The initial assumption should be that there is no user action during the entire update, the proper scripts and stages of update should be driven autonomously

Second Step - Using fwupd

If a vendor has never used fwupd

  • Chrome OS gives requirements for firmware update through fwupd to OEM. OEM should communicate this directly to chip / component suppliers

  • In some cases, ODM can help OEM interface with chip vendors directly. It is the responsibility of the OEM to communicate pass along these requirements accordingly

  • Please note that if providing source code with LGPLv2+ licence, deriving the plugin from this code is typically not feasible (a lot of intricacies). So in this scenario the chip vendor will be required to have someone that can work with the fwupd maintainers and Google engineers.

  • The OEM can be proactive and help in getting commitment from the chip vendors to work closely with the maintainers. The ask for the engineering support on the vendor side has the following requirements:

    • Very familiar with quirks and design features of the updatable hardware component, preferably even be on the same team that wrote the firmware

    • Understand the difference between common open source licenses (e.g. LGPLv2 and MIT)

    • Be proficient in C, with a basic understanding of GLib and GObject, specifically understanding GErrors as well

    • Have a github account and know how to open and update a pull request, do GitHub code reviews, and learn how fwupd is structured with all the helpers fwupd provides (e.g. chunking, attach/detach, device retries, HID, etc)

    • Optional: ability to send hardware samples to the UK - really useful for fwupd maintainers to help the vendor debug issues and to add the board to fwupd tests that are run on each release. The latter being important to stop regressions in the development branch.

  • In parallel, the OEM can start engaging through the fwupd mailing list or with Richard Hughes (hughsient@gmail.com) directly and go over the plan before plugin code is written

  • If a company is small with little to no engineering resources or understanding of open source, the following suggestion might help:

    • The component vendor could use consulting companies, familiar with open source work (not that this incurs additional cost)

    • While this suggestion can help scale, the value of the vendor doing it in-house is that the engineers get familiar with the process and they can easily add VID/PID in the future for new hardware. It is also quicker to close on questions / issues to debug on the hardware

Third Step - Final Steps

  • Eventually the code is refactored into small reviewable commits using all the shared functionality in fwupd

  • Once complete, the plugin gets merged upstream

    • The code used upstream would be the same code in ChromeOS

    • The firmware update binaries used outside of ChromeOS would be distributed to LVFS

In the ChromeOS case specifically:

  • The OEM has to upload the firmware binary into our servers via CPFE

  • There still needs to be redistributable update cabinet archives on the LVFS for the hardware regression tests to work

Fourth Step (Optional) - Adding new components

  • If the fwupd framework is already in place, the only additional step is the updatable component supplier must work on pull requests to add quirks and VID/PIDs for hardware variants

Other Guidance - Working on LVFS

  • Create a new vendor account (~2 minutes to set up)

  • Vendors create users for their own domain or use something like Azure AD to sync user accounts to the LVFS. They can upload firmware to private and vendor-embargo completely for free with very few checks (so it's often the engineers doing this right from the start)

  • Eventually push to testing or stable requires some kind of document from their legal department which clearly says the LVFS can redistribute and analyse the firmware. PDF guideline is provided by Richard. ● If the vendor is just a silicon supplier or an ODM they can become "affiliates" of the OEM and can upload firmware on their behalf, with the OEM having full visibility of what's happening with firmware branded with their name.

  • There are lots of other things to set up (e.g. the Vendor ID restricts them to a set of PCI or USB IDs) but most of the vendors already have an assigned ID and this is 20 seconds to set up.

Other Guidance - Chrome OS Specific Bits

  • In our case, firmware update binaries are not pulled from LVFS directly. Instead the CAB file will be stored in the local file system (rootfs)

    • Future workstream: incorporate the firmware binary in DLC by creating a portage ebuild on the appropriate portage overlay

  • fwupd needs to be invoked (via its CLI fwupdtool) at the right time. For each updatable component a udev rule (or equivalent script) must be created that emits a fwuptool-update upstart event. This event will the be automatically handled to execute fwupdtool with the right arguments and proper sandboxing (minijail)

  • Another component is deciding if UI is required - only under certain circumstances depending on the nature of the component updated. To be evaluated by the PM and Eng team. The higher level guidance, as mentioned in the first step, is to minimize action on the user side

Extra Resources for Vendors

  • External documentation reference: https://lvfs.readthedocs.io/

  • External vendor agreements reference: fwupd.org/lvfs/docs/agreement

  • Developing Plugin tutorial: https://fwupd.github.io/tutorial.html

  • Debugging Plugin tutorial: https://lvfs.readthedocs.io/en/latest/custom-plugin.html

  • Sample quirk file: https://github.com/fwupd/fwupd/blob/master/plugins/wacom-usb/wacom-usb.quirk

Revision History

Date Version Notes
2025-03-12 1.0.2 Convert text from pdf to markdown
2024-01-31 1.0.1 Republication on new platform
2023-10-12 1.0 Initial publication