File site/docs/uboot/uboot-x86.md added (mode: 100644) (index 0000000..53bd8ed) |
|
1 |
|
--- |
|
2 |
|
title: U-Boot payload (x86 specific) |
|
3 |
|
x-toc-enable: true |
|
4 |
|
... |
|
5 |
|
|
|
6 |
|
Introduction |
|
7 |
|
============ |
|
8 |
|
|
|
9 |
|
U-Boot is available as a coreboot payload, in Libreboot 20241205 and later, |
|
10 |
|
on x86 boards; on ARM it has been available since late 2022 Libreboot releases. |
|
11 |
|
|
|
12 |
|
Please read <https://www.u-boot.org/>, especially the full U-Boot documentation |
|
13 |
|
available there. |
|
14 |
|
|
|
15 |
|
**NOTE: This documentation refers only to x86. For ARM, please refer back to |
|
16 |
|
the [main U-Boot page](index.md).** |
|
17 |
|
|
|
18 |
|
More documentation about this will be written at a later date, but just before |
|
19 |
|
the Libreboot 20241205 release in December 2024, U-Boot support was added as |
|
20 |
|
a payload on x86 machines, both 32- and 64-bit. This is using the excellent work |
|
21 |
|
done by Simon Glass and others, on making U-Boot run as a generic x86 coreboot |
|
22 |
|
payload. It has several boot methods but the most interesting (in an x86 |
|
23 |
|
context) is UEFI. U-Boot provides a very sensible UEFI implementation that can |
|
24 |
|
reliably boot many Linux and BSD systems. |
|
25 |
|
|
|
26 |
|
Availability |
|
27 |
|
------------ |
|
28 |
|
|
|
29 |
|
Do this in lbmk.git (Libreboot's build system) to check whether your board has |
|
30 |
|
U-Boot enabled: |
|
31 |
|
|
|
32 |
|
git grep payload_uboot_amd64 |
|
33 |
|
git grep payload_uboot_i386 |
|
34 |
|
|
|
35 |
|
In `target.cfg` files for each coreboot board, you will find this option if |
|
36 |
|
it's enabled. You also need either `u-boot/i386coreboot` |
|
37 |
|
or `u-boot/amd64coreboot` in the `build_depend` variable for a given board, for |
|
38 |
|
it to automatically compile at build time. |
|
39 |
|
|
|
40 |
|
Not every board has it yet. U-Boot is still experimental on x86. Libreboot has |
|
41 |
|
made several modifications to the default *bootflow* menu, used for selecting |
|
42 |
|
an EFI application at boot (e.g. installed GRUB bootloader for e.g. Debian). |
|
43 |
|
For example, upstream didn't implement an auto-boot timeout for the first |
|
44 |
|
selected boot item, so this was implemented. Libreboot also themed it to look |
|
45 |
|
more like an official Libreboot bootloader. |
|
46 |
|
|
|
47 |
|
Here is an example of what it looks like on the boot menu: |
|
48 |
|
|
|
49 |
|
<https://mas.to/@libreleah/113596262378713418> |
|
50 |
|
|
|
51 |
|
Boot Linux/BSD installer (USB) |
|
52 |
|
--------------------------- |
|
53 |
|
|
|
54 |
|
Just stick your formatted USB stick in. U-Boot should detect it. Sometimes some |
|
55 |
|
USB flash drives are broken, because many of them violate specifications and |
|
56 |
|
U-Boot doesn't properly hack around that like Linux does (buggy USB mass storage |
|
57 |
|
implementation) - also, xhci suppport is still a bit unstable, on machines that |
|
58 |
|
don't have EHCI controllers (e.g. Haswell setups and beyond). |
|
59 |
|
|
|
60 |
|
If your USB drive is detected at boot, a menu might appear, showing it and you |
|
61 |
|
can select it, sometimes it doesn't and you could instead do in the U-Boot shell: |
|
62 |
|
|
|
63 |
|
bootflow list |
|
64 |
|
bootflow select X |
|
65 |
|
|
|
66 |
|
Where `X` is the number of the boot device, as shown by the output of the list |
|
67 |
|
command. |
|
68 |
|
|
|
69 |
|
After selecting the device, you can do: |
|
70 |
|
|
|
71 |
|
bootflow boot |
|
72 |
|
|
|
73 |
|
Booting installed system |
|
74 |
|
------------------------ |
|
75 |
|
|
|
76 |
|
It should just work. If all is well, it'll show the bootflow menu. Simply |
|
77 |
|
select your device. If you see error, perhaps try: |
|
78 |
|
|
|
79 |
|
bootefi bootmgr |
|
80 |
|
|
|
81 |
|
Tested operating systems |
|
82 |
|
======================== |
|
83 |
|
|
|
84 |
|
Linux/BSD |
|
85 |
|
--------- |
|
86 |
|
|
|
87 |
|
Arch Linux, Debian Linux and OpenBSD have been tested. |
|
88 |
|
|
|
89 |
|
Some GRUB setups that use the *console* output mode end up using the U-Boot |
|
90 |
|
console driver, which is buggy in UEFI GRUB, so menus can get quite messed up |
|
91 |
|
indeed; text in the wrong place, countdown timers mangled, etc. E.g. the Arch |
|
92 |
|
Linux installer is completely broken, but you can hit enter to boot Linux which |
|
93 |
|
then uses KMS and the installed system uses it (and you could install another |
|
94 |
|
bootloader in the installed system). |
|
95 |
|
|
|
96 |
|
EFI-based GRUB menus like in the Debian installer seemed to work just fine, |
|
97 |
|
that is: setups that use the EFI framebuffer instead of a text console. |
|
98 |
|
|
|
99 |
|
Windows |
|
100 |
|
------- |
|
101 |
|
|
|
102 |
|
Windows was tested, and doesn't work yet. Simon Glass maintains the x86 |
|
103 |
|
coreboot payload, and has informed me that he still has some work to do |
|
104 |
|
there. |
|
105 |
|
|
|
106 |
|
SecureBoot |
|
107 |
|
========== |
|
108 |
|
|
|
109 |
|
Supported by U-Boot, though U-Boot does not currently have a robust way of |
|
110 |
|
storing EFI variables, and Libreboot disables SecureBoot by default. However, |
|
111 |
|
you can enable it. Information is available in U-Boot's official documentation. |
|
112 |
|
|
|
113 |
|
If you want real boot security, don't use UEFI. Libreboot's GRUB payload can |
|
114 |
|
be heavily hardened, by following the [GRUB hardening](../linux/grub_hardening.md) |
|
115 |
|
guide; this means using the GRUB payload instead of U-Boot. |
|
116 |
|
|
|
117 |
|
UEFI SecureBoot with a Linux UKI could achieve similar results in a security |
|
118 |
|
sense to Libreboot's GRUB hardening setup, though the latter is more flexible, |
|
119 |
|
albeit not widely used by the mainstream, but it does work (I use it myself!). |
|
120 |
|
|
|
121 |
|
Bugs |
|
122 |
|
==== |
|
123 |
|
|
|
124 |
|
Limited testing, at least as of 5 December 2024, but some issues that appeared |
|
125 |
|
included: |
|
126 |
|
|
|
127 |
|
* Haswell: USB support very flaky. E.g. some keyboards work, some don't, some |
|
128 |
|
USB drives work, some don't. |
|
129 |
|
* ThinkPad T480: U-Boot simply boot loops endlessly, but sometimes boots and |
|
130 |
|
shows a menu: SATA doesn't work, but NVMe SSDs do, and you can boot just |
|
131 |
|
fine, but you might not be able to boot with the bootflow menu; |
|
132 |
|
the `bootefi` command can be used. |
|
133 |
|
* Certain ivybridge laptops eg. Dell Latitude: EFI framebuffer got completely |
|
134 |
|
b0rked. |
|
135 |
|
|
|
136 |
|
The good news is that a few systems were tested that seemed to work well. |
|
137 |
|
Haswell machines mostly work OK (with a few bugs), some Kaby Lake machines work |
|
138 |
|
but some don't very well; the GM45 machines work well, e.g. a ThinkPad X200 was |
|
139 |
|
tested. |
|
140 |
|
|
|
141 |
|
Mitigating instability |
|
142 |
|
======================= |
|
143 |
|
|
|
144 |
|
U-Boot is not a primary payload on any board where it's enabled. It's instead |
|
145 |
|
chainloaded from SeaBIOS on 64-bit x86, and from GRUB on 32-bit x86. You select |
|
146 |
|
it in the SeaBIOS menu (ESC menu), or you can use a ROM image that |
|
147 |
|
has `seauboot` in the name, where SeaBIOS auto-boots U-Boot unless interrupted |
|
148 |
|
via the ESC prompt. |
|
149 |
|
|
|
150 |
|
So if U-Boot is unstable on your board, you can press ESC in SeaBIOS and boot a |
|
151 |
|
device in SeaBIOS, or select the available GRUB payload from SeaBIOS. |
|
152 |
|
|
|
153 |
|
Please do report any failures or successes with your testing, if you want to |
|
154 |
|
try out U-Boot. |
|
155 |
|
|
|
156 |
|
**TODO: A lot more documentation and testing notes should be written here over |
|
157 |
|
time, and lots more bug fixes are needed for U-Boot to become stable. It is |
|
158 |
|
the intention of Libreboot that U-Boot become the DEFAULT payload on x86 |
|
159 |
|
in a future release.** |