update the porting guide

[notgivenby]

updates the porting guide based on recent t480 port

[notgivenby]

https://notgivenby.github.io/heads-wiki/Porting/
Here is promised draft. It definitely needs improvements/corrections. @tlaurion @gaspar-ilom @akunterkontrolle @mblanqui. I thought it is important just to get started somewhere. Feel free to comment, criticize, improve :-)

[tlaurion]

First read! Awesome! Have a lot of nitpicks, and will do thorough review hopefully today. You took notes of everything it seems, at least I do not see anything missing! Thank you so much!

I really appreciated your analogies at the end at https://notgivenby.github.io/heads-wiki/Porting/#contribute-to-maintance btw.
You write way more thorough and good docs I can on first draft, staying straight to the point and your graphs are good (how you did this so easily?!?) Graphs are missing since forever in the bootblock RoT -> measured boot of coreboot -> heads additional measurements -> TOTPM -> HOTP. Would definitely reuse that. Neat!

[tlaurion]

Unfortunately, that won't work, but should. Didn't tested: would build linuxboot payload with u-root, I'm not aware this was ever tested here. Hence why my previous comment.

[gaspar-ilom]

I think bzImage is a requirement for the payload here:

CONFIG_PAYLOAD_LINUX=y
CONFIG_PAYLOAD_FILE="@BOARD_BUILD_DIR@/bzImage"
CONFIG_LINUX_INITRD="@BOARD_BUILD_DIR@/initrd.cpio.xz"

[tlaurion]

First review! Thanks @notgivenby !

[gaspar-ilom]

Thanks @notgivenby it looks already pretty good. I will later give you some feedback.

@tlaurion I wonder if some of the content of this guide should actually go into a dedicated wiki page with an overview over the project/repository and some of the fundamental design concepts. This may not be exclusively relevant to porting boards but to anyone who wants to contribute code and the relevant sections could still be referenced from the porting guide.

[gaspar-ilom]

Thanks again @notgivenby. Great porting guide!

I suggested a lot of changes. Sorry for that. However, those changes are just suggestions. Decide if they improve the guide. I don't mind if you don't include (all of) them.

[gaspar-ilom]

Suggested change

	modify `.circleci/config.yml` to add support for `new_board`. Initially, configure it to depend directly on musl-cross-make. At this stage, do not reuse caches—this simplifies debugging and ensures a clean build process.
	Modify `.circleci/config.yml` to add support for `new_board`. Initially, configure it to depend directly on musl-cross-make. At this stage, do not reuse caches—this simplifies debugging and ensures a clean build process.

[tlaurion]

Now is time to take a macro view of the guide (not looking for nitpicks)

• It doesn't make much sense to create coreboot and linux config after a board config, even less if we tell porter to call a make board out of if with coreboot.modify.... helper (no board config: reuses qemu by default)
  • -> reorder board config duplication as first step, taking one close to arch + platform

I guess this is linked to https://osresearch.net/Makefile/#build-configuration

[tlaurion]

Thanks @notgivenby it looks already pretty good. I will later give you some feedback.

@tlaurion I wonder if some of the content of this guide should actually go into a dedicated wiki page with an overview over the project/repository and some of the fundamental design concepts. This may not be exclusively relevant to porting boards but to anyone who wants to contribute code and the relevant sections could still be referenced from the porting guide.

@gaspar-ilom : https://osresearch.net/Makefile/#build-configuration ? Maybe misplaced.

[notgivenby]

Now is time to take a macro view of the guide (not looking for nitpicks)

@tlaurion thank you for the nice catch! I overlooked that. As we started the t480 port we followed manual changes of the coreboot.config. But after @gaspar-ilom PR, and the comment I thought it is a good idea to automate it. Should we still mention that manual changes are possible?

It doesn't make much sense to create coreboot and linux config after a board config,

But at the current version we start with coreboot config...I am a bit confused.

The order should be: board.config > coreboot.config > linux.config etc.?

Is the new figures style okay?

Edit: perhaps rearranging the order of the files on the scheme is also needed. Should we follow the structure of the heads tree? .circleci > blobs > boards etc. Or better the logic of the port starting with board.config > coreboot .config> etc.

[gaspar-ilom]

@tlaurion @notgivenby Maybe summarizing how I approached the T480 port helps. I did it in January on my own when there was no issue or PR for the board yet and thought I would open those when I had a working prototype. Of course, I did not find enough time to move things quickly and in the meanwhile someone would open an issue and parallel approaches started happening here.

1. Make sure the prerequisites are met (coreboot port and dTPM in particular)
2. Create the blobs (IFD, GBE) and scripts (ME) under blobs/xx80. Sidenote: I also created scripts for the the FSP blobs, because I thought it would not be enough to rely on the blobs coreboot produces with its submodules.
3. Create a coreboot fork.
   1. For starters I just created a fork in my own github which included the patches from https://review.coreboot.org/c/coreboot/+/83274 I did this knowingly that I would later probably end up using patches, but at this point there was no similar coreboot version like 24.12. So it seemed like the fastest path towards a working build.
   2. Create the coreboot version under modules/corebootjust for the T480.
4. Create a board config (from T440p).
   1. Referencing the T480 coreboot fork and an existing linux config (from T440P I think). The linux fork required some changes which we would later find together.
   2. At this point I created the targets/xx80_me_blobs.mk file to declare board specific targets (ME blobs and for me still FSP blobs). I referenced this at the bottom of the board config.
5. Create a coreboot config by copying an existing one and using make menuconfig. I then double checked this by looking at the diff to the libreboot coreboot config and at the diff with the T440p coreboot config.
6. Add the board to circleci.
7. Then I started trying to get the board to build and fixed issues as I encountered them. I struggled a lot with artifacts in the local build, since I reused a tree I had created years ago when porting the W541 (which by the way was a lot less work because there was already the almost identical T440P supported by Heads). In the end all the clean script would not fix it, but using a fresh git clone worked.
8. When I had a first working build I created my PR (and when doing that realized that there was already an ongoing effort).

I am not saying everybody should approach it like that, but that is how I did it and it has worked ok for me. Maybe it helps to re-read the guide from that perspective. Especially wrt the order of things in the guide. The hardest part for me was actually fixing build issues both with circleci and locally as it often seemed to be completely unrelated to my changes (e.g. because of artifacts from previous builds) or I just would not have enough background in order to quickly get to the root cause of some issue. Never got stuck completely, though. Otherwise, I would have asked for help earlier.

[notgivenby]

Thanks again @notgivenby. Great porting guide!

I suggested a lot of changes. Sorry for that. However, those changes are just suggestions. Decide if they improve the guide. I don't mind if you don't include (all of) them.

Thank you for the review @gaspar-ilom . It is a joint work based on the t480 port. Since you contributed a lot, I included almost all comments. I also changed the structure of the guide and the files scheme according to the logic @tlaurion . I hope I did not miss anything. Please take a look.

[gaspar-ilom]

Thanks again @notgivenby . I have a few nitpicks. The only real change I would suggest is moving the binary blobs section above the board config section. In my opinion it is just work that is more of a prerequisite before you can start with the actual. That said, if you and @tlaurion prefer it the way it is, I am fine with that.

One other change, that I would suggest, but that may be out of scope for this PR: We should reference the porting guide now from https://github.com/linuxboot/heads-wiki/blob/master/Development/make-details.md as it explains so much of the organization of the repository that it might be worth reading it for new contributors not just when they port a new board. One sentence and a link should be fine I think.

[tlaurion]

@notgivenby used the testing notes of this PR under linuxboot/heads#1658 (comment)

Please review things I corrected there

• Tasklist for PR0 are not subtasks
• Some corrections this PR would benefit from
• Neglect TPM DUK: Omnigol's CR50 TPM2 is not feature complete and doesn't support TPM additional secret sealing is additional nvram for unknown reasons up to now.

@notgivenby Thanks!

[tlaurion]

LGTM! let's iterate more in mall changes. Will also help for omnigol feedback and next ports.

[notgivenby]

That was a lot of fun and new knowledge! Thank you @tlaurion and @gaspar-ilom for help!