Bundling/Updating multiple images

[Sanjay Sheth]

We have multiple firmware files (e.g. to update Audio module, to update Video module etc). How do we bundle these separate .bin files into single firmware.bin?
Also at runtime we want to query version of these independent (Audio/Video) modules, and update firmware only if needed. How do we extract these desired firmware file?

[Richard Hughes]

Hi Sanjay,

On Tue, 17 May 2022 at 07:50, Sanjay Sheth <ssh...@logitech.com> wrote:
> We have multiple firmware files (e.g. to update Audio module, to update Video module etc). How do we bundle these separate .bin files into single firmware.bin?

There are two ways to do this -- if you have multiple devices (or
subdevices) with different GUIDs then you would have something like
this for ONE physical USB device:

- Device 1:
| - InstanceID: USB\VID_1234&PID_5678&TYPE=video
| - Version: 1.2.3
\ Device 2 (virtual audio subcomponent):
- InstanceID: USB\VID_1234&PID_5678&TYPE=audio
- Version: 11.22.33

Then you would have four files in the firmware.cab file:
- dev1-firmware.bin
- dev2-firmware.bin
- dev1.metainfo.xml (referencing the GUID that's formed from
USB\VID_1234&PID_5678&TYPE=video)
- dev2.metainfo.xml (referencing the GUID that's formed from
USB\VID_1234&PID_5678&TYPE=audio)

Then if you asked fwupd to install firmware.cab then fwupd would look
at both XML files, find both devices, compare their versions and then
order them according to their priority (typically child, then parent,
but that can be reversed with a quirk), then install dev2 and then
install dev1.

The other way of doing this is a composite device:

Device:
InstanceID: USB\VID_1234&PID_5678
Version: 11.2.34

And then you package up the firmware into a zip file, so you have in
the firmware.cab file:
- dev-firmware.zip (containing dev1-firmware.bin and dev2-firmware.bin)
- dev.metainfo.xml (referencing the GUID that's formed from
USB\VID_1234&PID_5678)

...and then the plugin has to _know_ how to parse the dev-firmware.zip
(using FuArchiveFirmware perhaps) and also has to know how to map the
firmware filename inside the archive to the specific part of the
composite device.

The drawback in the second is that both components have to share a
version number, but the advantage is there is only one device and only
one "deliverable" where the versions can't get "out of sync". In fwupd
we have both kinds, e.g. a fingerprint reader might have a main
firmware and a config subdevice (with different firmware versions) and
a modem might have one composite device, but with about half a dozen
"partitions" that get extracted out of an archive.

> Also at runtime we want to query version of these independent (Audio/Video) modules, and update firmware only if needed. How do we extract these desired firmware file?

For separate versions you want multiple devices for the same physical
device. The only thing to keep in mind is that although the different
sub-devices can share a physical ID (e.g. the USB connection) they
need different logical IDs. So for instance, a Logitech mouse has one
parent device with a physical address set, and no logical ID, and the
radio component in the mouse has the same physical ID and a logical ID
of "radio". When the child radio is added to the parent the logical
and physical IDs get hashed together so that each has a unique
device-id and therefore they can be updated separately if needed.

I guess my preference is multiple devices over the archive solution,
but it's really your choice.

Richard

[Sanjay Sheth]

Thanks Richard, that clarifies. We are developing new plugin for Webcams. They are composite device with single PID, but has independent firmware files. Would you please provide pointers to both of those plugins (fingerprint reader, modem). Also share LVFS repo/doc details for these plugins to understand metainfo.xml.

[Richard Hughes]

On Tue, 17 May 2022 at 19:26, Sanjay Sheth <ssh...@logitech.com> wrote:
> Would you please provide pointers to both of those plugins (fingerprint reader, modem).

I guess one that uses an archive would be
https://github.com/fwupd/fwupd/blob/main/plugins/nordic-hid/fu-nordic-hid-archive.c
or https://github.com/fwupd/fwupd/blob/main/plugins/modem-manager/fu-mm-device.c#L1000
-- the former possibly easier to understand.

For the different devices, e.g. a virtual child device, then something
like https://github.com/fwupd/fwupd/blob/main/plugins/synaptics-prometheus/fu-synaprom-device.c#L231
would be a good example to follow.

> Also share LVFS repo/doc details for these plugins to understand metainfo.xml.

I think https://lvfs.readthedocs.io/en/latest/metainfo.html#composite-hardware
is the link you want.

Richard.