From ba2f0ae1d4f55bbb349971b44ee3d3c2b3774b7e Mon Sep 17 00:00:00 2001 From: Richard Hughes Date: Thu, 8 Nov 2018 17:12:31 +0000 Subject: [PATCH] trivial: Document the GUID generation scheme Fixes https://github.com/hughsie/fwupd/issues/837 --- plugins/altos/README.md | 9 +++++++++ plugins/amt/README.md | 5 +++++ plugins/colorhug/README.md | 9 +++++++++ plugins/dell-dock/README.md | 12 ++++++++++++ plugins/dell-esrt/README.md | 5 +++++ plugins/dell/README.md | 10 ++++++++++ plugins/dfu/README.md | 9 +++++++++ plugins/ebitdo/README.md | 9 +++++++++ plugins/flashrom/README.md | 7 +++++++ plugins/nitrokey/README.md | 9 +++++++++ plugins/nvme/README.md | 16 ++++++++++++++++ plugins/redfish/README.md | 6 ++++++ plugins/rts54hid/README.md | 13 +++++++++++++ plugins/rts54hub/README.md | 8 ++++++++ plugins/steelseries/README.md | 9 +++++++++ plugins/superio/README.md | 7 +++++++ plugins/synapticsmst/README.md | 10 ++++++++++ plugins/test/README.md | 6 ++++++ plugins/thunderbolt/README.md | 12 ++++++++++++ plugins/udev/README.md | 9 +++++++++ plugins/uefi/README.md | 9 +++++++++ plugins/unifying/README.md | 14 ++++++++++++++ plugins/wacomhid/README.md | 9 +++++++++ 23 files changed, 212 insertions(+) diff --git a/plugins/altos/README.md b/plugins/altos/README.md index 4b3a3c272..d683807ed 100644 --- a/plugins/altos/README.md +++ b/plugins/altos/README.md @@ -15,6 +15,15 @@ The bootloader communication is not handled in the kernel, and a tty device is created so userspace can communicate with the hardware. Commands the bootloader accept are as follows: +GUID Generation +--------------- + +These devices use the standard USB DeviceInstanceId values, e.g. + + * `USB\VID_1D50&PID_60C6&REV_0001` + * `USB\VID_1D50&PID_60C6` + * `USB\VID_1D50` + ### List Information Command: `l\n` diff --git a/plugins/amt/README.md b/plugins/amt/README.md index 4a053b229..5494815a4 100644 --- a/plugins/amt/README.md +++ b/plugins/amt/README.md @@ -15,3 +15,8 @@ which can be found here: https://github.com/mjg59/mei-amt-check That tool in turn is heavily based on mei-amt-version from samples/mei in the Linux source tree and copyright Intel Corporation. + +GUID Generation +--------------- + +These devices use the existing GUID provided by the AMT host interface. diff --git a/plugins/colorhug/README.md b/plugins/colorhug/README.md index 06eae25d1..867d03dae 100644 --- a/plugins/colorhug/README.md +++ b/plugins/colorhug/README.md @@ -10,3 +10,12 @@ accurate color matching. ColorHug versions 1 and 2 support a custom HID-based flashing protocol, but version 3 (ColorHug+) has now switched to DFU. + +GUID Generation +--------------- + +These devices use the standard USB DeviceInstanceId values, e.g. + + * `USB\VID_273F&PID_1001&REV_0001` + * `USB\VID_273F&PID_1001` + * `USB\VID_273F` diff --git a/plugins/dell-dock/README.md b/plugins/dell-dock/README.md index 101ba4332..d896717a4 100644 --- a/plugins/dell-dock/README.md +++ b/plugins/dell-dock/README.md @@ -4,6 +4,18 @@ Dell USB-C Dock ### Dell System Unlike previous Dell USB-C devices, a Dell system is not needed for updating. +GUID Generation +--------------- + +These devices use several different generation schemes, e.g. + + * USB Hub1: `USB\VID_413C&PID_B06F&hub` + * USB Hub2: `USB\VID_413C&PID_B06E&hub` + * Embedded Controller: `USB\VID_413C&PID_B06E&hub&embedded` + * Update Level: `USB\VID_413C&PID_B06E&hub&status` + * MST Hub: `MST-panamera-vmm5331-259` + * Thunderbolt Controller: `TBT-00d4b070` + ### Components The device contains components the following directly updatable components: * USB hubs diff --git a/plugins/dell-esrt/README.md b/plugins/dell-esrt/README.md index 0a0f9dd68..797558a14 100644 --- a/plugins/dell-esrt/README.md +++ b/plugins/dell-esrt/README.md @@ -7,6 +7,11 @@ Introduction This allows enabling the BIOS setup option for UEFI capsule updates without manually going into BIOS setup. +GUID Generation +--------------- + +These device uses a hardcoded GUID of `2d47f29b-83a2-4f31-a2e8-63474f4d4c2e`. + Build Requirements ------------------ diff --git a/plugins/dell/README.md b/plugins/dell/README.md index 292b64688..eb54bcfa0 100644 --- a/plugins/dell/README.md +++ b/plugins/dell/README.md @@ -6,6 +6,16 @@ Introduction This allows installing Dell capsules that are not part of the ESRT table. +GUID Generation +--------------- + +These devices uses custom GUIDs for Dell-specific hardware. + + * Thunderbolt devices: `TBT-0x00d4u$(system-id)` + * TPM devices `$(system-id)-$(mode)`, where `mode` is either `2.0` or `1.2` + +In both cases the `system-id` is derived from the SMBIOS Product SKU property. + Build Requirements ------------------ diff --git a/plugins/dfu/README.md b/plugins/dfu/README.md index 4a408f90a..5a8e5d90d 100644 --- a/plugins/dfu/README.md +++ b/plugins/dfu/README.md @@ -6,3 +6,12 @@ Introduction Device Firmware Update is a standard that allows USB devices to be easily and safely updated by any operating system. + +GUID Generation +--------------- + +These devices use the standard USB DeviceInstanceId values, e.g. + + * `USB\VID_273F&PID_1003&REV_0001` + * `USB\VID_273F&PID_1003` + * `USB\VID_273F` diff --git a/plugins/ebitdo/README.md b/plugins/ebitdo/README.md index 8fe729bcd..157e77623 100644 --- a/plugins/ebitdo/README.md +++ b/plugins/ebitdo/README.md @@ -11,3 +11,12 @@ library and is possible thanks to the vendor open sourcing the flashing tool. The 8Bitdo devices share legacy USB VID/PIDs with other projects and so we have to be a bit careful to not claim other devices as our own. + +GUID Generation +--------------- + +These devices use the standard USB DeviceInstanceId values, e.g. + + * `USB\VID_2DC8&PID_AB11&REV_0001` + * `USB\VID_2DC8&PID_AB11` + * `USB\VID_2DC8` diff --git a/plugins/flashrom/README.md b/plugins/flashrom/README.md index 4df977c38..a65bc9104 100644 --- a/plugins/flashrom/README.md +++ b/plugins/flashrom/README.md @@ -5,3 +5,10 @@ Introduction ------------ This plugin uses `flashrom` to update the system firmware. + +GUID Generation +--------------- + +These device uses hardware ID values which are derived from SMBIOS. They should +match the values provided by `fwupdtool hwids` or the `ComputerHardwareIds.exe` +Windows utility. diff --git a/plugins/nitrokey/README.md b/plugins/nitrokey/README.md index fa01fd052..df0151ea9 100644 --- a/plugins/nitrokey/README.md +++ b/plugins/nitrokey/README.md @@ -10,3 +10,12 @@ available from the vendor. The device is switched to a DFU bootloader only when the secret firmware pin is entered into the nitrokey-app tool. This cannot be automated. + +GUID Generation +--------------- + +These devices use the standard USB DeviceInstanceId values, e.g. + + * `USB\VID_20A0&PID_4109&REV_0001` + * `USB\VID_20A0&PID_4109` + * `USB\VID_20A0` diff --git a/plugins/nvme/README.md b/plugins/nvme/README.md index dd189dea0..ca6685d8c 100644 --- a/plugins/nvme/README.md +++ b/plugins/nvme/README.md @@ -10,3 +10,19 @@ firmware file. Firmware is sent in 4kB chunks and activated on next reboot. The device GUID is read from the vendor specific area and if not found then generated from the trimmed model string. + +GUID Generation +--------------- + +These device use the NVMe DeviceInstanceId values, e.g. + + * `NVME\VEN_1179&DEV_010F&REV_01` + * `NVME\VEN_1179&DEV_010F` + * `NVME\VEN_1179` + +Additionally, for NVMe drives with Dell vendor firmware two extra GUIDs are +added: + + * `STORAGE-DELL-${component-id}` + +and any optional GUID saved in the vendor extension block. diff --git a/plugins/redfish/README.md b/plugins/redfish/README.md index a27563599..217a42151 100644 --- a/plugins/redfish/README.md +++ b/plugins/redfish/README.md @@ -10,6 +10,12 @@ simple and secure management of modern scalable platform hardware. By specifying a RESTful interface and utilizing JSON and OData, Redfish helps customers integrate solutions within their existing tool chains. +GUID Generation +--------------- + +These devices use the provided GUID provided in the `SoftwareId` parameter +without modification. Devices without GUIDs are not supported. + Setting Service IP Manually --------------------------- diff --git a/plugins/rts54hid/README.md b/plugins/rts54hid/README.md index 835dc9b29..9ea488829 100644 --- a/plugins/rts54hid/README.md +++ b/plugins/rts54hid/README.md @@ -10,3 +10,16 @@ device using the HUB update protocol. Other devices connected to the RTS54HIDxx using I2C will be supported soon. +GUID Generation +--------------- + +These devices use the standard USB DeviceInstanceId values, e.g. + + * `USB\VID_0BDA&PID_1100&REV_0001` + * `USB\VID_0BDA&PID_1100` + * `USB\VID_0BDA` + +Child I²C devices are created using the device number as a suffix, for instance: + + * `USB\VID_0BDA&PID_1100&I2C_01` + diff --git a/plugins/rts54hub/README.md b/plugins/rts54hub/README.md index 85c3e3d91..dd17cbc5a 100644 --- a/plugins/rts54hub/README.md +++ b/plugins/rts54hub/README.md @@ -10,3 +10,11 @@ device using the HID update protocol. Other devices connected to the RTS54xx using I2C will be supported soon. +GUID Generation +--------------- + +These devices use the standard USB DeviceInstanceId values, e.g. + + * `USB\VID_0BDA&PID_5423&REV_0001` + * `USB\VID_0BDA&PID_5423` + * `USB\VID_0BDA` diff --git a/plugins/steelseries/README.md b/plugins/steelseries/README.md index 314feffef..1266c6f6d 100644 --- a/plugins/steelseries/README.md +++ b/plugins/steelseries/README.md @@ -7,3 +7,12 @@ Introduction This plugin is used to get the correct version number on SteelSeries gaming mice. These mice have updatable firmware but so far no updates are available from the vendor. + +GUID Generation +--------------- + +These devices use the standard USB DeviceInstanceId values, e.g. + + * `USB\VID_1038&PID_1702&REV_0001` + * `USB\VID_1038&PID_1702` + * `USB\VID_1038` diff --git a/plugins/superio/README.md b/plugins/superio/README.md index c6c89f002..3be1ae935 100644 --- a/plugins/superio/README.md +++ b/plugins/superio/README.md @@ -20,3 +20,10 @@ Other useful links: * https://github.com/coreboot/coreboot/blob/master/util/superiotool/superiotool.h * https://github.com/flashrom/flashrom/blob/master/it85spi.c * http://wiki.laptop.org/go/Ec_specification + +GUID Generation +--------------- + +These devices use a custom GUID generated using the SuperIO chipset name: + + * `SuperIO-$(chipset)`, for example `SuperIO-IT8512` diff --git a/plugins/synapticsmst/README.md b/plugins/synapticsmst/README.md index e50a7c996..b32fa46b1 100644 --- a/plugins/synapticsmst/README.md +++ b/plugins/synapticsmst/README.md @@ -3,6 +3,16 @@ This plugin supports querying and flashing Synaptics MST hubs used in Dell systems and docks. +GUID Generation +--------------- + +These devices use custom GUID values, e.g. + + * `MST-$(device_kind)-$(chip-ID)-$(board-ID)` + +Please refer to the plugin source for more details about how the GUID is +constructed for specific hardware. + ## Requirements ### (Kernel) DP Aux Interface Kernel 4.6 introduced an DRM DP Aux interface for manipulation of the registers diff --git a/plugins/test/README.md b/plugins/test/README.md index bef15c829..4c8891cfb 100644 --- a/plugins/test/README.md +++ b/plugins/test/README.md @@ -5,3 +5,9 @@ Introduction ------------ This plugin is used when running the self tests in the fwupd project. + +GUID Generation +--------------- + +The devices created by this plugin use hardcoded GUIDs that do not correspond +to any kind of DeviceInstanceId values. diff --git a/plugins/thunderbolt/README.md b/plugins/thunderbolt/README.md index 5ceeca54d..7757f5b1d 100644 --- a/plugins/thunderbolt/README.md +++ b/plugins/thunderbolt/README.md @@ -9,6 +9,18 @@ allows the connection of external peripherals to a computer. Versions 1 and 2 use the same connector as Mini DisplayPort (MDP), whereas version 3 uses USB Type-C. +GUID Generation +--------------- + +These devices use a custom GUID generation scheme. +When the device is in "safe mode" the GUID is hardcoded using: + + * `TBT-safemode` + +... and when in runtime mode the GUID is: + + * `TBT-$(vid)$(pid)-native` when native, and `TBT-$(vid)$(pid)` otherwise. + Runtime Power Management ------------------------ diff --git a/plugins/udev/README.md b/plugins/udev/README.md index cf254bc4e..994769762 100644 --- a/plugins/udev/README.md +++ b/plugins/udev/README.md @@ -10,3 +10,12 @@ require booting into another operating system to apply. This plugin is also able to read and parse the firmware of some PCI devices which allows some host state verification to be done. + +GUID Generation +--------------- + +These devices use the standard USB DeviceInstanceId values, e.g. + + * `PCI\VEN_%04X&DEV_%04X` + +Additionally, GUIDs found in OptionROMs may also be added. diff --git a/plugins/uefi/README.md b/plugins/uefi/README.md index c005abf7f..7082bc9eb 100644 --- a/plugins/uefi/README.md +++ b/plugins/uefi/README.md @@ -11,6 +11,15 @@ With the UpdateCapsule boot service it can be used to update system firmware. If you don't want or need this functionality you can use the `-Dplugin_uefi=false` option. +GUID Generation +--------------- + +These devices use the UEFI GUID as provided in the ESRT. Additionally, for the +system device the `main-system-firmware` GUID is also added. + +For compatibility with Windows 10, the plugin also adds GUIDs of the form +`UEFI\RES_{$(esrt)}`. + UEFI Unlock Support ------------------- diff --git a/plugins/unifying/README.md b/plugins/unifying/README.md index 94c255d13..e724da15d 100644 --- a/plugins/unifying/README.md +++ b/plugins/unifying/README.md @@ -16,6 +16,20 @@ supplied by Logitech. Additional constants were taken from the Solaar[2] project. +GUID Generation +--------------- + +These devices use the standard USB DeviceInstanceId values when in DFU mode: + + * `USB\VID_046D&PID_AAAA&REV_0001` + * `USB\VID_046D&PID_AAAA` + * `USB\VID_046D` + +When in runtime mode, the HID raw DeviceInstanceId values are used: + + * `HIDRAW\VEN_046D&DEV_C52B` + * `HIDRAW\VEN_046D` + Design Notes ------------ diff --git a/plugins/wacomhid/README.md b/plugins/wacomhid/README.md index 69758aff2..8e01ec53b 100644 --- a/plugins/wacomhid/README.md +++ b/plugins/wacomhid/README.md @@ -15,3 +15,12 @@ Wacom devices are actually composite devices, with the main ARM CPU being programmed using a more complicated erase, write, verify algorithm based on a historical update protocol. The "sub-module" devices use a newer protocol, again based on HID, but are handled differently depending on thier type. + +GUID Generation +--------------- + +These devices use the standard USB DeviceInstanceId values, e.g. + + * `USB\VID_056A&PID_0378&REV_0001` + * `USB\VID_056A&PID_0378` + * `USB\VID_056A`