trivial: Add extra documentation for Dell provider

2025-08-03 21:35:58 +00:00 · 2016-07-20 11:30:33 -05:00 · 2016-07-20 11:30:33 -05:00 · 21a09f09fa
commit 21a09f09fa
parent 09e2630a59
1 changed files with 146 additions and 0 deletions
--- a/docs/dell-provider.md
+++ b/docs/dell-provider.md
@ -0,0 +1,146 @@
+
+# Devices powered by the Dell Provider
+The Dell provider creates device nodes for PC's that have switchable TPMs as
+well as the Type-C docks (WD15/TB15).
+
+These device nodes can be flashed using UEFI capsule (and fwupdate) but don't
+use the ESRT table to communicate device status or version information.
+
+This is intentional behavior because more complicated decisions need to be made
+on the OS side to determine if the devices should be offered to flash.
+
+## Switchable TPM Devices
+Machines with switchable TPMs can operate in both TPM 1.2 and TPM 2.0 modes.
+Switching modes will require flashing an alternative firmware and clearing the
+contents of the TPM.
+
+Machines that offer this functionality will display two devices in
+```# fwupdmgr get-devices``` output.
+
+Example (from a *Precision 5510*):
+```
+Precision 5510 TPM 1.2
+  Guid:                 b2088ba1-51ae-514e-8f0a-64756c6e4ffc
+  DeviceID:             DELL-b2088ba1-51ae-514e-8f0a-64756c6e4ffclu
+  Provider:             Dell
+  Flags:                internal|allow-offline|require-ac
+  Version:              5.81.0.0
+  FlashesLeft:          127
+  Created:              2016-07-19
+
+Precision 5510 TPM 2.0
+  Guid:                 475d9bbd-1b7a-554e-8ca7-54985174a962
+  DeviceID:             DELL-475d9bbd-1b7a-554e-8ca7-54985174a962lu
+  Provider:             Dell
+  Flags:                internal|require-ac|locked
+  Created:              2016-07-19
+```
+
+In this example, the TPM is currently operating in **TPM 1.2 mode**.  Any
+firmware updates posted to *LVFS* for TPM 1.2 mode will be applied as long as
+the remaining flash counter is greater than 0.
+
+### Switching TPM Modes
+In order to be offered to switch the TPM to **TPM 2.0 mode**, the virtual device
+representing the *TPM 2.0 mode* will need to be unlocked.
+
+```# fwupdmgr unlock DELL-475d9bbd-1b7a-554e-8ca7-54985174a962lu```
+
+If the TPM is currently *owned*, an error will be displayed such as this one:
+
+	ERROR: Precision 5510 TPM 1.2 is currently OWNED. Ownership must be removed to switch modes.
+
+TPM Ownership can be cleared from within the BIOS setup menus.
+
+If the unlock process was successful, then the devices will be modified:
+```
+Precision 5510 TPM 1.2
+  Guid:                 b2088ba1-51ae-514e-8f0a-64756c6e4ffc
+  DeviceID:             DELL-b2088ba1-51ae-514e-8f0a-64756c6e4ffclu
+  Provider:             Dell
+  Flags:                internal|require-ac
+  Version:              5.81.0.0
+  FlashesLeft:          127
+  Created:              2016-07-19
+
+Precision 5510 TPM 2.0
+  Guid:                 475d9bbd-1b7a-554e-8ca7-54985174a962
+  DeviceID:             DELL-475d9bbd-1b7a-554e-8ca7-54985174a962lu
+  Provider:             Dell
+  Flags:                internal|allow-offline|require-ac
+  Version:              0.0.0.0
+  FlashesLeft:          127
+  Created:              2016-07-19
+  Modified:             2016-07-19
+```
+
+Now the firmware for TPM 2.0 mode can be pulled down from LVFS and flashed:
+
+```# fwupdmgr update```
+
+Upon the next reboot, the new TPM firmware will be flashed.  If the firmware is
+*not offered from LVFS*, then switching modes may not work on this machine.
+
+After updating the output from ```# fwupdmgr get-devices```  will reflect the
+new mode.
+
+```
+Precision 5510 TPM 2.0
+  Guid:                 475d9bbd-1b7a-554e-8ca7-54985174a962
+  DeviceID:             DELL-475d9bbd-1b7a-554e-8ca7-54985174a962lu
+  Provider:             Dell
+  Flags:                internal|allow-offline|require-ac
+  Version:              1.3.0.1
+  FlashesLeft:          126
+  Created:              2016-07-20
+
+Precision 5510 TPM 1.2
+  Guid:                 b2088ba1-51ae-514e-8f0a-64756c6e4ffc
+  DeviceID:             DELL-b2088ba1-51ae-514e-8f0a-64756c6e4ffclu
+  Provider:             Dell
+  Flags:                internal|require-ac|locked
+  FlashesLeft:          126
+  Created:              2016-07-20
+```
+
+Keep in mind that **TPM 1.2** and **TPM 2.0** will require different userspace
+tools.
+
+## Dock Devices
+The *TB15* and *WD15* have a variety of updatable components.  Each component
+will create a virtual device in ```# fwupdmgr get-devices```
+
+For example the WD15 will display these components:
+```
+Dell WD15 Port Controller 1
+  Guid:                 8ba2b709-6f97-47fc-b7e7-6a87b578fe25
+  DeviceID:             DELL-8ba2b709-6f97-47fc-b7e7-6a87b578fe25lu
+  Provider:             Dell
+  Flags:                allow-offline|require-ac
+  Version:              0.1.1.8
+  Created:              2016-07-19
+
+Dell WD15 MST Hub
+  Guid:                 7bee2a28-b909-540d-9fa9-6a4c9611d992
+  DeviceID:             DELL-7bee2a28-b909-540d-9fa9-6a4c9611d992lu
+  Provider:             Dell
+  Flags:                require-ac
+  Created:              2016-07-19
+
+Dell WD15
+  Guid:                 e7ca1f36-bf73-4574-afe6-a4ccacabf479
+  DeviceID:             DELL-e7ca1f36-bf73-4574-afe6-a4ccacabf479lu
+  Provider:             Dell
+  Flags:                allow-offline|require-ac
+  Version:              0.0.0.67
+  Created:              2016-07-19
+```
+
+Components that can be updated via UEFI capsule will have the
+```allow-offline``` moniker applied.
+
+These updates can be performed the standard method of using:
+```# fwupdmgr update```
+
+Some components are not currently updatable by fwupd such as multi stream
+transport hub and thunderbolt NVM.