SAFELY flash Canoeboot on Intel IvyBridge, SandyBridge and Haswell mainboards

Return to index

These words pertain to Intel Ivybridge, Sandybridge and Haswell systems that are supported by Canoeboot. Those systems are possible to support in Canoeboot, 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 Libreboot to Canoeboot on DELL systems, please also read GbE safety.

Canoeboot is a Free Software project that replaces proprietary BIOS/UEFI firmware, but some newer boards still occasionally need code from the hardware manufacturer in order to boot properly. Canoeboot 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.

This design differs from Libreboot, in that Libreboot builds complete ROM images, including all of these files when possible, which means downloading them at build time and inserting them, or inserting them after-the-fact on release images (because release images exclude them), using the same scripts.

Therefore, Canoeboot’s installation method can be a bit more finnicky, but it is done this way precisely because Canoeboot 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 Canoeboot’s Binary Blob Extermination Policy.

PLEASE MAKE SURE you read and follow the instructions on this page, prior to flashing Canoeboot, 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 - 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 Canoeboot doesn’t distribute, such as Intel ME, you’re pretty much stuck unless either 1) You made a full dump of the flash first, as a backup and/or 2) You use a Libreboot image for recovery instead, and then migrate back to Canoeboot. YOU HAVE BEEN WARNED.

This way of doing things is very hazardous unless you know what you’re doing, and it’s how Libreboot previously handled these newer boards. Be careful.

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

Canoeboot 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, Canoeboot 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 (Canoeboot 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.

This differs from Libreboot, because Libreboot does all of this too, but also downloads the ME at build time, and shrinks it using me_cleaner; ME cleaner itself is not required for merely disabling the ME, but it also removes all of the extra modules that you no longer need.

Canoeboot 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 as Libreboot does.

Canoeboot’s policy 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.

On systems with two flash chips, e.g. 8MB and 4MB (4MB being SPI2 and 8MB being SPI1), where an IFD is used, Canoeboot 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).

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 before using this guide, and note that this guide assumes you use cbmk.git.

On systems with IFD, Canoeboot uses the default, smaller BIOS region size, instead of enlarging it. This size differs per platform. This means that Canoeboot’s IFD sets a larger ME region size and smaller BIOS region size.

This is because Canoeboot avoids distributing Intel ME, instead telling you to avoid overwriting what’s already present fram the factory; instead, you only flash the BIOS region.

Canoeboot therefore must be flashed carefully; if migrating from Libreboot, you can just flash the BIOS region. This is true because Canoeboot has the smaller BIOS region, so you’d just be flashing an image with smaller CBFS size which would be compatible.

The reverse is not true; migrating from Canoeboot to Libreboot would just be done by re-flashing the entire chip. However, this guide only covers migrating to Canoeboot, from either Libreboot or the vendor firmware.

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!

If you have a system with the intel Flash Descriptor, you can do first:

flashprog -p PROGRAMMER --ifd -i bios -w canoeboot.rom

This will flash just the BIOS region. If you’re migrating from Libreboot, this is all you should do. You can optionally re-flash the GbE section, but please read GbE Safety first. Like so:

flashprog -p PROGRAMMER --ifd -i gbe -w canoeboot.rom

WARNING: Dell systems use a larger 16KB GbE region on Canoeboot, versus 8KB on Libreboot. Doing the above -i gbe command for Canoeboot will brick your system, if migrating from Libreboot, because it would overwrite the first 8KB of your Intel ME.

You can optionally re-flash the Intel IFD:

flashprog -p PROGRAMMER --ifd -i fd -w canoeboot.rom

WARNING: DO NOT do this if migrating from Libreboot. Only do it if migrating from factory firmware. This is because Libreboot shrinks the Intel ME region and enlarges the BIOS region, modifying the IFD accordingly. Therefore, doing this in a LB-to-Canoe context would result in an enlarged ME region, possibly containing junk that would then brick the ME at boot time, resulting in your machine not booting properly. Canoeboot and Libreboot both modify the IFD to set the flash read-write and to disable the ME after early bringup, so you really just need to flash the BIOS region.

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.

As already alluded to in previous sections, Canoeboot cannot directly handle the Intel ME in its build system, as that would mean technically leading the user toward proprietary software.

Canoeboot’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 Canoeboot, please note that Canoeboot 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 Canoeboot source archive, or in cbmk.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 Canoeboot release archives, or in the cbmk.git repository. Do this:

./mk -b flashprog

Please note that you need build dependencies 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 Canoeboot 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; Canoeboot doesn’t do this, because Canoeboot 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. (don’t bother. GRUB, SeaBIOS and U-Boot easily fit into the smaller space anyway)

The Libreboot version of this page is: https://libreboot.org/docs/install/ivy_has_common.html

SPDX-License-Identifier: GFDL-1.3-or-later

Markdown file for this page: https://canoeboot.org/docs/install/ivy_has_common.md

Site map

This HTML page was generated by the Libreboot Static Site Generator.