--- title: SAFELY flash RBoot on Intel IvyBridge, SandyBridge and Haswell mainboards x-toc-enable: true ... These words pertain to Intel Ivybridge, Sandybridge and Haswell systems that are supported by RBoot. Those systems are possible to support in RBoot, with only Free Software, but you have to flash it in specific regions of the flash, while avoiding others, in order to prevent a soft-brick scenario. **If migrating from another coreboot distro to RBoot on DELL systems, please also read [GbE safety](dell_gbe.md).** libre BIOS/UEFI firmware ------------------------------ RBoot is a [Free Software](https://www.gnu.org/philosophy/free-sw) project that replaces proprietary BIOS/UEFI firmware, but some newer boards still occasionally need code from the hardware manufacturer in order to boot properly. RBoot is a *fully free* coreboot distro, which means that it will not distribute these files; however, supporting these machines is still possible, by avoiding overwriting the versions of these files that are already present. For example, you can avoid overwriting the original Intel ME, while still disabling Intel ME after early bringup by setting the HAP bit in the Intel Flash Descriptor. This is similar conceptually to when you, say, flash LibreCMC on a router, but you have to avoid overwriting the vendor bootloader which is non-free. LibreCMC is free software, but has to be flashed around certain vendor code. It's really the same sort of thing here, from the user's point of view. Therefore, RBoot's installation method can be a bit more finnicky, but it is done this way precisely because RBoot *only* provides free software. It is an interesting design difference, and can create some very interesting results. This article will teach you how to manage everything. for it. For more context, please read RBoot's [Binary Blob Extermination Policy](../../news/policy.md). **PLEASE MAKE SURE you read and follow the instructions on this page, prior to flashing RBoot, if required for your motherboard; failure to heed this warning can and will result in a soft-brick, which would then necessitate recovery via [external flashing](spi.md) - regardless, you are advised to also read the external flashing guide just in caes, and have an external flasher handy in case you need it.** **WARNING: If you DO overwrite something that RBoot doesn't distribute, such as Intel ME, you're pretty much stuck unless you made a backup image. Intel ME -------- The flash is divided into regions, on systems where an Intel ME is present: * Intel Flash Descriptor / IFD (config data, also defines regions) * Intel GbE NVM (config data for Intel Gigabit Ethernet devices) * Intel ME * BIOS RBoot provides only the IFD, GbE and BIOS parts. The *ME* region is skipped, so you leave what's already there from the factory intact. In this way, RBoot still provides a fully free software coreboot distro on these newer machines. A special bit in IFD is set, called HAP (High Assurance Platform), also known as altMeDisable, which disables the ME after early bringup; this is done on all IvyBridge, SandyBridge and Haswell mainboards. On Ivybridge and Sandybridge, there is a second setting applies: ME Soft Temporary Disable. This does the same thing as setting the HAP bit, but without needing to modify the IFD (RBoot does that too, on these machines). By "disable after early bringup", we specifically mean: the ME's `ROMP` and `BUP` modules still run at boot time. These are essentially the ME's own boot firmware, analogous to coreboot, but other modules like the ME's kernel and networking stack are dysfunction, and features like AMT are disabled. In other words: The ME initialises itself, and then stops. It's comparable to running coreboot without a payload. This configuration basically bricks the Intel ME. It's an intentional feature provided by Intel themselves, which some vendors even offer to customers when they purchase a computer. RBoot can't use `me_cleaner`, because that would mean handling the Intel ME directly, which would then mean either distributing it, or leading the user to download and handle it. RBoot's [policy](../../news/policy.md) is specifically that it must NOT distribute binary blobs, and must never lead users toward them. Therefore, it must ensure that the user leaves what's already in flash intact, unless a full replacement were to become possible one day. Two-chip IFD systems -------------------- On systems with two flash chips, e.g. 8MB and 4MB (4MB being SPI2 and 8MB being SPI1), where an IFD is used, RBoot uses a CBFS region size equivalent to the capacity of the second chip. For example, if the second IC was 4MB, then CBFS would be 4MB. This enables easier external flashing, while avoiding overwriting the wrong regions; then you can externally flash the second chip, only flashing the IFD and GBE regions specifically (if desirable). Install build dependencies first ------------------------------------ **You will be compiling several small utilities from source code. This means you need the compilers and various libraries.** **Please make sure to install [build dependencies](../build/)** before using this guide, and note that this guide assumes you use [rbmk.git](../../git.md). Introduction ------------ ### BIOS region size On systems with IFD, RBoot uses the default, smaller BIOS region size, instead of enlarging it. Some distros enlarge it. This size differs per platform. This means that RBoot's IFD sets a larger ME region size and smaller BIOS region size. This is so that the user can avoid touching the Intel ME; by doing this, RBoot complies with its own zero-blobs policy because then it doesn't need to distribute or handle the Intel ME. This is because RBoot avoids distributing Intel ME, instead telling you to avoid overwriting what's already present fram the factory; instead, you only flash the BIOS region. RBoot therefore must be flashed carefully; if migrating from other distros, you can just flash the BIOS region because it's unlikely that other distros will set a *smaller* BIOS region size, so RBoot's default, highly conservative configuration is very likely safe. This is true because RBoot has the smaller BIOS region, so you'd just be flashing an image with smaller CBFS size which would be compatible. ### MAC address Regardless of whether your board uses vendorfiles or not, you can also use this command to change the MAC address on systems with Intel GbE regions in the flash, where an Intel gigabit ethernet device is used. For example, a Lenovo ThinkPad X200 doesn't need such files in ROM, but can still have the mac address changed; please continue reading! ### Flash by region, not the whole chip! If you have a system with the intel Flash Descriptor, you can do first: ``` flashprog -p PROGRAMMER --ifd -i bios -w rboot.rom ``` This will flash *just* the BIOS region. You can optionally re-flash the GbE section, but please read [GbE Safety](dell_gbe.md) first. Like so: ``` flashprog -p PROGRAMMER --ifd -i gbe -w rboot.rom ``` **WARNING: Dell systems use a larger 16KB GbE region on RBoot, versus 8KB on certain other coreboot distros. Please check your configuration accordingly. Doing the above `-i gbe` command for RBoot will brick your system, if migrating from setups with 8KB GbE, because it would overwrite the first 8KB of your Intel ME and thus brick your machine.** You can optionally re-flash the Intel IFD (**Please read the notes below first, before doing this**): ``` flashprog -p PROGRAMMER --ifd -i fd -w rboot.rom ``` **WARNING: DO NOT mess with the IFD if you're migrating from another coreboot distro that already modified it; otherwise, you might end up with a brick. The above command is only safe if migrating from Dell's original firmware, unmodified. Please ONLY flash the BIOS region, if migrating from any other coreboot-based setup, unless you know exactly what you're doing. You have been warned!** **WARNING: Older versions of nvmutil used `?` for random characters. Newer versions use `x` instead. If you have an older version, use `?` instead, when generating random characters in MAC addresses.** Run me\_cleaner after booting RBoot --------------------------------------- As already alluded to in previous sections, RBoot cannot directly handle the Intel ME in its build system, as that would mean technically leading the user toward proprietary software. RBoot's installation method, as you've seen, tip-toes around the ME by flashing only the regions around it, while not flashing the ME region itself. Now, after you boot RBoot, please note that RBoot sets the ME Alt Disable (HAP) bit in the Intel Flash Descriptor. This means that the ME shuts down after early boot. Since the ME is no longer operating after you boot into your distro, you can now safely read and write the entire flash from your OS. Within the RBoot source archive, or in `rbmk.git` after doing: ``` ./mk -f coreboot default ``` You will find the ME Cleaner python script in the following directory: * `src/coreboot/default/util/me_cleaner` There is a README file there, but in general you can do this: ``` python me_cleaner.py -S -O modified_image.bin original_dump.bin ``` Do this on a dump of your firmware. You can use the `-r` option in flashprog, to dump your firmware: ``` flashprog -p internal -r original_dump.bin ``` Now just do the ME Cleaner command as above. It'll give you some output, showing you what it did. Then you will re-flash the modified image, thus: ``` flashprog -p internal -w modified_image.bin ``` The flashprog program can be found in RBoot release archives, or in the `rbmk.git` repository. Do this: ``` ./mk -b flashprog ``` Please note that you need [build dependencies](../build/) to compile sources, as shown above. Once you've build flashprog, you'll see it in `elf/flashprog/` and you can run the binary that was generated there. Your mileage may vary when doing this. Simply leaving the default Intel ME region in place is totally OK, because RBoot both sets the HAP bit and, where possible, turns on *ME Soft Temporary Disable* in coreboot. However, for peace of mind, you may consider running ME Cleaner after the fact, using the instructions shown above. What ME Cleaner does is remove all the unnecessary components of the Intel ME, leaving only those components that are the only parts that would run anyway, when setting the HAP bit. There is also a truncate option for the ME region, which would allow you to shrink the ME region itself, and enlarge the BIOS region; RBoot doesn't do this, because RBoot images are designed to be flashed with the default BIOS region size, so as to be compatible with all setups, but you could do this yourself. [//]: # "SPDX-License-Identifier: GFDL-1.3-or-later"