Reminder: Heads requires coreboot. Instructions above **must** be performed
before flashing Heads. It also requires a [compatible USB security dongle](https://osresearch.net/Prerequisites#usb-security-dongles-aka-security-token-aka-smartcard)
and TPM (more about it later).
> Technically, TPM isn't a hard requirement of Heads, however its usefulness
> without it is very limited, up to a point where it doesn't have any advantages
> over Petitboot.
1. Just as earlier, start with cloning the repository:
```
git clone https://github.com/Dasharo/heads.git \
--depth=1 -b raptor-cs_talos-2/release
```
2. Start docker container:
```
cd heads
docker run --rm -it \
-v $PWD:/home/heads/heads \
-w /home/heads/heads \
-u "$(id -u):$(id -g)" \
3mdeb/heads-docker:2.4.0 /bin/bash
```
3. Build:
```
(docker) make BOARD=talos-2
```
This will take a while, wait for it to finish and then exit the container. In
the process, a coreboot image will also be built, but with slightly different
configuration. For security and reproducible images, `BUILD_TIMELESS` is always
enabled. While it actually strips file paths, it also removes file names and
line numbers from asserts in the code. It makes reporting and debugging
potential issues harder, so we suggest using coreboot built manually, at least
for the time being.
Steps for flashing Heads are similar to those done for coreboot.
1. Copy the Heads binary to the BMC (assuming in the Heads root directory):
Change `<partition>` to one of `HBB`, `HBI`, `BOOTKERNEL` and `<image_file>` to
`/tmp/bootblock.signed.ecc`, `/tmp/coreboot.rom.signed.ecc` or
`/tmp/zImage.bundled`, respectively.
To tell BMC to present the contents of this file as flash, run:
```
mboxctl --backend file:/tmp/talos.pnor
```
Sometimes this command fails with a timeout, in that case run it again until it
succeeds.
> We've noticed that sometimes, despite no error message printed, physical flash
> was used anyway. It is easy to spot when one copy has Hostboot and the other
> has coreboot, but it can be missed when both images have different versions of
> coreboot. It caused us few hours of unnecessary debugging of issues that were
> already fixed...
With the file now mounted, platform can be started. Host firmware and OS
shouldn't be able to tell the difference, except for different reported erase
block size and maybe different access times.
To get back to original flash, run:
```
mboxctl --backend vpnor
```
It will report an error (`Failed to post message: Connection timed out`), but
will revert to physical device nonetheless. This can be confirmed by checking
the output of `mboxctl --lpc-state`:
```
root@talos:~# mboxctl --lpc-state
LPC Bus Maps: Flash Device
```
Since the file is now the full image with coreboot (and optionally Heads), it
can be simply written to flash, should you choose to accept it:
```
pflash -E -p /tmp/talos.pnor
```
## Noticeable differences between Hostboot and coreboot
For those wondering why we even started this project, here are some of the
differences between Hostboot and coreboot.
First of all, coreboot uses C, while Hostboot was written in C++. The latter can
be viewed as a complete operating system - it can use multiple threads
simultaneously, manages virtual memory and uses memory swapping (even before RAM
is trained). Each major [istep](https://wiki.raptorcs.com/w/images/b/bd/IPL-Flow-POWER9.pdf)
(IPL Step, which in turn stands for Initial Program Load) is a separate
application, with some common dynamically loaded libraries. coreboot, on the
other hand, runs all of the code in just 3 separate stages - bootblock, romstage
and ramstage. This allows for tighter linking process, which reduces the final
size of the code.
Another significant difference is reduced amount of RAS (Reliability,
Availability, Serviceability) features enabled in coreboot. Talos II is often
used as a workstation, and while RAS has its uses in servers (it is preferred
to start with partially working hardware than not starting at all), for home
users booting fast is usually more important. Because of that coreboot doesn't
support bad DQ masking for DRAM, it can also optionally skip initial RAM
scrubbing. Because of these reasons, as well as smaller size of code in general,
booting coreboot is significantly faster than Hostboot - some preliminary
results can be found [here](https://github.com/3mdeb/openpower-coreboot-docs/blob/main/devnotes/user_perspective.md).
Another technical difference is the way data is passed to Skiboot. Hostboot uses
HDAT - a format specific to this particular firmware. For coreboot, a device
tree conforming to a well-defined specification is used. In fact, Skiboot
internally converts HDAT to device tree anyway. At the moment, some information
is not presented by coreboot (https://github.com/Dasharo/dasharo-issues/issues/446,
https://github.com/Dasharo/dasharo-issues/issues/32), but those seem to be
rather cosmetic than anything else - if you know about something that requires
those pieces of information to be present, let us know.
## TPM
TPM is an integral part of security mechanisms added by Heads. As existing I2C
TPMs were [hard to obtain](https://github.com/3mdeb/openpower-coreboot-docs/blob/main/devnotes/tpm_over_i2c.md)
at the time we were working on this part of the project, and LPC TPMs couldn't
be used [due to the way POWER9 processor exposed access to LPC bus](https://github.com/3mdeb/openpower-coreboot-docs/blob/main/devnotes/tpm_over_lpc.md#tpm-over-lpc-interface),
we had to [consider other options](https://github.com/3mdeb/openpower-coreboot-docs/blob/main/devnotes/tpm.md).
The solution we ended up with was to create our own [I2C TPM 1.2 module](https://docs.dasharo.com/variants/talos_2/tpm-support/),
based on Infineon SLB9645TT1.2 chip. This chip isn't supported by drivers in
Hostboot and upstream Skiboot, to make use of it you have to use coreboot and
Dasharo's fork of Skiboot.
{{<imagesrc="blog/TPM-1.2-Talos-II.jpg">}}
## Links and references
Here are some links to documentation related to this project:
- [main user documentation page](https://docs.dasharo.com/variants/talos_2/overview/)
- [release notes and binaries](https://docs.dasharo.com/variants/talos_2/releases/)
- [list of known issues](https://github.com/Dasharo/dasharo-issues/labels/raptor-cs_talos-2),
if you want to create new issue remember to add proper tag
- [scripts for dumping debug data and logs](https://github.com/3mdeb/openpower-coreboot-docs/tree/main/devnotes/scripts)
- [dump of SCOM accesses and other debug output divided by isteps](https://github.com/3mdeb/openpower-coreboot-docs/tree/main/logs/scom_dumps)
