mirror of
https://git.proxmox.com/git/fwupd
synced 2026-03-28 23:31:42 +00:00
7e38dffdcb
Systems with multiple host controllers will most likely have a different NVM image for each controller but there is no guarantee that the device_id within the NVM image varies from one controller to another. To account for this, build a GUID that contains the last element of the Thunderbolt controller's udev path. Sample GUID strings from an XPS 9380 (which only contains one host controller): ``` Guid: 0f401ed2-b847-532a-adc8-3193fc737be6 <- TBT-00d408af-native Guid: 420b0596-f5cb-5fd7-8416-c99d48ad8de9 <- TBT-00d408af-native-0000:05:00.0 ``` This commit follows the presumption that the kernel will enumerate the controllers in the same order every time.
83 lines
3.1 KiB
Markdown
83 lines
3.1 KiB
Markdown
Thunderbolt™ Support
|
|
====================
|
|
|
|
Introduction
|
|
------------
|
|
|
|
Thunderbolt™ is the brand name of a hardware interface developed by Intel that
|
|
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.
|
|
|
|
Firmware Format
|
|
---------------
|
|
|
|
The daemon will decompress the cabinet archive and extract a firmware blob in
|
|
an unspecified binary file format, with vendor specific header.
|
|
|
|
This plugin supports the following protocol ID:
|
|
|
|
* com.intel.thunderbolt
|
|
|
|
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.
|
|
|
|
Additionally for host system thunderbolt controllers another GUID is added
|
|
containing the PCI slot designation of the controller. This is intended to be
|
|
used for systems with multiple host controllers to disambiguiate between controllers.
|
|
|
|
* `TBT-$(vid)$(pid)-native-$(slot)`
|
|
|
|
Runtime Power Management
|
|
------------------------
|
|
|
|
Thunderbolt controllers are slightly unusual in that they power down completely
|
|
when no thunderbolt devices are detected. This poses a problem for fwupd as
|
|
it can't coldplug devices to see if there are firmware updates available, and
|
|
also can't ensure the controller stays awake during a firmware upgrade.
|
|
|
|
On Dell hardware the `Thunderbolt::CanForcePower` metadata value is set as the
|
|
system can force the thunderbolt controller on during coldplug or during the
|
|
firmware update process. This is typically done calling a SMI or ACPI method
|
|
which asserts the GPIO for the duration of the request.
|
|
|
|
On non-Dell hardware you will have to insert a Thunderbolt device (e.g. a dock)
|
|
into the laptop to be able to update the controller itself.
|
|
|
|
Safe Mode
|
|
---------
|
|
|
|
Thunderbolt hardware is also slightly unusual in that it goes into "safe mode"
|
|
whenever it encounters a critical firmware error, for instance if an update
|
|
failed to be completed. In this safe mode you cannot query the controller vendor
|
|
or model and therefore the thunderbolt plugin cannot add the correct GUID used
|
|
to match it to the correct firmware.
|
|
|
|
In this case the metadata value `Thunderbolt::IsSafeMode` is set which would
|
|
allow a different plugin to add the correct GUID based on some out-of-band
|
|
device discovery. At the moment this only happens on Dell hardware.
|
|
|
|
GUID generation for LVFS
|
|
------------------------
|
|
|
|
The GUID for the controller, which must appear in the metadata when uploading an
|
|
NVM to LVFS, can be generated by a tool like `appstream-util` (with
|
|
`generate-guid` command) or by Python (with
|
|
`uuid.uuid5(uuid.NAMESPACE_DNS, 'string')`).
|
|
|
|
The format of the string used as input is "TBT-vvvvdddd", where vvvvv is the
|
|
vendor ID and dddd is the device ID, both in hex, as appear in the controller's
|
|
DROM and exposed in the relevant sysfs attributes.
|
|
|
|
If the controller is in native enumeration mode, the string "-native" is added
|
|
at the end so the format is "TBT-vvvvdddd-native".
|