From e33cba84da44af3ede4823db44b9ce90ee852ebd Mon Sep 17 00:00:00 2001 From: Leah Rowe <leah@libreboot.org> Date: Fri, 13 Oct 2023 00:45:54 +0100 Subject: [PATCH] docs/build: add section: post-compilation it also mentions specific binary blobs such as nvidia vga rom (dell e6400) and cpu microcode. Signed-off-by: Leah Rowe <leah@libreboot.org> --- site/docs/build/index.md | 114 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 114 insertions(+) diff --git a/site/docs/build/index.md b/site/docs/build/index.md index 7ee7c8e..5e40f2a 100644 --- a/site/docs/build/index.md +++ b/site/docs/build/index.md @@ -120,6 +120,120 @@ individual parts of the build system manually, if you choose. This may be beneficial when you're making changes, and you wish to test a specific part of lbmk. +Post-compilation steps +====================== + +So you compiled your Libreboot image? Congratulations! + +Before you flash, please make sure that you *dumped* two copies of the original +firmware just in case (verifying the hashes of each dump, to ensure that they +match), using the `-r` option in flashrom. + +There are some additional considerations: + +Regarding binary blobs +---------------------- + +Firstly, you should read the Libreboot *Binary Blob Reduction Policy*: +<https://libreboot.org/news/policy.html> + +A lot of mainboards in Libreboot will boot entirely with free software, +but there are certain newer mainboards supported in Libreboot +that need binary blobs added to them, mostly for minor initialisation tasks. + +They are *automatically* inserted during the build process, but then deleted +during the *release* process; images built directly from lbmk can be flashed +without further modification, but release images need to have these files +re-inserted (e.g. KBC1126 EC firmware on HP EliteBooks). Please read this page +for context: +<https://libreboot.org/docs/install/ivy_has_common.html> + +The scripts under directory `script/update/vendor/` are the ones that do this. +Specifically, `script/update/vendor/download`. The benefit of this is that you +do not need to extract anything from the original vendor image (e.g. Lenovo +UEFI image). + +To know if this was performed on your board, you can read the Freedom Status +page which documents which files are used (if any), on which boards: +<https://libreboot.org/freedom-status.html> + +There are specific files that you must know about, so they will be covered +next: + +### Regarding CPU microcode + +Libreboot release archives provide ROMs with or without CPU microcode updates, +but the newest revisions of lbmk (from `lbmk.git`) *only* build ROM images that +contain microcode updates, by default. Libreboot's build system contains a script +that will generate release archives, and this is used to provide Libreboot +releases; this script is what provides the images with microcode removed, +alongside the default ones generated by lbmk during the build. + +Please read: +<https://libreboot.org/freedom-status.html#cpu-microcode> + +The linked page has info, and includes instructions about how to manually remove +them, if you wish to do so. Removal of CPU microcode updates (on Intel/AMD +processors) will result in unpredictable security/stability issues, so beware. + +Further context is provided in the Libreboot *Binary Blob Reduction Policy*: +<https://libreboot.org/news/policy.html> + +We *recommend* that you do not delete these updates, but you have the freedom +to choose. Additionally: we have only tested certain mainboards under this +configuration. To know which ones they are, do this in `lbmk.git`: + + cd config/coreboot/ + git grep microcode_required + +Example entry: + + e6400_4mb/target.cfg:microcode_required="n" + +If it says `="n"`, that means it has been tested. That *does not* mean it will +be stable, it's just that we're reasonably sure it will at least *boot* most +of the time, but you should expect random instability e.g. kernel panics. + +If a given mainboard *excludes* `microcode_required` in `target.cfg`, or if +it says `microcode_required="y"`, then the release ROMs will only contain +microcode updates. Manual removal (as above) is still possible, but it has +not been tested and is not recommended. + +NOTE: ARM-based chromebooks (that Libreboot supports) don't use microcode at +all. This section is only revelant for x86 (Intel/AMD). + +### Regarding Nvidia GPU ROM (Dell Latitude E6400) + +Dell Latitude E6400 comes in two variants: Nvidia graphics, or Intel graphics. +More information is available on the page: +<https://libreboot.org/docs/hardware/e6400.html> + +The intel graphics model can boot with coreboot's native video initialisation, +which is free software. The *Nvidia* model (comes with Nvidia GPU) requires +proprietary code called a *VGA Option ROM* to initialise the video display in +early boot. + +Libreboot automatically fetches this during the build process, inserting it into +the very same ROM image that can be flashed on either model, but the VGA ROM +will only be *executed* if you actually have the Nvidia ROM. + +ALSO: Libreboot 20230625 did not support Nvidia models at all (only Intel). + +Pre-built ROM images from release archives after 20230625 will *not* contain +this file by default, but it will be present if you compiled directly from lbmk. +To remove it, do this: + + ./cbutils/default/cbfstool libreboot.rom remove -n pci10de,06eb.rom + +The cbfstool binary was compiled when your image (target `e6400_4mb`) was +compiled, which can alter the file system within your coreboot image. + +Obviously, removing this VGA ROM will mean that the ROM image will only work +correctly on Intel GPU variants of E6400, but you probably knew that already! + +(If you're using a release archive instead, you can re-insert the VGA ROM by +following [these instructions](../install/ivy_has_common.md)) + 20230625 build error (release archive) ====================================== -- GitLab