update safety advice for ifdtool/inject

also tidy up the ivy_has_common guide. the .uk one was in
english anyway so i removed that one.

reference the platform option needed in ifdtool, on kabylake

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

site/docs/install/ivy_has_common.md

@@ -3,9 +3,21 @@ title: Insert vendor files not included in release images
 x-toc-enable: true
 ...
 
-Please make sure to install [build dependencies](../build/) if following this
+**Install build dependencies first**
-guide, and note that this guide assumes you use [lbmk.git](../git.md), not the
+================================
-release archives, even if you're using release *ROM images*, which is fine.
+
+**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
@@ -23,13 +35,6 @@ 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!
 
-Therefore, you should just follow this guide if in any doubt. Otherwise, the
-freedom status page lists all boards that require vendor files, and it says
-what they are. This is because Libreboot cannot directly distribute some of them,
-but they are extracted from vendor updates at build time, and inserted into
-images; when those images are then archived for release, the non-redistributable
-filejs are removed.
-
 The same logic can be used after the fact, to re-download and re-insert these
 files; the page that you're reading now will tell you how to do so.
 
@@ -38,7 +43,7 @@ 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 into ROM
+Injecting vendor files ROMs tarball
 ------------------------------------
 
 You must determine the correct board name, for your board, based on the list
@@ -53,13 +58,25 @@ Run the injection script pointing to the release archive you downloaded:
 
 	./vendor inject 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/`
+
+*This is the recommended way to do it, injecting into the tarball.*
+
+Injecting vendor files into single ROMs
+---------------------------------------
+
 **You are strongly advised only to insert it on the tarball, because then
 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:**
 
-The script can automatically detect the board as long as you do not change the file name.
+**However, when injecting into the tarball in bulk like that, lbmk currently
-You can then find flash-ready ROMs in `/bin/release/`
+cannot change the MAC addresses automatically, using the `-m` option mentioned
+below.**
+
+**Therefore, if you want to rely on insertion into the tarball, you can just
+copy the ROM you want and [change the MAC address manually](nvmutil.md).**
 
 Alternatively, you may patch only a single rom file, but you must supply the
 correct board target name as alluded to above.
@@ -72,6 +89,12 @@ For example:
 
 	./vendor inject -r x230_libreboot.rom -b x230_12mb -m 00:f6:f0:40:71:fd
 
+You are *strongly* advised to inject the tarballs instead. However, so long as
+you're careful, injecting into single ROM images is perfectly safe. Just know
+once more that the checksum verification is unavailable in the latter, so you
+must absolutely ensure that you specified the correct board with the `-b`
+option.
+
 Check that the files were inserted
 ==================================
 

site/docs/install/ivy_has_common.uk.md

@@ -1,179 +0,0 @@
----
-title: Insert vendor files not included in release images
-x-toc-enable: true
-...
-
-Regarding vendorfile insertion: if unsure, just follow these instructions.
-If a given target does not require vendor files, none will be inserted.
-
-**TODO: Re-translate this again to Ukrainian. It was translated before, but
-the english page got heavily re-written.**
-
-Libreboot can't directly distribute *all* of these blobs, 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.**
-
-**NOTE: This page also applies to PM45 machine Dell Latitude E6400 if it
-contains an Nvidia GPU (Libreboot vendor scripts can insert the VGA ROM)**
-
-This is not a general purpose installation guide, but you *should read it*
-before installing Libreboot! *This* guide *must* be followed, no matter what
-method you use to install Libreboot; even if you compile from source, you should
-still read this page for later reference.
-
-For how to use an external programmer see the [25xx NOR flashing guide](/docs/install/spi.html)
-
-Introduction
-============
-
-**PLEASE MAKE SURE you have build dependencies installed first. Although you
-do not need to re-compile release ROMs, you should follow these instructions
-before reading the instructions below:
-<https://libreboot.org/docs/build/#first-install-build-dependencies>**
-
-Coreboot is nominally free software, but requires certain vendor code on some
-boards, for certain functionalities; it differs per board, and some boards do
-not require vendor code of any kind in the flash. We cover this more thoroughly in
-the [Freedom Status](../../freedom-status.md) page and in the [Binary Blob
-Reduction Policy](../../news/policy.md).
-
-Well, not all of these files are freely redistributable. Coreboot does provide
-vendor files in some cases, if the vendor has allowed it. In other cases,
-extraction from factory firmware is required, or you can extract them from
-vendor-supplied updates - Libreboot's build system does the latter.
-
-When you [compile Libreboot ROM images from source](../build/), Libreboot will
-automatically download any given vendor files required, for any given board
-target. This is done without user intervention, and only when absolutely needed
-to make the machine boot properly.
-
-The problem?
-------------
-
-Well, if the files cannot be freely redistributed, then we can't provide them.
-So how do we handle *that*, in the context of Libreboot releases?
-
-The solution
-------------
-
-The answer is very simple:  these files are **NOT** provided, at all! However,
-the very same logic used by the build system can be run standalone, to re-insert
-these vendor files on release ROMs. The `inject` script detects what files are
-needed for your ROM image.
-
-The script will detect what board you're inserting on, or you can manually tell
-it what board, and it will fetch them for you, inserting them, so that your
-board is ready to flash - flashing it without these required files may result in
-a brick.
-
-Vendor file locations
---------------
-
-During auto-download of files, they are saved to these locations within the
-Libreboot build system:
-
-* ME firmware: `vendor/*/me.bin` - the `*` can be any given directory. Different ones will
-  be used by given boards, but the directory name may not match the board
-  target name.
-* SMSC SCH5545 fan control firmware (for Dell T1650): `vendor/t1650/sch5545ec.bin` -
-  ditto 7010/9010 MT/SFF optiplex machines.
-* SMSC KBC1126 embedded controller firmware, on HP EliteBooks: `ec/`
-* Intel MRC firmware, provides raminit on HP EliteBook 820 G2
-
-The above list refers to the *non-redistributable files*, and these are not
-directly included in releases. These are auto-downloaded during the build.
-The `me.bin` files are produced by extracting them from vendor updates and
-neutering them with `me_cleaner` so that Intel ME is disabled during early boot.
-
-Inject vendor files into ROM
-------------------------------------
-
-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.
-Run the injection script pointing to the release archive you downloaded:
-
-	./vendor inject /path/to/libreboot-20230319-18-g9f76c92_t440pmrc_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, but you must supply the
-correct board target name as alluded to above.
-For example:
-
-	./vendor 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:
-
-	./vendor inject -r x230_libreboot.rom -b x230_12mb -m 00:f6:f0:40:71:fd
-
-Check that the files were inserted
-==================================
-
-You *must* ensure that the files were inserted.
-
-Some examples of how to do that in lbmk:
-
-	./update trees -d coreboot TREENAME
-
-Now you find `cbutitls/default`, which is a directory containing `cbfstool`
-and `ifdtool`. Do this on your ROM image (`libreboot.rom` in the example
-below):
-
-	./cbutils/default/cbfstool libreboot.rom print
-
-You should check that the files were inserted in cbfs, if needed; for example,
-EC firmware or MRC firmware.
-
-Next:
-
-	./cbutils/default/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 otherwise isn't a bunch
-of code, then the Intel ME firmware wasn't inserted.
-
-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
-======
-
-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)
-
-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).

site/docs/install/nvmutil.md

@@ -170,12 +170,24 @@ with `make`, to get an ifdtool binary.
 
 To make internal flashing possible later on, you might do:
 
-	ifdtool --unlock rom.bin
+	ifdtool --unlock rom.bin # READ THE WARNING BELOW FIRST
+
+**WARNING: On ThinkPad T480/T480s and OptiPlex 3050 Micro, do this instead:**
+
+	ifdtool --platform sklkbl --unlock rom.bin
 
 Running this command will create a modified image,
 named `rom.bin.new`. This file will have all regions set
 to read-write, per configuration in the Intel Flash Descriptor.
 
+Note: if you want the original image to be modified, without needing to
+keep track of `rom.bin.new` as mentioned above, use the -O switch. For example,
+repeating the above command:
+
+	ifdtool --unlock rom.bin -O rom.bin
+
+(add the `--platform` option if you need to)
+
 In addition to unlocked regions, you may wish to *neuter* the
 Intel Management Engine, removing all the nasty spying features
 from it, using `me_cleaner`. See:
@@ -188,7 +200,7 @@ article, so you should read their documentation.
 
 Now run this:
 
-	ifdtool -x rom.bin
+	ifdtool -x rom.bin # For T480/3050micro, add: --platform sklkbl
 
 Several files will be created, and the one you need to
 operate on is named `flashregion_3_gbe.bin` so please
@@ -198,7 +210,7 @@ Read the notes below about how to use the `nvmutil` program,
 operating on this file. When you're done, you can insert the
 modified GbE file back into your ROM image, like so:
 
-	ifdtool -i gbe:flashregion_3_gbe.bin rom.bin
+	ifdtool -i gbe:flashregion_3_gbe.bin rom.bin  # For T480/3050micro, add: --platform sklkbl
 
 This will create the file `rom.bin.new`, which contains
 your modified GbE section with the NVM images inside; this
@@ -215,6 +227,16 @@ region, like so:
 
 	flashprog -p internal --ifd -i gbe -w rom.bin.new
 
+**WARNING: If using `--ifd` in flashprog, note that flashprog probably doesn't
+have anything similar to the `--platform` option in ifdtool. Therefore, you
+way wish to specify the regions manually. You can do this quite simply, by:**
+
+	ifdtool -f layout.txt rom.bin  # For T480/3050micro, add: --platform sklkbl
+
+and instead of `--ifd` in flashprog, use:
+
+	flashprog -p internal -l layout.txt -i gbe -w rom.bin.new
+
 If you're running flashprog from host CPU on the target
 system, and it's dual flash, you can just flash the
 concatenated image, which you created earlier by running

site/freedom-status.uk.md

@@ -211,7 +211,7 @@ Git, ні в випусках. Де необхідно, Libreboot надає
 оригінального образа продавця, в регіоні ME інтегральної схеми флеш-пам'яті).
 
 Ви можете дізнатись про це більше на наступній сторінці:
-[docs/install/ivy_has_common.uk.md](docs/install/ivy_has_common.uk.md)
+[docs/install/ivy_has_common.md](docs/install/ivy_has_common.md)
 
 Прошивка ME є *обов'язковою* на майже всіх платформах Intel, або машина
 *вимкнеться* після 30 хвилин. В нейтралізованому налаштуванні, код BringUp