grub payload warning

Signed-off-by: Leah Rowe <info@minifree.org>

site/docs/install/index.md

@@ -3,6 +3,54 @@ title: Installation instructions
 x-toc-enable: true
 ...
 
+**GRUB payload warning**
+====================
+
+Firstly, it should be stated: in almost all cases, GRUB works just fine, on
+all of the machines that we test, but as of 26 May 2024 we got the error
+report:
+
+See: <https://codeberg.org/libreboot/lbmk/issues/216>
+
+We've seen this elsewhere too, always on Sandybridge-based Dell Latitude
+laptops, which Canoeboot doesn't support anyway (the above report is for
+Libreboot, upon which Canoeboot is based), but:
+
+Although we've only seen this thus far (as per user reports) on Intel
+SandyBridge based Dell Latitude laptops, we advise:
+
+**DO NOT use a ROM image where GRUB is the first payload. If you want to
+use the GRUB payload, please use a ROM image with `seabios_` at the start
+of the file name. Avoid images with `grub_` at the start of the file name.**
+
+ROM images with `grubonly` in them should also be avoided; if you want GRUB
+to be the first thing you see (without interruption), use a ROM image
+with `seabios_` at the start of the file name, and `grubfirst` at the end;
+these place a bootorder file in CBFS, so that SeaBIOS loads GRUB first, but
+you can still press ESC to bring up the SeaBIOS boot select menu.
+
+The error above, in the linked bug report, occurs on `grub_free()`
+or `grub_realloc()` and could be caused by anything in GRUB; the user tested
+on memtest86plus and got no errors, and SeaBIOS works; BIOS GRUB (from a distro)
+also works, where GRUB doesn't need as many drivers; we suspect this may be
+a use-after-free in a GRUB driver, or otherwise something writing to heap memory
+wrongly. The bug is not yet known, only the symptom (the fatal error message).
+
+Canoeboot releases after 20240510 will *only* (on x86) contain ROM images where
+SeaBIOS is the first payload, without disabling the SeaBIOS menu (no `grubonly`). You'll still be able to use GRUB, either by pressing ESC for the boot
+select menu, and/or using an image with `grubfirst` in the file name so that
+SeaBIOS loads it first (while still permitting boot select via ESC keypress).
+
+Canoeboot releases after 20240510 will *only* (on x86) contain ROM images where
+SeaBIOS is the first payload, without disabling the SeaBIOS menu (no `grubonly`).
+
+GRUB's code is vast, and complicated, so this policy change is permanent,
+until GRUB can be well-audited (likely forked, with dead/legacy code removed).
+SeaBIOS code is much smaller and more robust. Remember always: code equals bugs.
+
+Flashprog
+=========
+
 **NOTE: Canoeboot standardises on [flashprog](https://flashprog.org/wiki/Flashprog)
 now, as of 3 May 2024, which is a fork of flashrom.**
 
@@ -161,11 +209,45 @@ an option in the boot menu.
 ROM images that have `seabios_withgrub` in the file name start with SeaBIOS
 first, but also have GRUB available in the boot menu when you press ESC.
 
+ROM images with this and `grubonly` in the image start SeaBIOS, but only load
+GRUB from SeaBIOS and the SeaBIOS menu is disabled. Use these images if you
+only want GRUB; they are provided on systems that only have VGA ROM-based
+initialisation, usually discrete graphics cards on desktop machines.
+
 Which systems are supported?
 ============================
 
 [Refer to the hardware compatibility page](../hardware/)
 
+Intel GbE MAC address (IFD-based systems)
+=====================================================================
+
+You can change the MAC address in flash, on these machines. See:
+[nvmutil documentation](nvmutil.md)
+
+The MAC address is stored in a region of the boot flashed called *GbE NVM*
+which is short for *gigabit ethernet non-volatile memory*. Refer to the
+following article:
+
+For GM45/ICH9M systems (e.g. ThinkPad X200/T400, Dell Latitude E6400), see:
+[ich9utils documentation](ich9utils.md) (you can also use nvmutil, see link
+above)
+
+Canoeboot puts a default MAC address in the available ROM images, but this is
+a generic MAC address and it's identical on every ROM image. Technically, you
+can use it but if you encounter other Canoeboot users on the same ethernet
+switch, using the same physical network as you, you will encounter a MAC
+address conflict.
+
+NOTE: R500 thinkpads do not have an Intel gigabit ethernet NIC, so on that
+laptop you can just flash the default ROM and you do not have to worry.
+
+There are also some Intel X4X platforms that use an ICH10 southbridge,
+supported in Canoeboot, but these are flashed in a *descriptorless* setup,
+which means that the MAC address is irrelevant (either there will be an Intel
+PHY module that is now unusable, and you use an add-on card, or it doesn't use
+an Intel PHY module and the onboard NIC is usable).
+
 Install via host CPU (internal flashing)
 ========================================