You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: Development/Porting.md
+41-43Lines changed: 41 additions & 43 deletions
Original file line number
Diff line number
Diff line change
@@ -35,43 +35,31 @@ Files needed to be created/modified are depicted on the scheme.
35
35
36
36
Prerequisites for building the ROM
37
37
===
38
-
The goal is to build a ROM before the code review. `new_board` refers to the name of your board (e.g., `t480`). It is recommended to clone the Heads GitHub repository and create a new branch:
38
+
The goal is to build a ROM before the code review. `NEW_BOARD` refers to the name of your board (e.g., `t480`). It is recommended to clone the Heads GitHub repository and create a new branch:
39
39
```shell
40
40
git clone https://github.com/linuxboot/heads.git
41
-
git checkout -b Poc_new_board
41
+
git checkout -b Poc_NEW_BOARD
42
42
```
43
43
44
-
coreboot.config:
45
-
---
46
-
You need a coreboot configuration. Ideally, this config should be adapted from the closest possible platform. You can inspect existing configurations for boards in the master branch and select one with a similar architecture, if available. Next, you can create a coreboot config using coreboot's `make menuconfig` for `new_board` and adapt it accordingly.
./docker_repro.sh make coreboot.modiy_and_save_oldconfig_in_place
50
-
```
51
-
Note, the configuration needs to define the correct path references to all binary blobs, that are not provided by coreboot, on most architectures this includes at least `IFD`, `ME` and `GBE`(see below). The configuration file path should be: `heads/config/coreboot-new_board.config`.
52
-
* Note:
53
-
TPM measured boot (```CONFIG_TPM_MEASURED_BOOT=y```) and verified boot (```CONFIG_VBOOT_LIB=y```) should be enabled. Ensure that you select CONFIG_TPM_MEASURED_BOOT and CONFIG_VBOOT_LIB in Kconfig. Furthermore, enable the TPM and pick the correct TPM version for the board.
54
-
Other parameters depend on the board. It is up to you to determine the correct settings, as not all community members will have access to your board.
55
-
56
-
linux.config:
44
+
modules/coreboot:
57
45
---
58
-
This should be adapted from a similar board. The file path should be `heads/config/linux-new_board.config`.
46
+
coreboot fork that will be used should be added under `heads/modules/coreboot`. This will be the version you reference from the board config files. You should aim for building the board with an existing coreboot version, usually the main version that most boards use. If you need a different coreboot version, consider patching an existing version without breaking any other boards depending on it, of course. However, if you need to add a new coreboot fork, it should be done here. This is not ideal and not recommended, as there are already 2 different coreboot forks. It often leads to maintenance and resources burden.
59
47
60
48
board.config:
61
49
---
62
-
There should be a file `new_board-hotp-maximized.config`, which inherits all the parameters from `new_board-maximized.config` and adds HOTP verification. This is Heads specific configuration and should be adapted from a similar platform. The top of the board config files is also a good place to put some technical board-specific documentation, known issues etc.
63
-
You should point in `new_board-hotp-maximized` and `new_board-maximized` to the coreboot version e.g. `export CONFIG_COREBOOT_VERSION=X.Y.Z.`- that will be modified under modules/coreboot (see corresponding section below). Additionally, the configurations should reference the appropriate coreboot and linux configs created above:
50
+
There should be a file `NEW_BOARD-hotp-maximized.config`, which inherits all the parameters from `NEW_BOARD-maximized.config` and adds HOTP verification. Those files should be located in the folder `heads/boards/NEW_BOARD-hotp-maximized` and `heads/boards/NEW_BOARD-maximized`, respectively. This is Heads specific configuration and should be adapted from a similar platform. The top of the board config files is also a good place to put some technical board-specific documentation, known issues etc.
51
+
You should point in `NEW_BOARD-hotp-maximized` and `NEW_BOARD-maximized` to the coreboot version e.g. `export CONFIG_COREBOOT_VERSION=X.Y.Z.`- that was modified under `modules/coreboot` (see corresponding section above). Additionally, the configurations should reference the appropriate coreboot and linux configs created below:
* For early testing, enabling debug mode is a good idea. However, these options should be removed before merging:
69
57
```
70
58
export CONFIG_DEBUG_OUTPUT=y
71
59
export CONFIG_ENABLE_FUNCTION_TRACING_OUTPUT=y
72
60
```
73
61
Note: This may cause glitches where the screen output appears overwritten until an arrow key is pressed. This is normal for DEBUG mode, as the additional tracing output uses the same console as fbwhiptail. The issue will disappear once debug options are removed from the board configs.
74
-
* It is important to define the correct TPM configuration (TPM 1.2 vs. TPM 2.0), ensuring they are mutually exclusive, similar to the coreboot configuration. The selected option misses `#`:
62
+
* It is important to define the correct TPM configuration (TPM 1.2 vs. TPM 2.0), ensuring they are mutually exclusive, similar to the coreboot configuration (described in coreboot config below). The selected option misses `#`:
In the configuration, the path to the folder containing binary blobs must be specified. These are required by coreboot for building the ROM (please see binary blobs session).
85
-
86
-
modules/coreboot:
87
-
---
88
-
coreboot fork that will be used should be added under `heads/modules/coreboot`. You should aim for building the board with an existing coreboot version, usually the main version that most boards use. If you need a different coreboot version, consider patching an existing version. Without breaking any other boards depending on it, of course. However if you need to add a new coreboot fork add it under modules/coreboot. This will be the version you reference from the board config files.
72
+
In the configuration, the path to the folder containing binary blobs must be specified. It is the line at the bottom of the board config `BOARD_TARGETS := NEW_BOARD` declaring the dependency. It corresponds to the name of the `mk file` referencing the needed binary blobs. These are required by coreboot for building the ROM.
89
73
90
74
binary blobs:
91
75
---
92
-
Check the coreboot configuration for the ported board. This will indicate which binary blobs are required and where they are expected to be located. Heads has architecture-/board-specific scripts under `blobs/*` which do the magic, called by the main makefile that handles everything in Heads. For additional details please see [Makefiles]({{ site.baseurl }}/Development/make-details.md). These scripts must create reproducible binary blobs when invoked. The blobs should be placed in the `blobs/new_board/`. Make sure the coreboot config file references the correct path for each blob.
76
+
Check the coreboot configuration for the ported board. This will indicate which binary blobs are required and where they are expected to be located. Heads has architecture-/board-specific scripts under `blobs/*` which do the magic, called by the main makefile that handles everything in Heads. These scripts must create reproducible binary blobs when invoked. The blobs should be placed in the `blobs/NEW_BOARD/`. Make sure the coreboot config file references the correct path for each blob.
93
77
Generally, three binary blobs are required: Management Engine (ME), Intel Flash Descriptor Region (IFD), and Gigabit Ethernet (GBE) The IFD and GBE can be extracted from a donor board using coreboot’s ifdtool. For more details, refer to the [upstream documentation](https://doc.coreboot.org/util/ifdtool/layout.html). On some boards it may be necessary to provide more blobs to coreboot, for instance an MRC blob for ram initialization if coreboot cannot distribute the blob itself for legal reasons.
94
78
95
79
Please note, if the ME is neutered, the IFD, coreboot CBFS region, and ME neutering space should be adjusted accordingly. Rationale: the ME region defined under IFD must fit. With the IFD ME region reduced, the BIOS region can grow with the freed ME space. With the BIOS region augmented, the CBFS region of the coreboot configuration must be increased to fit the ["maximized" space](https://osresearch.net/Prerequisites#legacy-vs-maximized-boards).
96
80
97
81
Please note the GBE MAC address should be forged to: `00:DE:AD:C0:FF:EE MAC`. It can be done with [nvmutil](https://libreboot.org/docs/install/nvmutil.html). Due to licensing restrictions, the ME firmware cannot be uploaded to the GitHub. However, scripts can be used to build it locally and within CircleCI (a gray area legally, but still possible).
98
-
* Note: When calling scripts in Nix-based environments, Python must be invoked explicitly, as Nix does not allow executing Python scripts directly from files. One can use last clean example for t480:`python ./finalimage.py` will work and just `./finalimage.py` will not work.
82
+
* Note: When calling scripts in Nix-based environments, Python must be invoked explicitly, as Nix does not allow executing Python scripts directly from files. One can use last clean example for t480:`python ./finalimage.py` will work and just `./finalimage.py` will not work.
99
83
The blobs folder should have a script.sh which handles downloading, deactivating ME etc. It should also contain a README.md file briefly explaining the process. Hashes of the blobs should be stored either in `README.md` or in `hashes.txt file`. Furthermore, the script must ensure the integrity of the blobs it produced by comparing a SHA256 hash.
100
84
101
-
new_board.mk:
85
+
NEW_BOARD.mk:
102
86
---
103
-
Create a new `heads/targets/new_board.mk` file which deals with calling blobs/script.sh* download and extraction of blobs placing the blobs in correct location. This will be used by the main makefile and defines the board specific targets and dependencies, such as the binary blobs.
104
-
Please not that you should add a line at the bottom of the board config `BOARD_TARGETS := new_board` to declare the dependency.
87
+
Create a new `heads/targets/NEW_BOARD.mk` file which deals with calling blobs/script.sh*, download and extraction, and placing the blobs in correct location. This will be used by the main makefile and defines the board specific targets and dependencies, such as the binary blobs. For additional details, please see [Makefiles]({{ site.baseurl }}/Development/make-details.md).
88
+
89
+
coreboot.config:
90
+
---
91
+
You need a coreboot configuration for the new board. Ideally, this config should be adapted from the closest possible platform. You can inspect existing configurations for boards in the master branch and select one with a similar architecture, if available. Next, you can create a coreboot config by copying it from closest platform and adapt it accordingly. You may use coreboot's `make menuconfig` for `NEW_BOARD`:
./docker_repro.sh make coreboot.modify_and_save_oldconfig_in_place
95
+
```
96
+
Note, the configuration needs to define the correct path references to all binary blobs, that are not provided by coreboot, on most architectures this includes at least `IFD`, `ME` and `GBE`(see below). The configuration file path should be: `heads/config/coreboot-NEW_BOARD.config`.
97
+
* Note:
98
+
TPM measured boot (```CONFIG_TPM_MEASURED_BOOT=y```) and verified boot (```CONFIG_VBOOT_LIB=y```) should be enabled. Ensure that you select CONFIG_TPM_MEASURED_BOOT and CONFIG_VBOOT_LIB in Kconfig. Furthermore, enable the TPM and pick the correct TPM version for the board.
99
+
Other parameters depend on the board. It is up to you to determine the correct settings, as not all community members will have access to your board. `git diff` between `coreboot-CLOSEST_PLATFORM.config` and `coreboot-NEW_BOARD.config` may help.
100
+
101
+
linux.config:
102
+
---
103
+
This should be adapted from a similar board. The file path should be `heads/config/linux-NEW_BOARD.config`.
105
104
106
105
CircleCI:
107
106
---
108
-
Modify `heads/.circleci/config.yml` to add support for the `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.
107
+
Modify `heads/.circleci/config.yml` to add support for the `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.
109
108
```
110
-
# new_board is based on `X.Y.Z`. coreboot release, not sharing any buildstack from now, depend on muscl-cross cache
109
+
# NEW_BOARD is based on `X.Y.Z`. coreboot release, not sharing any buildstack from now, depend on muscl-cross cache
111
110
- build:
112
-
name: new_board-hotp-maximized
113
-
target: new_board-hotp-maximized
111
+
name: NEW_BOARD-hotp-maximized
112
+
target: NEW_BOARD-hotp-maximized
114
113
subcommand: ""
115
114
requires:
116
115
- x86-musl-cross-make
117
116
```
118
-
CircleCI creates reproducible builds, allowing users to verify that the flashable roms were indeed produced by the given source code. In the development/debugging phase, it helps to ensure that you talk about the same build. It optimizes the collaboration between peers-board owners. Moreover, CI builds are significantly faster than local builds, reducing overall development time. As circleCI always builds all boards it makes it easier to find regression early.
117
+
CircleCI creates reproducible builds, allowing users to verify that the "flashable" roms were indeed produced by the given source code. In the development/debugging phase, it helps to ensure that you talk about the same build. It optimizes the collaboration between peers-board owners. Moreover, CI builds are significantly faster than local builds, reducing overall development time. As circleCI always builds all boards it makes it easier to find regression early.
119
118
120
119
* Optional: local builds.
121
-
If you need to build locally (e.g. to ensure that some new features work) pay attention to the helper functions at the end of the Makefiles. It is strongly recommended that local builders review the end of the Makefiles (including modules/*files), as these helper functions were designed to facilitate coreboot and Linux version bumps.
122
-
For a completely clean build (the most radical approach), remove all build artifacts using:
120
+
If you need to build locally (e.g. to ensure that some features work) pay attention to the helper functions at the end of the Makefiles. It is strongly recommended that local builders review the end of the Makefiles (including modules/*files), as these helper functions were designed to facilitate coreboot and Linux version bumps.
121
+
For a completely clean build (the most radical approach), either clone the Heads repository again or remove all build artifacts using:
123
122
```bash
124
-
./docker_repro.sh BOARD=new_board real.clean
123
+
./docker_repro.sh BOARD=NEW_BOARD real.clean
125
124
```
126
-
For a less radical approach, run:
125
+
Building all tools needed will take a while depending on the number of cores and RAM available on your machine. For a less radical approach, run:
Then, inject any changes into the coreboot fork canary file so that the build system refetches, repatches, and rebuilds the coreboot fork:
131
130
```shell
132
131
echo"bogus"| sudo tee build/x86/coreboot-t480/.canary
133
132
```
134
-
Note, patches that attempt to create files that are not expected to exist but exist will fail, showing at console what files already existed that couldn't be created. In this case, you need to remove them manually `rm -rf`, and restart the build with `./docker_repro.sh BOARD=new_board` which will progress until each modules/* required per board config is successfully built.
133
+
Note, patches that attempt to create files that are not expected to exist but exist will fail, showing at console what files already existed that couldn't be created. In this case, you need to remove them manually `rm -rf`, and restart the build with `./docker_repro.sh BOARD=NEW_BOARD` which will progress until each modules/* required per board config is successfully built.
135
134
136
135
Testing
137
136
===
138
-
139
137
For thorough testing—especially for a new board—using the following template (tasks to check) may be beneficial. Copy and paste this template into the GitHub message window when reporting test results. Mark completed tasks with an `x` inside the brackets []. Replace `X.Y.Z` with the relevant information. It is recommended also to upload relevant screenshots For additional safety, you may wish to remove the metadata from these files.
140
138
```
141
139
- [ ] Successful external flash link to circleci: https://X.Y.Z. from commit `X.Y.Z.` using external programmer model `X.Y.Z.` on `X.Y.Z.` Voltage mode
0 commit comments