What to download/How to upgrade

What board configuration should I choose?

Please refer to the devices compatibility matrix.

Migrating from one board configuration to another

If Heads is already installed on your board and you want to migrate to its Maximized version:

Under Heads: go into Recovery Shell to make sure if you should download Legacy or Maximized board ROMs:
- If aiming to go to Maximized firmware, make sure you have unlocked Intel Flash Descriptor (IFD) and ME regions on initial flash
  - This is compatible
    - If you have no warning/error (see above), you can proceed with a manual flashrom command to migrate once and for all to Maximized board: flashrom -p internal -w /media/heads-hotp-maximized-version-gcommit.rom
  - !!!This is not compatible!!!
    - You either have to download a non-maximized ROM version, or have to flash externally the (xx30 boards: top and bottom) ROM(s) for your platform’s maximized board configuration. This needs to be done once, after which you can upgrade from the GUI.

Downloading Heads from CircleCI

Alternatively to building your own ROM, you can download ROMs directly from CircleCI for the most recent commits (build artifacts are kept for 30 days automatically). If no artifacts are available for download, please poke us so we manually relaunch a build.

A lot of efforts have been put into CircleCI so that most of the community platforms have their ROMs built and downloadable as artifacts from CircleCI.

Note that CircleCI keeps artifacts for 30 days after build time.

No hardware programmer? BE CAUTIOUS!

Considering Heads is a rolling release as of now, it is advised to wait a day or two prior of flashing a ROM downloaded from CircleCI if you do not own a external programmer. Maybe wait even longer when last merge was linked to a coreboot upgrade or kernel upgrade, just to be sure no regression happened. Watch the most recently reported issues. Heads project is hosted on GitHub where most of the Pull Requests (PR) are merged and closed after review(purple). The general advise here is to review the latest PR linked to last commit that was merged and make sure that some other owners of the same platform you use have tested the changes if you are in doubt.

Most of the changes happening in the codebase are policy related (scripts).

Those changes are normally tested on at least 2 different platforms to validate no regression happened prior of merging.

Kernel and coreboot version bumps require a lot more testing from the community board owners prior of merging the changes in the project. When those cause regressions, an untested platform might simply brick. This is why coreboot/linux version bumps are not following upstream projects versions tightly: it requires a lot of collaboration and time with board owners.

How to download

Go to Heads GitHub repository and click on latest commit’s green check
Select your desired platform (hopefully, choosing maximized builds over legacy counterparts and choosing hotp variants if you already own a compatible USB Security dongle). Here, we choose x230-hotp-maximized as an example.
This brings us to CircleCI web interface. First, we scroll and click on the Make Board step so we can see the hash of the ROM we are about to download
This opens the build log and shows the last output of the board being built. Highlight/copy the hash for future comparison.
Scroll back up and select the Artifacts tab.
This opens the artifacts that were saved for that commit id. We are interested in the ROM we are interested to download, which is the full ROM in this upgrade example, as opposed to bottom and top ROM images which are aimed to be flashed externally.
Save the link to your already prepared and mounted USB drive locally
Validate the checksum against saved checksum
If you saved it locally, pass it over to sys-usb once you verified checksum for compartmentalization
Mount your USB drive and move the ROM to it
Unmount your USB drive by pressing the eject button.

Upgrading firmware

The documentation related to upgrading is here