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
|
---
title: BOS DS20 Specification
---
## Introduction
When `fwupd` starts it enumerates all PCI and USB hardware and generates *Instance IDs* based on the reported vendor and product so that it can match the device to a plugin.
The plugin knows how to communicate with the device (for instance using vendor-specific USB control transfers) and also knows how to parse the firmware and deliver it to the device.
Before a vendor can ship a firmware on the LVFS to a machine using Linux (or ChromeOS) the fwupd package often must be updated so that it knows what plugin to use for that specific device.
At this point other overridden [quirk data](https://fwupd.github.io/libfwupdplugin/class.Quirks.html) can also be set. For instance, the icon, long summary or even per-plugin flags that change device behavior.
For example `colorhug.quirk`:
[USB\VID_273F&PID_1001]
Plugin = colorhug
Flags = self-recovery
Icon = colorimeter-colorhug
Updating the fwupd binary package might take anywhere from a few weeks to several years due to various Linux distribution policies.
Clearly this isn't good when the majority of firmware updates are distributed to address security issues.
One suggestion would be to put this quirk information into the existing update metadata provided by the configured remote, but this has several problems:
* The daemon needs to *enumerate* hardware that does not have updates on the main LVFS remote.
* A *lot* of machines using fwupd have never connected to the internet and we still want to enumerate hardware for audit and verification purposes.
* Re-enumerating all physical hardware (to get the latest quirks) when updating the metadata is not straightforward.
* The VID/PID is not necessarily the information that the plugin matches to assign the firmware stream, and so this would have to be a separate facet of metadata -- which may have to include quirks too.
Matching devices to plugins should be thought of as *orthogonal* to matching firmware to devices.
To simplify deployment it should be possible to allow the device itself to specify the plugin to use and optionally additional quirk data.
## Specification
Devices that implement a fwupd BOS DS20 descriptor can be updated without always needing to update the runtime version of fwupd for updated quirk entries, assuming the device is updatable by the existing vendor plugin.
USB devices can create a new platform device capability BOS *“Binary Object Store”* descriptor with `bDevCapabilityType=0x05` and a fwupd-specific UUID, specifically `010aec63-f574-52cd-9dda-2852550d94f0`.
This UUID is generated type-5 SHA-1 hash of the word `fwupd` using a DNS namespace.
Using this custom UUID will ensure that Microsoft Windows does not try to parse the capability descriptor as a *Microsoft OS 2.0 descriptor set*.
## Implementation
Create a BOS DS20 descriptor such as:
1C 10 05 00 63 ec 0a 01 74 f5 cd 52 9d da 28 52 55 0d 94 f0 0e 09 01 00 20 00 2a 00
├┘ ├┘ ├┘ ├┘ └─────────────┬───────────────────────────────┘ └─┬───────┘ └─┬─┘ ├┘ ├┘
│ │ │ │ └─PlatformCapabilityUUID │ wLength─┘ │ │
│ │ │ └─bReserved dwVersion─┘ bVendorCode─┘ │
│ │ └────bDevCapability bAltEnumCmd────┘
│ └───────bDescriptorType
└──────────bLength
The `dwVersion` encoded here is fwupd `1.9.14`, which is also the first version that with working BOS DS20 support.
The BOS descriptors are sorted by the requester and can appear in any order.
The descriptor with the highest `dwVersion` that is not newer than the current running daemon version is used.
This means that `dwVersion` is effectively the minimum version of fwupd that should read the descriptor.
This allows devices to set different quirks depending on the fwupd version, although in practice this should not be required.
A suitable bVendorCode should be chosen that is not used for existing device operation.
* The `dwVersion` parameter **must** be larger than `0x0001090e`, i.e. 1.9.14.
* The `bAltEnumCmd` parameter **must** be zero.
* The `PlatformCapabilityUUID` **must** be `010aec63-f574-52cd-9dda-2852550d94f0`.
Then allow the device to reply to a USB control request with the following parameters:
transfer-direction: device-to-host
request-type: vendor
recipient: device
bRequest: {value of bVendorCode in the BOS descriptor}
wValue: 0x00
wIndex: 0x07
wLength: {value of wLength in the BOS descriptor}
The device should return something like:
50 6c 75 67 69 6e 3d 64 66 75 0a 49 63 6f 6e 3d 63 6f 6d 70 75 74 65 72 0a 00 00 00 00 00 00 00
...which is the UTF-8 quirk data, e.g.
Plugin=dfu
Icon=computer
The UTF-8 quirk data must **not** contain Windows *CRLF-style* line endings.
## Workflow
To generate the fwupd DS20 descriptor save a file such as `fw-ds20.builder.xml`:
<firmware gtype="FuUsbDeviceFwDs20">
<idx>42</idx> <!-- bVendorCode -->
<size>32</size> <!-- wLength -->
</firmware>
Then run `fwupdtool firmware-build fw-ds20.builder.xml fw-ds20.bin`.
To generate the control transfer response, save a file such as `fw-ds20.quirk`:
[USB\VID_273F&PID_1004]
Plugin = dfu
Icon = computer
Then run `contrib/generate-ds20.py fw-ds20.quirk --bufsz 32`.
The maximum buffer size is typically hardcoded for the device and may be specified in a microcontroller datasheet.
## Prior Art
### Hardcoded Class & Subclass
The fwupd project already support two plugins that use the USB class code, rather than the exact instance ID with the VID/PID.
For example, this DFU entry means *“match any USB device with class 0xFE (application specific) and subclass 0x01”*:
[USB\CLASS_FE&SUBCLASS_01]
Plugin = dfu
These kind of devices do not need any device to plugin mapping (although, they still might need a quirk if they are non-complaint in some way, for example needing `Flags = detach-for-attach`) – but in the most cases they just work.
The same can be done for Fastboot devices, matching class `0xFF` (vendor specific), subclass `0x42` and protocol `0x03`, although there is the same caveat for non-compliant devices that need quirk entries like `FastbootOperationDelay = 250`:
[USB\CLASS_FF&SUBCLASS_42&PROT_03]
Plugin = fastboot
#### Microsoft OS Descriptors 1.0
The [Microsoft OS Descriptors 1.0 Specification](https://docs.microsoft.com/en-us/windows-hardware/drivers/usbcon/microsoft-os-1-0-descriptors-specification) defines a device-specific variable-length metadata block of `CompatibleID`:`SubCompatibleID` on a string index of `0xEE` where the `CompatibleID` and `SubCompatibleID` are also both hardcoded at 8 bytes.
Using `FWUPDPLU` or `FWUPDFLA` as the `CompatibleID` would be acceptable, but we could not fit the plugin name (e.g. `logitech-bulkcontroller`) or the GUID (16 bytes) in an 8 byte `SubCompatibleID`.
Some non-compliant devices also hang and stop working when probing this specific string index.
#### Microsoft OS Descriptors 2.0
The [Microsoft OS Descriptors 2.0 Specification](https://docs.microsoft.com/en-us/windows-hardware/drivers/usbcon/microsoft-os-2-0-descriptors-specification) is more useful as it defines a new device capability that can return a variable length vendor-defined section of data, using a UUID as a key.
Using the `BOS` *“Binary Object Store”* descriptor is only available for devices using USB specification version 2.1 and newer.
The BOS descriptor is used for Wireless USB details, USB 2.0 extensions, SuperSpeed USB connection details and a Container ID.
The BOS descriptor does give the OS the ability to parse the platform capability, which is `bDevCapabilityType=0x05`. For UUID `D8DD60DF-4589-4CC7-9CD2-659D9E648A9F` this is identified as a structured blob of data Microsoft Windows uses for the suspend mode of the device.
Creating a new `bDevCapabilityType` would allow vendors to store a binary blob (e.g. `Plugin=foobarbaz\nFlags=QuirkValueHere\n`) but that would be out-of-specification and difficult to implement.
|
