From 21a09f09fa373daba812a2b5324af9dce29322d9 Mon Sep 17 00:00:00 2001 From: Mario Limonciello Date: Wed, 20 Jul 2016 11:30:33 -0500 Subject: [PATCH] trivial: Add extra documentation for Dell provider --- docs/dell-provider.md | 146 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 146 insertions(+) create mode 100644 docs/dell-provider.md diff --git a/docs/dell-provider.md b/docs/dell-provider.md new file mode 100644 index 000000000..e76f1a8cd --- /dev/null +++ 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.