mirror of
https://git.proxmox.com/git/fwupd
synced 2025-07-27 09:25:38 +00:00
078beafb2d
It is far too easy to forget to set FWUPD_DEVICE_FLAG_NO_GUID_MATCHING for new
plugins, and without it it all works really well *until* a user has two devices
of the same type installed at the same time and then one 'disappears' for hard
to explain reasons. Typically we only need it for replug anyway!
Explicitly opt-in to this rarely-required behaviour, with the default to just
use the physical and logical IDs. Also document the update behavior for each
plugin to explain why the flag is being used.
This allows you to have two identical Unifying plugged in without one of them
being hidden from the user, at the same time allowing a HIDRAW<->USB transition
when going to and from bootloader and runtime modes.
This removes the workaround added in 99eb3f06b6.
Fixes https://github.com/fwupd/fwupd/issues/2915
114 lines
4.1 KiB
Markdown
114 lines
4.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 domain designation of the controller. This is intended to be
|
|
used for systems with multiple host controllers to disambiguiate between controllers.
|
|
|
|
* `TBT-$(vid)$(pid)-native-controller$(num)`
|
|
|
|
For retimers the only GUID created is as follows:
|
|
* `TBT-$(vid)$(pid)-retimer$index`
|
|
|
|
The retimer index is oriented around the physical connection within
|
|
the machine. It is important as multiple controllers may otherwise
|
|
identify identically.
|
|
|
|
Update Behavior
|
|
---------------
|
|
|
|
For most devices the firmware is written to the device at runtime and the
|
|
update is applied immediately. Once complete the controller may reboot
|
|
which may cause all connected USB and TBT devices to be reenumerated.
|
|
|
|
For some devices and circumstances (such as the Dell WD19 with a new enough
|
|
kernel) the device will remain functional for the duration of the update.
|
|
The update will complete on unplug.
|
|
|
|
If a user sets `DelayedActivation` configuration option then the update will
|
|
be staged but not completed until `activate` is separately called such as at
|
|
logout or shutdown.
|
|
|
|
Vendor ID Security
|
|
------------------
|
|
|
|
The vendor ID is set from the udev vendor, for example set to `TBT:0x$(vid)`
|
|
|
|
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".
|
|
|
|
External interface access
|
|
-------------------------
|
|
This plugin requires read/write access to `/sys/bus/thunderbolt`.
|