Board Status

From coreboot
Jump to navigation Jump to search

The wiki is being retired!

Documentation is now handled by the same processes we use for code: Add something to the Documentation/ directory in the coreboot repo, and it will be rendered to https://doc.coreboot.org/. Contributions welcome!

Board Status

Semi-automated crowdsourced information about what boards and versions of coreboot are known to work together.

Intro

For many years the list of Supported Mainboards was maintained by a small handful of people with wiki access. This was challenging in a couple of ways: Wiki access was different from repository commit access, and the process of updating the wiki is somewhat tedious especially if we want an ongoing list of which coreboot versions work on a particular mainboard.

To address this problem the board_status.sh script was created to glean some basic information using cbmem and the kernel log on a machine that had successfully booted coreboot. The script (both shell and Go versions) reside under the util/board_status directory.

How It Works

board_status.sh gathers build information and runtime information. Build information includes data from git such as the repository from where the code came from. Runtime information includes CBMEM data and kernel log.

Steps

In a nutshell, here are the steps involved:

  1. Read coreboot and payload configuration and version. This includes information from git metadata.
  2. Read CBMEM log from DUT.
  3. Read kernel log from DUT
  4. (Optional) Upload results to the board_status repository [1] via git. The Supported Mainboards page is generated automatically using this data.

To upload results, the user must have an account with commit rights on coreboot.org. This is simply to prevent spam and abuse. If you have an idea for how to improve this so that more people can contribute without needing an account please let us know on the Mailinglist!

What Is Tested

Currently the only thing that is tested is whether or not the machine booted successfully. Other tests may be added in the future, but for now the lowest common denominator is simply a test of whether the machine booted far enough to run the board_status script.

How To Use It

Dependencies

  • The device under test (DUT) must have the cbmem utility. The '-c' option may be used to specify the location if it is not in $PATH.
  • To upload results, the user must have git commit access. This requires an OpenID/OAth2 account, see https://www.coreboot.org/Git#Gerrit [2] for details.

Local usage

In this use case, the coreboot is built and run on the same machine. If the user is not root, then sudo will be used to invoke cbmem.

Steps:

  1. Build coreboot on local machine and flash it.
  2. Reboot, login, and cd to coreboot directory.
  3. Run `util/board_status/board_status.sh. Add `-u` to upload the results.

Remote via SSH

In this use case coreboot is built on a separate machine from the DUT. The DUT is configured to allow root login via SSH pubkey authentication, and the script runs cbmem on the DUT via SSH.

Steps:

  1. Set up DUT with public key authentication and root login.
  2. Build coreboot on local machine.
  3. Flash DUT with coreboot image and boot it.
  4. Run `util/board_status/board_status.sh -r <host>` on local machine. Add the `-u` option to upload the results.

Live Image

The util/board_status/set_up_live_image.sh script was added to help set up Ubuntu so that board_status can be used via SSH.

This is especially convenient for developers who wish to report coreboot results on multiple devices and needs quick and easy setup.

Remote via Serial

In this use case coreboot is build on a separate machine from the DUT. The DUT is assumed to not have network access. Since we don't run the cbmem command on the DUT in this mode, the user should turn serial console verbosity high enough to produce meaningful output.

Also, since we do not log into the machine (via SSH) the coreboot_console.txt file may contain both coreboot and kernel messages. If kernel messages are desired, then the user must also set kernel serial console verbosity high enough to produce meaningful output.

Steps:

  1. Ensure CONFIG_CONSOLE_SERIAL=y in coreboot config.
  2. Set CONFIG_DEFAULT_CONSOLE_LOGLEVEL to a high value, such as 8 (SPEW).
  3. Flash DUT with coreboot image and boot it.
  4. Run `util/board_status/board_status -s <serial_device>`