This repository contain documentation and scripts that aim to help PC Engines apuX platform users and developers to customize firmware to their needs.
- Repository structure
- Versioning scheme change
- Feature/bug fix development
- Steps for new release
- Using iPXE
This repository aims to gather all debug notes and documentation related to PC Engines apu1/2/3/4/5 firmware and hardware. Structure of the repository:
- configs - directory with kernel configs used in 3mdeb pxe-server for validation purposes
- docs - overall directory with documents
- docs/debug - documents containing various problems debugging notes
- docs/images - images included in certain documents
- docs/logs - directory containing variosu logs from debugging
- docs/research - directory with notes from research of new features
- ipxe - iPXE scripts, headers and configuration files used in old build system
- scripts - BASH scripts used in the old build system
-
Linux issues - document describes known issues with Linux of different versions and how to work around them when it's possible.
-
CPU Boost - document briefly describes what the Core Performance Boost is and how to verify it works in BIOS and operating system.
-
Fast Boot - document describing research for Fast Boot path for apu boards. The Fast Boot was intended to restore memory configuration from non-volatile storage and reduce the boot time of the platform. You will find the issues and limitations which did not allow to implement the feature.
-
ROCA - document describing ROCA TPM vulnerablity status and verification on TPM1a module form PC Engines.
-
APU mPCIe capabilities - list of all signals and interfaces present on mPCIe connectors for apu2/3/4 boards. The document also describes possible usage of the slots.
-
Cold reset - document describing reset types for the platform.
-
Firmware flashing - document describes how to flash new firmware for apu2 board on various operating systems. Also there is a description how to safely reboot the platform after a firmware update.
-
Microcode patching - a guide how to apply a microcode patch on the firmware level by building a custom firmware image.
-
mPCIe modules - list of supported and tested WiFi and LTE modules. The document also describes issues with certain modules and possible solutions/workarounds.
-
pfSense installation guide - as in the title
-
PXELINUX configuration - documents describing possible solutions when experiencing problems with PXELINUX on apu boards.
-
Old build system procedure (deprecated) - document describing build procedure for older PC Engines firmware releases. It is deprecated, do not use unless You want to build old binaries.
-
COM2 serial console - a practical guide how to build a firmware binary with native COM2 console support. If You want to use full RS232 COM1 port for other purposes, read the document how to change the main console port.
-
TPM menu - document describes the usage of TPM configuration menu in SeaBIOS.
-
TPM pin mapping - document showing the TPM1a module pinout. It may be useful for users that would like to connect the TPM1a module to boards other than apu2.
-
VBOOT HOWTO - document describing how to build a coreboot image with vboot support and measured boot mode
-
coreboot with Tianocore payload - document describes how to build a coreboot image with Tianocore payload
-
GPIO guide - quick guide how to manipulate GPIOs from Linux sysfs
-
Order of PCI addresses - Describes how PCIe devices are being numbered on APU, and how it can be changed.
-
Runtime configuration - A guide how to change apu firmware configuration options in the BIOS setup or via OS application
You may also find many other documents out there, but we have listed only the most useful. Other are mostly developers notes which may not be that interesting.
Since version v4.8.0.1 we changed versioning scheme skipping coreboot v4.7
release.
In recent version coreboot community introduced tag v4.8.1 this breaks our
previous versioning scheme which was v4.6.z, where z was PC Engines fork
patch number. Because 3rd digit was already taken by coreboot tag this breaks
our versioning scheme. As a result we start to use new versioning scheme
v4.8.0.w, where w will be PC Engines fork patch number as always for each
new release counted from 0.
If you take a look at coreboot tag dates:
refs/tags/4.6 Sun Apr 30 19:48:38 2017 -0600
refs/tags/4.7 Mon Jan 15 00:57:04 2018 +0000
refs/tags/4.8 Tue May 15 17:40:15 2018 +0000
refs/tags/4.8.1 Wed May 16 19:07:34 2018 +0000
After release of 4.7 we simply didn't have enough time to adjust to 4.7 before 4.8 popped up. Please note that coreboot releases are just arbitrary points in time, so trying to follow mainline in each release may make more sense, but requires decent testing.
All information about firmware releases (including changes, fixes and known issues) are available on the PC Engines Github site pcengines.github.io.
All the newest binaries can be found there.
Also please take a look at changelogs:
Since releases v4.6.10 and v4.0.17 build process has been simplified. PC Engines firmware builder is a dedicated tool to build fully featured apu firmware binaries using separated docker environment. It provides users-friendly scripts that allow to build release and custom binaries. For more information and usage details please visit: pce-fw-builder.
For releases older than v4.0.17 and v4.6.10 use the procedure described in this document
master- keeps track of coreboot's master branchrelease- where all releases are mergeddevelop- where current development takes place periodically synced with coreboot masterrel_x.y.z.w- release branches, where:xis coreboot major versionyis coreboot minor versionzis coreboot patch numberwis PC Engines firmware fork patch number counted from0
feature_branch- sample feature branch name for workflow explanation needs
We are in favor of Test Driven Bug Fixing (TDBF).
- Create automated test that validate feature or reproduce bug - test fails at this point
- Pull
coreboot's master branchtomaster - Merge
mastertodevelop - Create new branch
feature_branchfromdevelop - Commit changes to
feature_branch - Run regression tests and fix bugs - test written in point 1 should pass at this point
- Submit PR to
develop
- Checkout new branch
rel_x.y.z.wfrom recent commit onrelease - Merge current
developtorel_x.y.z.w - End of month we close merge window
- Perform automated regression testing on
rel_x.y.z.wincluding all new tests - Fix all required issues and repeat point 4 until fixed - this doesn't mean all tests pass, this mean that approved set passed
- If results are accepted merge it to
releasebranch - Add tag, which should trigger CI and publish binaries
- Merge release branch to develop
This option assume that your apuX is in the same networks as your PC. Your PC in this case is used as HTTP and NFS server, which will be utilized to boot apuX over iPXE.
git clone https://github.com/3mdeb/pxe-server.git
cd pxe-server
NFS_SRV_IP=<your_ip> ./init.sh
./start.sh
Please note that you may have NFS server running on host what leads to ports conflicts.
After starting NFS and HTTP you can boot apuX. Please enable network booting using sortbootorder.
iPXE> ifconf net0
iPXE> dhcp net0
iPXE> chain http://<your_ip>:8000/menu.ipxe
Choose Debian stable netboot 4.14.y after boot login ([root:debian]) and
for apu2/3/4/5 run:
flashrom -p internal -w apuX_x.y.z.rom
For apu1 flashrom command line looks like that:
flashrom -p internal -w apu1_x.y.z.rom -c MX25L1605A/MX25L1606E/MX25L1608E
A full power cycle is required after flashing. See firmware_flashing.md for a workaround when this is not possible (e.g. when upgrading remotely).
Some binaries may need boardmismatch=force flashrom option because of SMBIOS
table issue we had in old releases. Please double check you flashing correct
binary before forcing.
Feel free to send pull request if you find bugs, typos or will have issues with provided procedures.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent