lbwww/site/docs/install/ivy_has_common.md

---
title: Insert vendor files not included in release images
x-toc-enable: true
...

**PLEASE MAKE SURE you read and follow the instructions on this page, prior
to flashing Libreboot, if required for your mainboard; 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.**

Even if your board doesn't need vendor firmware inserted, you can also use this
guide to change the GbE MAC address in the flash, if your board has an Intel
Gigabit Ethernet device (where an Intel Flash Descriptor is used).

WARNING: eCryptfs file name limits
=================================

Do not run the build system on a eCryptfs file system, because it has
very short file name limits and Libreboot's build system deals with very
long file names. We commonly get reports from this by Linux Mint users
who encrypt their home directory with eCryptfs; regular LUKS encryption will
do nicely.

**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 [lbmk.git](../../git.md).

**Failure to adhere to this warning will result in vendor file insertion not
working. The insertion must work correctly, prior to Libreboot installation,
if your board requires it, otherwise your board simply will not boot.**

Introduction
============

Coreboot is nominally free software, but requires certain vendor code on some
boards, for certain functionalities; we cover this more thoroughly in
the [Freedom Status](../../freedom-status.md) page and in the [Binary Blob
Reduction Policy](../../news/policy.md).

Libreboot can't directly distribute *all* of these files, so some of them are
downloaded at build-time, and processed for insertion into the firmware images.
**On pre-compiled ROM images in releases, these files are removed, and can be
re-added using the same automation that was applied during the build process.**

Examples of vendor files can include, for example: Intel ME (disabled after
boot with me\_cleaner), Embedded Controller firmware (e.g. KBC1126 EC firmware
on HP EliteBooks), VGA ROMs (e.g. Nvidia GPU ROM for Dell Latitude E6400),
and so on. Without these, your machine may not boot correctly, or not boot at
all!

If in doubt, you should simply follow these instructions. If your board
doesn't need vendor files, the tar archive won't be modified.

MAC address
-----------

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](nvmutil.md);
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](ivy_has_common.md).

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](https://www.youtube.com/watch?v=0ZEuWJ4muYc) 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](../../news/policy.md) 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.