Amlogic/Porting set top boxes
| 🚧 | This page is a work-in-progress. Some information contained within may be inaccurate or incomplete. |
With BayLibre, Amlogic, and Linaro, along with other independent developers slowly (but surely) adding full support for more and more Amlogic SoCs to mainline Linux (including the S905!), getting core functionality on your Amlogic-based set top box is now easier than ever (on most of them).
This page documents how you can get it to load postmarketOS, with core features such as working HDMI. Please note that because there are many, many set top boxes using an Amlogic SoC, it's not easy to get everything to work, but for some people it's still a fun experience!
Please note that this covers running postmarketOS on an SD card or any other removable device. Getting it to work on the internal storage is left as an exercise to the reader. It also only covers set-top boxes running U-Boot as their primary bootloader that have a "mode" to boot a specific script on a removable device, thus postmarketOS would boot from the vendor U-Boot fork, not mainline (it's actually chainloading a mainline U-Boot binary which in turn runs pmOS).
Overview
Prerequisites
- pmbootstrap
- A working device tree
- Your set-top box :)
- (UART)
(Don't worry. We'll set everything up later on)
Components
Kernel package
As of now (March 2023) the kernel used on most Amlogic devices is just mainline Linux with a few patches on-top that fix up small things on existing device trees or add new ones. Those patches are slowly going to get dropped as they land upstream.
Common SoC package
This is a common package used by most Amlogic S905 devices as well as some Amlogic S912 and S905X devices. It has a U-Boot script for loading a mainline U-Boot binary from the stock U-Boot found on your device. It also includes an X11 config for those devices because without it X11 refuses to run.
U-Boot
The U-Boot binary mentioned before is provided by u-boot-amlogic-s905-tv. It's basically v2020.07 U-Boot, with a patch to
modify the Amlogic p201's (a reference board by Amlogic) defconfig to have more functionality working (HDMI, ...).
It's only confirmed to work on the Amlogic S905 SoC.
There's another U-Boot package used by Amlogic S905X/S905W/S905Z/S905L/S805X/S805Y devices (u-boot-amlogic-s905x-tv).
Optional firmware
Most set top boxes require non-free firmware for non-essential features to work out of the box (Wi-Fi, Bluetooth, ...). It'll heavily depend on the set top box you own, as Amlogic SoCs usually don't have built-in Wi-Fi nor Bluetooth.
Most devices use a Broadcom Wi-Fi/Bluetooth. You can use firmware located here for these devices.
Getting started
The build environment
This guide heavily depends on pmbootstrap. Install it if you haven't already.
You should also install git.
Then:
$ pmbootstrap pull
$ pmbootstrap init # type in the manufacturer of your set-top box as well as the codename, this will generate packages for you.
$ cd .local/var/pmbootstrap/cache_git/pmaports # ...or the directory where pmaports got cloned
$ rm -Rf device/testing/linux-$vendor-$codename # replace $vendor and $codename with your vendor and codename respectively
Device tree
Try to find a device tree that's made for your device or for a similar one. For example, if your device happens to be similar to the Amlogic p201 reference board then you should base your device tree on the p201's.
Building the kernel
After adding your device tree patch (if any), try building the kernel!
$ cd device/testing/linux-postmarketos-amlogic
$ cp /tmp/000X-add-initial-support-for-$vendor-$codename.patch . # if any
$ nvim APKBUILD
$ pmbootstrap checksum linux-postmarketos-amlogic
$ pmbootstrap --details-to-stdout build linux-postmarketos-amlogic
Useful notes
Wiping the stock U-Boot
 |
WARNING: Some devices DO NOT support this and it's very risky to do it if you haven't made a backup or don't have a working image you can restore. CONTINUE AT YOUR OWN RISK. |
You need to wipe the entire eMMC:
# dd if=/dev/zero of=/dev/mmcblkX conv=fsync,notrunc bs=512 count=4 seek=1
# dd if=/dev/zero of=/dev/mmcblkXboot0 conv=fsync,notrunc bs=512 count=4 seek=1
# dd if=/dev/zero of=/dev/mmcblkXboot1 conv=fsync,notrunc bs=512 count=4 seek=1
The bootrom should now boot from the SD card. You'd need to build a working U-Boot as described
in this git repository. You also need a working acs.bin binary, which contains DDR timings.