update the vendorfile injection guide

the script was re-written recently, adding a bunch
of safety changes.

Signed-off-by: Leah Rowe <info@minifree.org>

site/docs/install/dell3050.md

@@ -289,12 +289,6 @@ 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 `dell3050micro_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

site/docs/install/ivy_has_common.md

@@ -3,6 +3,13 @@ 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.**
+
 WARNING: eCryptfs file name limits
 =================================
 
@@ -45,22 +52,22 @@ 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!
 
-The same logic can be used after the fact, to re-download and re-insert these
+If in doubt, you should simply follow these instructions. If your board
-files; the page that you're reading now will tell you how to do so.
+doesn't need vendor files, the tar archive won't be modified.
 
-*If in doubt, just follow these instructions anyway; if your board doesn't need
+MAC address
-vendor files inserted, nothing will happen. You only need to follow this guide
+-----------
-if you use release ROMs; if you're building directly from source, using the
-Libreboot build system, then you can just flash the result.*
 
-Injecting vendor files ROMs tarball
+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
 ------------------------------------
 
-You must determine the correct board name, for your board, based on the list
-generated when running this command:
-
-	./mk -b coreboot list
-
 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.
@@ -68,51 +75,125 @@ 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.
-You can then find flash-ready ROMs in `/bin/release/`
 
-*This is the recommended way to do it, injecting into the tarball.*
+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*.
 
-Injecting vendor files into single ROMs
+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.
 
-**You are strongly advised only to insert it on the tarball, because then
+Behaviour changes in Libreboot 20241206 rev8
-checksums are verified to ensure that the vendor files were inserted correctly.
+--------------------------------------------
-Otherwise, you can do it manually on each individual image, specifying the
-board name with the instructions provided below:**
 
-**However, when injecting into the tarball in bulk like that, lbmk currently
+*Older* versions of this script would have produced the injected images under
-cannot change the MAC addresses automatically, using the `-m` option mentioned
+the `bin/release/` directory, and/or allow you to do it on specific ROM images.
-below.**
 
-**Therefore, if you want to rely on insertion into the tarball, you can just
+The *current* version, pertaining to this documentation, *only* supports injecting
-copy the ROM you want and [change the MAC address manually](nvmutil.md).**
+tarballs, because the tarball-based mechanism verifies checksums on images,
+after insertion.
 
-Alternatively, you may patch only a single rom file, but you must supply the
+The older versions of this script would have left the tarball unmodified, while
-correct board target name as alluded to above.
+producing `bin/release/` containing your images.
-For example:
 
-	./mk inject -r x230_libreboot.rom -b x230_12mb
+The *current* version, pertaining to this documentation, modifies the tarball
+itself. You can inject and un-inject. To un-inject, you can do:
 
-Optionally, you can use this script to modify the mac address of the rom with the `-m` flag.
+	./mk inject libreboot-RELEASE_targetname.tar.xz nuke
-For example:
 
-	./mk inject -r x230_libreboot.rom -b x230_12mb -m 00:f6:f0:40:71:fd
+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.
 
-You are *strongly* advised to inject the tarballs instead. However, so long as
+The nuke command is available because Libreboot's build system uses it when
-you're careful, injecting into single ROM images is perfectly safe. Just know
+producing release archives. You otherwise shouldn't use `nuke` yourself, except
-once more that the checksum verification is unavailable in the latter, so you
+for testing purposes or if you're just curious.
-must absolutely ensure that you specified the correct board with the `-b`
+
-option.
+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, but not when running it manually on an individual image;
+release tarball.
-checking it manually is useful for the latter, but you should probably just
+
-insert it into the 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:
 
@@ -129,7 +210,15 @@ 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.
+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:
 
@@ -140,16 +229,15 @@ Run hexdump on it:
 
 	hexdump flashregion_2_intel_me.bin
 
-Check the output. If it's all `0xFF` (all ones) or otherwise isn't a bunch
+Check the output. If it's all `0xFF` (all ones) or zeroes or otherwise isn't a
-of code, then the Intel ME firmware wasn't inserted.
+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.
 
-NOTE: the MAC changer makes use of `nvmutil`, which you can read more about in
-the [nvmutil documentation](nvmutil.md).
-
 Errata
 ======
 
@@ -166,6 +254,11 @@ raminit. The following targets no longer exist in the build system:
 * `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
@@ -175,3 +268,5 @@ 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.

site/docs/install/latitude.md

@@ -47,7 +47,7 @@ Latitude E6400
 Vendor files not required for Dell Latitude E6400 if you have the Intel GPU.
 
 If you have the Nvidia model, please use the `e6400nvidia_4mb` target, and
-make sure to run the inject script.
+make sure to run the [inject script](ivy_has_common.md) prior to flashing.
 
 E6400 nvidia issues
 -------------------

site/docs/install/t420_external.md

@@ -18,26 +18,12 @@ The following instructions expect you to have these on hand:
 Preparing a release Rom
 -----------------------
 
-You must patch the release rom with the necessary vendor files *and then* flash it to your board.
+**Please follow this prior to flashing, or you may brick your machine.**
 
-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.
+Please [inject vendor files](ivy_has_common.md) prior to flashing. You can also
-
+use this guide to change the built-in MAC address for your Intel Gigabit
-If you only wish to flash a release rom then the process of injecting the necessary files is quite simple.
+Ethernet device; doing so is advisable, because otherwise you will have a
-Run the injection script pointing to the release archive you downloaded:
+default, generic MAC address.
-	
-	./mk inject /path/to/libreboot-20230423_t420_8mb.tar.xz
-
-The script can automatically detect the board as long as you do not change the file name.
-You can then find flash-ready ROMs in `/bin/release/`
-
-Alternatively, you may patch only a single rom file.
-
-	./mk inject -r t420_libreboot.rom -b t420_8mb
-
-Optionally, you can use this script to modify the mac address of the rom with the `-m` flag.
-For example:
-
-	./mk inject -r t420_libreboot.rom -b t420_8mb -m 00:f6:f0:40:71:fd
 
 Disassembly
 -----------

site/docs/install/t440p_external.md

@@ -32,33 +32,12 @@ You can now follow the rest of the instructions.
 Preparing a release Rom
 -----------------------
 
-You must patch the release rom with the necessary vendor files *and then* flash it to your board.
+**Please follow this prior to flashing, or you may brick your machine.**
 
-Lbmk includes a script that will automatically inject the necessary files into a rom file.
+Please [inject vendor files](ivy_has_common.md) prior to flashing. You can also
-The script can determine the board automatically if you have not changed the name, but you can also manually set the board name with the `-b` flag.
+use this guide to change the built-in MAC address for your Intel Gigabit
-
+Ethernet device; doing so is advisable, because otherwise you will have a
-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.
+default, generic MAC address.
-
-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 /path/to/libreboot-RELEASE_targetname.tar.xz
-
-The script can automatically detect the board as long as you do not change the file name.
-You can then find flash-ready ROMs in `/bin/release/`
-
-Alternatively, you may patch only a single rom file.
-For example:
-
-	./mk inject -r t440p_libreboot.rom -b t440plibremrc_12mb
-
-Optionally, you can use this script to modify the mac address of the rom with the `-m` flag.
-For example:
-
-	./mk inject -r t440p_libreboot.rom -b t440plibremrc_12mb -m 00:f6:f0:40:71:fd
-
-NOTE: this makes use of `nvmutil`, which you can read more about in
-the [nvmutil documentation](nvmutil.md).
 
 Splitting The Rom
 -----------------

site/docs/install/t480.md

@@ -87,6 +87,16 @@ This port is implemented in Libreboot by merging Mate Kukri's T480/T480s
 patchset. See: <https://review.coreboot.org/c/coreboot/+/83274> - as of 5
 December 2024, Libreboot's code matches that of patchset 22.
 
+Preparing a release Rom
+-----------------------
+
+**Please follow this prior to flashing, or you may brick your machine.**
+
+Please [inject vendor files](ivy_has_common.md) prior to flashing. You can also
+use this guide to change the built-in MAC address for your Intel Gigabit
+Ethernet device; doing so is advisable, because otherwise you will have a
+default, generic MAC address.
+
 Absolutely unsigned Intel ME!
 -----------------------------
 
@@ -701,6 +711,9 @@ for details as to how to fix this.
 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
 --------
 

site/docs/install/w541_external.md

@@ -35,33 +35,12 @@ You can now follow the rest of the instructions.
 Preparing a release Rom
 -----------------------
 
-You must patch the release rom with the necessary vendor files *and then* flash it to your board.
+**Please follow this prior to flashing, or you may brick your machine.**
 
-Lbmk includes a script that will automatically inject the necessary files into a rom file.
+Please [inject vendor files](ivy_has_common.md) prior to flashing. You can also
-The script can determine the board automatically if you have not changed the name, but you can also manually set the board name with the `-b` flag.
+use this guide to change the built-in MAC address for your Intel Gigabit
-
+Ethernet device; doing so is advisable, because otherwise you will have a
-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.
+default, generic MAC address.
-
-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 /path/to/libreboot-RELEASE_targetname.tar.xz
-
-The script can automatically detect the board as long as you do not change the file name.
-You can then find flash-ready ROMs in `/bin/release/`
-
-Alternatively, you may patch only a single rom file.
-For example:
-
-	./mk inject -r w541_libreboot.rom -b w541_12mb
-
-Optionally, you can use this script to modify the mac address of the rom with the `-m` flag.
-For example:
-
-	./mk inject -r w541_libreboot.rom -b w541_12mb -m 00:f6:f0:40:71:fd
-
-NOTE: this makes use of `nvmutil`, which you can read more about in
-the [nvmutil documentation](nvmutil.md).
 
 Splitting The Rom
 -----------------
@@ -76,7 +55,6 @@ Flash the top chip with top.rom, and tho bottom chip with bottom.rom.
 Don't worry about knowing which chip is which on a standard setup; flashprog will let you know if the 
 image size is incorrect for the chip you're flashing.
 
-
 Disassembly
 -----------
 

site/docs/install/x230_external.md

@@ -30,31 +30,12 @@ You can now follow the rest of the instructions.
 Preparing a release Rom
 -----------------------
 
-You must patch the release rom with the necessary vendor files *and then* flash it to your board.
+**Please follow this prior to flashing, or you may brick your machine.**
 
-Lbmk includes a script that will automatically inject the necessary files into a rom image.
+Please [inject vendor files](ivy_has_common.md) prior to flashing. You can also
-The script can determine the board automatically if you have not changed the name, but you can also manually set the board name with the `-b` flag.
+use this guide to change the built-in MAC address for your Intel Gigabit
-
+Ethernet device; doing so is advisable, because otherwise you will have a
-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.
+default, generic MAC address.
-Run the injection script pointing to the release archive you downloaded:
-
-	./mk inject /path/to/libreboot-20230319-18-g9f76c92_t440_12mb.tar.xz
-
-The script can automatically detect the board as long as you do not change the file name.
-You can then find flash-ready ROMs in `/bin/release/`
-
-Alternatively, you may patch only a single rom file.
-For example:
-
-	./mk inject -r x230_libreboot.rom -b x230_12mb
-
-Optionally, you can use this script to modify the mac address of the rom with the `-m` flag.
-For example:
-
-	./mk inject -r x230_libreboot.rom -b x230_12mb -m 00:f6:f0:40:71:fd
-
-NOTE: this makes use of `nvmutil`, which you can read more about in
-the [nvmutil documentation](nvmutil.md).
 
 Splitting The Rom
 -----------------
@@ -69,8 +50,6 @@ Flash the top chip with top.rom, and tho bottom chip with bottom.rom.
 Don't worry about knowing which chip is which on a standard setup; flashprog will let you know if the 
 image size is incorrect for the chip you're flashing.
 
-
-
 Disassembly
 -----------
 

site/docs/maintain/index.md

@@ -1497,7 +1497,8 @@ Helper functions for downloading and injecting vendor files. How to use:
 	./mk inject ARGUMENTS
 	./mk -d coreboot TARGET
 
-Refer elsewhere in the documentation for how to handle vendor files.
+Refer elsewhere in the documentation for how to handle vendor files, and/or
+read [the guide](../install/ivy_has_common.md).
 
 script/
 =======

site/news/e6400nvidia.md

@@ -31,6 +31,19 @@ than Libreboot 20231021 only support the Intel GPU variant.**
 The 6400 XFR testing+photo was provided, courtesy Mark Cornick (`mcornick` on
 Libreboot IRC).
 
+Preparing a release Rom
+-----------------------
+
+NOTE: Not strictly required on Intel graphics models, but still useful for
+changing the MAC address.
+
+**Please follow this prior to flashing, or you may brick your machine.**
+
+Please [inject vendor files](ivy_has_common.md) prior to flashing. You can also
+use this guide to change the built-in MAC address for your Intel Gigabit
+Ethernet device; doing so is advisable, because otherwise you will have a
+default, generic MAC address.
+
 Dell Latitude E6400 with Nvidia GPU
 ===================================