lbwww/site/docs/install/ivy_has_common.md

Regardless of whether your board needs 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 any files added, but can still have the mac address changed; please continue reading!

Injecting vendor files into tarballs

In order to inject the necessary files into a rom image, run the script from the root of lbmk and point to the rom image.

If you only wish to flash a release rom then the process of injecting the necessary files is quite simple. Run the injection script pointing to the release archive you downloaded:

./mk inject libreboot-RELEASE_targetname.tar.xz

Where a GbE region is present in the flash, you can also use the above command to change the MAC address, by modifying it like so:

./mk inject libreboot-RELEASE_targetname.tar.xz setmac

Note that setmac, without additional argument, will randomise the MAC address, setting a local, unicast MAC address. You can specify a custom MAC address, like so:

./mk inject libreboot-RELEASE_targetname.tar.xz setmac 00:1f:16:00:01:02

The above MAC address is a random example; please make sure to use one that matches your board, if you wish. You can also use randomisation this way; the ? character will be randomised, e.g.:

./mk inject libreboot-RELEASE_targetname.tar.xz setmac ??:??:??:??:??:??

You can mix and match arbitrary characters with random ones, e.g.:

./mk inject libreboot-RELEASE_targetname.tar.xz setmac 0?:??:12:?a:6?:69

The script can automatically detect the board as long as you do not change the file name.

On Libreboot 20241206 rev8 or newer, releases newer than the 20241206 series, and in the latest lbmk Git repository branch revisions (master branch), the commands above directly modify the tarball.

Older versions left the tarball unmodified, and extracted the modified images to bin/release/ - on current behaviour, you inject the tarball and then extract the tarball yourself afterward, to flash the modified images.

Behaviour changes in Libreboot 20241206 rev8

Older versions of this script would have produced the injected images under the bin/release/ directory, and/or allow you to do it on specific ROM images.

The current version, pertaining to this documentation, only supports injecting tarballs, because the tarball-based mechanism verifies checksums on images, after insertion.

The older versions of this script would have left the tarball unmodified, while producing bin/release/ containing your images.

The current version, pertaining to this documentation, modifies the tarball itself. You can inject and un-inject. To un-inject, you can do:

./mk inject libreboot-RELEASE_targetname.tar.xz nuke

Running the nuke command will remove vendorfiles, and re-generate a file inside the archive named vendorhashes. When running regular inject, not nuke, the vendorfiles file is removed after insertion; this way, subsequent injections are avoided, by detecting whether they're needed on the basis of that file.

The nuke command is available because Libreboot's build system uses it when producing release archives. You otherwise shouldn't use nuke yourself, except for testing purposes or if you're just curious.

Libreboot 20241206 rev8 have different command structure for the inject script. Older versions could insert into lone ROM images, with a special command, and generally didn't have good error checking. The new version of this script is much safer and easier to use. These changes are also present in the latest lbmk git repository.

ALSO: Non-injected images do, on Libreboot 20241206 rev8 or higher, have 1 byte of padding - yes, 1 byte - at the end, to make flashprog fail to flash it due to size mismatch versus chip size, and the words DO_NOT_FLASH are inserted into the file name. With both of these things, the user is unlikely to flash an image that hasn't been injected.

After injection, the DO_NOT_FLASH file name prefix is removed, as is the padding, so that the injected images are ready to flash, and the tarball is re-generated with these images.

ALSO: If vendorfiles are not needed, or if an error occurs, modification of the tarball is avoided and it's left alone, UNLESS the following condition is met:

If no errors occured, but no vendor files are needed, you can still inject a new MAC address, where there is a GbE region. If there isn't a GbE region, such modification is skipped (some boards don't have Intel gigabit ethernet, and might have a different ethernet adapter instead).

When vendor files are inserted and/or a MAC address is inserted, the tarball is re-generated. MAC address insertion is handled with nvmutil; the steps there are applied automatically.

Older release images, prior to 20241206 rev8, do not have DO_NOT_FLASH or the 1-byte padding, so watch out! However, this script, the new version, is backwards compatible with older releases.

That's one possible use for the nuke command, running it yourself. If you're distributing the older release images, you could inject them, and then nuke them; doing so will re-generate the vendorhashes file, and retroactively pad them (and add DO_NOT_FLASH to the image file names). It would be pointless for Libreboot to retroactively modify the official images in this way, since 20241206 rev8 and newer already has this done to it. Just be careful when using the older tarballs.

Check that the files were inserted

Automatic verification

You must ensure that the files were inserted. The inject command automatically verifies checksums of the complete images, when you run it directly on a release tarball.

If there was an error, and/or the checksums didn't match, then the tarball won't be modified. If you're using newer release images with DO_NOT_FLASH and the one-byte padding (as described above), that's a good indicator, but older release images didn't have this modification.

Manual inspection

You could check the files manually, if you're paranoid, after insertion.

Some examples of how to do that in lbmk:

./mk -d coreboot TREENAME

TREENAME should be the coreboot tree corresponding to your board. Check this in config/coreboot/BOARD/target.cfg for your board, and tree will be set to e.g. default, or some other tree name.

Now you find elf/cbfstool, which is a directory containing cbfstool and ifdtool. Do this on your ROM image (libreboot.rom in the example below):

./elf/cbfstool/TREENAME/cbfstool libreboot.rom print

You should check that the files were inserted in cbfs, if needed; for example, EC firmware or MRC firmware, perhaps FSP.

FSP is redistributable by Intel, but not with modification. Since coreboot has to de-concatenate FSP into its modules, and modify pointers in the FSP-M module, for raminit, Libreboot treats FSP modules like other injectable vendor files.

(in the original 20241206 release, FSP was directly baked in; the change described above was applied in Libreboot 20241206 and newer, and the 3050micro image from Libreboot 20241008 was removed from Libreboot's rsync server)

Next:

./elf/ifdtool/TREENAME/ifdtool -x libreboot.rom

This creates several .bin files, one of which says me in it (Intel ME). Run hexdump on it:

hexdump flashregion_2_intel_me.bin

Check the output. If it's all 0xFF (all ones) or zeroes or otherwise isn't a bunch of code, then the Intel ME firmware wasn't inserted. You could also run the me_cleaner program on this file, to see if it gives you any information, if you're not savvy enough to look at stuff in hexdump.

You'll note the small size of the Intel ME, e.g. 84KB on sandybridge platforms. This is because lbmk automatically neuters it, disabling it during early boot. This is done using me_cleaner, which lbmk imports.

Intel FSP copyright

If you just want to inject Intel FSP and ME into your image, ready for flashing, please read the guide.

Abstract

The initial Libreboot 20241206 release included Intel FSP directly inside the ROM images. Intel provides the FSP under a license which states (and I paraphrase): you must not modify it, but you can redistribute it freely, so long as the license notice is retained.

The FSP is a concatenation of three modules: FSP-T, FSP-S and FSP-M. T basically does CAR, S is essentially romstage components, and M is raminit. Due to how coreboot works, these components must be split into single components. Coreboot doesn't use T by default (it implements CAR itself), but has the option to use it. It will use M and S, only.

Technically, the process of splitting FSP into these three files counts as a modification. Furthermore, coreboot also rebases the M module by modifying certain pointers, so that it can integrate with coreboot to provide raminit.

Intel themselves own the copyright to the tool for splitting FSP, at 3rdparty/fsp/Tools/SplitFspBin.py, and it seems that they do intend for the FSP to be used this way. However, until now, those using the Intel FSP have built coreboot images from source, so the issue of modified distributions didn't come up.

By the strictest possible interpretation of Intel's licensing, Libreboot was technically in violation. To mitigate this, Libreboot 20241206 revision 8 and newer, will no longer include the Intel FSP inside images. Instead, the vendor inject script is used for inserting the FSP into release images, which is what we already do for several other components.

_fsp vs _vfsp targets

The original 20241206 release images had _fsp in the file name. From rev8 onward, _vfsp is specified instead.

Libreboot's inject script verifies checksums on files, when inserting into the images. Because of this, if we inject FSP after the fact, that means anyone using the old images will find errors when they try.

To mitigate this, the build targets containing _fsp in the name have been retained, but these targets are set release="n" so that no ROM images are provided in releases. The _vfsp images are provided pre-compiled, instead.

With this re-design, modern lbmk (from Libreboot 20241206 rev8 onward) can still reliably inject Intel ME into the old _fsp images, if you already downloaded those before.

Therefore, you must be especially careful to get this right. If you're running the inject script into a tarball, it will generally detect the right one, but inserting manually into individual image files is also possible; if you do this, you must remember to correctly specify t480_vfsp_16mb or t480s_vfsp_16mb, or to specify the _fsp targets if you're doing this on older images.

It is extremely unlikely that Intel would have ever cracked down on Libreboot for its previous mistake, since many other projects exist that include FSP directly in coreboot images, even commercially. However, Libreboot wishes to respect Intel's license, in the most technically correct way possible.

Errata

NOTE: As of Libreboot releases from May 2024 onward, the Intel MRC is no longer included for Haswell; MRC is a blob for raminit, but we now provide libre raminit. The following targets no longer exist in the build system:

• t440pmrc_12mb (use t440plibremrc_12mb instead)
• t440pbmrc_12mb (use t440plibremrc_12mb instead)
• w541mrc_12mb (use w541_12mb instead)
• w541bmrc_12mb (use w541_12mb instead)
• dell9020sff_12mb (use dell9020sff_nri_12mb instead)
• dell9020sffbmrc (use dell9020sff_nri_12mb instead)
• dell9020mt_12mb (use dell9020mt_nri_12mb instead)
• dell9020mtbmrc (use dell9020mt_nri_12mb instead)

FSP images are also no longer baked in on release images, from Libreboot 20241206 rev8 or higher (or releases newer than the 20241206 series), but the machines that use them still need them; they are injected instead, using the commands shown above on this very page.

This is written as errata because some users may still be using older release images but on the newer build system from May 2024 onward; you must use the Libreboot 20240225 release if you want to inject MRC and so on, for these older targets.

Libreboot's binary blob reduction policy is very strict, and states: if a blob can be avoided, it must be avoided. Therefore, the MRC is removed on Haswell and Libreboot will only use the libre raminit (called NRI, short for Native Ram Initialisation).

The four freedoms are absolute.