trivial: Document the GUID generation scheme

Fixes https://github.com/hughsie/fwupd/issues/837

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`

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.

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`

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

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
 ------------------
 

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
 ------------------
 

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`

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`

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.

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`

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.

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
 ---------------------------
 

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`
+

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`

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`

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`

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

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.

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
 ------------------------
 

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.

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
 -------------------
 

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
 ------------
 

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`