- -

Configuring libreboot

- -

- Before building a ROM in libreboot (or coreboot, for that matter), you need to configure it. - Configuration files should already be included, so you don't need to do anything. This information - is only for reference. If you are updating or modifying coreboot-libre, and need to update the configs - in any way, refer to ../maintain/index.html#newboard_libreboot. -

- -

- If you've already built a kernel before, you know how to use this interface. -

- -

- dmidecode -

- There is certain information that can be useful to enter in particular: -

Local version string
SMBIOS Serial Number
SMBIOS Manufacturer
SMBIOS Version
SMBIOS Product name

- This information can be obtained using:
- $ sudo dmidecode
- # dmidecode -

- Specifically, it's good practise to enter the same information for libreboot that you found when running this - with the original BIOS or firmware. libreboot has already done this for you. This information is for reference, - in the hope that it will be useful. -

- In practise, this information is useless and you can - just leave it on the defaults that coreboot uses (this - is what libreboot does, on most boards). -

- -

GRUB payload

- -

- GRUB is one of the payloads that libreboot targets. -

- -

- Configurations are then saved as files called ".config". Copies of each configuration used - for each system type by the libreboot build scripts are stored in resources/libreboot/config/grub/ -

- -

- Generic configuration file (file: resources/libreboot/config/payload/board/config) -

General setup / Expert mode = enable
General / Use CMOS for configuration values = enable
Mainboard / Mainboard vendor = Name of manufacturer
Mainboard / Mainboard model = Model name
Mainboard / ROM chip size = size of flash chip
Chipset / Include CPU microcode in CBFS = Do not include microcode updates
Devices / Use native graphics initialization = enable
- Display / Keep VESA framebuffer = disable (disable for text-mode graphics, enable for coreboot vesa framebuffer) -
- Libreboot provides this with text-mode enabled by default, but it automatically patches a copy of the config at build time - to enable coreboot framebuffer for a separate set of ROM images, in each system.
-
Generic Drivers / USB 2.0 EHCI debug dongle support = Enable
Generic Drivers / Enable early (pre-RAM) usbdebug = Enable
Generic Drivers / Type of dongle = Net20DC or compatible
Generic Drivers / Digitizer = Present
Console / USB dongle console output = enable
Payload / Add a payload = An ELF executable payload
Payload / Payload path and filename = grub.elf

- Now go back into Devices: -

Devices / Run VGA Option ROMs = disable
Devices / Run Option ROMs on PCI devices = disable

- The resulting .config file was saved as resources/libreboot/config/payload/board/config and is used by the build - scripts for this system. -

- -

Configuring libreboot for chromebooks

- Depthcharge is one of the payloads that libreboot targets. -

- Configurations are then saved as files called ".config". Copies of each configuration used - for each system type by the libreboot build scripts are stored in resources/libreboot/config/depthcharge/ -

- Generic configuration file (file: resources/libreboot/config/depthcharge/board/config) -

Mainboard / Mainboard vendor = Google
Mainboard / Mainboard model = name of model
Chipset / ChromeOS / Build for ChromeOS = enable
Chipset / ChromeOS / Verify firmware with vboot. = disable
Payload / Add a payload = An ELF executable payload
Payload / Payload path and filename = depthcharge.elf

- The resulting .config file was saved as resources/libreboot/config/depthcharge/board/config and is used by the build - scripts for this system. -

- -

How to build the ROM images

diff --git a/docs/index.html b/docs/index.html index 48bf18f1..c278230f 100644 --- a/docs/index.html +++ b/docs/index.html @@ -34,12 +34,7 @@

What systems can I use libreboot on? - NOTE: GNU/Linux is expected to be running on your device.

How to install libreboot

How to install GNU/Linux on a libreboot system

- How to compile the libreboot source code (optional, intended for developers) -

Information about libreboot's build system.

How to compile the libreboot source code (optional, intended for developers)

Hardware security

Hardware maintenance

Depthcharge payload

diff --git a/docs/maintain/index.html b/docs/maintain/index.html deleted file mode 100644 index 81f7e56a..00000000 --- a/docs/maintain/index.html +++ /dev/null @@ -1,656 +0,0 @@ - - - - - - - - - Maintaining libreboot - - - - -

- -

Maintaining libreboot

- -

- This section relates to maintaining libreboot. -

- Do not follow anything here to the letter; is it only a rough guide - representing how libreboot is maintained (for reference). -

- This section of the documentation applies mainly to the - development version of libreboot, which is hosted in a git - repository. It is not intended for the release versions of - libreboot. -

- -

Overview
- Updating coreboot-libre -
- Adding a new board to libreboot
- Add/remove/modify patches in coreboot-libre
-
- Updating GRUB -
-
- Updating depthcharge -
- Updating flashrom -
- Updating bucts -
- Updating MemTest86+ -

- -

- Or Back to main index. -

- -

Overview

- -

- The way the libreboot project is run is very similar to how - a GNU/Linux distribution project is run (but for the boot - firmware, not your operating system). Thus, libreboot is - a coreboot distribution. -

- This page demonstrates on a high level how - libreboot is maintained, how the project is run, how everything - goes together, etc. For a more detailed guide, refer to each - subsection for the various components/modules used in libreboot. -

- -

- Back to top of page. -

- -

Updating coreboot-libre

- -

- NOTE: it helps to own all libreboot-compatible systems here, - or have reliable (and fast) access to a team of testers. -

- -

- Coreboot-libre is the name of the deblobbed coreboot sources - used in libreboot. It is also the name of the collection - of scripts used for deblobbing coreboot, on each new update. -

- -

- This section shows an example of how to update (re-base) to - the latest version of coreboot, how to update the deblobbing - scripts, and so on. This does not teach you how to - change what custom patches are used, nor does it tell - you how to add new boards to libreboot. It assumes that you - simply want to re-base to the latest version (for instance, - there could be bug fixes that you want). For those things - not listed in this section, you can refer to other sections - on this page instead. -

- -

- Open these files in your editor (you will most likely be editing them): -

resources/scripts/helpers/download/coreboot
resources/scripts/helpers/build/module/coreboot
resources/utilities/coreboot-libre/deblob
resources/utilities/coreboot-libre/nonblobs
resources/utilities/coreboot-libre/nonblobs_notes
resources/scripts/helpers/build/roms/helper
resources/scripts/helpers/build/roms/withgrub

- -

- If you already had a coreboot/ directory in your libreboot - tree, delete it:
- $ rm -Rf coreboot/ -

- -

- Firstly, download coreboot. Do not use ./download coreboot - for this, just clone coreboot, as it does in that script, like so:
- $ git clone http://review.coreboot.org/coreboot -

- -

- $ cd coreboot/
- Get the ID of the latest commit in this clone, by reading the commit ID using - e.g.:
- $ git log
- In resources/scripts/helpers/download/coreboot you will - find a line that says git reset --hard and then - a commit ID next to it. Replace this with the commit ID of the latest - commit from the coreboot version that you just downloaded. -

- You must also checkout the vboot submodule:
- $ git submodule update --init --checkout -- 3rdparty/vboot/ -

- Delete the .git* resources. For example:
- $ rm -Rf .git* 3rdparty/*/.git*
- ...this is to avoid the deblobbing script from picking up files - in there as blobs, which would be only false positives and - increase the amount of time taken. Now come out of coreboot:
- $ cd ../ -

- -

- Check all coreboot file names/paths in deblob; if any - of them no longer exist at that name/path in the coreboot tree that you downloaded, - delete the reference(s) in deblob. -

- -

- Check all coreboot file names/paths in nonblobs; if - any of them no longer exist at that name/path in the coreboot tree that you downloaded, - delete the reference in nonblobs. -

- -

- Now, back in the main root directory of libreboot (git repository), - run the deblob script. This is to prevent the findblobs - scripts from finding the blobs that are already deleted - when running the deblob script. Like so:
- $ ./resources/utilities/coreboot-libre/deblob -

- -

- Now search for new blobs:
- $ cd resources/utilities/coreboot-libre/
- $ ./findblobs
- WARNING: this will take a *long* time. Be patient! - What this will do is look through the coreboot source directory, - looking for blobs. It will not find the blobs that you deleted - before (because they no longer exist), and it will ignore any - files listed in nonblobs. -

- -

- Once the findblobs script has finished, check the file - tocheck (from the root, this will be resources/utilities/coreboot-libre/tocheck). - These are the files detected as blobs; some might be blobs, some not. - The findblobs script doesn't know how to determine between blobs - and non-blobs, it only knows patterns. Distinguishing between blobs and - non-blobs must be performed by you, the human being. -

- Files in tocheck that you identify as blobs, - should be added appropriately to resources/utilities/coreboot-libre/deblob -
- Files in tocheck that you identify as non-blobs, - should be added appropriately to resources/utilities/coreboot-libre/nonblobs - - also, if you feel it necessary, add an explanation of it in - resources/utilities/coreboot-libre/nonblobs_notes -

- -

- Now come back to the main libreboot root directory (root - of the git clone). If you are still in resources/utilities/coreboot-libre/ - for instance, you would do something like:
- $ cd ../../../ -

- -

- Now delete the coreboot directory:
- $ rm -Rf coreboot/ -

- -

- Download coreboot again, only this time, using the download - script. The download script also applies custom patches - to coreboot (see resources/scripts/helpers/download/coreboot); - if they do not apply anymore, you will have to re-base them - and then update resources/scripts/helpers/download/coreboot - accordingly. Anyway, download coreboot like so:
- $ ./download coreboot -

- -

- If the custom patches no longer apply, and you have to re-base - (or replace?) some patches, please do this in coreboot upstream, - not in libreboot. Then re-include new patches from upstream, - into libreboot. Here is coreboot's guide for contributing - patches:
- http://www.coreboot.org/Git. -

- -

- Update all configs:
- $ ./build config grubupdate
- $ ./build config dcupdate
- This simply takes all of the coreboot .config files from - resources/libreboot/config/ and does make oldconfig - on them. It usually works. If it doesn't, you'll need to recreate - those configs from scratch using ./build config grubreplace - or ./build config dcreplace (optionally - add a config name), or ./build config grubmodify - or ./build config dcmodify (ditto) - (see ../git/index.html#config) -

- -

- Finally, build *all* ROM images using the instructions at - ../git/index.html, to verify - that everything still builds. -

- -

- Once you've verified that building isn't broken, test *all* - boards (you don't need to test all ROM images, only one - vesafb and one txtmode image for each configuration). If you - do not have all systems supported in libreboot, then you will - need to get other testers for those boards. -

- -

- If you have established a build issue, or a board no longer - works (booting issues, bugs during/after boot, etc), you'll - need to fix it upstream: - http://www.coreboot.org/Git - and then re-update coreboot (or apply patches from upstream). -

- -

- You should also test the resulting ROM images from building - with the new or modified coreboot revision. -

- -

- Back to top of page. -

- -

Adding a new board to libreboot

- -

- Make sure that the board is supported, and that the patches - are included (if there are custom patches that you need). - Add configs for it like so (for GRUB payload):
- $ ./build config grubreplace payload/boardname
- Alternatively, for depthcharge payload:
- $ ./build config dcreplace payload/boardname -

- -

- This can also be used for replacing an existing config. -

- -

- Configure the board. Make sure to add the steps to the config section - in ../git/index.html. -

- -

- When you're done, the config will be stored in resources/libreboot/config/. - Now build-test it and then check that it actually works. -

- -

- The following scripts may also need to be modified before building: - resources/scripts/helpers/build/roms/withgrub and - resources/scripts/helpers/build/roms/helper -

- -

- The following can be used when updating coreboot-libre (GRUB payload):
- $ ./build config grubupdate
- You must also do this for boards that use the depthcharge payload:
- $ ./build config dcupdate
- (adding a board name on the end is optional, for either of these) -

- -

- The following can be used if you want to modify an existing - configuration (GRUB payload):
- $ ./build config grubmodify
- For those boards which use the depthcharge payload:
- $ ./build config dcmodify
- (adding a board name on the end is optional) -

- -

- Examples (GRUB payload):
- $ ./build config grubmodify x60
- $ ./build config grubreplace x60
- $ ./build config grubupdate x60
- $ ./build config grubmodify kfsn4-dre
- $ ./build config grubreplace kfsn4-dre
- $ ./build config grubupdate kfsn4-dre
-

- Examples (depthcharge payload):
- $ ./build config dcmodify veyron_speedy
- $ ./build config dcreplace veyron_speedy
- $ ./build config dcupdate veyron_speedy -

- -

- Back to top of page. -

- -

Add/remove/modify patches in coreboot-libre

- -

- Under resources/scripts/helpers/download/coreboot you can find - the instructions used for patching coreboot. -

- -

- Modify the commit ID on the git reset --hard line accordingly, - and update the list of patches used accordingly. Do not cherry-pick - from review.coreboot.org directly; instead, include the diff in - resources/libreboot/patch/ and use git am - (you can get the diff by using git-format-patch). -

- -

- When you're done, simply download coreboot again:
- $ ./download coreboot -

- -

- Finally, re-build the parts from coreboot that are used - by the build system (also builds GCC):
- $ ./build module coreboot -

- -

- Before running the above command, you can save time - by copying out the crossgcc that you compiled before - (from coreboot/util/crossgcc/) and then putting it back. - After you've done that, run everything in - resources/scripts/helpers/build/module/coreboot - except for the part that builds GCC. - Only do this if the version is correct. -

- -

- You should also test the resulting ROM images from building - with the new or modified coreboot revision. -

- -

- Back to top of page. -

- -

Updating GRUB

- -

- $ rm -Rf grub/
- $ git clone git://git.savannah.gnu.org/grub.git
- $ cd grub/
- $ git log -

- -

- Open the file resources/scripts/helpers/download/grub and - replace the commit ID on the line that performs git reset --hard - with the commit ID of the GRUB revision that you just downloaded. -

- -

- $ cd ../
- $ ./download grub -

- -

- If it fails because of merge conflicts, you'll need to re-base - or (as appropriate) remove the offending patch(es) in - resources/scripts/helpers/download/grub. -

- -

- Finally, verify that it will build:
- $ ./build module grub -

- -

- Since GRUB is the payload in libreboot, you should also - build the ROM images and test them, with this different - GRUB version that you have prepared. -

- -

- Back to top of page. -

- -

Change how the GRUB payload (grub.elf) is built (utility: grub-assemble)

- -

- Look in resources/utilities/grub-assemble/. -

- -

- gen.sh creates ELF executables of GRUB with different configurations: - text-mode or framebuffer mode in coreboot. Essentially, - the text-mode version has no background nor any custom fonts, - and contains MemTest86+. You probably don't need to modify these - files at all. -

- -

- modules.conf defines which modules will be included in the GRUB - ELF executable. -

- -

- Since GRUB is the payload in libreboot, you should also - build the ROM images and test them, with this different - GRUB version that you have prepared. -

- -

- Back to top of page. -

- -

Modify the configuration used in GRUB

- -

- Look in resources/scripts/helpers/build/roms/withgrub to - see how the GRUB configuration files are generated. -

- -

- You might need to modify this. You can also modify the - default configuration by making changes to the files - under resources/grub/config/ -

- -

- Since GRUB is the payload in libreboot, you should also - build the ROM images and test them, with this different - GRUB version that you have prepared. -

- -

- Back to top of page. -

- -

Updating depthcharge

- -

- The script to download depthcharge is: resources/scripts/helpers/download/depthcharge. -

- -

- Patches are in resources/depthcharge/patch/. -

- -

- The configuration used for depthcharge is located in depthcharge/board. - Each board has a defconfig Kconfig configuration and a fmap.dts FMAP device-tree configuration. - Those shouldn't need much attention, but when needed, it's best to modify them in the depthcharge tree (with patches) to keep things in one place. -

- -

- Back to top of page. -

- -

Updating flashrom

- -

- Modify these files: resources/scripts/helpers/download/flashrom - and resources/scripts/helpers/build/module/flashrom. -

- -

- Patches are in resources/flashrom/patch/ -

- -

- Back to top of page. -

- -

Updating bucts

- -

- bucts doesn't really need updating, but the patches are - in resources/bucts/patch, the download script - is resources/scripts/helpers/download/bucts and - the build script is resources/scripts/helpers/build/module/bucts. -

- -

- Back to top of page. -

- -

Updating MemTest86+

- -

- MemTest86+ doesn't really need updating, but the patches are - in resources/memtest86plus/patch, the download script - is resources/scripts/helpers/download/memtest86plus and - the build script is resources/scripts/helpers/build/module/memtest86plus. -

- -

- In the download script for memtest86plus, make sure to update the checksum that it matches - for the downloaded source tarball. -

- -

- Back to top of page. -

- -

- Copyright © 2015 Leah Rowe <info@minifree.org>
- Permission is granted to copy, distribute and/or modify this document - under the terms of the GNU Free Documentation License, Version 1.3 - or any later version published by the Free Software Foundation; - with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. - A copy of the license can be found at ../gfdl-1.3.txt -

- -

- Updated versions of the license (when available) can be found at - https://www.gnu.org/licenses/licenses.html -

- -

- UNLESS OTHERWISE SEPARATELY UNDERTAKEN BY THE LICENSOR, TO THE - EXTENT POSSIBLE, THE LICENSOR OFFERS THE LICENSED MATERIAL AS-IS - AND AS-AVAILABLE, AND MAKES NO REPRESENTATIONS OR WARRANTIES OF - ANY KIND CONCERNING THE LICENSED MATERIAL, WHETHER EXPRESS, - IMPLIED, STATUTORY, OR OTHER. THIS INCLUDES, WITHOUT LIMITATION, - WARRANTIES OF TITLE, MERCHANTABILITY, FITNESS FOR A PARTICULAR - PURPOSE, NON-INFRINGEMENT, ABSENCE OF LATENT OR OTHER DEFECTS, - ACCURACY, OR THE PRESENCE OR ABSENCE OF ERRORS, WHETHER OR NOT - KNOWN OR DISCOVERABLE. WHERE DISCLAIMERS OF WARRANTIES ARE NOT - ALLOWED IN FULL OR IN PART, THIS DISCLAIMER MAY NOT APPLY TO YOU. -

- TO THE EXTENT POSSIBLE, IN NO EVENT WILL THE LICENSOR BE LIABLE - TO YOU ON ANY LEGAL THEORY (INCLUDING, WITHOUT LIMITATION, - NEGLIGENCE) OR OTHERWISE FOR ANY DIRECT, SPECIAL, INDIRECT, - INCIDENTAL, CONSEQUENTIAL, PUNITIVE, EXEMPLARY, OR OTHER LOSSES, - COSTS, EXPENSES, OR DAMAGES ARISING OUT OF THIS PUBLIC LICENSE OR - USE OF THE LICENSED MATERIAL, EVEN IF THE LICENSOR HAS BEEN - ADVISED OF THE POSSIBILITY OF SUCH LOSSES, COSTS, EXPENSES, OR - DAMAGES. WHERE A LIMITATION OF LIABILITY IS NOT ALLOWED IN FULL OR - IN PART, THIS LIMITATION MAY NOT APPLY TO YOU. -

- The disclaimer of warranties and limitation of liability provided - above shall be interpreted in a manner that, to the extent - possible, most closely approximates an absolute disclaimer and - waiver of all liability. -

- -

- - - -- cgit v1.2.3-70-g09d2