xx20 xx30 maximized vs legacy board configs

[tlaurion]

Complimentary documentation to https://github.com/osresearch/heads/pull/1015 about Legacy vs Maximized xx20 xx30 boards

Please review, specifically upgrade paths.

[tlaurion]

Missing:

• Notes on maximized boards coming from https://github.com/osresearch/heads/pull/1015 needed to install (cryptsetup2) and boot (vbt and coreboot fixes under coreboot 4.13) to boot QubesOS 4.1
• Notes missing for Librem boards with QubesOS 4.0 (coreboot 4.8.1 based boards for 4.0 support) and QubesOS 4.1 support (coreboot 4.13+ breaks QubesOS 4.0 compatibility) (@MrChromebox: Should we modify the board list and columns with need to know? How whould that be better? A link to go to for Librem users pointing to Purism doc? Probably another documentation issue needs to be opened )

[tlaurion]

Tagging @copyvar that was explicitly stated being interested to contribute from https://github.com/osresearch/heads/issues/1054

[MrChromebox]

@MrChromebox: Should we modify the board list and columns with need to know? How whould that be better? A link to go to for Librem users pointing to Purism doc? Probably another documentation issue needs to be opened

On our end, we tagged a new version for Pureboot so users can revert to an older version should they need to run Qubes 4.0.x. It would probably be helpful if we had a Heads tag before the migration so we can point users to that should the 4.13+ update end up breaking things we don't know about currently

[tlaurion]

@MrChromebox: Should we modify the board list and columns with need to know? How whould that be better? A link to go to for Librem users pointing to Purism doc? Probably another documentation issue needs to be opened

On our end, we tagged a new version for Pureboot so users can revert to an older version should they need to run Qubes 4.0.x. It would probably be helpful if we had a Heads tag before the migration so we can point users to that should the 4.13+ update end up breaking things we don't know about currently

@MrChromebox Pinged @osresearch over slack. Maybe you can try too so that we get more rights over this project?

[tlaurion]

Should we give exerpt of non-maximized boards coreboot build for clarity?

FMAP REGION: COREBOOT
Name                           Offset     Type           Size   Comp
cbfs master header             0x0        cbfs header        32 none
fallback/romstage              0x80       stage           87948 none
fallback/ramstage              0x15880    stage           99973 none
config                         0x2df40    raw               684 none
revision                       0x2e240    raw               690 none
fallback/dsdt.aml              0x2e540    raw             14609 none
cmos.default                   0x31ec0    cmos_default      256 none
vbt.bin                        0x32000    raw              1409 LZMA (4459 decompressed)
cmos_layout.bin                0x325c0    cmos_layout      1980 none
fallback/postcar               0x32dc0    stage           27288 none
fallback/payload               0x398c0    simple elf    6854599 none
(empty)                        0x6c30c0   null           117976 none
bootblock                      0x6dfdc0   bootblock       65536 none
    HOSTCC     cbfstool/ifwitool.o
    HOSTCC     cbfstool/ifwitool (link)

Built lenovo/t430 (ThinkPad T430)

    ** WARNING **
coreboot has been built without an Intel Firmware Descriptor.
Never write a complete coreboot.rom without an IFD to your
board's flash chip! You can use flashrom's IFD or layout
parameters to flash only to the BIOS region.

make[1]: Leaving directory '/home/user/heads/build/coreboot-4.13'

Where the warning says the ROM is incomplete and cannot be flashed wholly, not containing a valid IFD. There still seem to be confusion into upgrade paths and why.

I welcome proof reading.

[tlaurion]

The following shows the result of attempting to flash over a locked IFD and ME region, with a hotp-verification (legacy board aimed to flash only the known available to all 7MB BIOS region instead of the 11.5MB BIOS region that would be made available if a whole internal flash was possible if ME and IFD were unlocked):

Two errors here:

• You CANNOT flash hotp-verification ROMs as if they were complete ROM images. Those do not contain neither GBE, ME nor a valid IFD descriptor and if flashing was successful, the board would become a brick. The end user was wanting to flash a maximized board's ROM here, not a hotp-verification (legacy) ROM. But he couldn't because...
• Initial external flashed ROM didn't have either IFD nor ME regions unlocked as exposed by flashrom error, which complains that those regions being protected. The end user didn't follow https://osresearch.net/Clean-the-ME-firmware/ step which was saying:

Next, unlock the descriptor and ME regions with ifdtool. We consider here that you already build Heads through make BOARD=x230: ~/heads/build/coreboot-4.8.1/util/ifdtool/ifdtool -u down.rom This produced a new unlocked rom under down.rom.new

At that stage, if user have done those errors, the end user would need to only flash the BIOS region from the hotp-verification ROM he is intending to flash (x230-hotp-verification, t430-hotp-verification) or original board ROM (x230, t430 etc) with the standard flash script flashrom statement: flashrom --force --noverify-all -p internal --ifd --image bios -w NonMaximizedBoard.rom

IF IFD AND ME INITIALLY UNLOCKED, a full maximized board ROM can be flashed internally, which won't give the above errors on IFD and ME locked regions: flashrom --force --noverify-all -p internal -w MaximizedBoard.rom

I tend to generally create documentation specifying what to do, not what to not do. So suggestions welcome to make this clear here prior of PR merge

Tagging https://github.com/osresearch/heads/pull/1015 participants for review: @techge @natterangell @Thrilleratplay @shamen123 @BlackMaria @MrChromebox @no-sauce @nitrosimon

[copyvar]

@tlaurion I have also a specific question due to building x230-hotp-maximized.

I think, it would be a great advantage to have a step-by-step tutorial of the most common heads cases (e.g. the two maximized boards).

As far as I understood, when I build a maximized board, I do not have to do anything else (e.g. cleaning ME and so on, because it is already done).

So the steps would be:

• flash/downgrade/upgrade to 2.76 bios version
• flash top rom to the top SPI externally
• flash bottom rom to the bottom SPI externally
• restart computer and follow your guide "Configuring keys"

Please correct me, if I am wrong.

[tlaurion]

@copyvar Well, yeah it is legit. The last part is supposed to work automatically, since no user gpg keyring will be found under Heads, triggering OEM factory reset to generate such keys on USB Security dongle supporting gpg per documentation.

What is unclear? Please tag the lines in current PR.

[tlaurion]

@tlaurion I have also a specific question due to building x230-hotp-maximized.

I think, it would be a great advantage to have a step-by-step tutorial of the most common heads cases (e.g. the two maximized boards).

As far as I understood, when I build a maximized board, I do not have to do anything else (e.g. cleaning ME and so on, because it is already done).

So the steps would be:

* flash/downgrade/upgrade to 2.76 bios version

* flash top rom to the top SPI externally

* flash bottom rom to the bottom SPI externally

* restart computer and follow your guide "Configuring keys"

Please correct me, if I am wrong.

@copyvar : Those are considerations for flashing guides. My insight is to probably reorganize boards into meta categories (xx30, xx20) and have a reminder of what maximized vs legacy boards mean for xx30 and point to the proper section for more information, where your guidelines should be highlighted under xx30 for legacy->legacy, legacy->maximized and maximized flashing instructions.

I will merge this, where improvements can then be made on this base. Simplifications needed, I agree.