Amlogic/Porting set top boxes

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). 
== Getting help ==
We are available in the #amlogic-postmarketos IRC channel on OFTC.
If you are a Matrix user you can join #oftc_#amlogic-postmarketos:pixie.town to connect to that IRC channel.
== Overview ==
=== Prerequisites ===
* pmbootstrap
* A working device tree
* Your set-top box :)
* (UART)
(Don't worry. We'll set everything up later on)
=== Components ===
̣==== Generic TV box port ====
Most Amlogic set-top boxes are now supported in one single TV box port. This makes packaging and maintenance easier as all the common bits and pieces are shared.
==== ====
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
=== 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 ===
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.
=== Booting ===
See Amlogic#Boot_process
== Maintainers ==
* FerassElHafidi
* exkc
== See also ==
* Amlogic wiki page
* Generic guide on porting U-Boot