Amlogic/Porting set top boxes
| 🚧 | This page is a work-in-progress. Some information contained within may be inaccurate or incomplete. |
You have an Amlogic-based TV box in your hands, and you want to run Linux on it. 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, which boot a modified U-Boot from the vendor.
Getting help
We are available in the #amlogic-postmarketos IRC channel on OFTC.
If you are a Matrix user you can join #amlogic-postmarketos:matrix.org to connect to that IRC channel.
Overview
Prerequisites
- pmbootstrap
- A working device tree
- Your set-top box :)
- UART-to-TTL adapter and a few cables
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
Identifying the hardware
It is very important to identify exactly what kind of hardware we're dealing with here. The main thing to consider is which SoC your box uses, and there are many ways to find out. The easiest way is to just look it up, but note it may not necessarily apply to your specific model (vendors have been known to put out completely different hardware under the exact same marketing name, or similar marketing names).
Another way is to simply check on the actual board. If there is no heatsink, the SoC should be visible right away, else you will have to remove it to see the marking.
Yet another way of finding out is to install some hardware info app in Android. These will tell you the SoC family and often the exact SoC, sometimes will also tell you what Amlogic reference board your box is based on.
During booting, the bootROM will print out over UART (see next section) the SoC family/generation, which can be GXL, SM1, etc. This will give you an idea what kind of SoC is in there, since SoCs in the same family tend to be very similar between them with a few minor differences.
Finding the UART port
UART is very useful for debugging issues and may also be the only way to have your box boot postmarketOS. Fortunately for many boxes, identifying the UART port is very easy.
Many Amlogic-based appliances will have visible pads (but oftentimes no actual headers, mostly to save a few bucks) with TX/RX/GND/VCC markings. While booting, you can try them out until you get the correct UART port.
A multimeter may also be of help here.
After you find the correct port, you can solder to its pads. However, MAKE SURE TO NEVER EVER CONNECT THE VCC/3V3/5V PAD.
Trying to enter the U-Boot shell
Many devices expose a U-Boot shell over UART. With the RX and TX pins connected, mash to enter a shell. Typically, the U-Boot version will be based on U-Boot v2015.01. Example from the Xiaomi Mi TV Stick (xiaomi-aquaman):
U-Boot 2015.01-g0a28df3-dirty (May 26 2020 - 19:23:51), Build: jenkins-aquaman_release-293
<...>
Hit Enter or space or Ctrl+C key to stop autoboot -- : 0
gxl_aquaman_v1#The prompt may be different, and so may be the U-Boot version banner, and there will be a huge stream of logs before this point.
Once you get a U-Boot shell, you can already try to inspect various things. The first thing to check is if the go command is compiled in or not. If it is, this allows chainloading a modern U-Boot binary from the vendor one, but if there isn't it is not the end of the world.
Another helpful thing to check is the environment. You can do this by running printenv to inspect.
Some Android boxes will silence Android kernel log output after boot. You can prevent this by running:
gxl_aquaman_v1# setenv bootargs "$bootargs ignore_loglevel"
gxl_aquaman_v1# run bootcmdUsing a "close-enough" Amlogic reference board port to test booting
With the information you gathered about what SoC is in your TV box, and with UART logging available, you can already get started by trying to boot a reference board device port.
In pmbootstrap init select amlogic-aarch64-tvbox, you will be presented with a list of available "kernels":
$ pmbootstrap init
...
[20:18:50] Device codename: aarch64-tvbox
[20:18:51] Which kernel do you want to use with your device?
[20:18:51] Available kernels (11):
[20:18:51] * p201: Kernel for Amlogic P201-based TV box (S905) [ONLY FOR TESTING]
[20:18:51] * p212: Kernel for Amlogic P212-based TV box (S905X) [ONLY FOR TESTING]
[20:18:51] * p241: Kernel for Amlogic P241-based TV box (S805X/S805Y) [ONLY FOR TESTING]
[20:18:51] * p281: Kernel for Amlogic P281-based TV box (S905W) [ONLY FOR TESTING]
[20:18:51] * sei510: Kernel for SEI Robotics SEI510-based TV box (S905X2) [ONLY FOR TESTING]
...
(list trimmed for brevity, may not be up to date)
From there, pick the one that is closest to your box. Continue with the rest of the setup as usual, then:
$ pmbootstrap install --disk=/dev/your_sdcard_or_usb
You can then plug your SD card or USB stick to your box and plug in power, enter U-Boot shell.
To boot from USB, try:
# usb start
# fatload usb 0 ${loadaddr} aml_autoscript
# autoscr ${loadaddr}
Or from SD, try:
# fatload mmc 0|1|2|3 ${loadaddr} aml_autoscript
# autoscr ${loadaddr}
This should eventually boot to Linux after a few errors. If it does not, and you're out of ideas, feel free to ask us in the IRC/Matrix channel!
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.