Plugin Tutorial

Introduction

At the heart of fwupd are plugins that gets run at startup, when devices get hotplugged and when updates are done. The idea is we have lots of small plugins that each do one thing, and are ordered by dependencies against each other at runtime. Using plugins we can add support for new hardware or new policies without making big changes all over the source tree.

There are broadly 3 types of plugin methods:

  • Mechanism: Upload binary data into a specific hardware device.
  • Policy: Control the system when updates are happening, e.g. preventing the user from powering-off.
  • Helpers: Providing more metadata about devices, for instance handling device quirks.

A plugin only needs to define the vfuncs that are required, and the plugin name is taken automatically from the GType.

/* fu-foo-plugin.h
 *
 * Copyright 2022 Richard Hughes <richard@hughsie.com>
 *
 * SPDX-License-Identifier: LGPL-2.1-or-later
 */

#pragma once

#include <fwupdplugin.h>

G_DECLARE_FINAL_TYPE(FuFooPlugin, fu_foo_plugin, FU, FOO_PLUGIN, FuPlugin)

/* fu-foo-plugin.c
 *
 * Copyright Richard Hughes <richard@hughsie.com>
 *
 * SPDX-License-Identifier: LGPL-2.1-or-later
 */

#include "config.h"

#include "fu-foo-plugin.h"

struct _FuFooPlugin {
    FuPlugin parent_instance;
    gpointer proxy;
};

G_DEFINE_TYPE(FuFooPlugin, fu_foo_plugin, FU_TYPE_PLUGIN)

static gboolean
fu_foo_plugin_startup(FuPlugin *plugin, FuProgress *progress, GError **error)
{
    FuPluginData *data = fu_plugin_get_data(plugin);
    self->proxy = create_proxy();
    if(self->proxy == NULL) {
        g_set_error(error, FWUPD_ERROR, FWUPD_ERROR_NOT_SUPPORTED,
                    "failed to create proxy");
        return FALSE;
    }
    return TRUE;
}

static void
fu_foo_plugin_init(FuFooPlugin *self)
{
}

static void
fu_foo_constructed(GObject *obj)
{
    FuPlugin *plugin = FU_PLUGIN(obj);
    FuContext *ctx = fu_plugin_get_context(plugin);
    fu_plugin_add_rule(plugin, FU_PLUGIN_RULE_RUN_BEFORE, "dfu");
}

static void
fu_foo_finalize(GObject *obj)
{
    FuFooPlugin *self = FU_FOO_PLUGIN(obj);
    destroy_proxy(self->proxy);
    G_OBJECT_CLASS(fu_foo_plugin_parent_class)->finalize(obj);
}

static void
fu_foo_plugin_class_init(FuFooPluginClass *klass)
{
    FuPluginClass *plugin_class = FU_PLUGIN_CLASS(klass);
    GObjectClass *object_class = G_OBJECT_CLASS(klass);

    object_class->constructed = fu_foo_constructed;
    object_class->finalize = fu_foo_finalize;
    plugin_class->startup = fu_foo_plugin_startup;
}

We have to define when our plugin is run in reference to other plugins, in this case, making sure we run before the dfu plugin.

For most plugins it does not matter in what order they are run and this information is not required.

Creating an abstract device

This section shows how you would create a device which is exported to the daemon and thus can be queried and updated by the client software. The example here is all hardcoded, and a true plugin would have to derive the details about the FuDevice from the hardware, for example reading data from sysfs or /dev.

static gboolean
fu_foo_plugin_coldplug(FuPlugin *plugin, FuProgress *progress, GError **error)
{
    g_autoptr(FuDevice) dev = NULL;
    fu_device_set_id(dev, "dummy-1:2:3");
    fu_device_add_guid(dev, "2d47f29b-83a2-4f31-a2e8-63474f4d4c2e");
    fu_device_set_version(dev, "1.2.3");
    fu_device_get_version_lowest(dev, "1.2.2");
    fu_device_get_version_bootloader(dev, "0.1.2");
    fu_device_add_icon(dev, "computer");
    fu_device_add_flag(dev, FWUPD_DEVICE_FLAG_UPDATABLE);
    fu_plugin_device_add(plugin, dev);
    return TRUE;
}

static void
fu_foo_plugin_class_init(FuFooPluginClass *klass)
{
    …
    plugin_class->coldplug = fu_foo_plugin_coldplug;
    …
}

This shows a lot of the plugin architecture in action. Some notable points:

  • The device ID (dummy-1:2:3) has to be unique on the system between all plugins, so including the plugin name as a prefix is probably a good idea.

  • The GUID value can be generated automatically using fu_device_add_guid(dev,"some-identifier") but is quoted here explicitly. The GUID value has to match the provides value in the .metainfo.xml file for the firmware update to succeed.

  • Setting a display name and an icon is a good idea in case the GUI software needs to display the device to the user. Icons can be specified using a full path, although icon theme names should be preferred for most devices.

  • The FWUPD_DEVICE_FLAG_UPDATABLE flag tells the client code that the device is in a state where it can be updated. If the device needs to be in a special mode (e.g. a bootloader) then the FWUPD_DEVICE_FLAG_NEEDS_BOOTLOADER flag can also be used. If the update should only be allowed when there is AC power available to the computer (i.e. not on battery) then FWUPD_DEVICE_FLAG_REQUIRE_AC should be used as well. There are other flags and the API documentation should be used when choosing what flags to use for each kind of device.

  • Setting the lowest allows client software to refuse downgrading the device to specific versions. This is required in case the upgrade migrates some kind of data-store so as to be incompatible with previous versions. Similarly, setting the version of the bootloader (if known) allows the firmware to depend on a specific bootloader version, for instance allowing signed firmware to only be installable on hardware with a bootloader new enough to deploy it.

Setting the device version

Although the version can be set easily as a string using fu_device_set_version() directly, it is more flexible to tell fwupd what the version format should be, and to allow the daemon to convert it to a string internally.

This also means that if we get the version format from a quirk file, or from metadata, or even if it changes at runtime — the correct string version is used at all times.

static gchar *
fu_foo_device_convert_version(FuDevice *device, guint64 version_raw)
{
    return fu_version_from_uint24(version_raw, FWUPD_VERSION_FORMAT_TRIPLET);
}

static void
fu_foo_device_class_init(FuFooDeviceClass *klass)
{
    …
    device_class->convert_version = fu_foo_device_convert_version;
    …
}

Mechanism Plugins

Although it would be a wonderful world if we could update all hardware using a standard shared protocol this is not the universe we live in. Using a mechanism like DFU or UpdateCapsule means that fwupd will just work without requiring any special code, but for the real world we need to support vendor-specific update protocols with layers of backwards compatibility.

When a plugin has created a device that is FWUPD_DEVICE_FLAG_UPDATABLE we can ask the daemon to update the device with a suitable .cab file. When this is done the daemon checks the update for compatibility with the device, and then calls the vfuncs to update the device.

static gboolean
fu_foo_plugin_write_firmware(FuPlugin *plugin,
                             FuDevice *dev,
                             GBytes *blob_fw,
                             FuProgress *progress,
                             FwupdInstallFlags flags,
                             GError **error)
{
    gsize sz = 0;
    guint8 *buf = g_bytes_get_data(blob_fw, &sz);
    /* write 'buf' of size 'sz' to the hardware */
    return TRUE;
}

static void
fu_foo_plugin_class_init(FuFooPluginClass *klass)
{
    …
    plugin_class->write_firmware = fu_foo_plugin_write_firmware;
    …
}

It’s important to note that the blob_fw is the binary firmware file (e.g. .dfu) and not the .cab binary data.

If FWUPD_INSTALL_FLAG_FORCE is used then the usual checks done by the flashing process can be relaxed (e.g. checking for quirks), but please don’t brick the users hardware even if they ask you to.

Policy Helpers

For some hardware, we might want to do an action before or after the actual firmware is squirted into the device. This could be something as simple as checking the system battery level is over a certain threshold, or it could be as complicated as ensuring a vendor-specific GPIO is asserted when specific types of hardware are updated.

static gboolean
fu_foo_plugin_prepare(FuPlugin *plugin, FuDevice *device, GError **error)
{
    if (fu_device_has_flag(device, FWUPD_DEVICE_FLAG_REQUIRE_AC && !on_ac_power()) {
            g_set_error_literal(error,
                                FWUPD_ERROR,
                                FWUPD_ERROR_AC_POWER_REQUIRED,
                                "Cannot install update "
                                "when not on AC power");
            return FALSE;
    }
    return TRUE;
}

static gboolean
fu_foo_plugin_cleanup(FuPlugin *plugin, FuDevice *device, GError **error)
{
    return g_file_set_contents("/var/lib/fwupd/something",
                               fu_device_get_id(device), -1, error);
}

static void
fu_foo_plugin_class_init(FuFooPluginClass *klass)
{
    …
    plugin_class->prepare = fu_foo_plugin_prepare;
    plugin_class->cleanup = fu_foo_plugin_cleanup;
    …
}

Detaching to bootloader mode

Some hardware can only be updated in a special bootloader mode, which for most devices can be switched to automatically. In some cases the user to do something manually, for instance re-inserting the hardware with a secret button pressed.

Before the device update is performed the fwupd daemon runs an optional update_detach() vfunc which switches the device to bootloader mode.

After the update (or if the update fails) an the daemon runs an optional update_attach() vfunc which should switch the hardware back to runtime mode. Finally an optional update_reload() vfunc is run to get the new firmware version from the hardware.

The optional vfuncs are only run on the plugin currently registered to handle the device ID, although the registered plugin can change during the attach and detach phases.

static gboolean
fu_foo_plugin_detach(FuPlugin *plugin, FuDevice *device, FuProgress *progress, GError **error)
{
    if (hardware_in_bootloader)
        return TRUE;
    return _device_detach(device, progress, error);
}

static gboolean
fu_foo_plugin_attach(FuPlugin *plugin, FuDevice *device, FuProgress *progress, GError **error)
{
    if (!hardware_in_bootloader)
        return TRUE;
    return _device_attach(device, progress, error);
}

static gboolean
fu_foo_plugin_reload(FuPlugin *plugin, FuDevice *device, GError **error)
{
    g_autofree gchar *version = _get_version(plugin, device, error);
    if (version == NULL)
        return FALSE;
    fu_device_set_version(device, version);
    return TRUE;
}

static void
fu_foo_plugin_class_init(FuFooPluginClass *klass)
{
    …
    plugin_class->detach = fu_foo_plugin_detach;
    plugin_class->attach = fu_foo_plugin_attach;
    plugin_class->reload = fu_foo_plugin_reload;
    …
}

The Plugin Object Cache

The fwupd daemon provides a per-plugin cache which allows objects to be added, removed and queried using a specified key. Objects added to the cache must be GObjects to enable the cache objects to be properly refcounted.

Debugging a Plugin

If the fwupd daemon is started with --plugin-verbose=$plugin then the environment variable FWUPD_$PLUGIN_VERBOSE is set process-wide. This allows plugins to detect when they should output detailed debugging information that would normally be too verbose to keep in the journal. For example, using --plugin-verbose=logitech_hidpp would set FWUPD_LOGITECH_HID_VERBOSE=1.

Using existing code to develop a plugin

It is not usually possible to share a plugin codebase with firmware update programs designed for other operating systems.

Matching the same rationale as the Linux kernel, trying to use one code base between projects with a compatibility shim layer in-between is real headache to maintain.

The general consensus is that trying to use a abstraction layer for hardware is a very bad idea as you’re not able to take advantage of the platform specific helpers — for instance quirk files and the custom GType device creation.

The time the vendor saves by creating a shim layer and importing existing source code into fwupd will be overtaken 100x by upstream maintenance costs longer term, which isn’t fair.

In a similar way, using C++ rather than GObject C means expanding the test matrix to include clang in C++ mode and GNU g++ too. It’s also doubled the runtime requirements to now include both the C standard library as well as the C++ standard library and increases the dependency surface.

Most rewritten fwupd plugins at up to x10 smaller than the standalone code as they can take advantage of helpers provided by fwupd rather than re-implementing error handling, device quirking and data chunking.

General guidelines for plugin developers

General considerations

When adding support for a new device in fwupd some things need to be evaluated beforehand:

  • how the hardware is discovered, identified and polled.
  • how to communicate with the device (USB? file open/read/write?)
  • does the device need to be switched to bootloader mode to make it upgradable?
  • about the format of the firmware files, do they follow any standard? are they already supported in fwupd?
  • about the update protocol, is it already supported in fwupd?
  • Is the device composed of multiple different devices? Are those devices enumerated and programmed independently or are they accessed and flashed through a “root” device?

In most cases, even if the features you need aren’t implemented yet, there’s already a plugin that does something similar and can be used as an example, so it’s always a good idea to read the code of the existing plugins to understand how they work and how to write a new one, as no documentation will be as complete and updated as the code itself. Besides, the mechanisms implemented in the plugin collection are very diverse and the best way of knowing what can be done is to check what is already been done.

Leveraging existing fwupd code

Depending on how much of the key items for the device update (firmware format, update protocol, transport layer) are already supported in fwupd, the work needed to add support for a new device can range from editing a quirk file to having to fully implement new device and firmware types, although in most cases fwupd already implements helper code that can be extended.

If the firmware format, update protocol and device communication are already supported

This is the simplest case, where an existing plugin fully implements the update process for the new device and we only have to let fwupd know that that plugin should be used for our device. In this case the only thing to do is to edit the plugin quirk file and add the device identifier in the format expected by the plugin together with any required options for it (at least a “Plugin” key to declare that this is the plugin to use for this device). Example: https://github.com/fwupd/fwupd/blob/main/plugins/vli/vli-usbhub.quirk

If the device type is not supported

Then we have to take a look at the existing device types and check if there’s any of them that have similarities and which can be partially reused or extended for our device. If the device type is derivable and it can support our new device by implementing the proper vfuncs, then we can simply subclass it and add the required functionalities. If not, we’ll need to study what is the best way to reuse it for our needs.

If a plugin already implements most of the things we need besides the device type, we can add our new device type to that plugin. Otherwise we should create a plugin that will hold the new device type.

The core fwupd code contains some basic device types (such as FuUdevDevice, FuUsbDevice, FuBluezDevice) that can be used as a base type for most devices in case we have to implement our own device access, identification and communication from scratch.

If the device is natively visible by the OS, most of the time fwupd can detect the device connection and disconnection by listening to udev events, but a supported device may also be not directly accessible from the OS — for example, a composite device that contains an updatable chip that’s connected through I2C to a USB hub that acts as an interface. In that case, the device discovery and enumeration must be programmed by the developer, but the same device identification and management mechanisms apply in all cases. See the “Creating a new device type” and “Device identification” below for more details.

If the firmware type is not supported

Same as with the new device type, there could be an existing firmware type that can be used as a base type for our new type, so first of all we should look for firmware types that are similar to the one we’re using. Then, choosing where to define the new type depends on whether there’s already a plugin that implements most of the functionalities we need or not.

Example: extending a firmware type

Our firmware files are Intel HEX files that have optional vendor-specific sections at fixed addresses, this is not supported by any firmware type in fwupd out of the box but the FuIhexFirmare class parses and models a standard Intel HEX file, so we can create a subclass of it for our firmware type and override the parse method so that it calls the method from the parent class, which would parse the file, and then we can get the data with fu_firmware_get_bytes() and do the rest of the custom parsing. Example: https://github.com/fwupd/fwupd/blob/main/plugins/analogix/fu-analogix-firmware.c

Example: extending a device type

Communication with our new device is carried out by doing read/write/ioctl operations on a device file, but using a custom protocol that is not supported in fwupd.

For this type of device we can create a new type derived from FuUdevDevice, which takes care of discovering this type of devices, possibly using a vendor-specific protocol, as well as of opening, reading and writing device files, so we would only have to implement the protocol on top of those primitives. (Example: fu_logitech_hidpp_runtime_bolt_poll_peripherals() in https://github.com/fwupd/fwupd/blob/main/plugins/logitech-hidpp/fu-logitech-hidpp-runtime-bolt.c) The process would be similar if our device was handled by a different backend (USB or BlueZ).

Creating a new plugin

The bare minimum a plugin should have is a constructed function that defines the plugin characteristics such as the device type and firmware type handled by it, the build hash and any plugin-specific quirk keys that can be used for the plugin.

static void
fu_foo_plugin_constructed(GObject *obj)
{
    FuPlugin *plugin = FU_PLUGIN(obj);
    FuContext *ctx = fu_plugin_get_context(plugin);
    fu_plugin_add_device_gtype(plugin, FU_TYPE_STEELSERIES_MOUSE);
    fu_plugin_add_device_gtype(plugin, FU_TYPE_STEELSERIES_GAMEPAD);
}

static void
fu_foo_plugin_class_init(FuFooPluginClass *klass)
{
    plugin_class->init = fu_foo_plugin_constructed;
}

Creating a new device type

Besides defining its attributes as a data type, a device type should implement at least the usual init, finalize and class_init functions, and then, depending on its parent type, which methods it overrides and what it does, it must implement a set of device methods. These are some of them, the complete list is in libfwupdplugin/fu-device.h.

to_string

Called whenever fwupd needs a human-readable representation of the device.

probe

The probe method is called the first time a device is opened, before actually opening it. The generic probe methods implemented in the base device types (such as USB/udev) take care of basic device identification and setting the non-specific parameters that don’t need the device to be opened or the interface claimed (vendor id, product id, guids, etc.).

The device-specific probe method should start by calling the generic method upwards in the class tree and then do any other specific setup such as setting the appropriate device flags.

open

Depending on the type of device, opening it means different things. For instance, opening a udev device means opening its device file.

If there’s no interface-specific open method, then opening a device simply calls the probe() and setup() methods (the open() method would be called in between if it exists).

setup

Sets parameters on the device object that require the device to be open and have the interface claimed. USB/udev generic devices don’t implement this method, this is normally implemented for each different plugin device type if needed.

prepare

If implemented, this takes care of decompressing or parsing the firmware data. For example, to check if the firmware is valid, if it’s suitable for the device, etc.

It takes a stream of bytes (GBytes) as a parameter, representing the raw binary firmware data.

It should create the firmware object and call the appropriate method to load the firmware. Otherwise, if it’s not implemented for the specific device type, the generic implementation in libfwupdplugin/fu-device.c:fu_device_prepare_firmware() creates a firmware object loaded with a provided image.

detach

Implemented if the device needs to be put in bootloader mode before updating, this does all the necessary operations to put the device in that mode. fwupd can handle the case where a device needs to be disconnected to do the mode switch if the device has the FWUPD_DEVICE_FLAG_WAIT_FOR_REPLUG flag.

attach

The inverse of detach(), to configure the device back to application mode.

reload

If implemented, this is called after the device update if it needs to perform any kind of post-update operation.

write_firmware

Writes a firmware passed as a raw byte stream. The firmware parsing and processing is done by the firmware object, so that when this method gets the blob it simply has to write it to the device in the appropriate way following the device update protocol.

read_firmware

Reads the firmware data from the device without any device-specific configuration or serial numbers. This is meant to retrieve the current firmware contents for verification purposes. The data read can then be output to a binary blob using fu_firmware_write().

set_progress

Informs the daemon of the expected duration percentages for the different phases of update. The daemon runs the ->detach(), ->write_firmware(), ->attach() and ->reload() phases as part of the engine during the firmware update (rather than being done by plugin-specific code) and so this vfunc informs the daemon how to scale the progress output accordingly.

For instance, if your update takes 2 seconds to detach into bootloader mode, 10 seconds to write the firmware, 7 seconds to attach back into runtime mode (which includes the time required for USB enumeration) and then 1 second to read the new firmware version you would use:

fu_progress_set_id(progress, G_STRLOC);
fu_progress_add_step(progress, FWUPD_STATUS_DEVICE_RESTART, 10, "detach");
fu_progress_add_step(progress, FWUPD_STATUS_DEVICE_WRITE, 45, "write");
fu_progress_add_step(progress, FWUPD_STATUS_DEVICE_RESTART, 40, "attach");
fu_progress_add_step(progress, FWUPD_STATUS_DEVICE_BUSY, 5, "reload");

If however your device does not require ->detach() or ->attach(), and ->reload() is instantaneous, you still however need to include 4 steps:

fu_progress_set_id(progress, G_STRLOC);
fu_progress_add_step(progress, FWUPD_STATUS_DEVICE_RESTART, 0, "detach");
fu_progress_add_step(progress, FWUPD_STATUS_DEVICE_WRITE, 100, "write");
fu_progress_add_step(progress, FWUPD_STATUS_DEVICE_RESTART, 0, "attach");
fu_progress_add_step(progress, FWUPD_STATUS_DEVICE_BUSY, 0, "reload");

If the device has multiple phases that occur when actually in the write phase then it is perfectly okay to split up the FuProgress steps in the ->write_firmware() vfunc further. For instance:

fu_progress_set_id(progress, G_STRLOC);
fu_progress_add_step(progress, FWUPD_STATUS_DEVICE_RESTART, 5, "wait-for-idle");
fu_progress_add_step(progress, FWUPD_STATUS_DEVICE_WRITE, 90, "write");
fu_progress_add_step(progress, FWUPD_STATUS_DEVICE_RESTART, 5, "reset");

It should be noted that actions that are required to be done before the update should be added as a ->prepare() vfunc, and those to be done after in the ->cleanup() as the daemon will then recover the hardware if the update fails. For instance, putting the device back into a normal runtime power saving state should always be done during cleanup.

Creating a new firmware type

The same way a device type implements some methods to complete its functionality and override certain behaviors, there’s a set of firmware methods that a firmware class can (or must) implement:

parse

If implemented, it parses the firmware file passed as a byte sequence. If the firmware to be used contains a custom header, a specific structured format or multiple images embedded, this method should take care of processing the format and appropriately populating the FuFirmware object passed as a parameter. If not implemented, the whole data blob is taken as is.

write

Returns a FuFirmware object as a byte sequence. This can be used to output a firmware read with fu_device_read_firmware() as a binary blob.

export

Converts a FuFirmware object to an xml representation. If not implemented, the default implementation generates an xml representation containing only generic attributes and, optionally, the firmware data as well as the representation of children firmware nodes.

When testing the implementation of a new firmware type, this is useful to show if the parsing and processing of the firmware are correct and can be checked with:

fwupdtool firmware-parse --plugins <plugin> <firmware_file> <firmware_type>

tokenize

If implemented it tokenizes a firmware, breaking it into records.

build

This is the reverse of export(), it builds a FuFirmware object from an xml representation.

get_checksum

The default implementation returns a checksum of the payload data of a FuFirmware object. Subclass it only if the checksum of your firmware needs to be computed differently.

Generating a skeleton

Rather than copy-and-pasting from other plugins, or using the FuDeviceClass as a guide we have also provided a script that can generate a plugin skeleton.

This skeleton contains all the parts typically needed by a plugin, and plugin developers might find it easier to delete unneeded code rather then trying to copy and paste the correct code from other plugins.

To use this, navivate to the root directory and run:

./contrib/create-plugin.py \
    --vendor VendorName \
    --example ProductName \
    --parent Usb \
    --author "Your Name" \
    --email "your@email.com"

Device identification

A device is identified in fwupd by its physical and logical ids. A physical id represents the electrical connection of the device to the system and many devices can have the same physical id. For example, PCI_SLOT_NAME=0000:3e:00:0 (see libfwupdplugin/fu-udev-device.c:fu_udev_device_set_physical_id() for examples) . The logical id is used to disambiguate devices with the same physical id. Together they identify a device uniquely. There are many examples of this in the existing plugins, such as fu_pxi_receiver_device_add_peripherals() in https://github.com/fwupd/fwupd/blob/main/plugins/pixart-rf/fu-pxi-receiver-device.c

Besides that, each device type will have a unique instance id, which is a string representing the device subsystem, vendor, model and revision (specific details depend on the device type). This should identify a device type in the system, that is, a particular device type, model and revision by a specific vendor will have a defined instance id and two of the same device will have the same instance id (see libfwupdplugin/fu-udev-device.c:fu_udev_device_probe() for examples).

One or more GUIDs are generated for a device from its identifying attributes, these GUIDs are then used to match a firmware metadata against a specific device type. See the implementation of the many probe() methods for examples.

Support for BLE devices

BLE support in fwupd on Linux is provided by BlueZ. If the device implements the standard HID-over-GATT BLE profile, then communication with the device can be done through the hidraw interface. If the device implements a custom BLE profile instead, then it will have to be managed by the FuBluezBackend, which uses the BlueZ DBus interface to communicate with the devices. The FuBluezDevice type implements device enumeration as well as the basic primitives to read and write BLE characteristics, and can be used as the base type for a more specific BLE device.

Battery checks

If the device can be updated wirelessly or if the update process doesn’t rely on an external power supply, the vendor might define a minimum operative battery level to guarantee a correct update. fwupd provides a simple API to define these requirements per-device.

fu_device_set_battery_threshold() can be used to define the minimum battery level required to allow a firmware update on a device (10% by default). If the battery level is below that threshold, fwupd will inhibit the device to prevent the user from starting a firmware update. Then, the battery level of a device can be queried and then set with fu_device_set_battery_level().

Howtos

How to create a child device

fwupd devices can be hierarchically ordered to model dependent and composite devices such as docking stations composed of multiple updatable chips. When writing support for a new composite device the parent device should, at some point, poll the devices that “hang” from it and register them in fwupd. The process of polling and identifying a child device is totally vendor and device-specific, although the main requirement for it is that the child device is properly identified (having physical/logical and instance ids). Then, fu_device_add_child() can be used to add a new child device to an existing one. See fu_logitech_hidpp_runtime_bolt_poll_peripherals() in https://github.com/fwupd/fwupd/blob/main/plugins/logitech-hidpp/fu-logitech-hidpp-runtime-bolt.c for an example.

Note that when deploying and installing a firmware set for a composite device, there might be firmware dependencies between parent and child devices that require a specific update ordering (for instance, child devices first, then the parent). This can be modeled by setting an appropriate firmware priority in the firmware metainfo or by setting the FU_DEVICE_PRIVATE_FLAG_INSTALL_PARENT_FIRST device flag.

How to add a delay

In certain scenarios you may need to introduce small controlled delays in the plugin code, for instance, to comply with a communications protocol or to wait for the device to be ready after a particular operation. In this case you can insert a delay in microseconds with g_usleep or a delay in seconds that shows a progress bar with fu_device_sleep_with_progress. Note that, in both cases, this will stop the application main loop during the wait, so use it only when necessary.

How to define private flags

Besides the regular flags and internal flags that any device can have, a device can define private flags for specific uses. These can be enabled in the code as well as in quirk files, just as the rest of flags. To define a private flag:

  1. Define the flag value. This is normally defined as a macro that expands to a binary flag, for example: #define MY_PRIVATE_FLAG (1 << 2). Note that this will be part of the ABI, so it must be versioned
  2. Call fu_device_register_private_flag in the device init function and assign a string identifier to the flag: fu_device_register_private_flag(FU_DEVICE (self), MY_PRIVATE_FLAG);

You can then add it to the device programmatically with fu_device_add_private_flag, remove it with fu_device_remove_private_flag and query it with fu_device_has_private_flag. In a quirk file, you can add the flag identifier to the Flags attribute of a device (eg. Flags = myflag,is-bootloader)

How to make fwupd wait for a device replug

Certain devices require a disconnection and reconnection to start the update process. A common example are devices that have two booting modes: application or runtime mode, and bootloader mode, where the runtime mode is the normal operation mode and the bootloader mode is exclusively used to update the device firmware. It’s common for these devices to require some operation from fwupd to switch the booting mode and then to need a reset to enter bootloader mode. Often, the device is enumerated differently in both modes, so fwupd needs to know that the same device will be identified differently depending on the boot mode.

The common way to do this is to add the FWUPD_DEVICE_FLAG_WAIT_FOR_REPLUG flag in the device before its detach method returns. This will make fwupd wait for a predetermined amount of time for the device to be detected again. Then, to inform fwupd about the two identities of the same device, the CounterpartGuid key can be used in a device entry to match it with another defined device (example: https://github.com/fwupd/fwupd/blob/main/plugins/steelseries/steelseries.quirk).

Inhibiting a device

If a device becomes unsuitable for an update for whatever reason (see “Battery checks” above for an example), a plugin can temporarily disable firmware updates on it by calling fu_device_inhibit(). The device will still be listed as present by fwupdmgr get-devices, but fwupd won’t allow firmware updates on it. Device inhibition can be disabled with fu_device_uninhibit().

Note that there might be multiple inhibits on a specific device, the device will only be updatable when all of them are removed.

Debugging tips

The most important rule when debugging is using the --verbose and duplicate --verbose flag when running fwupd or fwupdtool.

Adding debug messages

The usual way to print a debug message is using the g_debug macro. Each relevant module will define its own G_LOG_DOMAIN to tag the debug traces accordingly. See https://docs.gtk.org/glib/logging.html and https://docs.gtk.org/glib/running.html for more information.

Inspecting raw binary data

The fu_dump_full and fu_dump_raw functions implement the printing of a binary buffer to the console as a stream of bytes in hexadecimal. See libfwupdplugin/fu-common.c for their definitions, you can find many examples of how to use them in the plugins code.

The rustgen Helper

The rustgen script generates C source files that allow parsing, modifying and querying a packed structure or enumeration. This functionality is provided as parsing untrusted structured data from devices or firmware files is something fwupd does a lot, and so it makes sense to abstract out common code for maintainability reasons. It also allows us to force best-practices into the plugins without having to do careful review of buffer reading and writing.

Structures support integers of specific widths, arrays, GUIDs, strings, default and constant data of variable size. The generated code is endian safe and if used correctly, is also safe against malicious data.

In most cases the structure or enumeration will be defined in a .rs file — which is the usual file extension of Rust programs. This was done as the format is heavily inspired by Rust, and it makes editor highlighting support work correctly. Although these files look like Rust files they’re not actually compiled by rustc, so small differences may be noticeable.

#[derive(New, Validate, Parse)]
struct FuExampleHdr {
    magic: Guid,
    hdrver: u8,
    hdrsz: u16le = $struct_size,
    payloadsz: u32le,
    flags: u8,
}

#[derive(ToString, FromString)]
#[repr(u8)] // optional, and only required if using the enum as a struct item type
enum FuExampleFamily {
    Unknown,
    Sps,
    Txe = 0x5,
    Me,
    Csme,
}
struct ExamplePacket {
    family: FuExampleFamily = Csme,
    data: [u8; 254],
}

The struct types currently supported are:

  • u8: a guint8
  • u16le: little endian guint16
  • u24: a 24 bit number represented as a guint32
  • u32le: little endian guint32
  • u64be: big endian guint64
  • char: a NUL-terminated string
  • Guid: a GUID
  • Any enum created in the .rs file with #[repr(type)]
  • Any struct previously created in the .rs file

Arrays of types are also allowed, with the format [type; multiple], for example:

  • buf: [u8; 3] = 0x123456 for a C array of guint8 buf[3] = {0x12, 0x34, 0x56};
  • val: [u64be; 7] for a C array of guint64 val[7] = {0};
  • str: [char; 4] = "ABCD" for a C array of gchar buf[4] = {'A','B','C','D'}; — NOTE: fu_struct_example_get_str() would return a NUL-terminated string of ABCD\0.

Additionally, default or constant values can be auto-populated:

  • $struct_size: the total struct size
  • $struct_offset: the internal offset in the struct
  • string values, specified without double or single quotes
  • integer values, specified with a 0x prefix for base-16 and with no prefix for base-10
  • previously specified enum values

Per-field metadata can also be defined, such as:

  • =: set as the default value, or for u8 arrays initialize with a padding byte
  • ==: set as the default, and is also verified during unpacking.

Default values and padding will be used when creating a new structure, for instance using fu_struct_example_new().

Building

When building a plugin with meson a generator can be used:

diff --git a/plugins/example/meson.build b/plugins/example/meson.build
@@ -3,7 +3,6 @@
 plugin_quirks += files('example.quirk')
 plugin_builtins += static_library('fu_plugin_example',
+  rustgen.process('fu-example.rs'),
   sources:

…which creates the files plugins/libfu_plugin_example.a.p/fu-example-struct.c and plugins/libfu_plugin_example.a.p/fu-example-struct.h in the build tree.

The latter can be included using #include fu-example-struct.h in the existing plugin code.

Structs

There are traits that control the generation of struct code. These include:

  • New: for fu_struct_example_new(), needed to create new instances
  • Validate: for fu_struct_example_validate(), needed to check memory buffers are valid
  • Parse: for fu_struct_example_parse(), to create a struct from a memory buffer
  • Getters: for fu_struct_example_get_XXXX(), to get access to field values
  • Setters: for fu_struct_example_set_XXXX(), to set specific field values

Getters is implied by Parse, and [Getters,Setters] is implied by New.

Regardless of traits used, the header offset addresses are defined, for instance:

#define FU_STRUCT_EXAMPLE_OFFSET_MAGIC 0x0
#define FU_STRUCT_EXAMPLE_OFFSET_HDRVER 0x10
#define FU_STRUCT_EXAMPLE_OFFSET_HDRSZ 0x11
#define FU_STRUCT_EXAMPLE_OFFSET_PAYLOADSZ 0x13
#define FU_STRUCT_EXAMPLE_OFFSET_FLAGS 0x17

Any elements defined as a typed array (e.g. [u8; 16]) will also have the element size defined in bytes:

#define FU_STRUCT_EXAMPLE_SIZE_MAGIC 0x10

If the default has been set (but not a constant value) the default is also defined:

#define FU_STRUCT_EXAMPLE_DEFAULT_HDRSZ 24

Finally, the size in bytes of the whole structure is also included:

#define FU_STRUCT_EXAMPLE_SIZE 0x18

NOTE: constants never have getters or setters defined — they’re constant after all. They are verified during _validate() and _parse() however.

Enums

There are traits that control the generation of enum code. These include:

  • ToString: for fu_example_family_to_string(), needed to create output
  • ToBitString: for fu_example_family_to_string(), needed to create output for bitfields
  • FromString: for fu_example_family_from_string(), needed to parse input

NOTE: Enums are defined as a native unsigned type, and should not be copied by reference without first casting to an integer of known width.