1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
|
---
title: Plugin: CFU - Component Firmware Update
---
## Introduction
CFU is a protocol from Microsoft to make it easy to install firmware on HID devices.
See <https://docs.microsoft.com/en-us/windows-hardware/drivers/cfu/cfu-specification> for more
details.
This plugin supports the following protocol ID:
* `com.microsoft.cfu`
## Implementation Notes
CFU has a pre-download phase that is used to send the firmware *offer* to the microcontroller, so the
device can check if the firmware is required and compatible.
CFU also requires devices to be able to transfer the entire new transfer mode in runtime mode.
The pre-download “offer” allows the device to check any sub-components attached (e.g. other devices
attached to the SoC) and forces it to do dependency resolution in case sub-components have to be
updated in a specific order.
Pushing the dependency resolution down to the device means the low-power device has to do all the
version comparisons and also know all the logic with regard to protocol incompatibilities.
The end-user could be in a position where the device firmware needs to be updated so that it “knows”
about the new protocol restrictions, which are needed to update the device and the things attached
in the right order in a subsequent update.
If the user always updates the device to the latest version, the factory-default running version
*might yet know* about the new restrictions.
It is therefore imperative that all previous versions are tested being updated *from*.
Something that we support in fwupd is being able to restrict the peripheral device firmware to a
specific SMBIOS CHID or a system firmware vendor, which lets vendors solve the *same hardware in
different chassis, with custom firmware* problem.
Using CFU in Microsoft Windows also means that the peripheral is unaware of the other devices in the
system, so for instance couldn’t only install a new firmware version for only new builds of Windows
for example.
A few other consideration for vendors is the doubling of flash storage required to do an runtime
transfer, the extra power budget of being woken up to process the *offer* and providing enough bulk
power to stay alive if *unplugged* during a A/B swap.
On most existing hardware the easiest way to implement CFU is an additional ARM micro-controller
to act as a CFU “bridge” for legacy silicon. The CFU “bridge” could also do signing and encryption.
CFU does not define any standard way to encrypt and sign firmware, or to detect if devices have any
firmware verification capabilities and so this too will need to be set per-device either in the
metadata or in the quirk file.
CFU also downloads in the runtime mode in the background, at a maximum of 52 bytes per HID request
and response.
This means even small updates will take a long time to complete due to the huge number of USB control
transfers required.
The specification also doesn't specify the HID reports to use, so it all needs to be hardcoded
per-device unless the exact same defaults are used as in `CFU/Tools/ComponentFirmwareUpdateStandAloneToolSample/protocolCfgExample.cfg`.
In fwupd these can be set as quirks in `cfu.quirk`.
The included `https://github.com/fwupd/fwupd/blob/main/contrib/cfu-inf-to-quirk.py` script may be
useful to convert an existing `.inf` file to fwupd `.quirk` format.
## Firmware Format
Due to the one-shot way fwupd deploys firmware, the daemon only deals with one “payload” per
update. The offer and payload currently have to be combined in an archive where they are
transferred to the device one after the other.
The files in the firmware archive therefore should have the extensions `.offer.bin` and `.payload.bin`.
## GUID Generation
These devices use standard USB DeviceInstanceId values, as well as two extra for the component ID
and the bank, e.g.
* `HIDRAW\VEN_17EF&DEV_7226&CID_01&BANK_1`
* `HIDRAW\VEN_17EF&DEV_7226&CID_01`
* `HIDRAW\VEN_17EF&DEV_7226`
## Quirk Use
This plugin uses the following plugin-specific quirks:
### CfuVersionGetReport
The HID report usage to use when parsing the response of `GET_FIRMWARE_VERSION`.
This usually corresponds to the `VersionsFeatureValueCapabilityUsageRangeMinimum` value
set in the `.inf` file.
Since: 1.9.1
### CfuOfferSetReport
The HID report usage to use when sending the request for `FIRMWARE_UPDATE_OFFER`.
This usually corresponds to the `OfferOutputValueCapabilityUsageRangeMinimum` value
set in the `.inf` file.
Since: 1.9.1
### CfuOfferGetReport
The HID report usage to use when parsing the response of `FIRMWARE_UPDATE_OFFER`.
This usually corresponds to the `OfferInputValueCapabilityUsageRangeMinimum` value
set in the `.inf` file.
Since: 1.9.1
### CfuContentSetReport
The HID report usage to use when sending the request for `FIRMWARE_UPDATE_CONTENT`.
This usually corresponds to the `PayloadOutputValueCapabilityUsageRangeMinimum` value
set in the `.inf` file.
Since: 1.9.1
### CfuContentGetReport
The HID report usage to use when parsing the response of `FIRMWARE_UPDATE_CONTENT`.
This usually corresponds to the `PayloadInputValueCapabilityUsageRangeMinimum` value
set in the `.inf` file.
Since: 1.9.1
## Update Behavior
The device has to support runtime updates and does not have a detach-into-bootloader mode -- but
after the install has completed the device still has to reboot into the new firmware.
## Vendor ID Security
The vendor ID is set from the USB vendor, in this instance set to `HIDRAW:0x17EF`
## External Interface Access
This plugin requires read/write access to `/dev/bus/usb`.
## Version Considerations
This plugin has been available since fwupd version `1.7.1`.
|
