Merge remote-tracking branch 'upstream/master' into system76

Documentation/acpi/index.md

@@ -0,0 +1,13 @@
+# ACPI-specific documentation
+
+This section contains documentation about coreboot on ACPI.
+
+- [SSDT UID generation](uid.md)
+
+## GPIO
+
+- [GPIO toggling in ACPI AML](gpio.md)
+
+## devicetree
+
+- [Adding devices to a device tree](devicetree.md)

Documentation/acpi/uid.md

@@ -0,0 +1,14 @@
+# ACPI SSDT \_UID generation
+
+According to the ACPI spec:
+
+> The _UID must be unique across all devices with either a common _HID or _CID.
+
+
+When generating SSDTs in coreboot the independent drivers don't know
+which \_UID is already in use for a specific \_HID or \_CID. To generate
+unique \_UIDs the ACPI device's path is hashed and used as ID. As every ACPI
+device has a different path, the hash will be also different for every device.
+
+Windows 10 verifies all devices with the same \_HID or \_CID and makes
+sure that no \_UID is duplicated. If it is it'll BSOD.

Documentation/arch/riscv/index.md

@@ -19,6 +19,9 @@ On entry to a stage or payload (including SELF payloads),
 * all harts are running.
 * A0 is the hart ID.
 * A1 is the pointer to the Flattened Device Tree (FDT).
+* A2 contains the additional program calling argument:
+  - cbmem_top for ramstage
+  - the address of the payload for opensbi
 
 ## Additional payload handoff requirements
 The location of cbmem should be placed in a node in the FDT.

Documentation/conf.py

@@ -25,6 +25,8 @@ release = subprocess.check_output(('git', 'describe')).decode("utf-8")
 # The short X.Y version.
 version = release.split("-")[0]
 
+extensions = ['sphinxcontrib.ditaa']
+
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
 #

Documentation/contributing/project_ideas.md

@@ -64,7 +64,7 @@ across architectures.
 ### Mentors
 * Timothy Pearson <tpearson@raptorengineering.com>
 
-## Support QEMU AArch64 or MIPS
+## Support QEMU AArch64
 Having QEMU support for the architectures coreboot can boot helps with
 some (limited) compatibility testing: While QEMU generally doesn't need
 much hardware init, any CPU state changes in the boot flow will likely
@@ -105,7 +105,7 @@ would help to ensure code quality and make the runtime code more robust.
 ### Mentors
 * Werner Zeh <werner.zeh@gmx.net>
 
-## Port payloads to ARM, AArch64, MIPS or RISC-V
+## Port payloads to ARM, AArch64 or RISC-V
 While we have a rather big set of payloads for x86 based platforms, all other
 architectures are rather limited. Improve the situation by porting a payload
 to one of the platforms, for example GRUB2, U-Boot (the UI part), Tianocore,

Documentation/drivers/index.md

@@ -5,3 +5,4 @@ and plugin devices, significantly reducing integration complexity and
 they allow to easily reuse existing code accross platforms.
 
 * [IPMI KCS](ipmi_kcs.md)
+* [SMMSTORE](smmstore.md)

Documentation/drivers/smmstore.md

@@ -0,0 +1,123 @@
+# SMM based flash storage driver
+
+This documents the API exposed by the x86 system management based
+storage driver.
+
+## SMMSTORE
+
+SMMSTORE is a SMM mediated driver to read from, write to and erase a
+predefined region in flash. It can be enabled by setting
+`CONFIG_SMMSTORE=y` in menuconfig.
+
+This can be used by the OS or the payload to implement persistent
+storage to hold for instance configuration data, without needing
+to implement a (platform specific) storage driver in the payload
+itself.
+
+The API provides append-only semantics for key/value pairs.
+
+## API
+
+### Storage region
+
+By default SMMSTORE will operate on a separate FMAP region called
+`SMMSTORE`. The default generated FMAP will include such a region.
+On systems with a locked FMAP, e.g. in an existing VBOOT setup
+with a locked RO region, the option exists to add a cbfsfile
+called `smm_store` in the `RW_LEGACY` (if CHROMEOS) or in the
+`COREBOOT` FMAP regions. It is recommended for new builds using
+a handcrafted FMD that intend to make use of SMMSTORE to include a
+sufficiently large `SMMSTORE` FMAP region. It is recommended to
+align the `SMMSTORE` region to 64KiB for the largest flash erase
+op compatibility.
+
+When a default generated FMAP is used the size of the FMAP region
+is equal to `CONFIG_SMMSTORE_SIZE`. UEFI payloads expect at least
+64KiB. Given that the current implementation lacks a way to rewrite
+key-value pairs at least a multiple of this is recommended.
+
+### generating the SMI
+
+SMMSTORE is called via an SMI, which is generated via a write to the
+IO port defined in the smi_cmd entry of the FADT ACPI table. `%al`
+contains `APM_CNT_SMMSTORE=0xed` and is written to the smi_cmd IO
+port. `%ah` contains the SMMSTORE command. `%ebx` contains the
+parameter buffer to the SMMSTORE command.
+
+### Return values
+
+If a command succeeds, SMMSTORE will return with
+`SMMSTORE_RET_SUCCESS=0` on `%eax`. On failure SMMSTORE will return
+`SMMSTORE_RET_FAILURE=1`. For unsupported SMMSTORE commands
+`SMMSTORE_REG_UNSUPPORTED=2` is returned.
+
+**NOTE1**: The caller **must** check the return value and should make
+no assumption on the returned data if `%eax` does not contain
+`SMMSTORE_RET_SUCCESS`.
+
+**NOTE2**: If the SMI returns without changing `%ax` assume that the
+SMMSTORE feature is not installed.
+
+### Calling arguments
+
+SMMSTORE supports 3 subcommands that are passed via `%ah`, the additional
+calling arguments are passed via `%ebx`.
+
+**NOTE**: The size of the struct entries are in the native word size of
+smihandler. This means 32 bits in almost all cases.
+
+
+#### - SMMSTORE_CMD_CLEAR = 1
+
+This clears the `SMMSTORE` storage region. The argument in `%ebx` is
+unused.
+
+#### - SMMSTORE_CMD_READ = 2
+
+The additional parameter buffer `%ebx` contains a pointer to
+the following struct:
+
+```C
+struct smmstore_params_read {
+	void *buf;
+	ssize_t bufsize;
+};
+```
+
+INPUT:
+- `buf`: is a pointer to where the data needs to be read
+- `bufsize`: is the size of the buffer
+
+OUTPUT:
+- `buf`
+- `bufsize`: returns the amount of data that has actually been read.
+
+#### - SMMSTORE_CMD_APPEND = 3
+
+SMMSTORE takes a key-value approach to appending data. key-value pairs
+are never updated, they are always appended. It is up to the caller to
+walk through the key-value pairs after reading SMMSTORE to find the
+latest one.
+
+The additional parameter buffer `%ebx` contains a pointer to
+the following struct:
+
+```C
+struct smmstore_params_append {
+	void *key;
+	size_t keysize;
+	void *val;
+	size_t valsize;
+};
+```
+
+INPUT:
+- `key`: pointer to the key data
+- `keysize`: size of the key data
+- `val`: pointer to the value data
+- `valsize`: size of the value data
+
+## External links
+
+* [A Tour Beyond BIOS Implementing UEFI Authenticated Variables in SMM with EDKI](https://software.intel.com/sites/default/files/managed/cf/ea/a_tour_beyond_bios_implementing_uefi_authenticated_variables_in_smm_with_edkii.pdf)
+Note, this differs significantly from coreboot's implementation.

Documentation/getting_started/gpio.md

@@ -0,0 +1,136 @@
+# Configuring a mainboard's GPIOs in coreboot
+
+## Introduction
+
+Every mainboard needs to appropriately configure its General Purpose Inputs /
+Outputs (GPIOs). There are many facets of this issue, including which boot
+stage a GPIO might need to be configured.
+
+## Boot stages
+
+Typically, coreboot does most of its non-memory related initialization work in
+ramstage, when DRAM is available for use. Hence, the bulk of a mainboard's GPIOs
+are configured in this stage. However, some boards might need a few GPIOs
+configured before that; think of memory strapping pins which indicate what kind
+of DRAM is installed. These pins might need to be read before initializing the
+memory, so these GPIOs are then typically configured in bootblock or romstage.
+
+## Configuration
+
+Most mainboards will have a ``gpio.c`` file in their mainboard directory. This
+file typically contains tables which describe the configuration of the GPIO
+registers. Since these registers could be different on a per-SoC or per
+SoC-family basis, you may need to consult the datasheet for your SoC to find out
+how to appropriately set these registers. In addition, some mainboards are
+based on a baseboard/variant model, where several variant mainboards may share a
+lot of their circuitry and ICs and the commonality between the boards is
+collected into a virtual ``baseboard.`` In that case, the GPIOs which are shared
+between multiple boards are placed in the baseboard's ``gpio.c` file, while the
+ones that are board-specific go into each variant's ``gpio.c`` file.
+
+## Intel SoCs
+
+Many newer Intel SoCs share a common IP block for GPIOs, and that commonality
+has been taken advantage of in coreboot, which has a large set of macros that
+can be used to describe the configuration of each GPIO pad. This file lives in
+``src/soc/intel/common/block/include/intelblocks/gpio_defs.h``.
+
+### Older Intel SoCs
+
+Baytrail and Braswell, for example, simply expect the mainboard to supply a
+callback, `mainboard_get_gpios` which returns an array of `struct soc_gpio`
+objects, defining the configuration of each pin.
+
+### AMD SoCs
+
+Some AMD SoCs use a list of `struct soc_amd_gpio` objects to define the
+register values configuring each pin, similar to Intel.
+
+### Register details
+
+GPIO configuration registers typically control properties such as:
+1. Input / Output
+2. Pullups / Pulldowns
+3. Termination
+4. Tx / Rx Disable
+5. Which reset signal to use
+6. Native Function / IO
+7. Interrupts
+    * IRQ routing (e.g. on x86, APIC, SCI, SMI)
+    * Edge or Level Triggered
+    * Active High or Active Low
+8. Debouncing
+
+## Configuring GPIOs for pre-ramstage
+
+coreboot provides for several SoC-specific and mainboard-specific callbacks at
+specific points in time, such as bootblock-early, bootblock, romstage entry,
+pre-silicon init, pre-RAM init, or post-RAM init. The GPIOs that are
+configured in either bootblock or romstage, depending on when they are needed,
+are denoted the "early" GPIOs. Some mainboard will use
+``bootblock_mainboard_init()`` to configure their early GPIOs, and this is
+probably a good place to start. Many mainboards will declare their GPIO
+configuration as structs, i.e. (Intel),
+
+```C
+struct pad_config {
+    /* offset of pad within community */
+        int             pad;
+    /* Pad config data corresponding to DW0, DW1,.... */
+        uint32_t        pad_config[GPIO_NUM_PAD_CFG_REGS];
+};
+```
+
+and will usually place these in an array, one for each pad to be configured.
+Mainboards using Intel SoCs can use a library which combines common
+configurations together into a set of macros, e.g.,
+
+```C
+    /* Native function configuration */
+    #define PAD_CFG_NF(pad, pull, rst, func)
+    /*
+     * Set native function with RX Level/Edge configuration and disable
+     * input/output buffer if necessary
+     */
+    #define PAD_CFG_NF_BUF_TRIG(pad, pull, rst, func, bufdis, trig)
+    /* General purpose output, no pullup/down. */
+    #define PAD_CFG_GPO(pad, val, rst)
+    /* General purpose output, with termination specified */
+    #define PAD_CFG_TERM_GPO(pad, val, pull, rst)
+    /* General purpose output, no pullup/down. */
+    #define PAD_CFG_GPO_GPIO_DRIVER(pad, val, rst, pull)
+    /* General purpose input */
+    #define PAD_CFG_GPI(pad, pull, rst)
+```
+etc.
+
+## Configuring GPIOs for ramstage and beyond...
+
+In ramstage, most mainboards will configure the rest of their GPIOs for the
+function they will be performing while the device is active. The goal is the
+same as above in bootblock; another ``static const`` array is created, and the
+rest of the GPIO registers are programmed.
+
+In the baseboard/variant model described above, the baseboard will provide the
+configuration for the GPIOs which are configured identically between variants,
+and will provide a mechanism for a variant to override the baseboard's
+configuration. This is usually done via two tables: the baseboard table and the
+variant's override table.
+
+This configuration is often hooked into the mainboard's `enable_dev` callback,
+defined in its `struct chip_operations`.
+
+## Potential issues (gotchas!)
+
+There are a couple of configurations that you need to especially careful about,
+as they can have a large impact on your mainboard.
+
+The first is configuring a pin as an output, when it was designed to be an
+input. There is a real risk in this case of short-circuiting a component which
+could cause catastrophic failures, up to and including your mainboard!
+
+The other configuration option to watch out for deals with unconnected GPIOs.
+If no pullup or pulldown is declared with these, they may end up "floating",
+i.e., not at logical high or logical low. This can cause problems such as
+unwanted power consumption or not reading the pin correctly, if it was intended
+to be strapped.

Documentation/getting_started/index.md

@@ -7,3 +7,4 @@
 * [Gerrit Guidelines](gerrit_guidelines.md)
 * [Documentation License](license.md)
 * [Writing Documentation](writing_documentation.md)
+* [Setting up GPIOs](gpio.md)

Documentation/getting_started/writing_documentation.md

@@ -42,8 +42,25 @@ Please follow this official [guide] to install sphinx.
 You will also need python-recommonmark for sphinx to be able to handle
 markdown documentation.
 
-The recommended version is sphinx 1.7.7, sphinx_rtd_theme 0.4.1 and
-recommonmark 0.4.0.
+Since some Linux distributions don't package every needed sphinx extension,
+the installation via pip in a venv is recommended. You'll need these python3
+modules:
+
+* sphinx
+* recommonmark
+* sphinx_rtd_theme
+* sphinxcontrib-ditaa
+
+The following combination of versions has been tested: sphinx 2.3.1,
+recommonmark 0.6.0, sphinx_rtd_theme 0.4.3 and sphinxcontrib-ditaa 0.7.
+
+Now change into the `Documentation` folder in the coreboot directory and run
+this command in there
+
+	make sphinx
+
+If no error occurs, you can find the generated HTML documentation in
+`Documentation/_build` now.
 
 ### Optional
 

Documentation/index.md

@@ -171,20 +171,19 @@ Contents:
 * [Payloads](payloads.md)
 * [Distributions](distributions.md)
 * [Technotes](technotes/index.md)
-* [GPIO toggling in ACPI AML](acpi/gpio.md)
-* [Adding devices to a device tree](acpi/devicetree.md)
+* [ACPI](acpi/index.md)
 * [Native Graphics Initialization with libgfxinit](gfx/libgfxinit.md)
-* [Display panel-specific documentation](gfx/display-panel.md)
-* [Architecture-specific documentation](arch/index.md)
-* [Platform independend drivers documentation](drivers/index.md)
-* [Northbridge-specific documentation](northbridge/index.md)
-* [System on Chip-specific documentation](soc/index.md)
-* [Mainboard-specific documentation](mainboard/index.md)
-* [Payload-specific documentation](lib/payloads/index.md)
-* [Library-specific documentation](lib/index.md)
+* [Display panel](gfx/display-panel.md)
+* [CPU Architecture](arch/index.md)
+* [Platform independent drivers](drivers/index.md)
+* [Northbridge](northbridge/index.md)
+* [System on Chip](soc/index.md)
+* [Mainboard](mainboard/index.md)
+* [Payloads](lib/payloads/index.md)
+* [Libraries](lib/index.md)
 * [Security](security/index.md)
-* [SuperIO-specific documentation](superio/index.md)
-* [Vendorcode-specific documentation](vendorcode/index.md)
+* [SuperIO](superio/index.md)
+* [Vendorcode](vendorcode/index.md)
 * [Utilities](util.md)
 * [Release notes for past releases](releases/index.md)
 * [Flashing firmware tutorial](flash_tutorial/index.md)

Documentation/lib/payloads/fit.md

@@ -58,7 +58,7 @@ Supported compression algorithms:
 The config entries contain a compatible string, that is used to find a
 matching config.
 
-The following mainboard specific funtions provide the BOARDID and SKUID:
+The following mainboard specific functions provide the BOARDID and SKUID:
 
 ```c
 uint32_t board_id(void);

Documentation/mainboard/asus/p5q.md

@@ -0,0 +1,77 @@
+# ASUS P5Q
+
+This page describes how to run coreboot on the [ASUS P5Q] desktop board.
+
+## TODO
+
+The following things are working in this coreboot port:
+
++ PCI slots
++ PCI-e slots
++ Onboard Ethernet
++ USB
++ Onboard sound card
++ PS/2 keyboard
++ All 4 DIMM slots
++ S3 suspend and resume
++ Red SATA ports
+
+The following things are still missing from this coreboot port:
+
++ PS/2 mouse support
++ PATA aka IDE (because of buggy IDE controller)
++ Fan control (will be working on 100% power)
++ TPM module (support not implemented)
+
+The following things are untested on this coreboot port:
+
++ S/PDIF
++ CD Audio In
++ Floppy disk drive
++ FireWire: PCI device shows up and driver loads, no further test
+
+
+## Flashing coreboot
+
+```eval_rst
++-------------------+----------------+
+| Type              | Value          |
++===================+================+
+| Socketed flash    | Yes            |
++-------------------+----------------+
+| Model             | MX25L8005      |
++-------------------+----------------+
+| Size              | 1 MiB          |
++-------------------+----------------+
+| Package           | Socketed DIP-8 |
++-------------------+----------------+
+| Write protection  | No             |
++-------------------+----------------+
+| Dual BIOS feature | No             |
++-------------------+----------------+
+| Internal flashing | Yes            |
++-------------------+----------------+
+```
+
+You can flash coreboot into your motherboard using [this guide].
+
+## Technology
+
+```eval_rst
++------------------+---------------------------------------------------+
+| Northbridge      | Intel P45 (called x4x in coreboot code)           |
++------------------+---------------------------------------------------+
+| Southbridge      | Intel ICH10R (called i82801jx in coreboot code)   |
++------------------+---------------------------------------------------+
+| CPU (LGA775)     | Model f4x, f6x, 6fx, 1067x (Pentium 4, d, Core 2) |
++------------------+---------------------------------------------------+
+| SuperIO          | Winbond W83667HG                                  |
++------------------+---------------------------------------------------+
+| Coprocessor      | No                                                |
++------------------+---------------------------------------------------+
+| Clockgen (CK505) | ICS 9LPRS918JKLF                                  |
++------------------+---------------------------------------------------+
+```
+
+[ASUS P5Q]: https://www.asus.com/Motherboards/P5Q
+[this guide]: https://doc.coreboot.org/flash_tutorial/int_flashrom.html

Documentation/mainboard/facebook/fbg1701.md

@@ -14,8 +14,7 @@ Mainboard menu.
 
 This board currently requires:
 fsp blob	3rdparty/fsp/BraswellFspBinPkg/FspBin/BSWFSP.fd
-Microcode	Intel Braswell cpuid 1046C4 version 410
-		(Used pre-built binary retrieved from Intel site)
+Microcode	3rdparty/intel-microcode/intel-ucode/06-4c-04
 
 ## Flashing coreboot
 
@@ -73,7 +72,7 @@ Specifically, it's a Winbond W25Q64FV (3.3V), whose datasheet can be found
 +------------------+--------------------------------------------------+
 | CPU              | Intel Braswell (N3710)                           |
 +------------------+--------------------------------------------------+
-| Super I/O, EC    | ITE8256                                          |
+| Super I/O, EC    | ITE8528                                          |
 +------------------+--------------------------------------------------+
 | Coprocessor      | Intel Management Engine                          |
 +------------------+--------------------------------------------------+

Documentation/mainboard/facebook/monolith.md

@@ -0,0 +1,78 @@
+# Facebook Monolith
+
+This page describes how to run coreboot on the Facebook Monolith.
+
+Please note: the coreboot implementation for this boards is in its
+Alpha state and isn't fully tested yet.
+
+## Required blobs
+
+This board currently requires:
+fsp blobs	3rdparty/fsp/KabylakeFspBinPkg/Fsp_M.fd
+		3rdparty/fsp/KabylakeFspBinPkg/Fsp_S.fd
+
+Microcode	3rdparty/intel-microcode/intel-ucode
+
+## Flashing coreboot
+
+### Internal programming
+
+The SPI flash can be accessed using [flashrom].
+
+### External programming
+
+The system has an internal flash chip which is a 16 MiB soldered SOIC-8 chip.
+Specifically, it's a Winbond W25Q128JVSIQ (3.3V).
+
+The system has an external flash chip which is a 16 MiB soldered SOIC-8 chip.
+Specifically, it's a Winbond W25Q128JVSIM (3.3V).
+
+Flashing of these devices is very difficult, disassembling the system destroys the cooling
+solution. Wires need to be connected to be able to flash using an external programmer.
+
+## Known issues
+
+- None
+
+## Untested
+
+- Hardware monitor
+- SDIO
+- Full Embedded Controller support
+- eMMC
+- SATA
+
+## Working
+
+- USB
+- Gigabit Ethernet
+- Graphics (Using FSP GOP)
+- flashrom
+- PCIe
+- EC serial port
+- SMBus
+- Initialization with FSP
+- SeaBIOS payload (commit a5cab58e9a3fb6e168aba919c5669bea406573b4)
+- TianoCore payload (commit a5cab58e9a3fb6e168aba919c5669bea406573b4)
+
+All of the above has been briefly tested by booting Linux from the TianoCore payload.
+SeaBios has been checked to the extend that it runs to the boot selection and provides display
+output.
+
+## Technology
+
+```eval_rst
++------------------+--------------------------------------------------+
+| SoC              | Intel Kaby Lake U                                |
++------------------+--------------------------------------------------+
+| CPU              | Intel i3-7100U                                   |
++------------------+--------------------------------------------------+
+| Super I/O, EC    | ITE8528                                          |
++------------------+--------------------------------------------------+
+| Coprocessor      | Intel Management Engine                          |
++------------------+--------------------------------------------------+
+```
+
+[W25Q128JVSIQ]: https://www.winbond.com/resource-files/w25q128jv%20revf%2003272018%20plus.pdf
+[W25Q128JVSIM]: https://www.winbond.com/resource-files/w25q128jv%20dtr%20revb%2011042016.pdf
+[flashrom]: https://flashrom.org/Flashrom

Documentation/mainboard/gigabyte/ga-h61m-s2pv.md

@@ -39,27 +39,23 @@ leave the backup chip untouched.
 
 The original IFD defines the BIOS region as the whole flash chip. While this is
 not an issue if flashing a complete image, it confuses flashrom and trashes the
-flash chip's contents when using the --ifd option. However, this can be easily
-fixed by reading the IFD with flashrom, editing the correct values into it with
-ifdtool and then reflashing it.
-
-Create a layout.txt with the following contents:
+flash chip's contents when using the `--ifd` option. A possible workaround is
+to create a `layout.txt` file with a non-overlapping BIOS region:
 
 	00000000:00000fff fd
 	00180000:003fffff bios
 	00001000:0017ffff me
 
-After that, simply run:
+After that, use flashrom with the new layout file. For example, to create a
+backup of the BIOS region and then flash a `coreboot.rom`, do:
 
 ```bash
-sudo flashrom -p internal --ifd -i fd -r ifd.rom
-ifdtool -n layout.txt ifd.rom
-sudo flashrom -p internal --ifd -i fd -w ifd.rom.new
+sudo flashrom -p internal -l layout.txt -i bios -r backup.rom
+sudo flashrom -p internal -l layout.txt -i bios -w coreboot.rom
 ```
 
-After flashing, power cycle the computer to ensure the new IFD is being used.
-If only a reboot is done, the old IFD layout is still seen by flashrom, even if
-the IFD on the flash chip is correctly defining the new region layout.
+Modifying the IFD so that the BIOS region does not overlap would work as well.
+However, this makes DualBIOS unable to recover from a bad flash for some reason.
 
 ## Technology
 

Documentation/mainboard/index.md

@@ -32,6 +32,7 @@ The boards in this section are not real mainboards, but emulators.
 ## Facebook
 
 - [FBG-1701](facebook/fbg1701.md)
+- [Monolith](facebook/monolith.md)
 
 ## Foxconn
 
@@ -95,10 +96,6 @@ The boards in this section are not real mainboards, but emulators.
 
 - [T440p](lenovo/t440p.md)
 
-## Portwell
-
-- [PQ7-M107](portwell/pq7-m107.md)
-
 ## MSI
 
 - [MS-7707](msi/ms7707/ms7707.md)
@@ -129,6 +126,7 @@ The boards in this section are not real mainboards, but emulators.
 
 - [X10SLM+-F](supermicro/x10slm-f.md)
 - [X11 LGA1151 series](supermicro/x11-lga1151-series/x11-lga1151-series.md)
+- [Flashing using the BMC](supermicro/flashing_on_vendorbmc.md)
 
 ## UP
 

Documentation/mainboard/portwell/pq7-m107.md

@@ -14,8 +14,7 @@ menu.
 
 This board currently requires:
 fsp blob	3rdparty/fsp/BraswellFspBinPkg/FspBin/BSWFSP.fd
-Microcode	Intel Braswell cpuid 1046C4 version 410
-		(Used pre-built binary retrieved from Intel site)
+Microcode	3rdparty/intel-microcode/intel-ucode/06-4c-04
 
 ## Flashing coreboot
 
@@ -68,7 +67,7 @@ serial/video/pcie ports might be available.
 +------------------+--------------------------------------------------+
 | CPU              | Intel Braswell (N3710)                           |
 +------------------+--------------------------------------------------+
-| Super I/O, EC    | ITE8256                                          |
+| Super I/O, EC    | ITE8528                                          |
 +------------------+--------------------------------------------------+
 | Coprocessor      | Intel Management Engine                          |
 +------------------+--------------------------------------------------+

Documentation/mainboard/supermicro/flashing_on_vendorbmc.md

@@ -0,0 +1,32 @@
+# Flashing coreboot using SMC IPMI (BMC) firmware
+
+## Metadata
+In order to flash anything to the "BIOS" IC, it needs to contain a valid
+BIOSINFO struct.
+
+The BIOSINFO struct contains a `$FID` marker at the beginning and is
+128 bytes in total. Besides the *BoardID* it contains the *firmware version*
+and *build date*. The BMC verifies that the BoardID is correct and refuses to
+flash if it's not.
+
+The struct has no checksum or cryptographic protection.
+
+## The smcinfobios tool
+
+The smcbiosinfo tool can be found in `util/supermicro/smcbiosinfo`.
+
+It parses the `build/build.h` header to get the current coreboot version and
+build timestamp.
+The *board ID* is passed as command line argument.
+
+It will place a file in CBFS called `smcbiosinfo.bin`, which is then found
+by the vendor tools. The file contains the struct described above.
+
+## Flashing using SMCIPMItool
+
+You can use the *SMCIPMITool* to remotely flash the BIOS:
+
+`SMCIPMITool <remote BMC IP> <user> <password> bios update build/coreboot.rom`
+
+Make sure that the ME isn't in recovery mode, otherwise you get an error
+message on updating the BIOS.

Documentation/mainboard/supermicro/x10slm-f.md

@@ -68,7 +68,7 @@ region is not readable even by the host.
 The main firmware flash chip is an SOIC-8 package located near the CMOS
 battery and SATA ports. It should come with a sticker attached that
 states the firmware revision (e.g. "X10SLH 4.424"). The chip model is
-an N25Q128A, and the datasheet can be found [here][N25Q128A].
+an N25Q128A ([datasheet][N25Q128A]).
 
 As with [internal programming](#internal-programming), [flashrom] works
 reliably:
@@ -87,8 +87,7 @@ way without issue.
 
 This board has an ASPEED [AST2400], which has BMC functionality. The
 BMC firmware resides in a 32 MiB SOIC-16 chip just above the [AST2400].
-This chip is an MX25L25635F, whose datasheet can be found
-[here][MX25L25635F].
+This chip is an MX25L25635F ([datasheet][MX25L25635F]).
 
 ### Removing the BMC functionality
 

Documentation/mainboard/supermicro/x11-lga1151-series/x11-lga1151-series.md

@@ -31,7 +31,7 @@ Look at the [flashing tutorial] and the board-specific section.
 These issues apply to all boards. Have a look at the board-specific issues, too.
 
 - TianoCore doesn't work with Aspeed NGI, as it's text mode only (Fix is WIP CB:35726)
-- MRC caching does not work with cold boot
+- MRC caching does not work on cold boot with Intel SPS (see [Intel FSP2.0])
 
 ## ToDo
 

Documentation/releases/checklist.md

@@ -49,29 +49,34 @@ be more frequent than was needed, so we scaled it back to twice a year.
 ## Checklist
 ### ~2 weeks prior to release
 - [ ] Announce upcoming release to mailing list, ask people to test and
-      to update release notes
+      to update release notes.
 
 ### ~1 week prior to release
 - [ ] Send reminder email to mailing list, ask for people to test,
-      and to update the release notes
-- [ ] Update the topic in the irc channel with the date of the upcoming
-      release
+      and to update the release notes.
+- [ ] Update the topic in the IRC channel with the date of the upcoming
+      release.
+- [ ] If there are any deprecations announced for the following release,
+      make sure that a list of currently affected boards and chipsets is
+      part of the release notes.
+- [ ] Finalize release notes (as much as possible), without specifying
+      release commit ids.
 
 ### Day of release
-- [ ] Update release notes, without specifying release commit ids
 - [ ] Select a commit ID to base the release upon, announce to IRC,
       ask for testing.
-- [ ] Test the commit selected for release
-- [ ] Run release script
-- [ ] Test the release from the actual release tarballs
-- [ ] Push signed Tag to repo
-- [ ] Announce that the release tag is done on IRC
-- [ ] Update release notes with actual commit id, push to repo
+- [ ] Test the commit selected for release.
+- [ ] Update release notes with actual commit id, push to repo.
+- [ ] Run release script.
+- [ ] Test the release from the actual release tarballs.
+- [ ] Push signed Tag to repo.
+- [ ] Announce that the release tag is done on IRC.
 - [ ] Upload release files to web server
-- [ ] Upload crossgcc sources to web server
-- [ ] Update download page to point to files, push to repo
+- [ ] Upload crossgcc sources to web server.
+- [ ] Update download page to point to files, push to repo.
 - [ ] Write and publish blog post with release notes.
-- [ ] Update the topic in the irc channel that the release is done.
+- [ ] Update the topic in the IRC channel that the release is done.
+- [ ] Announce the release to the mailing list.
 
 ## Pre-Release tasks
 Announce the upcoming release to the mailing list release 2 weeks ahead
@@ -82,9 +87,7 @@ release notes that are in the making and ask people to test the hardware
 they have to make sure it's working with the current master branch,
 from which the release will ultimately be derived from.
 
-People should also be encouraged to provide additions to the
-release notes, for example by putting them on some [collaborative
-editor](https://www.piratenpad.de).
+People should be encouraged to provide additions to the release notes.
 
 The final release notes will reside in coreboot's Documentation/releases
 directory, so asking for additions to that through the regular Gerrit
@@ -99,7 +102,7 @@ to have in the release.  The release was based on the final of those
 patches to be pulled in.
 
 When a release candidate has been selected, announce the commit ID to
-the #coreboot irc channel, and request that it get some testing, just
+the #coreboot IRC channel, and request that it get some testing, just
 to make sure that everything is sane.
 
 ## Generate the release

Documentation/releases/coreboot-4.11-relnotes.md

@@ -1,35 +1,133 @@
-Upcoming release - coreboot 4.11
-================================
+coreboot 4.11
+=============
 
-The 4.11 release is planned for October 2019
+coreboot 4.11 was released on November 19th.
 
-Update this document with changes that should be in the release
-notes.
-* Please use Markdown.
-* See the [4.9](coreboot-4.9-relnotes.md) and [4.10](coreboot-4.10-relnotes.md)
-  release notes for the general format.
-* The chip and board additions and removals will be updated right
-  before the release, so those do not need to be added.
+This release cycle was a bit shorter to get closer to our regular
+schedule of releasing in spring and autumn.
+
+Since 4.10 there were 1630 new commits by over 130 developers.
+Of these, about 30 contributed to coreboot for the first time.
+
+Thank you to all contributors who made 4.11 what it is and welcome
+to the project to all new contributors!
 
 Clean Up
 --------
+
+The past few months saw lots of cleanup across the source tree:
+
+The included headers in source files were stripped down to avoid reading
+unused headers, and unused code fragments, duplicate preprocessor symbols
+and configuration options were eliminated. Even ACPI got its share
+of attention, making our tables and bytecode more standards compliant
+than ever.
+
+The code across Intel's chipsets was unified some more into drivers for
+common function blocks, an effort we're more confident will succeed now
+that Intel itself is driving it.
+
+Chipset work
+------------
+
+Most activity in the last couple months was on Intel support,
+specifically the Kaby Lake and Cannon Lake drivers were extended
+for the generations following them.
+
+On ARM, the Mediatek 8173 chipset support saw significant work while
+the AMD side worked on getting Picasso support in.
+
+But everything else also saw some action, the relatively old
+(e.g. Intel GM45, Via VX900), the tiny (RISC-V) and the obscure
+(Quark).
+
+Verified Boot
+-------------
+
+The vboot feature that Chromebooks brought into coreboot was extended
+to work on devices that weren't specially adapted for it: In addition
+to its original device family it's now supported on various Lenovo
+laptops, Open Compute Project systems and Siemens industrial machines.
+
+Eltan's support for measured boot continues to be integrated with
+vboot, sharing data structures and generally working together where
+possible.
+
+New devices
+-----------
+
+With 4.11 there's the beginning of support for Intel Tiger Lake and
+Qualcomm's SC7180 SoCs, while we removed the unmaintained support
+for Allwinner's A10 SoC.
+
+There are also 25 new mainboards in our tree:
+
+* AMD PADMELON
+* ASUS P5QL-EM
+* EMULATION QEMU-AARCH64
+* GOOGLE AKEMI
+* GOOGLE ARCADA CML
+* GOOGLE DAMU
+* GOOGLE DOOD
+* GOOGLE DRALLION
+* GOOGLE DRATINI
+* GOOGLE JACUZZI
+* GOOGLE JUNIPER
+* GOOGLE KAKADU
+* GOOGLE KAPPA
+* GOOGLE PUFF
+* GOOGLE SARIEN CML
+* GOOGLE TREEYA
+* GOOGLE TROGDOR
+* LENOVO R60
+* LENOVO T410
+* LENOVO THINKPAD T440P
+* LENOVO X301
+* RAZER BLADE-STEALTH KBL
+* SIEMENS MC-APL6
+* SUPERMICRO X11SSH-TF
+* SUPERMICRO X11SSM-F
+
+In addition to the Cubieboard (which uses the A10 SoC), we also
+removed Google Hatch WHL.
+
+Deprecations
+------------
+
 Because there was only a single developer board (AMD Torpedo)
 using AGESA family 12h, and because there were multiple,
 unique Coverity issues with it, the associated vendorcode will
 be removed shortly after this release.
 
+Support for the MIPS architecture will also be removed shortly after
+this release as the only board in the tree was a discontinued development
+board and no other work has picked up MIPS support, so it's very likely
+broken already.
+
+After more than a year of planning and following the announcement in
+coreboot 4.10, platforms not using relocatable ramstage, a C bootblock
+and, on systems using Cache as RAM, a postcar stage, won't be supported
+going forward.
+
 Significant changes
 -------------------
 
-### Add significant changes here
-
 ### `__PRE_RAM__` is deprecated
 
-Preprocessor use of `defined(__PRE_RAM_)` have been mostly replaced with
+Preprocessor use of `defined(__PRE_RAM__)` have been mostly replaced with
 `if (ENV_ROMSTAGE_OR_BEFORE)` or the inverse `if (ENV_RAMSTAGE)`.
 
 The remaining cases and `-D__PRE_RAM__` are to be removed soon after release.
 
+### `__BOOTBLOCK__` et.al. are converted
+
+This applies to all `ENV_xxx` definitions found in `<rules.h>`.
+
+Write code without preprocessor directives whenever possible, replacing
+`#ifdef __BOOTBLOCK__` with  `if (ENV_BOOTBLOCK)`
+
+In cases where preprocessor is needed use `#if ENV_BOOTBLOCK` instead.
+
 ### `CAR_GLOBAL` is removed where possible
 
 For all platform code with `NO_CAR_GLOBAL_MIGRATION=y`, any `CAR_GLOBAL`
@@ -40,3 +138,76 @@ removed soon after release.
 
 Significant refactoring has bee done to achieve some consistency across platforms
 and to reduce code duplication.
+
+### Build system amenities ###
+
+The build system now has an `all` class of source files to remove the need to
+list source files for each and every source class (romstage, ramstage, ...)
+
+The site-local/ mechanism became more robust.
+
+### Stricter coding standards to improve security ###
+
+The build now fails on variable length arrays (that make it way too easy to
+smash a stack) and case statements falling through without a note that it is
+intentional.
+
+### Shorter file headers ###
+
+This project is still under way, but we started moving author information
+from individual files into the global AUTHORS file (and there's the git
+history for more details).
+
+In the future, we also want to replace the license headers (lots of lines)
+in each file with spdx identifiers (one line) and so we added a LICENSES/
+directory that contains the full text of all the licenses that are used
+throughout our tree.
+
+### Variant creation scripts ###
+
+To ease the creation of variant boards, `util/mainboard/` now contains
+scripts to generate a new variant to a given board. These are still
+specific to google/hatch at this time, but they're written with the idea
+of becoming more generally useful.
+
+### Payloads ###
+
+Payload integration has been updated, coreinfo learned to cope with
+UPPER CASE commands and libpayload knows how to deal with USB3 hubs.
+
+### Added VBOOT support to the following platforms:
+
+* intel/gm45
+* intel/nehalem
+
+### Moved the following platforms to C_ENVIRONMENT_BOOTBLOCK:
+
+* intel/i945
+* intel/x4x
+* intel/gm45
+* intel/nehalem
+* intel/sandybridge
+* intel/braswell
+
+### libgfxinit ###
+
+Most notable, dynamic CDClk configuration was added to libgfxinit,
+to support higher resolution displays without changes in the static
+configuration. It also received some fixes for better DP and eDP
+compatibility, better error recovery for Intel's fickle GMBus and
+updated platform support:
+* Correct HDMI clock limit for G45.
+* DP support for Ibex Peak (Ironlake graphics).
+* Fixed scaling on eDP for Broadwell.
+* Support for ULX variants of Haswell and later.
+* Support for Kaby, Amber, Coffee and Whiskey Lake.
+
+### Other
+* Did cleanups around TSC timer
+* Improved automatic VR configuration on SKL/KBL
+* Filled additional fields in SMBIOS type 4
+* Removed magic value replay from Intel Nehalem/ibexpeak code base
+* Added OpenSBI on RISCV platforms
+* Did more preparations for Intel TXT support
+* Did more preparations for x86_64 stage support
+* Added SSDT generator for arbitrary SuperIO chips based on devicetree.cb

Documentation/releases/coreboot-4.12-relnotes.md

@@ -0,0 +1,20 @@
+Upcoming release - coreboot 4.12
+================================
+
+The 4.12 release is planned for April 2020
+
+Update this document with changes that should be in the release
+notes.
+* Please use Markdown.
+* See the past few release notes for the general format.
+* The chip and board additions and removals will be updated right
+  before the release, so those do not need to be added.
+
+Significant changes
+-------------------
+
+### SMMSTORE is now production ready
+
+See [smmstore](../drivers/smmstore.md) for the documentation on the API.
+
+### Add significant changes here

Documentation/releases/index.md

@@ -11,6 +11,7 @@ Release notes for previous releases
 * [4.8 - May 2018](coreboot-4.8.1-relnotes.md)
 * [4.9 - December 2018](coreboot-4.9-relnotes.md)
 * [4.10 - July 2019](coreboot-4.10-relnotes.md)
+* [4.11 - November 2019](coreboot-4.11-relnotes.md)
 
 The checklist contains instructions to ensure that a release covers all
 important things and provides a reliable format for tarballs, branch
@@ -22,4 +23,4 @@ Upcoming release
 ----------------
 
 Please add to the release notes as changes are added:
-* [4.11 - October 2019](coreboot-4.11-relnotes.md)
+* [4.12 - April 2020](coreboot-4.12-relnotes.md)

Documentation/security/vboot/index.md

@@ -186,6 +186,26 @@ In addition to adding the coreboot files into the read-only region,
 enabling vboot causes the build script to add the read/write files into
 coreboot file systems in *FW_MAIN_A* and *FW_MAIN_B*.
 
+**RO_REGION_ONLY**  
+
+The files added to this list will only be placed in the read-only region and
+not into the read/write coreboot file systems in *FW_MAIN_A* and *FW_MAIN_B*.
+
+**VBOOT_ENABLE_CBFS_FALLBACK**  
+
+Normally coreboot will use the active read/write coreboot file system for all
+of it's file access when VBOOT is active and is not in recovery mode.
+
+When the `VBOOT_ENABLE_CBFS_FALLBACK` option is enabled the cbfs file system will
+first try to locate a file in the active read/write file system. If the file
+doesn't exist here the file system will try to locate the file in the read-only
+file system.
+
+This option can be used to prevent duplication of static data. Files can be
+removed from the read/write partitions by adding them to the `RO_REGION_ONLY`
+config. If a file needs to be changed in a later stage simply remove it from
+this list.
+
 ***
 
 ## Signing the coreboot Image

Documentation/soc/intel/fsp/index.md

@@ -34,6 +34,11 @@ those are fixed. If possible a workaround is described here as well.
   * Workaround: none
   * Issue on public tracker: [Issue 22]
 
+* MRC forces memory re-training on cold boot on boards with Intel SPS
+  * Releases 3.7.1, 3.7.6
+  * Workaround: Flash Intel ME instead of SPS
+  * Issue on public tracker: [Issue 41]
+
 ### BraswellFsp
 * Internal UART can't be disabled using PcdEnableHsuart*
   * Release MR2
@@ -66,4 +71,5 @@ those are fixed. If possible a workaround is described here as well.
 [Issue 15]: https://github.com/IntelFsp/FSP/issues/15
 [Issue 22]: https://github.com/IntelFsp/FSP/issues/22
 [Issue 35]: https://github.com/IntelFsp/FSP/issues/35
+[Issue 41]: https://github.com/IntelFsp/FSP/issues/41
 

Documentation/superio/common/pnp.md

@@ -0,0 +1,114 @@
+# PNP devices
+
+Typical PNP devices are Super I/Os, LPC-connected TPMs and board
+management controllers.
+
+PNP devices are usually connected to the LPC or eSPI bus of a system
+and shouldn't be confused with PCI(e) devices that use a completely
+different plug and play mechanism. PNP originates in the ISA plug and
+play specification. Since the original ISA bus is more or less extinct,
+the auto-detection part of ISA PNP is mostly irrelevant nowadays. For
+the register offsets for different functionality, appendix A of that
+specification is still the main reference though.
+
+## Configuration access and config mode
+
+Super I/O chips connected via LPC to the southbridge usually have their
+I/O-mapped configuration interface with a size of two bytes at the base
+address 0x2e or 0x4e. Other PNP devices have their configuration
+interface at other addresses.
+
+The two byte registers allow access to an indirect 256 bytes big
+register space that contains the configuration. By writing the index
+to the lower byte (e.g. 0x2e), you can access the register contents at
+that index by reading/writing the higher byte (e.g. 0x2f).
+
+To prevent accidental changes of the Super I/O (SIO) configuration,
+the SIOs need a configuration mode unlock sequence. After changing the
+configuration, the configuration mode should be left again, by sending
+the configuration mode lock sequence.
+
+## Logical device numbers (LDN)
+
+Each PNP device can contain multiple logical devices. The bytes from
+0x00 to 0x2f in the indirect configuration register space are common
+for all LDNs, but some SIO chips require a certain LDN to be selected
+in order to write certain registers in there. An LDN gets selected by
+writing the LDN number to the LDN select register 0x07. Registers 0x30
+to 0xFF are specific to each LDN number.
+
+coreboot encodes the physical LDN number in the lower byte of the LDN
+number.
+
+### Virtual logical device numbers
+
+Register 0x30 is the LDN enable register and since it is an 8 bit
+register, it can contain up to 8 enable bits for different parts of
+the functionality of that logical device. To set a certain enable bit
+in one physical LDN, the concept of virtual LDNs was introduced.
+Virtual LDNs share the registers of their base LDN, but allow to
+specify which part of a LDN should be enabled.
+
+coreboot encodes the enable bit number and by that the virtual LDN
+part in the lower 3 bits of the higher byte of the LDN number.
+
+## I/O resources
+
+Starting at register address 0x60, each LDN has 2 byte wide I/O base
+address registers. The size of an I/O resource is always a power of
+two.
+
+### I/O resource masks
+
+The I/O resource masks encode both the size and the maximum base
+address of the corresponding IO resource. The number of zeros counted
+from the least significant bit encode the resource size. If N is the
+number of LSBs being zero, which can also be zero if the LSB is a one,
+the resource has N address bits and a size of 2\*\*N bytes. The mask
+address is also the highest possible address to map the I/O region.
+
+A typical example for an I/O resource mask is 0x07f8 which is
+0b0000011111111000 in binary notation. The three LSBs are zeros here,
+so it's an eight byte I/O resource with three address offset bits
+inside the resource. The highest base address it can be mapped to is
+0x07f8, so the region will end at 0x07ff.
+
+The Super I/O datasheets typically contain the information about the
+I/O resource masks. On most Super I/O chips the mask can also be found
+out by writing 0xffff to the corresponding I/O base address register
+and reading back the value; since the lowest and highest bits are
+hard-wired to zero according to the I/O resource size and maximal
+possible I/O address, this gives the mask.
+
+## IRQ resources
+
+Each physical LDN has up to two configurable interrupt request
+register pairs 0x70, 0x71 and 0x72, 0x73. Each pair can be configured
+to use a certain IRQ number. Writing 1 to 15 into the first register
+selects the IRQ number generated by the corresponding IRQ source and
+enables IRQ generation; writing 0 to it disables the generation of
+IRQs for the source. The second register selects the IRQ type (level
+or edge) and IRQ level (high or low). For LPC SIOs the IRQ type is
+hard-wired to edge.
+
+On the LPC bus a shared SERIRQ line is used to signal IRQs to the
+host; the IRQ number gets encoded by the number of LPC clock cycles
+after the start frame before the device pulls the open drain
+connection low.
+
+SERIRQ can be used in two different modes: In the continuous SERIRQ
+mode the host continuously sends IRQ frame starts and the devices
+signal their IRQ request by pulling low the SERIRQ line at the right
+time. In quiet SERIRQ mode the host doesn't send IRQ frame starts, so
+the devices have to send both the IRQ frame start and the encoded IRQ
+number. The quiet mode is often broken.
+
+## DRQ resources
+
+Each physical LDN has two legacy ISA-style DMA request channel
+registers at 0x74 and 0x75. Those are only used for legacy devices
+like parallel printer ports or floppy disk controllers.
+
+Each device using LPC legacy DMA needs its own LDMA line to the host.
+Some newer chipsets have dropped the LDMA line and with that the
+legacy DMA capability on LPC.

Documentation/superio/common/ssdt.md

@@ -45,12 +45,33 @@ chip superio/common
 end
 ```
 
+## Automatically generated methods
+
+The following methods are generated for each SuperIO:
+## AMTX()
+Acquire the global mutex and enter config mode.
+It's called this at the begining of an atomic operation to make sure
+no other ACPI code messes with the config space while working on it.
+
+## RMTX()
+Exit config mode and release the global mutex.
+It's called at the end of an atomic operation.
+
+## SLDN(Arg0)
+Selects the (virtual) LDN given as Arg0.
+This method isn't guarded with the global mutex.
+
+## DLDN(Arg0)
+Disables the (virtual) LDN given as Arg0.
+This method aquires the global mutex.
+
+## QLDN(Arg0)
+Queries the state of the (virtual) LDN given as Arg0.
+This method quires the global mutex.
+
 ## TODO
 
 1) Add ACPI HIDs to every SuperIO driver
-2) Don't guess ACPI HID of LDNs if it's known
-3) Add "enter config" and "exit config" bytes
-4) Generate support methods that allow
+2) Generate support methods that allow
    * Setting resource settings at runtime
    * Getting resource settings at runtime
-   * Disabling LDNs at runtime

Documentation/superio/index.md

@@ -7,4 +7,5 @@ This section contains documentation about coreboot on specific SuperIOs.
 - [NPCD378](nuvoton/npcd378.md)
 
 ## Common
+- [PNP devices](common/pnp.md)
 - [SSDT generator for generic SuperIOs](common/ssdt.md)

Documentation/tutorial/part1.md

@@ -15,7 +15,7 @@ Download, configure, and build coreboot
     $ cd coreboot
 
 ### Step 3 - Build the coreboot toolchain
-Please note that this can take a significant amount of time
+Please note that this can take a significant amount of time.
 
     $ make crossgcc-i386 CPUS=$(nproc)
 
@@ -53,7 +53,7 @@ These should be the default selections, so if anything else was set, run
        select < Exit >
        select < Yes >
 
-##### check your configuration (optional step):
+##### Check your configuration (optional step):
 
     $ make savedefconfig
     $ cat defconfig

Documentation/tutorial/part2.md

@@ -1,8 +1,8 @@
 # Tutorial, part 2: Submitting a patch to coreboot.org
 
-## Part 1: Setting up an account at coreboot.org
+## Step 1: Set up an account at coreboot.org
 
-If you already have an account, skip to Part 2.
+If you already have an account, skip to Step 2.
 
 Otherwise, go to <https://review.coreboot.org> in your preferred web browser.
 Select **Sign in** in the upper right corner.
@@ -12,13 +12,13 @@ select **Google OAuth2** (gerrit-oauth-provider plugin). **Note:** Your
 username for the account will be the username of the account you used to
 sign-in with. (ex. your Google username).
 
-## Part 2a: Set up RSA Private/Public Key
+## Step 2a: Set up RSA Private/Public Key
 
-If you prefer to use an HTTP password instead, skip to Part 2b.
+If you prefer to use an HTTP password instead, skip to Step 2b.
 
 For the most up-to-date instructions on how to set up SSH keys with Gerrit go to
 <https://gerrit-documentation.storage.googleapis.com/Documentation/2.14.2/user-upload.html#configure_ssh>
-and follow the instructions there. Then, skip to Part 3.
+and follow the instructions there. Then, skip to Step 3.
 
 Additionally, that section of the Web site provides explanation on starting
 an ssh-agent, which may be particularly helpful for those who anticipate
@@ -44,7 +44,7 @@ forego the password altogether as you will be using it very often.
 Open `id_rsa.pub`, copy all contents and paste into the textbox under
 "Add SSH Public Key" in the https://review.coreboot.org webpage.
 
-## Part 2b: Setting up an HTTP Password
+## Step 2b: Set up an HTTP Password
 
 Alternatively, instead of using SSH keys, you can use an HTTP password. To do so,
 after you select your name and click on **Settings** on the left-hand side, rather
@@ -58,7 +58,21 @@ the password, and add the following to your `$HOME/.netrc` file:
 where YourUserNameHere is your username, and YourPasswordHere is the password you
 just generated.
 
-## Part 3: Clone coreboot and configure it for submitting patches
+If your system is behind a snooping HTTPS proxy, you might also have to
+make its SSL certificate known to curl, a system specific operation.
+If that's not possible for some reason, you can also disable SSL
+certificate verification in git:
+
+	git config [--global] http.sslVerify [true|false]
+
+The `--global` argument sets it for all git transfers of your local
+user, `false` means not to validate the certificate.
+
+If that still doesn't allow you to pull or push changes to the server, the
+proxy is likely tampering with the data stream, in which case there's nothing
+we can do.
+
+## Step 3: Clone coreboot and configure it for submitting patches
 
 On Gerrit, click on the **Browse** tab in the upper left corner and select
 **Repositories**. From the listing, select the "coreboot" repo. You may have
@@ -87,7 +101,7 @@ and other configurations.
 	cd coreboot
 	make gitconfig
 
-## Part 4: Submit a commit
+## Step 4: Submit a commit
 
 An easy first commit to make is fixing existing checkpatch errors and warnings
 in the source files. To see errors that are already present, build the files in
@@ -105,9 +119,9 @@ and can be submitted for review.
 Once you finish making your desired changes, use the command line to stage
 and submit your changes. An alternative and potentially easier way to stage
 and submit commits is to use git cola, a graphical user interface for git. For
-instructions on how to do so, skip to Part 4b.
+instructions on how to do so, skip to Step 4b.
 
-## Part 4a: Using the command line to stage and submit a commit
+## Step 4a: Use the command line to stage and submit a commit
 
 To use the command line to stage a commit, run
 
@@ -157,17 +171,17 @@ commit, you wish to make changes to it, running `git commit --amend` allows
 you to take back your commit and amend it.
 
 When you are done with your commit, run `git push` to push your commit to
-coreboot.org. **Note:** To submit as a draft, use
-`git push origin HEAD:refs/drafts/master`. Submitting as a draft means that
-your commit will be on coreboot.org, but is only visible to those you add
-as reviewers.
+coreboot.org. **Note:** To submit as a private patch, use
+`git push origin HEAD:refs/for/master%private`. Submitting as a private patch
+means that your commit will be on review.coreboot.org, but is only visible to
+yourself and those you add as reviewers.
 
 This has been a quick primer on how to submit a change to Gerrit for review
 using git. You may wish to review the [Gerrit code review workflow
 documentation](https://gerrit-review.googlesource.com/Documentation/intro-user.html#code-review),
 especially if you plan to work on multiple changes at the same time.
 
-## Part 4b: Using git cola to stage and submit a commit
+## Step 4b: Use git cola to stage and submit a commit
 
 If git cola is not installed on your machine, see
 <https://git-cola.github.io/downloads.html> for download instructions.
@@ -227,11 +241,8 @@ explained in the extended description.
 
 When ready, select 'Commit' again. Once all errors have been satisfied
 and the commit succeeds, move to the command line and run `git push`.
-**Note:** To submit as a draft, use `git push origin HEAD:refs/drafts/master`.
-Submitting as a draft means that your commit will be on coreboot.org, but is
-only visible to those you add as reviewers.
 
-## Part 5: Getting your commit reviewed
+## Step 5: Let others review your commit
 
 Your commits can now be seen on review.coreboot.org if you select "Your"
 and click on "Changes" and can be reviewed by others. Your code will
@@ -241,7 +252,7 @@ users may also give your commit +1. For a commit to be merged, it needs
 to receive a +2. **Note:** A +1 and a +1 does not make a +2. Only certain users
 can give a +2.
 
-## Part 6 (optional): bash-git-prompt
+## Step 6 (optional): bash-git-prompt
 
 To help make it easier to understand the state of the git repository
 without running `git status` or `git log`, there is a way to make the

Documentation/util.md

@@ -14,9 +14,6 @@ settings. `Perl`
 platform. `C`
 * __autoport__ - Automated porting coreboot to Sandy Bridge/Ivy Bridge
 platforms `Go`
-* __bimgtool__ - A simple tool which generates and verifies boot images
-in the BIMG format, used in systems designed by Imagination
-Technologies, for example the Pistachio SoC. `C`
 * __bincfg__ - Compiler/Decompiler for data blobs with specs `Lex`
 `Yacc`
 * __board_status__ - Tools to collect logs and upload them to the board