Skip to content

Commit ba96d2d

Browse files
filipleplefilipleple
authored
Merge pull request #1230 from Dasharo/capupd_update
docs/guides/capsule-update.md: update for V2
2 parents 93606fd + dc9ab51 commit ba96d2d

5 files changed

Lines changed: 102 additions & 60 deletions

File tree

‎docs/guides/capsule-update.md‎

Lines changed: 102 additions & 60 deletions
Original file line numberDiff line numberDiff line change
@@ -18,16 +18,16 @@ The following table describes which devices support Update Capsules
1818
and since which firmware release, if applicable. If a particular device isn't
1919
mentioned, it means that it doesn't support this update method.
2020

21-
| Manufacturer | Device | Starting with FW version |
22-
| ------------ | --------------- | ------------------------ |
23-
| Hardkernel | Odroid H4+ | v0.9.1 |
24-
| MSI | Z690-A PRO | v1.1.4 |
25-
| MSI | Z790-P PRO | v0.9.2 |
26-
| NovaCustom | 11th Gen series | v1.6.0 |
27-
| NovaCustom | 12th Gen series | v1.8.0 |
28-
| NovaCustom | 14th Gen series | v1.0.0 |
29-
| NovaCustom | NUC BOX | v0.9.0 |
30-
| Protectli | Vault VP66xx | v0.9.3 |
21+
| Manufacturer | Device | Starting with FW version | V2 starting with FW version |
22+
| ------------ | --------------- | ------------------------ | --------------------------- |
23+
| Hardkernel | Odroid H4+ | v0.9.1 | — |
24+
| MSI | Z690-A PRO | v1.1.4 | v1.1.7 |
25+
| MSI | Z790-P PRO | v0.9.2 | v0.9.5 |
26+
| NovaCustom | 11th Gen series | v1.6.0 | — |
27+
| NovaCustom | 12th Gen series | v1.8.0 | — |
28+
| NovaCustom | 14th Gen series | v1.0.0 | — |
29+
| NovaCustom | NUC BOX | v0.9.0 | — |
30+
| Protectli | Vault VP66xx | v0.9.3 | — |
3131

3232
## Prerequisites
3333

@@ -38,7 +38,7 @@ mentioned, it means that it doesn't support this update method.
3838
* _Storage device available from UEFI Shell_<br>
3939
Not all file-systems are available to UEFI, so not all storage devices and
4040
partition on them will be usable for the purpose of capsule updates. An
41-
ESP (EFI System Partition, where `EFI/` directory is located) is a good choice
41+
ESP (EFI System Partition, where `EFI/` directory is located) is a good choice
4242
because it should be always readable by UEFI.
4343
If you're running the UEFI Shell from a USB drive, this step is already
4444
covered - you can simply continue using the same USB drive.
@@ -50,17 +50,19 @@ mentioned, it means that it doesn't support this update method.
5050

5151
## What's preserved by an update
5252

53-
| Type | Notes |
54-
| ---- | ----- |
55-
| SMMSTORE | holds UEFI Variables such as [settings] or [boot order] |
56-
| ROMHOLE | only on MSI |
57-
| SMBIOS | unique data like serial number or UUID |
58-
| boot logo | [set by the user](logo-customization.md) |
59-
| GbE | unique Gigabit Ethernet configuration (MAC address) |
53+
| Type | Notes |
54+
| ---- | ----- |
55+
| SMMSTORE | holds UEFI Variables such as [settings] or [boot order] |
56+
| ROMHOLE | only on MSI |
57+
| SMBIOS | unique data like serial number or UUID |
58+
| boot logo | [set by the user](logo-customization.md) |
59+
| GbE | unique Gigabit Ethernet configuration (MAC address) |
60+
| RW_MRC_CACHE (V2-only) | RAM training cache |
61+
| RECOVERY_MRC_CACHE (V2-only) | recovery RAM training cache, a/a for recovery boot path |
6062

6163
Preservation is done as a best effort. However some firmware changes are
6264
expected (e.g., current custom logo can be too large for the new firmware),
63-
thus a failure to move data in some cases won’t necessarily abort an update.
65+
thus a failure to move data in some cases won't necessarily abort an update.
6466

6567
[settings]: ../dasharo-menu-docs/dasharo-system-features.md
6668
[boot order]: ../dasharo-menu-docs/boot-maintenance-mgr.md
@@ -73,39 +75,18 @@ thus a failure to move data in some cases won’t necessarily abort an update.
7375
all of the steps described here, so you should only need to follow this
7476
guide if fwupd is unsupported for your device.
7577

76-
!!! note
77-
78-
Out of [technical necessity](https://github.com/Dasharo/dasharo-issues/issues/1302),
79-
Intel Management Engine (Intel ME) must be HAP-disabled in order for
80-
firmware to process a capsule successfully. If you're sure that the
81-
supplied capsule is the correct one, but you keep getting this error:
82-
83-
```
84-
[FIRMWARE WARNING] Capsule updates are only supported while Intel ME is in HAP mode!
85-
CapsuleApp: failed to query capsule capability - Unsupported
86-
```
87-
88-
Then double-check that Intel ME is in `Disabled (HAP)` state in [the
89-
corresponding menu][me-menu] or switch it to that state before performing
90-
an update.
91-
92-
1. Copy `CapsuleApp.efi` and `firmware.cap` files to a partition (the shorter
78+
1. Copy `CapsuleApp.efi` and `firmware.cap` files to a partition (the shorter
9379
the path from the root, the easier it will be to find in the UEFI Shell).
9480

95-
2. See the note above about Intel ME and HAP-disable it if it's enabled or
96-
soft-disabled at the moment. An update won't be initiated if this isn't
97-
done (`CapsuleApp.efi` will make an effort and give up, so no harm other than
98-
update not happening).
99-
100-
3. Enter [Boot Manager Menu][bmm] and select `UEFI Shell` entry. Alternatively,
81+
2. Enter [Boot Manager Menu][bmm] and select `UEFI Shell` entry. Alternatively,
10182
if you're in Setup, use [One Time Boot][otb] which is a different way to do
10283
the same.
10384

104-
4. Press `Escape` to get to the prompt. In practice pressing any key works the
85+
3. Press `Escape` to get to the prompt. In practice pressing any key works the
10586
same in most cases, so no problem if you didn't make it in 5 seconds.
10687

107-
5. The first thing that UEFI Shell prints, even before the prompt with the
108-
timer, is the list of file systems and block devices (it can also be
88+
4. The first thing that UEFI Shell prints, even before the prompt with the
89+
timer, is the list of file systems and block devices (it can also be
10990
retrieved later by running `map` command):
11091
![Top of UEFI Shell](../images/uefi-shell-top.png)
11192
The hard part is to find the drive with `CapsuleApp.efi` and `firmware.cap`
@@ -115,38 +96,99 @@ thus a failure to move data in some cases won’t necessarily abort an update.
11596
Once the file-system is identified, run its name to switch to it:
11697
![Change file-system in UEFI Shell](../images/uefi-shell-cd-fs.png)
11798

118-
6. If files are in file-system's root, no need to do anything here. Otherwise,
99+
5. If files are in file-system's root, no need to do anything here. Otherwise,
119100
use `cd` command to open a target directory to not have to enter full paths:
120101
![Change directory in UEFI Shell](../images/uefi-shell-cd-dir.png)
121102

122-
7. Now you should be in a position to initiate a capsule update (run `ls` again
123-
if in doubt about current location) via `CapsuleApp.efi
124-
firmware.cap` (substitute `firmware.cap` with an actual file name):
125-
![Initiating a capsule update](../images/uefi-shell-capsule-app-posting.png)
103+
6. Now you should be in a position to initiate a capsule update (run `ls` again
104+
if in doubt about current location):
105+
106+
=== "Newer versions (V2)"
107+
108+
Run `CapsuleApp.efi firmware.cap -OD` (substitute `firmware.cap` with an
109+
actual file name; the `-OD` flag must come after the capsule file name):
110+
![Initiating a capsule update](../images/uefi-shell-capsule-app-posting.png)
111+
112+
=== "Older versions"
113+
114+
!!! note
115+
116+
Out of [technical necessity](https://github.com/Dasharo/dasharo-issues/issues/1302),
117+
Intel Management Engine (Intel ME) must be HAP-disabled in order for
118+
firmware to process a capsule successfully. If you're sure that the
119+
supplied capsule is the correct one, but you keep getting this error:
120+
121+
```
122+
[FIRMWARE WARNING] Capsule updates are only supported while Intel ME is in HAP mode!
123+
CapsuleApp: failed to query capsule capability - Unsupported
124+
```
125+
126+
Then double-check that Intel ME is in `Disabled (HAP)` state in [the
127+
corresponding menu][me-menu] or switch it to that state before performing
128+
an update.
129+
130+
Ensure Intel ME is [HAP-disabled][me-menu] if it's enabled or soft-disabled
131+
at the moment. An update won't be initiated if this isn't done
132+
(`CapsuleApp.efi` will make an effort and give up, so no harm other than
133+
update not happening).
134+
135+
Then run `CapsuleApp.efi firmware.cap` (substitute `firmware.cap` with an
136+
actual file name):
137+
![Initiating a capsule update](../images/uefi-shell-capsule-app-posting.png)
138+
139+
7. An ongoing firmware update with graphical progress bar looks like this:
126140

127-
8. An ongoing firmware update with graphical progress bar looks like this:
128-
![Ongoing capsule update](../images/uefi-capsule-update.png)
141+
=== "Newer versions (V2)"
142+
143+
![Ongoing capsule update](../images/uefi-capsule-update.png)
144+
145+
=== "Older versions"
146+
147+
![Ongoing capsule update](../images/uefi-capsule-update-v1.png)
129148

130149
!!! note
131150

132-
Protectli devices have a textual progress bar.
151+
Some releases use a textual progress bar by design. If you happen to
152+
be doing the update over serial console with no monitor plugged in, V2
153+
releases will also fall back to the textual mode over serial.
133154

134155
!!! warning
135156

136157
Don't reboot or power off the device until the process is completed!
137158

138-
After either a successful or failed update, the machine should reboot
139-
automatically. After that, if everything succeeded, you should have an updated
140-
firmware with data migrated from the previous version.
159+
=== "Newer versions (V2)"
141160

142-
!!! note
161+
After the update is complete, a results screen will be shown. On success:
143162

144-
Since the settings were preserved, remember to re-enable Intel Management
145-
Engine after the update.
163+
![Successful capsule update](../images/uefi-capsule-update-success.png)
164+
165+
On failure:
166+
167+
![Failed capsule update](../images/uefi-capsule-update-failure.png)
168+
169+
A failed update is followed by a recovery attempt, which is not guaranteed to
170+
succeed, but should leave the system bootable in most cases.
171+
172+
After a successful update, the machine will reboot automatically. After that,
173+
if everything succeeded, you should have an updated firmware with data migrated
174+
from the previous version. In the case of a failure, you will be prompted
175+
to press `Enter` to attempt reboot. After such reboot successfully restored
176+
previous firmware might boot, but it can't be guaranteed.
177+
178+
=== "Older versions"
179+
180+
After either a successful or failed update, the machine should reboot
181+
automatically. After that, if everything succeeded, you should have an updated
182+
firmware with data migrated from the previous version.
183+
184+
!!! note
185+
186+
Since the settings were preserved, remember to re-enable Intel Management
187+
Engine after the update.
146188

147-
[me-menu]: ../dasharo-menu-docs/dasharo-system-features.md#intel-management-engine-options
148189
[bmm]: ../dasharo-menu-docs/overview.md#boot-manager-menu
149190
[otb]: ../dasharo-menu-docs/overview.md#one-time-boot
191+
[me-menu]: ../dasharo-menu-docs/dasharo-system-features.md#intel-management-engine-options
150192

151193
## Version verification
152194

‎docs/images/uefi-capsule-update-failure.png‎

1.55 MB
Loading

‎docs/images/uefi-capsule-update-success.png‎

12.6 KB
Loading

‎docs/images/uefi-capsule-update-v1.png‎

57 KB
Loading

‎docs/images/uefi-capsule-update.png‎

77.7 KB
Loading

0 commit comments

Comments
 (0)