site/contrib.md

@@ -61,6 +61,9 @@ using libreboot or in need of help.
 * Project goals. Caleb collaborates with Leah on determining project goals.
 Leah has the final say in every decision.
 
+External projects
+=================
+
 Coreboot project
 ----------------
 
@@ -82,6 +85,24 @@ SeaBIOS
 The libreboot firmware provides SeaBIOS as a payload option. SeaBIOS provides a
 legacy x86 BIOS implementation.
 
+U-Boot
+------
+
+Libreboot uses U-Boot as the coreboot payload on supported ARM Chromebooks.
+
+Contributors in alphabetical order
+==================================
+
+Alper Nebi Yasak
+----------------
+
+Contributed the build system integration and documentation for using
+U-Boot as payload, and initial Libreboot ports of some ARM Chromebooks
+based on that.
+
+Alper also does upstream development on U-Boot, e.g. continued an almost
+complete port of the `gru-kevin` board and got it merged upstream.
+
 Alyssa Rosenzweig
 -----------------
 

site/docs/build/index.md

@@ -147,6 +147,8 @@ If you wish to build payloads, you can also do that. For example:
 
     ./build payload seabios
 
+    ./build payload u-boot qemu_x86_12mb
+
 Previous steps will be performed automatically. However, you can *still* run
 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
@@ -202,6 +204,8 @@ Example of downloading an individual module:
 
     ./download flashrom
 
+    ./download u-boot
+
 Third, build all of the modules:
 --------------------------------
 
@@ -260,6 +264,17 @@ Example of building specific payloads:
 
     ./build payload seabios
 
+Each board has its own U-Boot build configuration in `lbmk` under
+`resources/u-boot`. To build U-Boot payloads, you need to specify the
+target board and maybe a cross compiler for its CPU architecture. These
+are handled automatically when building ROM images, but for example:
+
+    ./build payload u-boot qemu_x86_12mb	# on x86 hosts
+
+    CROSS_COMPILE=aarch64-linux-gnu- ./build payload u-boot gru_kevin
+
+    CROSS_COMPILE=arm-linux-gnueabi- ./build payload u-boot veyron_speedy
+
 The build-payload command is is a prerequsite for building ROM images.
 
 Fifth, build the ROMs!

site/docs/hardware/index.md

@@ -54,43 +54,28 @@ libreboot currently supports the following systems in this release:
 -   [Lenovo Thinkpad X230](../install/x230_external.md)
 -   [Lenovo Thinkpad X230t](../install/x230_external.md)
 
-### Laptops (ARM, u-boot, MOSTLY UNTESTED AS OF NOVEMBER 16, 2022)
-
--   Samsung Chromebook 2 13" (peach-pi)
--   Samsung Chromebook 2 11" (based on `peach_pit` in coreboot)
--   HP Chromebook 11 G1 (google/daisy)
--   Samsung Chromebook XE303 (google/daisy)
--   HP Chromebook 14 G3 (google/nyan\_blaze)
--   Acer Chromebook 13 (CB5-311, C810) (google/nyan\_big)
--   ASUS Chromebit CS10 (google/veyron\_mickey)
--   ASUS Chromebook Flip C100PA (google/veyron)
--   ASUS Chromebook C201PA (google/veyron\_speedy)
--   ASUS Chromebook Flip C101 (google/gru)
--   Samsung Chromebook Plus (v1) (google/gru)
-
-NOTE: the above list may be incomplete. For example, `gru_kevin`
-is also present in lbmk. This needs to be tidied up.
-
-NOTE: ARM hardware is currently undocumented in Libreboot, both for
-installation of Libreboot and the installation of an operating system. If you
-have one of these machines configured with Libreboot, you should consult
-u-boot documentation to learn how it's operated. You might ping `alpernebbi` on
-Libera IRC, who ported these boards to Libreboot. Extensive work was
-performed, to make u-boot work correctly. **TODO: installation instructions
-must be added to documentation!**
-
-NOTE: As of 11 December 2022, building of u-boot images has been tested on
-Debian Linux. Make sure you have the latest lbmk from the Git repository, and
-the build dependencies are installed like so, from `lbmk/` as root:
-
-    ./build dependencies debian
-
-This installs everything needed for cross-compiling, and part of the build
-process makes use of coreboot's own cross-compile toolchain.
+### Laptops (ARM, with U-Boot payload)
+
+-   [Samsung Chromebook 2 13" (peach-pi)](../install/chromebooks.md)
+-   [Samsung Chromebook 2 11" (peach-pit)](../install/chromebooks.md)
+-   [HP Chromebook 11 G1 (daisy-spring)](../install/chromebooks.md)
+-   [Samsung Chromebook XE303 (daisy-snow)](../install/chromebooks.md)
+-   [HP Chromebook 14 G3 (nyan-blaze)](../install/chromebooks.md)
+-   [Acer Chromebook 13 (CB5-311, C810) (nyan-big)](../install/chromebooks.md)
+-   [ASUS Chromebit CS10 (veyron-mickey)](../install/chromebooks.md)
+-   [ASUS Chromebook Flip C100PA (veyron-minnie)](../install/chromebooks.md)
+-   [ASUS Chromebook C201PA (veyron-speedy)](../install/chromebooks.md)
+-   [Hisense Chromebook C11 and more (veyron-jerry)](../install/chromebooks.md)
+-   [ASUS Chromebook Flip C101 (gru-bob)](../install/chromebooks.md)
+-   [Samsung Chromebook Plus (v1) (gru-kevin)](../install/chromebooks.md)
+
+WARNING: Support for these boards is at a proof-of-concept stage. Refer
+to [docs/u-boot/](../u-boot/) for more info about the U-Boot payload.
 
 ### Emulation
 
 -   [Qemu x86](../misc/emulation.md)
+-   [Qemu arm64](../misc/emulation.md)
 
 
 TODO: More hardware is supported. See `resources/coreboot/` in lbmk. Update

site/docs/index.md

@@ -19,7 +19,6 @@ Documentation related to operating systems
 
 -   [GNU+Linux Guides](gnulinux/)
 -   [How to install BSD on an x86 host system](bsd/)
--   [How to install BSD or Linux on ARM/uboot](uboot/) (TODO: write this section)
 
 Information for developers
 ==========================
@@ -27,6 +26,7 @@ Information for developers
 -   [How to compile the libreboot source code](build/)
 -   [Build system developer documentation](maintain/)
 -   [GRUB payload](grub/)
+-   [U-Boot payload](uboot/)
 
 Other information
 =================

site/docs/install/chromebooks.md

@@ -0,0 +1,157 @@
+---
+title: Chromebook flashing instructions
+x-toc-enable: true
+...
+
+This page attempts to give a brief, general overview of how to flash
+custom firmware on ChromeOS devices. This guide usually refers to all of
+them as "Chromebook"s since it's the most common form factor.
+
+Enable ChromeOS "Developer Mode"
+================================
+
+Chromebooks are locked-down by default to only run ChromeOS. Most things
+you will want to do on these require you unlock it by enabling their
+[Developer Mode](https://chromium.googlesource.com/chromiumos/docs/+/HEAD/developer_mode.md).
+On most devices, you would press the `Escape + Refresh + Power` key
+combination to restart into the Recovery Mode, then press `Ctrl + D` and
+finally confirm enabling Developer Mode with `Enter`.
+
+On your next boot, it will show you an "OS Verification is disabled"
+screen. Waiting for 30 seconds or pressing `Ctrl + D` on this screen will
+proceed to boot into ChromeOS, which then erases all data on the device
+and reboots again into a clean ChromeOS installation.
+
+With Developer Mode enabled, you can launch a terminal emulator inside
+ChromeOS by pressing the `Ctrl + Alt + T` key combination. Run `shell`
+inside the resulting `crosh` prompt to actually get to a `bash` session
+where you can run programs. Most of the root file system is read-only,
+except for `/usr/local` and any mounted drives under `/media/removable`.
+
+Identify your device
+====================
+
+It's more common to refer to ChromeOS boards by their codenames, and
+many compatible devices can share a single codename. Libreboot ROM
+images also use these, you should only use the one corresponding to your
+device's. There are a number of ways to find it, some are:
+
+- Check the "Model" on the Recovery Mode or Developer Mode screens
+- Visit `chrome://version` in ChromeOS and check the "Firmware Version"
+- Run `crossystem hwid` or `crossystem fwid` in a terminal
+
+Back up stock firmware
+======================
+
+The stock firmware on your device comes with some irreplaceable data
+that is unique to your device. This can include the serial number and
+hardware ID of the device, network MAC address, HDCP keys, maybe more.
+The stock firmware is also the only one that will properly boot and run
+ChromeOS.
+
+Make sure you back up the original firmware before trying to replace it.
+The version of flashrom in ChromeOS understands `host` as a programmer
+to flash firmware internally. To back up stock firmware you can run:
+
+    sudo flashrom -p host -r depthcharge.rom
+    sudo flashrom -p host -v depthcharge.rom
+
+Keep the resulting `depthcharge.rom` file safe and properly backed up on
+another device.
+
+If you can already boot a conventional Linux distro on your Chromebook,
+you may be able to use `flashrom -p linux_mtd` on that system instead.
+
+Check external flashability
+===========================
+
+If a ROM image you flash is broken, you may need to restore the stock
+firmware to fix the board to get internal flashing working. Refer to the
+[external flashing guide](spi.md), and check that the result of
+`flashrom -r` matches what you get when you run it from the device.
+Chromebooks may have 1.8V as the supply voltage for the SPI NOR chip, be
+extra careful about that.
+
+On newer Chromebooks, there is a root-of-trust chip providing a
+[Closed Case Debugging](https://chromium.googlesource.com/chromiumos/platform/ec/+/cr50_stab/docs/case_closed_debugging_cr50.md)
+mechanism that lets you flash externally using a special USB debugging
+cable. However, most boards that Libreboot supports do not have this.
+
+Disable write protection
+========================
+
+Chromebooks have the SPI flash chip partially write-protected by
+default, but thankfully this protection can be disabled by the device
+owner. How to do so depends on the board, refer to the
+[ChromiumOS documentation on Write Protection](https://chromium.googlesource.com/chromiumos/docs/+/HEAD/write_protection.md)
+for more info. You will usually need to do this only once for the
+board's lifetime, unless you manually enable it again.
+
+On most boards that Libreboot supports, write-protection is enforced by
+a physical screw. When screwed in, it forms an electrical connection
+that asserts the WP pin on the flash chip. The screw can be identified
+by the fact that it bridges electrical contacts, but finding and
+removing it might require you to disassemble most of the board.
+
+Newer boards have a root-of-trust chip enforcing write-protection. The
+[Closed Case Debugging](https://chromium.googlesource.com/chromiumos/platform/ec/+/cr50_stab/docs/case_closed_debugging_cr50.md)
+mechanism should be used to disable hardware write-protection. Opening
+the case and disconnecting the battery might also disable it.
+
+Disabling the write-protect signal doesn't directly make the chip stop
+protecting its data, it just allows you to disable its write-protection
+in software. That also needs to be done in ChromeOS afterwards:
+
+    sudo flashrom -p host --wp-status
+    sudo flashrom -p host --wp-disable
+    sudo flashrom -p host --wp-range 0x0,0x0
+
+The *--wp* arguments are only available on the
+[ChromiumOS fork of flashrom](https://sites.google.com/a/chromium.org/dev/chromium-os/packages/cros-flashrom).
+If you are using another OS or an external flasher, you may need to
+compile and use that flashrom fork to disable write-protection. There is
+no `lbmk` support yet for automatically building it.
+
+Prepare the ROM image
+=====================
+
+Libreboot ROM image layouts are currently incompatible with the regions
+that should be carried over from the stock firmware. However, the
+released images should still be somewhat usable, since the Chromebooks
+supported so far don't require any non-redistributable blobs to be
+injected by the end user.
+
+Future Libreboot versions will likely require post-processing to
+preserve irreplaceable data in the firmware image. For now, make sure to
+keep backups of the original firmware.
+
+TODO: Instructions to preserve vital data when FMAPs are compatible.
+
+Flash the ROM image
+===================
+
+WARNING: Although none are supported yet, make sure not to flash ROM
+images on x86 Chromebooks without injecting non-redistributable blobs
+first (like Intel ME firmware). This is not yet documented here.
+
+You can flash the ROM image both internally and externally. For the
+latter, see the [external flashing guide](spi.md) and the ChromiumOS
+[Closed Case Debugging](https://chromium.googlesource.com/chromiumos/platform/ec/+/cr50_stab/docs/case_closed_debugging_cr50.md)
+documentation if your board supports it.
+
+To flash the entire ROM image internally, run within ChromeOS:
+
+    sudo flashrom -p host -w libreboot.rom
+    sudo flashrom -p host -v libreboot.rom
+
+If you can already boot a conventional Linux distro on your Chromebook,
+you may be able to use `flashrom -p linux_mtd` on that system instead.
+
+See also
+========
+* [ChromiumOS Documentation](https://chromium.googlesource.com/chromiumos/docs/+/HEAD/)
+* [ChromiumOS Firmware Test Manual](https://chromium.googlesource.com/chromiumos/docs/+/HEAD/firmware_test_manual.md)
+* [ChromiumOS Flashrom Fork Information](https://www.chromium.org/chromium-os/packages/cros-flashrom/)
+* [MrChromebox's Unbricking Guide](https://wiki.mrchromebox.tech/Unbricking)
+* [MrChromebox's Write-Protection Notes](https://wiki.mrchromebox.tech/Firmware_Write_Protect)
+* [Coreboot Tutorial as used in ChromeOS](https://docs.google.com/presentation/d/1eGPMu03vCxIO0a3oNX8Hmij_Qwwz6R6ViFC_1HlHOYQ/preview)

site/docs/install/spi.md

@@ -37,10 +37,10 @@ is called *external* because it's not the *internal* one on your mainboard.
 Do not use CH341A!
 ==================
 
-NOR flashes on libreboot systems run on 3.3V DC, and this includes data lines.
-CH341A has 5V logic levels on data lines, which will damage your SPI flash and
-also the southbridge that it's connected to, plus anything else that it's
-connected to.
+NOR flashes on libreboot systems run on 3.3V DC or 1.8V DC, and this includes
+data lines. CH341A has 5V logic levels on data lines, which will damage your
+SPI flash and also the southbridge that it's connected to, plus anything else
+that it's connected to.
 
 These ch341a programmers are unfortunately very popular. DO NOT use it unless
 you have fixed the issue. You CAN fix it so that the data lines are 3.3v, if
@@ -54,6 +54,10 @@ to discourage use of that device.
 
 **Not covered on that eevblog page: the WP/HOLD pins (pins 3 and 7) must be held high via pull-up resistors, but on CH341A dongles, they are directly connected to 3.3V DC (continuity with pin 8). It is advisable to cut these two connections, to the WP and HOLD pins, and jump the cuts using pull-up resistors instead. A value between 1k to 10k (ohms) should be fine.**
 
+Alternatively, you might work around this by using an adapter or logic-level
+converter that can tolerate the overvoltage (which you would need for 1.8V chips
+anyway).
+
 In case it's not clear:
 
 Please do not buy the ch341a! It is incorrectly engineered for the purpose of
@@ -101,6 +105,19 @@ DIP8
 
 ![](https://av.libreboot.org/dip8/dip8.jpg)
 
+Supply Voltage
+--------------
+
+Historically, all boards that Libreboot supports happened to have SPI NOR chips
+which work at 3.3V DC. With the recent addition of Chromebooks whose chips are
+rated for 1.8V DC, this can no longer be assumed.
+
+Inspect the chip on your board for a part number, look up the datasheet for it.
+Find out and make note of the power supply voltage it needs. If it doesn't
+match the voltage output by your external flashing hardware, you should only
+connect it to the chip through an adapter or logic level converter, never
+directly.
+
 Software configuration
 ======================
 
@@ -312,7 +329,7 @@ It is advisable to take a *2nd* dump, e.g. `dump2.bin`, and then check sha1sum:
 
 If the checksums match, it indicates that you have a good dump. If they do not,
 check your wiring. Wires should be within 10cm length for best stability, and
-they should all be the same length (3.3V VCC and GND wires can be longer).
+they should all be the same length (VCC and GND wires can be longer).
 
 This advice is *especially* applicable to the BBB, which is highly unreliable.
 
@@ -374,20 +391,24 @@ will teach you how to wire each type of flash chip.
 WARNINGS
 --------
 
-Do not connect a 3.3V DC power source until your chip is otherwise properly
-wired. For instance, do not connect a test clip that has 3.3V DC attached.
+Do not connect the power source until your chip is otherwise properly
+wired. For instance, do not connect a test clip that has power attached.
 
 Do not *disconnect* your chip from the flasher until you've disconnected or
-turned off the 3.3V DC power source.
+turned off the power source.
 
-BE CAREFUL that you are indeed supplying 3.3V DC to the chip. All SPI flashes
-on all currently supported libreboot hardware run on 3.3V DC and logic at that
-level too.
+BE CAREFUL that you are indeed supplying the appropriate supply voltage to the
+chip. SPI flashes on most of the currently supported libreboot hardware run on
+3.3V DC and logic at that level too. Some of them (at least Chromebooks) can
+have chips that run on 1.8V DC. You should make sure to check the part number
+and datasheet of the SPI flash chip for the supply voltage it requires. If your
+external flashing hardware doesn't match it, use an adapter or logic level
+converter to flash.
 
 It is important to CHECK that you are running on the correct voltage, when you
-do anything with these chips. Lower than 3.3V won't damage anything, but higher
-will fry your chip (on most chips, the tolerated voltage range is between 2.7V
-and 3.6V, but 3.3V is the most ideal level).
+do anything with these chips. Lower than the rated supply voltage won't damage
+anything, but higher will fry your chip (on most 3.3V chips, the tolerated
+voltage range is between 2.7V and 3.6V, but 3.3V is the most ideal level).
 
 DO NOT connect more than 1 DC power source to your flash chip either!
 Mixing voltages like that can easily cause damage to your equipment, and to
@@ -397,7 +418,7 @@ MISO/MOSI/CS/CLK lines
 ----------------------
 
 You may want to add 47ohm series resistors on these lines, when flashing the
-chips. Only do it on those lines (NOT the 3.3V or GND lines). This provides
+chips. Only do it on those lines (NOT the VCC or GND lines). This provides
 some protection from over-current. On Intel platforms, the SPI flash is usually
 connected via such resistors, directly to the Southbridge chipset.
 
@@ -410,12 +431,13 @@ on.
 
 It may be beneficial to modify the mainboard so that the SPI flash is powered
 (on the VCC pin) through a diode, but please note: a diode will cause a voltage
-drop. The tolerated range for VCC on these chips is 2.7V to 3.6V DC. If you do
+drop. The tolerated range for a chip expecting 3.3V VCC is usually around 2.7V
+to 3.6V DC, and the drop may cause the voltage to fall outside that. If you do
 this, please also ensure that the WP and HOLD pins are still held to a high
 logic state; each via their own resistor (1K to 10K ohms) connected to the
-*same* 3.3V DC source going through the diode.
+*same* power source going through the diode.
 
-The reason is simple: on most systems, the flash shares a common 3.3V DC rail
+The reason is simple: on most systems, the flash shares a common power rail
 with many other components on the board, which draw a lot of current. Further,
 if you accidentally provide too much voltage or cause an overcurrent, you could
 fry those other components but if there is diode protection, you'll only fry
@@ -423,14 +445,15 @@ the boot flash (and it is very easy to replace, if you have good soldering
 skills).
 
 When you've placed the diode, ensure that VCC on the chip is isolated from all
-other components on that board, which share the same 3.3V DC rail. Further,
+other components on that board, which share the same power rail. Further,
 ensure that the pull-up resistors for WP/HOLD are *only* connected to the side
 of the diode that has continuity with the VCC pin (this is important because if
 they're not, they won't be held high while doing ISP flashing, even if they're
 still held high when the mainboard is fully powered on).
 
-Furthermore: ensure that the SPI flash is operating at 2.7 to 3.6V when fully
-powered on, after installing the diode.
+Furthermore: ensure that the SPI flash is operating at the appropriate supply
+voltage (2.7V to 3.6V for a 3.3V chip) when fully powered on, after installing
+the diode.
 
 If it's a desktop/workstation/server board (not a laptop), you could de-solder
 the SOIC8/WSON8 if it uses that, and replace with an IC socket (for SOIC8,
@@ -483,7 +506,7 @@ Refer to this diagram:
   5      MOSI        19         18
   6      CLK         23         22
   7      *not used*  *not used* *not used*
-  8      3.3V        1          3
+  8      VCC         1          3
 
 On your SOIC8, there will be a dot in one of the corners. The dot is pin 1.
 
@@ -512,7 +535,7 @@ Refer to this diagram:
   Pin \#   25xx signal    RPi(GPIO)   BBB(P9 header)
   -------- -------------- ----------- --------------
   1        *not used*     *not used*  *not used*
-  2        3.3V           1           3
+  2        VCC            1           3
   3        *not used*     *not used*  *not used*
   4        *not used*     *not used*  *not used*
   5        *not used*     *not used*  *not used*
@@ -547,8 +570,7 @@ mounted to a mainboard. You need pull-up resistors on the WP and HOLD pins,
 and decoupling capacitors on the VCC pin. If the chip is already mounted to a
 board, whether soldered or in a socket, these capacitors and resistors will
 probably already exist on the board and you can just flash it without pulling
-WP/HOLD high, and without capacitors(just connect your external 3.3V DC power
-source).
+WP/HOLD high, and without capacitors(just connect your external power source).
 
 The best way is as follows:
 
@@ -559,13 +581,12 @@ The best way is as follows:
   the correct wiring (see link to SPI flashing guides below)
 
 SOIC8/WSON8/DIP8: pin 3 and 7 must be held to a high logic state, which means
-that each pin
-has its own pull-up resistor to VCC (from the 3.3v voltage plane that pin 8
-connects to); anything from 1Kohm to 10Kohm will do. When you're flashing a chip
-that's already on a laptop/desktop/server mainboard, pin 3 and 7 are likely
-already held high, so you don't need to bother.
+that each pin has its own pull-up resistor to VCC (from the voltage plane that
+pin 8 connects to); anything from 1Kohm to 10Kohm will do. When you're flashing
+a chip that's already on a laptop/desktop/server mainboard, pin 3 and 7 are
+likely already held high, so you don't need to bother.
 
-SOIC8/WSON8/DIP8: pin 8, which is 3.3v VCC, will already have decoupling capacitors on it
+SOIC8/WSON8/DIP8: pin 8, which is VCC, will already have decoupling capacitors on it
 if the chip is on a mainboard, but lone chip flashing means that these capacitors
 do not exist. A capacitor passes AC but blocks DC. Due to electromagnetic
 indunctance, and RF noise from high-speed switching ICs, a DC voltage line isn't
@@ -584,8 +605,8 @@ seen on an oscilloscope).
 
 SOIC16: same as above, but use a SOIC16 socked on a breadboard. On SOIC16,
 WP/HOLD are not pin 3/7 like above, but instead pins 1 and 9, so wire your 
-pull-up resistors on those. 3.3v VCC on SOIC16 is pin 2, so wire your
-decoupling capacitors up on that.
+pull-up resistors on those. VCC on SOIC16 is pin 2, so wire your decoupling
+capacitors up on that.
 
 SOIC8/WSON8/DIP8/SOIC16 not mounted to a mainboard
 --------------------------------------------------
@@ -674,7 +695,7 @@ Pomona 5250 is a SOIC8 test clip. There are others available, but this is the
 best one. Use that. Use the SOIC8 diagram (see above) to wire up your Raspberry
 Pi.
 Your mainboard likely already pulls WP/HOLD (pins 3 and 7) high, so don't
-connect these. 3.3v VCC on SOIC8's pin 8 probably already has decoupling
+connect these. VCC on SOIC8's pin 8 probably already has decoupling
 capacitors on the mainboard, so just hook that up without using a capacitor.
 
 SOIC16:\

site/docs/maintain/index.md

@@ -252,8 +252,8 @@ For a full list of all `download` commands, run:
 modify
 ======
 
-This can be used to modify SeaBIOS and coreboot configs. It calls scripts
-in `resources/scripts/modify/`, for example:
+This can be used to modify SeaBIOS, coreboot and U-Boot configs. It calls
+scripts in `resources/scripts/modify/`, for example:
 
     ./modify coreboot configs
 
@@ -309,8 +309,10 @@ as:
 * `payload_grub_withseabios="y"` (example entry)
 * `payload_seabios="y"` (example entry)
 * `payload_memtest="y"` (example entry)
+* `payload_uboot="y"` (example entry)
 * `payload_seabios_withgrub="y"` (example entry)
 * `grub_scan_disk="ata"`
+* `uboot_config=default`
 
 More information about these and other variables will be provided throughout
 this document.
@@ -340,10 +342,10 @@ coreboot Git repository. *At present, lbmk only supports use of the official
 repository from the upstream coreboot project*.
 
 The `arch` entry specifies which CPU architecture is to be used: currently
-recognized entries are `x86_32`, `x86_64` and `ARMv7`. *At present, setting it
-to ARMv7 only means that crossgcc-arm will be compiled, but no support for
-actually building ROMs exists in lbmk exists yet, except for 32-bit and 64-bit
-x86 machines.*
+recognized entries are `x86_32`, `x86_64`, `ARMv7` and `AArch64`. *Setting it
+to a non-native arch means that necessary crossgcc-arch will be compiled and be
+available when building roms, but not necessarily built or discovered when
+individual scripts are called manually.*
 
 The `payload_grub` entry specifies whether or not GNU GRUB is to be included in
 ROM images.
@@ -361,6 +363,13 @@ The `payload_memtest` entry specifies whether or not MemTest86+ is to be
 included in ROM images; it will only be included in ROM images for *text mode*
 startup, on x86 machines.
 
+The `payload_uboot` entry specifies whether or not U-Boot is to be included in
+ROM images.
+
+The `uboot_config` option specifies which U-Boot board configuration file
+variant should be used. It currently doesn't make sense for this to be anything
+other than `default`, which is the default if the option is missing.
+
 The `grub_scan_disk` option specifies can be `ahci`, `ata` or `both`, and it
 determines which types of disks are to be scanned, when the `grub.cfg` file in
 GRUB payloads tries to automatically find other `grub.cfg` files supplied by
@@ -507,6 +516,137 @@ for instance, and `lbmk` will not erroneously try to apply `README` as though
 it were a patch file. This might be useful if you have a *lot* of patches, and
 you want to provide some explanations about specific files.
 
+resources/u-boot/
+=================
+
+This directory contains configuration, patches and so on, for each mainboard
+that can use U-Boot as a payload in the `lbmk` build system. U-Boot doesn't yet
+have reliable generic configurations that can work across all coreboot boards
+(per-architecture), so these are used to build it per-board.
+
+resources/u-boot/BOARDNAME/
+===========================
+
+Each `BOARDNAME` directory defines configuration for a corresponding mainboard.
+It doesn't actually have to be for a board; it can also be used to just define
+a U-Boot revision, with patches and so on. To enable use as a payload in ROM
+images, this must have the same name as its `resources/coreboot/BOARDNAME/`
+counterpart.
+
+resources/u-boot/BOARDNAME/board.cfg
+====================================
+
+This file can contain several configuration lines, each being a string, such
+as:
+
+* `ubtree="default"` (example entry)
+* `ubrevision="4debc57a3da6c3f4d3f89a637e99206f4cea0a96"` (example entry)
+* `arch="AArch64"` (example entry)
+
+These are similar in meaning to their coreboot counterparts.
+
+The `ubtree` entry is actually a link, where its value is a directory name
+under `resources/u-boot`. For example, `ubtree="default"` would refer to
+`resources/u-boot/default` and the corresponding U-Boot source tree created
+(when running `./download u-boot`, which makes use of `board.cfg`) would be
+`u-boot/default/`. In other words: a `board.cfg` file in `resources/u-boot/foo`
+might refer to `resources/u-boot/bar` by specifying `ubtree="bar"`, and the
+created u-boot source tree would be `u-boot/bar/`. ALSO:
+
+FUN FACT: such references are infinitely checked until resolved. For
+example, `foo` can refer to `bar` and `bar` can refer to `baz` but if there is
+an infinite loop, this is detected and handled by `lbmk`. For example,
+if `bar` refers to `foo` which refers back to `bar`, this is not permitted
+and will throw an error in `lbmk`.
+
+The `ubrevision` entry defines which U-Boot revision to use, from the U-Boot
+Git repository. *At present, lbmk only supports use of the official repository
+from the upstream U-Boot project*.
+
+The `arch` entry specifies which CPU architecture is to be used: currently
+recognized entries are `x86_32`, `x86_64`, `ARMv7` and `AArch64`. *Setting it
+to a non-native arch means that necessary crossgcc-arch will be compiled and be
+available when building roms, but not necessarily built or discovered when
+individual scripts are called manually.*
+
+resources/u-boot/BOARDNAME/config/\*
+====================================
+
+Files in this directory are *U-Boot* configuration files. Configuration file
+names can be anything, but for now `default` is the only one used.
+
+In `lbmk`, a board-specific directory under `resources/u-boot/` should never
+specify a U-Boot revision. Rather, a directory *without* U-Boot configs should
+be created, specifying a U-Boot revision. For example, the directory
+`resources/u-boot/default/` specifies a U-Boot revision. In the board-specific
+directory, your `board.cfg` could then specify `ubtree="default"` but without
+specifying a U-Boot revision (this is specified by
+`resources/u-boot/default/board.cfg`).
+
+Normally, the U-Boot build process results in the U-Boot executable and a
+device-tree file for the target board, which must further be packaged together
+to make things work. When you create a U-Boot configuration, you should enable
+`CONFIG_REMAKE_ELF` or `CONFIG_OF_EMBED` that handles this. The former option
+enables creation of a `u-boot.elf` that bundles them together after the build,
+and the latter option embeds it into the `u-boot` executable.
+
+When making a U-Boot configuration, you should also pay special attention to
+the `CONFIG_SYS_TEXT_BASE` (`CONFIG_TEXT_BASE` in later versions), whose defaults
+may cause it to overlap coreboot, in which case it won't boot. Normally, the
+upstream coreboot build system checks for this when given `CONFIG_PAYLOAD_ELF`,
+but `lbmk` injects the payload itself and doesn't check for this yet.
+
+Another interesting config option is `CONFIG_POSITION_INDEPENDENT` for ARM
+boards, which has been so far enabled in the ones `lbmk` supports, just to be
+safe.
+
+U-Boot build system
+-------------------
+
+If you wish to know about U-Boot, refer here:\
+<https://u-boot.readthedocs.io/en/latest/>
+
+This and other documents from U-Boot shall help you to understand *U-Boot*.
+
+You create a config, for `resources/u-boot/BOARDNAME/configs`, by finding the
+corresponding board name in the upstream U-Boot `configs` directory, and
+running `make BOARDNAME_defconfig` and `make menuconfig` commands in the
+*U-Boot* build system. You should do this after running `./download u-boot` in
+`lbmk`.
+
+You might want to consider basing your config on the upstream `coreboot` boards
+when possible, but such a board is not available upstream for ARM yet.
+
+You can simply clone U-Boot upstream, add whatever patches you want, and
+then you can make your config. It will appear afterwards in a file
+named `.config` which is your config for inside `resources/u-boot/BOARDNAME/`.
+
+You can then use `git format-patch -nX` where `X` is however many patches you
+added to that U-Boot tree. You can put them in the patches directory
+under `resources/u-boot/BOARDNAME`.
+
+The *base* revision, upon which any custom patches you wrote are applied,
+shall be the `ubrevision` entry.
+
+Scripts exist in `lbmk` for automating the modification/updating of *existing*
+configs, but not for adding them. Adding them is to be done manually, based on
+the above guidance.
+
+resources/u-boot/BOARDNAME/patches/\*
+=====================================
+
+In cases where `ubrevision` is specified, where the given directory
+under `resources/u-boot/` does in fact define a version of U-Boot to
+download, you can add custom *patches* on top of that revision. When you run
+the command `./download u-boot`, those patches will be applied chronologically
+in alphanumerical order as per patch file names.
+
+The patch files should be named with `.patch` file extensions. All other files
+will be ignored. By having `lbmk` do it this way, you could add a `README` file
+for instance, and `lbmk` will not erroneously try to apply `README` as though
+it were a patch file. This might be useful if you have a *lot* of patches, and
+you want to provide some explanations about specific files.
+
 resources/grub/background/
 ==========================
 
@@ -595,7 +735,7 @@ It automatically detects if `crossgcc` is to be compiled, on a given coreboot
 tree (in cases where it has not yet been compiled), and compiles it for a
 target based on the `arch` entry in `board.cfg`.
 
-It creates ROM images with GRUB and/or SeaBIOS, optionally with Memtest86+
+It creates ROM images with GRUB, SeaBIOS, U-Boot, optionally with Memtest86+
 also included, in various separate configurations in many different ROM images
 for user installation.
 
@@ -739,6 +879,14 @@ This runs `make clean` in the `seabios/` directory.
 
 Command: `./build clean seabios`
 
+resources/scripts/build/clean/u-boot
+======================================
+
+This runs `make distclean` and `git clean -fdx` on all of the U-Boot revisions
+present in lbmk.
+
+Command: `./build clean u-boot`
+
 resources/scripts/build/dependencies/arch
 =========================================
 
@@ -836,6 +984,17 @@ This builds the SeaBIOS payloads.
 
 Command: `./build payload seabios`
 
+resources/scripts/build/payload/u-boot
+======================================
+
+This builds the U-Boot payloads. Usually a target board and a cross-compiler
+appropriate for the board must be specified for it to work, because trying to
+build for all boards of varying architectures using only the host compiler will
+not work.
+
+Command: `CROSS_COMPILE=aarch64-gnu-linux- ./build payload u-boot qemu_arm64_12mb`
+
+
 resources/scripts/build/release/roms
 ====================================
 
@@ -908,6 +1067,14 @@ This downloads and patches SeaBIOS.
 
 Command: `./download seabios`
 
+resources/scripts/download/u-boot
+=================================
+
+This downloads, and patches U-Boot, as per `board.cfg` files
+in `resources/u-boot/`.
+
+Command: `./download u-boot`
+
 resources/scripts/misc/versioncheck
 ===================================
 
@@ -937,6 +1104,20 @@ This lets you modify SeaBIOS configs.
 
 Command: `./modify seabios configs`
 
+resources/scripts/modify/u-boot/configs
+=======================================
+
+Loads U-Boot configs into U-Boot trees, and runs `make menuconfig`, so
+that you can easily modify them in an ncurses interface. Additional parameters
+are accepted, for example:
+
+    ./modify u-boot configs gru_kevin gru_bob
+
+With no additional parameters given, it simply cycles through all configs
+under `resources/u-boot/`.
+
+Command: `./modify u-boot configs`
+
 resources/scripts/update/coreboot/configs
 =========================================
 
@@ -959,6 +1140,29 @@ the version of SeaBIOS used by lbmk.
 
 Command: `./update seabios configs`
 
+resources/scripts/update/u-boot/configs
+=========================================
+
+This runs `make oldconfig` on U-Boot configs under `resources/u-boot/`.
+It is most useful when updating a U-Boot revision, per `board.cfg`. It allows
+additional parameters, for example:
+
+    ./update u-boot configs gru_kevin gru_bob
+
+With no additional parameters given, it simply cycles through all configs
+under `resources/u-boot/`.
+
+However, using `make oldconfig` is not optimal for U-Boot, as their Kconfig
+dependencies/defaults are not as well specified as coreboot's is. When updating
+configs for an upstream board, it's usually better (but not automated) to:
+
+- Turn `lbmk` config into a defconfig in the old version
+- Compare it with the old version's upstream defconfig
+- Apply the difference to the new version's upstream defconfig
+- Create an updated config in the new version
+
+Command: `./update u-boot configs`
+
 resources/seabios/config/libgfxinit
 ===================================
 
@@ -975,8 +1179,8 @@ to be used.
 update
 ======
 
-This can be used to update SeaBIOS and coreboot configs. It calls scripts
-in `resources/scripts/update/`, for example:
+This can be used to update SeaBIOS, coreboot and U-Boot configs. It calls
+scripts in `resources/scripts/update/`, for example:
 
     ./update coreboot configs
 

site/docs/misc/codenames.md

@@ -32,7 +32,18 @@ List of models and codenames
 
 ### Codenames
 
--   Asus Chromebook C201PA: speedy\_rk3288, veyron-speedy
+-   Samsung Chromebook 2 13": peach-pi
+-   Samsung Chromebook 2 11": peach-pit
+-   HP Chromebook 11 G1: spring
+-   Samsung Chromebook XE303: snow
+-   HP Chromebook 14 G3: nyan-blaze
+-   Acer Chromebook 13: (CB5-311, C810) nyan-big
+-   ASUS Chromebit CS10: veyron-mickey
+-   ASUS Chromebook Flip C100PA: veyron-minnie
+-   ASUS Chromebook C201PA: veyron-speedy
+-   Hisense Chromebook C11 and more: veyron-jerry
+-   ASUS Chromebook Flip C101: bob
+-   Samsung Chromebook Plus (v1): kevin
 
 -   ThinkPad X60: KS Note (Sumo)
 -   ThinkPad X60s (slim): KS Note-2 / KS-2 (Kabuki)
@@ -112,3 +123,5 @@ See also
     [Wikipedia](https://en.wikipedia.org/wiki/List_of_Intel_codenames).
 -   For ThinkPads see [Documentation/thinkpad/codenames.csv @ Coreboot]
 (https://review.coreboot.org/cgit/coreboot.git/tree/Documentation/thinkpad/codenames.csv)
+-   For Chromebooks see [Developer information for ChromeOS devices]
+(https://www.chromium.org/chromium-os/developer-information-for-chrome-os-devices/)

site/docs/misc/emulation.md

@@ -25,6 +25,15 @@ For example:
 
 `qemu-system-x86_64 -bios bin/qemu_x86_12mb/grub_qemu_x86_12mb_libgfxinit_corebootfb_usqwerty.rom`
 
+`qemu-system-x86_64 -bios bin/qemu_x86_12mb/uboot_payload_qemu_x86_12mb_libgfxinit_corebootfb.rom -serial stdio`
+
+There is basic support for an arm64 virtual machine as well, although the payloads are not as developed as the x86 one:
+
+    ./build boot roms qemu_arm64_12mb
+
+    qemu-system-aarch64 -bios bin/qemu_arm64_12mb/uboot_payload_qemu_arm64_12mb_libgfxinit_corebootfb.rom \
+        -M virt,secure=on,virtualization=on,acpi=on -cpu cortex-a53 -m 768M -serial stdio -vga none -display none
+
 Use Cases
 =========