Document vendor-maintained Heads ports

About/Vendors_resellers.md

@@ -8,21 +8,15 @@ parent: About
 
 # Heads Vendors and Resellers
 
-For those who prefer not to manually flash Heads firmware on their devices,
-several vendors and resellers offer laptops, workstations, and servers with
-Heads preinstalled. These vendors provide a range of secure and privacy-focused
-devices, making it easier for potential users to get started with Heads without
-the hassle of searching for options online. By choosing one of these vendors or
-resellers, users who don't want to open their devices and flash manually can
-easily get a device with Heads preinstalled. This provides a straightforward
-solution for those who would benefit from Heads' secure firmware but need a more
-accessible option. Additionally, many of these vendors offer customization
-options, preinstallation of various operating systems, and anti-interdiction
-mechanisms to ensure the security and integrity of the devices.
+Several vendors and resellers offer Heads preinstalled. Other hardware vendors
+maintain coreboot platforms and contribute Heads ports without yet offering
+Heads as a factory option. The availability stated for each vendor is therefore
+important: an upstream port does not imply that Heads can be selected when
+ordering a machine.
 
 The vendors are listed alphabetically.
 
-## Vendors and Resellers
+## Heads preinstalled
 
 ### HardenedVault (VaultBoot)
 HardenedVault provides VaultBoot (a variant of Heads) preinstalled on their
@@ -61,6 +55,18 @@ The Librem Key is made in the USA.
 - **Products:** Laptops, phones, tablets, mini PCs, servers, and USB security
   dongles
 
+## Vendor-maintained ports
+
+### Star Labs
+
+Star Labs develops Linux laptops, tablets and mini PCs with coreboot firmware.
+The StarLite Mk V Heads port is
+[under upstream review](https://github.com/linuxboot/heads/pull/2164). Heads is
+not currently offered preinstalled; users must build and flash it themselves.
+
+- **Website:** [Star Labs](https://starlabs.systems)
+- **Products:** Laptops, tablets and mini PCs
+
 ## General Information
 
 Many of these vendors offer additional services and features, including:

Development/Porting.md

@@ -48,23 +48,64 @@ coreboot fork that will be used should be added under `heads/modules/coreboot`.
 
 binary blobs:
 ---
-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 expects 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 and the blobs are added to `.gitignore` so that they are not accidentally committed to git.
-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.
-
-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 optimized space (all current Heads boards use this approach).
-
-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). GBE and IFD blobs can be uploaded directly to GitHub. Please explain how they were obtained in the commit message.
+Check the coreboot configuration for the ported board. This will indicate which
+binary blobs are required and where they are expected to be located. Some
+coreboot repositories provide the common blobs needed by their supported
+boards. Other ports need architecture- or board-specific scripts under
+`blobs/*`, called by the main Heads makefile. These scripts must produce
+reproducible output, place it under `blobs/NEW_BOARD/`, verify its SHA256 hash,
+and keep generated blobs out of git.
+
+Intel ports commonly need Management Engine (ME), Intel Flash Descriptor (IFD)
+and Gigabit Ethernet (GBE) data. The IFD and GBE regions 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).
+Some boards also require an MRC or FSP blob for memory initialization.
+
+If a port neuters ME and reallocates the freed space, update the IFD and
+coreboot CBFS layout together. The ME region in the IFD must still contain the
+prepared ME image and the expanded BIOS region must match coreboot's layout.
+Do not apply this layout change to a vendor-maintained image unless the platform
+explicitly supports it.
+
+Do not overwrite per-device data such as a working GBE MAC address, VPD,
+calibration data or device identity with shared build artifacts. A placeholder
+such as `00:DE:AD:C0:FF:EE` may be used in a reproducible CI image that will not
+be flashed whole, but installation and update instructions must preserve the
+device's original region. Vendor-maintained ports with a fixed FMAP should
+normally limit writes to the intended firmware region.
+
+Due to licensing restrictions, ME firmware cannot be uploaded to GitHub.
+Scripts may download or prepare it locally and in CI where licensing permits.
+GBE and IFD blobs can be uploaded directly when redistribution is allowed.
+Explain how each blob was obtained in the commit message.
 * 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. 
-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.
+When a port needs a blobs folder, it should contain a `script.sh` which handles
+downloading or preparing the blobs and a `README.md` which explains the process.
+Store expected hashes in the README or a `hashes.txt` file and make the script
+reject unexpected output.
 
 NEW_BOARD.mk:
 ---
-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).
+If the port needs board-specific build targets, create
+`heads/targets/NEW_BOARD.mk`. It should call the blob preparation script and
+place its output where coreboot expects it. A board whose selected coreboot
+repository already provides every required common blob does not need an empty
+target file. For additional details, please see
+[Makefiles]({{ site.baseurl }}/Development/make-details.md).
 
 board.config: 
 ---
-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.
-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:
+A port needs at least one production board configuration. It may provide
+separate `NEW_BOARD-maximized` and `NEW_BOARD-hotp-maximized` targets when both
+profiles are useful, or one target with HOTP enabled when that is the supported
+configuration. Adapt the file from a maintained board on a similar platform.
+The top of the file is also a good place for technical notes, known issues and
+links to recovery instructions.
+
+Each board configuration must select the coreboot version added under
+`modules/coreboot`, for example `export CONFIG_COREBOOT_VERSION=X.Y.Z`, and
+reference the corresponding coreboot and Linux configurations:
 ```
 CONFIG_COREBOOT_CONFIG=config/coreboot-NEW_BOARD.config
 CONFIG_LINUX_CONFIG=config/linux-NEW_BOARD.config
@@ -85,7 +126,9 @@ export CONFIG_PRIMARY_KEY_TYPE=ecc
 #TPM1 requirements
 #export CONFIG_TPM=y
 ```
-In the configuration, the binary blobs must be specified as build targets, as coreboot depends on these blobs. It is the line at the bottom of the board config `BOARD_TARGETS := NEW_BOARD`. It ensures that the main Heads makefile builds the targets specified in the `NEW_BOARD.mk` file.
+When a board has binary preparation targets, list them in `BOARD_TARGETS` so
+Heads builds them before coreboot. Omit `BOARD_TARGETS` when the port has no
+board-specific target.
 
 coreboot.config:
 ---
@@ -220,7 +263,7 @@ export CONFIG_QUIET_MODE=y
 
 Write a flashing/disassembling guide
 ===
-Take pictures as you disassemble your board and flash the Heads ROM. You can use them later to write a guide. This will help less technical community members using the board. Your effort will improve the ecosystem. 
+Take pictures as you disassemble your board and flash the Heads ROM. You can use them later to write a guide. This will help less technical community members using the board. Your effort will improve the ecosystem. A maintained vendor guide is acceptable when it covers the same board revision, programmer connection and recovery procedure; link it from the Heads flashing-guide index and board configuration.
 If you cannot manage to finish writing the guide but talented enough to finish the port just create an issue on the GitHub and drop pictures. We will try to find time to help.
 The guide is essential part of the port.
 

Installing-and-Configuring/Flashing-Guides/StarLite-Mk-V.md

@@ -0,0 +1,66 @@
+---
+layout: default
+title: Star Labs StarLite Mk V
+permalink: /StarLite-Mk-V-flashing/
+published: false
+nav_order: 6
+parent: Step 2 - Flashing Guides
+grand_parent: Installing and configuring
+---
+
+Star Labs StarLite Mk V
+===
+
+> **Port status:** The StarLite Mk V port is still
+> [under review](https://github.com/linuxboot/heads/pull/2164). This page is draft
+> documentation for port testers and is excluded from the published site. It
+> can be published after the exact Heads revision has passed the porting
+> checklist and the code PR has merged.
+
+The StarLite Mk V uses a debug connector rather than a clip directly on the SPI
+flash. Follow the
+[Star Labs external programmer guide](https://support.starlabs.systems/hc/star-labs/articles/starlite-mk-v-installingrecovering-firmware-with-external-programmer)
+for disassembly, battery disconnection and connection of the FPC cable, debug
+board and CH341A programmer.
+
+Read the [SPI Programmer Best Practices guide]({{ site.baseurl }}/SPI-Programmer-Best-Practices/)
+before connecting the programmer.
+
+## Back up the flash
+
+With the StarLite battery and charger disconnected, take two complete reads:
+
+```shell
+sudo flashrom -p ch341a_spi -r starlite-backup-1.rom
+sudo flashrom -p ch341a_spi -r starlite-backup-2.rom
+sha256sum starlite-backup-1.rom starlite-backup-2.rom
+cmp starlite-backup-1.rom starlite-backup-2.rom
+```
+
+Stop if `cmp` reports a difference. Keep both backups on another device. They
+contain the original descriptor, Intel ME, EC, settings and per-device data
+needed for recovery.
+
+## Flash Heads
+
+After the port has merged, build the `starlabs_lite_adl` target and verify the
+ROM hash against the build output. Before merge, only port testers with recovery
+hardware should use the exact head commit from the code PR and its corresponding
+CI artifact. Set `HEADS_ROM` to the resulting
+`heads-starlabs_lite_adl-*.rom` file.
+
+The Heads ROM contains common build data outside the `COREBOOT` FMAP region.
+Do not use the whole-image write command at the end of the general Star Labs
+recovery guide with a Heads ROM. Preserve the existing descriptor, Intel ME,
+EC, SMMSTORE and per-device regions by writing only `COREBOOT`:
+
+```shell
+HEADS_ROM=path/to/heads-starlabs_lite_adl-version.rom
+sudo flashrom -p ch341a_spi --fmap -i COREBOOT \
+  -N -w "$HEADS_ROM"
+```
+
+`-N` limits automatic verification to the included `COREBOOT` region; it does
+not disable that verification. Do not use `-n`. If the write or verification
+fails, leave the programmer connected and restore `starlite-backup-1.rom`
+before attempting to boot.