system76-firmware-open/docs/adding-a-new-board.md

Adding a new board

In order to add support for a new board you will need the current proprietary BIOS ROM, the schematics for the system, and, if porting System76 EC, the EC specification document. While the BIOS ROM is available from the manufacturer, board schematics and EC specification typically require NDAs to access.

Recommended hardware

The presence of hardware will affect the output of the script used to generate the GPIO configuration for coreboot. It is recommended to have enough spare hardware to fill all available slots on the motherboard. This includes RAM modules, SATA drives, and M.2 modules. If the system has a Thunderbolt port, a dock will also be useful for verifying Thunderbolt and PCIe hotplug functionality.

These should be ready before attempting to boot a new port:

• An external programmer; for flashing the BIOS chip
• A Mega 2560; for flashing the EC and debug logging

Configuring the system

Before starting the porting process, the system should be configured to enable as many devices as possible to provide a more complete output for coreboot.

1. If the motherboard has open slots (RAM, M.2, SATA), fill them
2. Boot into the proprietary BIOS
3. Enable things such as
   • TPM
   • Network stack
   • VT-d
4. Disable the Intel Management Engine (IME) if possible
5. Exit, saving changes
6. If the system is a laptop, connect to AC power with the adapter
7. If the device has a Thunderbolt port, attach and authorize a TBT device
8. If the device has a dGPU, ensure it present on the PCI bus
   • On Pop!_OS, switch to NVIDIA graphics mode

sudo bash -c 'echo 1 > /sys/bus/pci/rescan'

Generating required output

The generate.sh script will perform most steps for collecting the required data for coreboot and EC firmware development. If regenerating for an existing model, it will automatically overwrite the data.

If planning to use System76 EC firmware, perform the following before running:

• Set keyboard backlight to full brightness and white light
• Set display backlight to full brightness
• Set CPU fan to full speed

./scripts/generate.sh <model> <firmware.rom> [ec.rom]

If the microcode blobs from coreboot will not be used, then microcode.rom must be generated for the correct CPU set from the private intel-microcode repo.

Porting coreboot

To port coreboot to a new board, see the coreboot documentation.

• TAS5825M smart amp

Once coreboot is ported, add its configuration.

cp coreboot/.config models/<model>/coreboot.config

devicetree

Some values to set in devicetree.cb that are not collected by generate.sh.

• Power limits

sudo cat /sys/class/powercap/intel-rapl:0/constraint_0_power_limit_uw
sudo cat /sys/class/powercap/intel-rapl:0/constraint_1_power_limit_uw

• Power

# pmc_bar + GEN_PMCON_A
sudo devmem2 0xfe001020
# PchPmSlpS3MinAssert = bits 11:10
# PchPmSlpS4MinAssert = bits 5:4

# pmc_bar + PM_CFG
sudo devmem2 0xfe001818
# PchPmSlpSusMinAssert = bits 19:18
# PchPmSlpAMinAssert = bits 17:16

• Thermal

sudo modprobe msr
sudo rdmsr --bitfield 31:24 --decimal 0x1A2

• LPC

sudo lspci -s 1f.0 -xxx
# gen1_dec: 0x84-0x87
# gen2_dec: 0x88-0x8B
# gen3_dec: 0x8C-0c8F
# gen4_dec: 0x90-0x93

Porting System76 EC

To port System76 EC firmware to a new board, see the EC documentation.

Once System76 EC is ported, add ec.config.

echo "BOARD=system76/<model>" > models/<model>/ec.config"

If the proprietary EC was previously used, remove ec.rom and regenerate the READMEs.