lbwww/site/docs/install/ivy_has_common.md

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

Open source BIOS/UEFI firmware
------------------------------

Libreboot is a [Free Software](https://writefreesoftware.org/learn) project
that replaces proprietary BIOS/UEFI firmware, but some newer boards still
occasionally need code from the hardware manufacturer in order to boot properly.
This document will teach you how to handle such a scenario, and how to check
for it. For more context, please read Libreboot's [Binary Blob Reduction
Policy](../../news/policy.md) and [Freedom Status](../../freedom-status.md)
pages.

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

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
------------

On *some* boards, but certainly not all of them, certain files are required from
the hardware vendor. Libreboot has strict [rules](../../news/policy.md)
governing this, and you can find more information on
the [Freedom Status](../../freedom-status.md) page.

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 these files can be found on
the [Freedom Status](../../freedom-status.md) page.

**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

**NOTE: As of Libreboot 20241206 rev8 or newer, the above command will behave
the same way as if you declared `setmac` without argument, mentioned below:**

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 `setmac` command, without argument, is technically redundant, since MAC
addresses are randomised by default, every time you run the inject script.

If you wish to *skip* changing the MAC address (not recommended), you can
use the `keep` argument, like so:

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

The `setmac` command works by inserting a reference GbE file, contained within
lbmk. The `keep` command makes lbmk *skip* changing your current GbE region;
it does not, for example, restore the reference GbE image from lbmk.

The `setmac` command, when not using `keep`, copied the default GbE file within
lbmk for that board, modifying the temporary copy and then inserting that. To
insert the *original file*, without modification, you can do this:

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

The `restore` setting does the same as `setmac` (without `keep`), but skips
running `nvmutil`; it also skips building nvmutil. Essentially, this will
restore the default MAC address from standard release images.

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. If the platform
uses MEv11 with Intel Boot Guard, the boot guard is automatically disabled
by processing the MEv11 image with Mate Kukri's [deguard](deguard.md) utility.

Errata
------

This section should not concern you, if you're using newer Libreboot releases.
This section largely concerns *bugs* which existed in older releases, pertaining
to this documentation, and design changes made accordingly.

NOTE: As of Libreboot releases from May 2024 onward, the Intel MRC is no longer
included for Haswell; MRC is a firmware for raminit, but we now provide native
raminit written by Angel Pons, for the coreboot project. 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. Older images with FSP baked
directly into release images had `_fsp` in the file names; newer images that
need it to be injected have `_vfsp` in the file name. Releases from Libreboot
20241206 release series at revision 8 or higher, or releases newer than the
20241206 series, no longer include `_fsp` images as they are set `release="n"`
in the build system; these releases include `_vfsp` images instead. Newer
targets added in the future, that need FSP, will also have `_vfsp` in the
file name, for consistency.

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 it can be done with free software exclusively, then it should be
done with free software exclusively. 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.