From 16fbd71384b8dae0ac2bc50cd8187277360f07aa Mon Sep 17 00:00:00 2001 From: pedrohrigolin Date: Thu, 12 Mar 2026 20:45:43 -0300 Subject: [PATCH 1/8] Add support for Amlogic s905x4 (HTV H8) Updated boot parameters in armbianEnv.txt: - Added earlycon=meson,0xfe07a000 for early serial debug console - Added console=ttyS0,921600n8 for proper serial communication at 921600 baud - Added watchdog.stop_on_reboot=0 to prevent reboot loops - Added pd_ignore_unused to preserve power domains - Added clk_ignore_unused to preserve clock domains - Added rootdelay=5 for proper FS mounting - Added bootlogo=false for cleaner boot output Tested on HTV H8 device running Armbian --- armbianEnv.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/armbianEnv.txt b/armbianEnv.txt index dfb3439..bbddae5 100644 --- a/armbianEnv.txt +++ b/armbianEnv.txt @@ -1,4 +1,4 @@ -extraargs=earlycon rootflags=data=writeback rw no_console_suspend consoleblank=0 fsck.fix=yes fsck.repair=yes net.ifnames=0 +extraargs=earlycon=meson,0xfe07a000 console=ttyS0,921600n8 rootflags=data=writeback rw no_console_suspend consoleblank=0 fsck.fix=yes fsck.repair=yes net.ifnames=0 watchdog.stop_on_reboot=0 pd_ignore_unused clk_ignore_unused rootdelay=5 bootlogo=false verbosity=7 usbstoragequirks=0x2537:0x1066:u,0x2537:0x1068:u From f3d0641ab9b5f2c589cfa30ffdcc8720f5dc236c Mon Sep 17 00:00:00 2001 From: pedrohrigolin Date: Thu, 12 Mar 2026 20:54:36 -0300 Subject: [PATCH 2/8] Update README: Add S905X4 to tested devices --- README.md | 6 +++--- armbianEnv.txt | 4 +--- 2 files changed, 4 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index f6d8dce..762c456 100644 --- a/README.md +++ b/README.md @@ -14,7 +14,7 @@ assumption: you have vendor u-boot (the one that came with the box) running on e + **Step 4:** If you have a GXBB (S905) or GXL (S905X/W/L) soc, you also need **[gxl-fixup.scr](https://github.com/devmfc/amlogic-bootscripts-Armbian/blob/main/gxl-fixup.scr)** + **Step 5:** Add an armbianEnv.txt file with the following content (file is also on github): ```bash -extraargs=earlycon rootflags=data=writeback rw no_console_suspend consoleblank=0 fsck.fix=yes fsck.repair=yes net.ifnames=0 +extraargs=earlycon=meson,0xfe07a000 console=ttyS0,921600n8 rootflags=data=writeback rw no_console_suspend consoleblank=0 fsck.fix=yes fsck.repair=yes net.ifnames=0 watchdog.stop_on_reboot=0 pd_ignore_unused clk_ignore_unused rootdelay=5 bootlogo=false verbosity=7 usbstoragequirks=0x2537:0x1066:u,0x2537:0x1068:u @@ -42,6 +42,6 @@ rootdev=UUID=92139c84-3871-41d7-a3f2-e8a943cbfa87 All used files and source files can be found on [Github](https://github.com/devmfc/amlogic-bootscripts-Armbian). -This is tested on S905X, S905W, S912, S905X2, S922X, S905X3 and they all boot the kernel. +This is tested on S905X, S905W, S912, S905X2, S922X, S905X3 and S905X4 (HTV H8) and they all boot the kernel. I did test S905 also, but it boots only the first time for some reason. -It will probably also work for S905X4 and S905W2, but did not test those. They are not supported by the Armbian kernel at this moment anyway. +It will probably also work for S905W2, but did not test that. They are not supported by the Armbian kernel at this moment anyway. diff --git a/armbianEnv.txt b/armbianEnv.txt index bbddae5..f9ff5db 100644 --- a/armbianEnv.txt +++ b/armbianEnv.txt @@ -14,6 +14,4 @@ fdtfile=amlogic/meson-sm1-x96-air-gbit.dtb #rootdev=LABEL=armbi_root # Enable ONLY for gxbb (S905) / gxl (S905X/L/W) to create fake u-boot header -#soc_fixup=gxl- - - +#soc_fixup=gxl- \ No newline at end of file From 1baa4715f5a82f3dc0956a5e0191c59946b06973 Mon Sep 17 00:00:00 2001 From: pedrohrigolin Date: Thu, 12 Mar 2026 22:09:02 -0300 Subject: [PATCH 3/8] Add bootcmd safety instructions with real-world examples --- README.md | 182 ++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 177 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 762c456..f0413a3 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,19 @@ # Amlogic boot scripts for Armbian +## Table of Contents +- [Overview](#overview) +- [Setup](#setup) +- [Supported Devices](#supported-devices) +- [Advanced - Bootloader Customization](#advanced---bootloader-customization) + +## Overview + The Armbian images for Amlogic TV Boxes use secondary, chain loaded u-boot blobs to boot mainline kernel images. The vendor u-boot bootloaders can however boot mainline Linux perfectly without them. So they are not needed. All it takes are some simple modifications of some of the Armbian u-boot scripts. -# Setup +## Setup assumption: you have vendor u-boot (the one that came with the box) running on eMMC. If you don't, you can just restore the stock Android image with Amlogic USB Burning tool. + **Step 1:** Download latest Armbian for s9xxx-box, let's use [bookworm minimal](https://dl.armbian.com/aml-s9xx-box/Bookworm_current_minimal) @@ -40,8 +48,172 @@ rootdev=UUID=92139c84-3871-41d7-a3f2-e8a943cbfa87 + **Step 12:** power up your box while holding the reset button for approx 7 seconds. + **Step 13:** If you're lucky, it will now boot Armbian with a mainline kernel. Without any secondary u-boot blobs. -All used files and source files can be found on [Github](https://github.com/devmfc/amlogic-bootscripts-Armbian). +## Supported Devices + +**✅ Fully Tested & Working:** +- S905X, S905W, S912, S905X2, S922X, S905X3, S905X4 (HTV H8) + +**⚠️ Partial Support:** +- S905: Boots only on first attempt (known limitation) + +**❓ Untested:** +- S905W2: Likely compatible but untested (not currently supported by Armbian kernel) + +All used files and source files can be found on [Github](https://github.com/devmfc/amlogic-bootscripts-Armbian). + +--- + +## Advanced - Bootloader Customization + +### ⚠️ Disclaimer & Prerequisites + +**DISCLAIMER:** Modifying your device's bootloader can result in a bricked device. Any damage or data loss is your sole responsibility. Proceed only if you understand the risks. + +**Required Prerequisites:** + +- **Functional ARM Linux System:** Armbian, Debian, or Ubuntu ARM running from USB/SD on your Amlogic device + - Necessary to access internal eMMC and run analysis/extraction commands + - System must boot correctly to provide shell access + +- **Serial TTL Adapter (3.3V UART):** High-quality USB serial adapter + - ⚠️ **CRITICAL:** Use 3.3V only. 5V will damage the device! + - Requires soldering skills to connect TX/RX/GND to the board -This is tested on S905X, S905W, S912, S905X2, S922X, S905X3 and S905X4 (HTV H8) and they all boot the kernel. -I did test S905 also, but it boots only the first time for some reason. -It will probably also work for S905W2, but did not test that. They are not supported by the Armbian kernel at this moment anyway. +- **Serial Terminal Software:** PuTTY, Minicom, or picocom + +- **Patience & Methodology:** Follow each step carefully + +### 🔒 Mandatory: Backup Your eMMC + +Before ANY experiment, create a complete backup: + +```bash +# Bit-by-bit backup with compression (saves space) +sudo dd if=/dev/mmcblkX bs=1M status=progress | gzip -c > backup_emmc_full.img.gz + +# To restore in case of disaster: +# gunzip -c backup_emmc_full.img.gz | sudo dd of=/dev/mmcblkX bs=1M status=progress +``` + +Why gzip? A 16GB backup becomes 2-4GB, saving significant space. + +### Checking Vendor Bootloader Support + +#### Step 1: Connect Serial Cable +Solder TX, RX, GND to your device's UART pads and connect to your PC. + +#### Step 2: Open Serial Console +Using picocom as example: + +```bash +# Find your serial device +ls -la /dev/ttyUSB* + +# Connect at 115200 baud (adjust if different) +picocom -b 115200 /dev/ttyUSB0 + +# Or with minicom: +minicom -D /dev/ttyUSB0 -b 115200 +``` + +#### Step 3: Interrupt U-Boot +Power on the device and quickly press `Ctrl+C` or `Enter` to interrupt U-Boot before it boots. + +#### Step 4: Check Bootloader Variables +Once in U-Boot console, type: + +```bash +printenv bootcmd +``` + +Expected output should be similar to: +``` +bootcmd=run start_autoscript; run storeboot +``` + +Check for related variables: +```bash +printenv start_usb_autoscript +printenv start_mmc_autoscript +printenv start_emmc_autoscript +``` + +**Note:** Variable names may differ slightly. Look for patterns like `start_*_autoscript`. + +### Modifying Vendor Bootloader (Advanced Users Only) + +If your bootloader is writable and you want to force script support, execute these commands in U-Boot console: + +```bash +setenv start_autoscript 'if mmcinfo; then run start_mmc_autoscript; fi; if usb start; then run start_usb_autoscript; fi; run start_emmc_autoscript' +setenv start_emmc_autoscript 'if fatload mmc 1 1020000 emmc_autoscript; then setenv devtype "mmc"; setenv devnum 1; autoscr 1020000; fi;' +setenv start_mmc_autoscript 'if fatload mmc 0 1020000 s905_autoscript; then setenv devtype "mmc"; setenv devnum 0; autoscr 1020000; fi;' +setenv start_usb_autoscript 'for usbdev in 0 1 2 3; do if fatload usb ${usbdev} 1020000 s905_autoscript; then setenv devtype "usb"; setenv devnum 0; autoscr 1020000; fi; done' +setenv bootdelay 1 +``` + +#### ⚠️ CRITICAL: Setting bootcmd - Preserve Your Original Command + +**DO NOT simply use `run start_autoscript; run storeboot`** - This is generic and may brick your device if your original bootcmd was different! + +**Step-by-step approach:** + +1. **First, WRITE DOWN your original bootcmd:** + ```bash + printenv bootcmd + # Write down the EXACT output here: + # _________________________________ + ``` + +2. **Then set bootcmd to preserve it:** + ```bash + setenv bootcmd 'run start_autoscript; [PASTE YOUR ORIGINAL BOOTCMD HERE]' + ``` + +**Examples from real devices:** + +**Example 1 - Generic Amlogic Box:** +```bash +# Original was: +# bootcmd=run storeboot + +# So you do: +setenv bootcmd 'run start_autoscript; run storeboot' +``` + +**Example 2 - Different Vendor (HTV H8):** +```bash +# Original was: +# bootcmd=run start_emmc_autoscript; run storeboot + +# So you do: +setenv bootcmd 'run start_autoscript; run start_emmc_autoscript; run storeboot' +``` + +**Example 3 - Complex Bootcmd:** +```bash +# Original was: +# bootcmd=if test -n ${upgrade_step}; then echo BOOT_STEP equals $upgrade_step; setenv upgrade_step; fi; run storeboot + +# So you do: +setenv bootcmd 'run start_autoscript; if test -n ${upgrade_step}; then echo BOOT_STEP equals $upgrade_step; setenv upgrade_step; fi; run storeboot' +``` + +#### Final step - Save & Verify Changes + +```bash +saveenv +reset +``` + +Interrupt U-Boot again and verify variables were saved: + +```bash +printenv bootcmd +``` + +**Success indicators:** +- Variables were saved → Bootloader is writable and modifications should work +- Variables weren't saved → Read-only bootloader; cannot apply this method + +--- From 286706e10c8ef5b438fbd42d0a61e844187eb58e Mon Sep 17 00:00:00 2001 From: pedrohrigolin Date: Thu, 12 Mar 2026 22:19:52 -0300 Subject: [PATCH 4/8] Fix: Change 'Caixas de TV' to 'TV Boxes' (not translated) --- README.md | 190 +++++++++++++++++++++++++++--------------------------- 1 file changed, 96 insertions(+), 94 deletions(-) diff --git a/README.md b/README.md index f0413a3..7a60b75 100644 --- a/README.md +++ b/README.md @@ -1,26 +1,28 @@ -# Amlogic boot scripts for Armbian +# Scripts de Boot do Amlogic para Armbian -## Table of Contents -- [Overview](#overview) -- [Setup](#setup) -- [Supported Devices](#supported-devices) -- [Advanced - Bootloader Customization](#advanced---bootloader-customization) +**Language / Idioma:** [🟢 Português](README.md) | [English](README.en.md) -## Overview +## Índice +- [Visão Geral](#visão-geral) +- [Configuração](#configuração) +- [Dispositivos Suportados](#dispositivos-suportados) +- [Avançado - Personalização do Bootloader](#avançado---personalização-do-bootloader) -The Armbian images for Amlogic TV Boxes use secondary, chain loaded u-boot blobs to boot mainline kernel images. -The vendor u-boot bootloaders can however boot mainline Linux perfectly without them. So they are not needed. +## Visão Geral -All it takes are some simple modifications of some of the Armbian u-boot scripts. +As imagens do Armbian para TV Boxes Amlogic usam blobs secundários de u-boot carregados em cadeia para inicializar imagens do kernel mainline. +Os bootloaders u-boot do fabricante, no entanto, podem inicializar o Linux mainline perfeitamente sem eles. Portanto, eles não são necessários. -## Setup -assumption: you have vendor u-boot (the one that came with the box) running on eMMC. If you don't, you can just restore the stock Android image with Amlogic USB Burning tool. +Tudo o que é necessário são algumas modificações simples em alguns dos scripts u-boot do Armbian. -+ **Step 1:** Download latest Armbian for s9xxx-box, let's use [bookworm minimal](https://dl.armbian.com/aml-s9xx-box/Bookworm_current_minimal) -+ **Step 2:** Burn the image to a USB flash drive -+ **Step 3:** Copy the modified boot scripts (**[aml_autoscript](https://github.com/devmfc/amlogic-bootscripts-Armbian/blob/main/aml_autoscript)**, **[s905_autoscript](https://github.com/devmfc/amlogic-bootscripts-Armbian/blob/main/s905_autoscript)**, **[emmc_autoscript](https://github.com/devmfc/amlogic-bootscripts-Armbian/blob/main/emmc_autoscript)** ) to the fat partition on the USB drive. Overwrite the existing files. -+ **Step 4:** If you have a GXBB (S905) or GXL (S905X/W/L) soc, you also need **[gxl-fixup.scr](https://github.com/devmfc/amlogic-bootscripts-Armbian/blob/main/gxl-fixup.scr)** -+ **Step 5:** Add an armbianEnv.txt file with the following content (file is also on github): +## Configuração +Pressuposição: você tem o u-boot do fabricante (o que veio com a box) rodando na eMMC. Se não, você pode restaurar a imagem Android original com a ferramenta Amlogic USB Burning. + ++ **Passo 1:** Baixe a versão mais recente do Armbian para s9xxx-box, vamos usar [bookworm minimal](https://dl.armbian.com/aml-s9xx-box/Bookworm_current_minimal) ++ **Passo 2:** Grave a imagem em um pendrive USB ++ **Passo 3:** Copie os scripts de boot modificados (**[aml_autoscript](https://github.com/projetotvbox/amlogic-bootscripts-Armbian/blob/main/aml_autoscript)**, **[s905_autoscript](https://github.com/projetotvbox/amlogic-bootscripts-Armbian/blob/main/s905_autoscript)**, **[emmc_autoscript](https://github.com/projetotvbox/amlogic-bootscripts-Armbian/blob/main/emmc_autoscript)** ) para a partição FAT no pendrive. Sobrescreva os arquivos existentes. ++ **Passo 4:** Se você tem um SoC GXBB (S905) ou GXL (S905X/W/L), você também precisa de **[gxl-fixup.scr](https://github.com/projetotvbox/amlogic-bootscripts-Armbian/blob/main/gxl-fixup.scr)** ++ **Passo 5:** Adicione um arquivo armbianEnv.txt com o seguinte conteúdo (o arquivo também está no github): ```bash extraargs=earlycon=meson,0xfe07a000 console=ttyS0,921600n8 rootflags=data=writeback rw no_console_suspend consoleblank=0 fsck.fix=yes fsck.repair=yes net.ifnames=0 watchdog.stop_on_reboot=0 pd_ignore_unused clk_ignore_unused rootdelay=5 bootlogo=false @@ -28,121 +30,121 @@ verbosity=7 usbstoragequirks=0x2537:0x1066:u,0x2537:0x1068:u console=both -# DTB file for this tvbox +# Arquivo DTB para este TV Box # fdtfile=amlogic/meson-gxl-s905x-nexbox-a95x.dtb fdtfile=amlogic/meson-sm1-x96-air-gbit.dtb -# set this to the UUID of the root partition (value can be found -# in /extlinux/extlinux.conf after APPEND root= or with blkid) +# defina isto para o UUID da partição raiz (o valor pode ser encontrado +# em /extlinux/extlinux.conf depois de APPEND root= ou com blkid) rootdev=UUID=92139c84-3871-41d7-a3f2-e8a943cbfa87 -# Enable ONLY for gxbb (S905) / gxl (S905X/L/W) to create fake u-boot header +# Ativar APENAS para gxbb (S905) / gxl (S905X/L/W) para criar cabeçalho u-boot falso #soc_fixup=gxl- ``` -+ **Step 6:** Change *fdtfile* to the DTB for your box. -+ **Step 7:** (optional since version 3:) Change *rootdev* to the right UUID for the rootfs for your image or change to /dev/sda2 when booting from USB or /dev/mmcblk0p2 when booting from SDCARD -+ **Step 8:** Only if your box has a GXBB (S905) or GXL (S905X/W/L) soc, uncomment the line *soc_fixup=gxl-* -+ **Step 9:** Power off the the box. -+ **Step 10:** Put the USB disk in your box. -+ **Step 11:** Push the reset button and hold the button -+ **Step 12:** power up your box while holding the reset button for approx 7 seconds. -+ **Step 13:** If you're lucky, it will now boot Armbian with a mainline kernel. Without any secondary u-boot blobs. - -## Supported Devices - -**✅ Fully Tested & Working:** ++ **Passo 6:** Altere *fdtfile* para o DTB da sua box. ++ **Passo 7:** (opcional desde a versão 3:) Altere *rootdev* para o UUID correto do rootfs para sua imagem ou mude para /dev/sda2 quando inicializar do USB ou /dev/mmcblk0p2 quando inicializar do SDCARD ++ **Passo 8:** Apenas se sua box tiver um SoC GXBB (S905) ou GXL (S905X/W/L), descomente a linha *soc_fixup=gxl-* ++ **Passo 9:** Desligue a box. ++ **Passo 10:** Coloque o disco USB na sua box. ++ **Passo 11:** Pressione o botão reset e mantenha pressionado ++ **Passo 12:** Ligue a box enquanto mantém o botão reset pressionado por aproximadamente 7 segundos. ++ **Passo 13:** Se você tiver sorte, agora ele inicializará o Armbian com um kernel mainline. Sem nenhum blob u-boot secundário. + +## Dispositivos Suportados + +**✅ Totalmente Testado e Funcionando:** - S905X, S905W, S912, S905X2, S922X, S905X3, S905X4 (HTV H8) -**⚠️ Partial Support:** -- S905: Boots only on first attempt (known limitation) +**⚠️ Suporte Parcial:** +- S905: Inicia apenas na primeira tentativa (limitação conhecida) -**❓ Untested:** -- S905W2: Likely compatible but untested (not currently supported by Armbian kernel) +**❓ Não Testado:** +- S905W2: Provavelmente compatível mas não testado (não suportado atualmente pelo kernel do Armbian) -All used files and source files can be found on [Github](https://github.com/devmfc/amlogic-bootscripts-Armbian). +Todos os arquivos usados e arquivos de origem podem ser encontrados no [Github](https://github.com/projetotvbox/amlogic-bootscripts-Armbian). --- -## Advanced - Bootloader Customization +## Avançado - Personalização do Bootloader -### ⚠️ Disclaimer & Prerequisites +### ⚠️ Aviso Legal & Pré-requisitos -**DISCLAIMER:** Modifying your device's bootloader can result in a bricked device. Any damage or data loss is your sole responsibility. Proceed only if you understand the risks. +**AVISO:** Modificar o bootloader do seu dispositivo pode resultar em um dispositivo travado (brick). Qualquer dano ou perda de dados é de sua responsabilidade exclusiva. Proceda apenas se entender os riscos. -**Required Prerequisites:** +**Pré-requisitos Obrigatórios:** -- **Functional ARM Linux System:** Armbian, Debian, or Ubuntu ARM running from USB/SD on your Amlogic device - - Necessary to access internal eMMC and run analysis/extraction commands - - System must boot correctly to provide shell access +- **Sistema ARM Linux Funcional:** Armbian, Debian ou Ubuntu ARM rodando a partir de USB/SD no seu dispositivo Amlogic + - Necessário para acessar a eMMC interna e executar comandos de análise/extração + - O sistema deve inicializar corretamente para fornecer acesso shell -- **Serial TTL Adapter (3.3V UART):** High-quality USB serial adapter - - ⚠️ **CRITICAL:** Use 3.3V only. 5V will damage the device! - - Requires soldering skills to connect TX/RX/GND to the board +- **Adaptador Serial TTL (3.3V UART):** Adaptador série USB de alta qualidade + - ⚠️ **CRÍTICO:** Use apenas 3.3V. 5V danificará o dispositivo! + - Requer habilidades de soldagem para conectar TX/RX/GND na placa -- **Serial Terminal Software:** PuTTY, Minicom, or picocom +- **Software de Terminal Serial:** PuTTY, Minicom ou picocom -- **Patience & Methodology:** Follow each step carefully +- **Paciência e Metodologia:** Siga cada passo cuidadosamente -### 🔒 Mandatory: Backup Your eMMC +### 🔒 Obrigatório: Faça Backup da sua eMMC -Before ANY experiment, create a complete backup: +Antes de QUALQUER experimento, crie um backup completo: ```bash -# Bit-by-bit backup with compression (saves space) +# Backup bit-a-bit com compressão (economiza espaço) sudo dd if=/dev/mmcblkX bs=1M status=progress | gzip -c > backup_emmc_full.img.gz -# To restore in case of disaster: +# Para restaurar em caso de desastre: # gunzip -c backup_emmc_full.img.gz | sudo dd of=/dev/mmcblkX bs=1M status=progress ``` -Why gzip? A 16GB backup becomes 2-4GB, saving significant space. +Por que gzip? Um backup de 16GB se torna 2-4GB, economizando espaço significativo. -### Checking Vendor Bootloader Support +### Verificando o Suporte do Bootloader do Fabricante -#### Step 1: Connect Serial Cable -Solder TX, RX, GND to your device's UART pads and connect to your PC. +#### Passo 1: Conectar Cabo Serial +Solde TX, RX, GND nos pads UART do seu dispositivo e conecte ao seu PC. -#### Step 2: Open Serial Console -Using picocom as example: +#### Passo 2: Abrir Console Serial +Usando picocom como exemplo: ```bash -# Find your serial device +# Encontre seu dispositivo serial ls -la /dev/ttyUSB* -# Connect at 115200 baud (adjust if different) +# Conecte a 115200 baud (ajuste se diferente) picocom -b 115200 /dev/ttyUSB0 -# Or with minicom: +# Ou com minicom: minicom -D /dev/ttyUSB0 -b 115200 ``` -#### Step 3: Interrupt U-Boot -Power on the device and quickly press `Ctrl+C` or `Enter` to interrupt U-Boot before it boots. +#### Passo 3: Interromper U-Boot +Ligue o dispositivo e pressione rapidamente `Ctrl+C` ou `Enter` para interromper o U-Boot antes de inicializar. -#### Step 4: Check Bootloader Variables -Once in U-Boot console, type: +#### Passo 4: Verificar Variáveis do Bootloader +Uma vez no console do U-Boot, digite: ```bash printenv bootcmd ``` -Expected output should be similar to: +A saída esperada deve ser semelhante a: ``` bootcmd=run start_autoscript; run storeboot ``` -Check for related variables: +Verifique as variáveis relacionadas: ```bash printenv start_usb_autoscript printenv start_mmc_autoscript printenv start_emmc_autoscript ``` -**Note:** Variable names may differ slightly. Look for patterns like `start_*_autoscript`. +**Nota:** Os nomes das variáveis podem ser ligeiramente diferentes. Procure por padrões como `start_*_autoscript`. -### Modifying Vendor Bootloader (Advanced Users Only) +### Modificando Bootloader do Fabricante (Apenas Usuários Avançados) -If your bootloader is writable and you want to force script support, execute these commands in U-Boot console: +Se seu bootloader é gravável e você quer forçar o suporte a scripts, execute esses comandos no console do U-Boot: ```bash setenv start_autoscript 'if mmcinfo; then run start_mmc_autoscript; fi; if usb start; then run start_usb_autoscript; fi; run start_emmc_autoscript' @@ -152,68 +154,68 @@ setenv start_usb_autoscript 'for usbdev in 0 1 2 3; do if fatload usb ${usbdev} setenv bootdelay 1 ``` -#### ⚠️ CRITICAL: Setting bootcmd - Preserve Your Original Command +#### ⚠️ CRÍTICO: Configurando bootcmd - Preserve Seu Comando Original -**DO NOT simply use `run start_autoscript; run storeboot`** - This is generic and may brick your device if your original bootcmd was different! +**NÃO use simplesmente `run start_autoscript; run storeboot`** - Isto é genérico e pode danificar seu dispositivo se seu bootcmd original foi diferente! -**Step-by-step approach:** +**Abordagem passo-a-passo:** -1. **First, WRITE DOWN your original bootcmd:** +1. **Primeiro, ANOTE seu bootcmd original:** ```bash printenv bootcmd - # Write down the EXACT output here: + # Anote a saída EXATA aqui: # _________________________________ ``` -2. **Then set bootcmd to preserve it:** +2. **Então configure bootcmd para preservá-lo:** ```bash - setenv bootcmd 'run start_autoscript; [PASTE YOUR ORIGINAL BOOTCMD HERE]' + setenv bootcmd 'run start_autoscript; [COLE SEU BOOTCMD ORIGINAL AQUI]' ``` -**Examples from real devices:** +**Exemplos de dispositivos reais:** -**Example 1 - Generic Amlogic Box:** +**Exemplo 1 - Box Amlogic Genérica:** ```bash -# Original was: +# Original era: # bootcmd=run storeboot -# So you do: +# Então você faz: setenv bootcmd 'run start_autoscript; run storeboot' ``` -**Example 2 - Different Vendor (HTV H8):** +**Exemplo 2 - Fabricante Diferente (HTV H8):** ```bash -# Original was: +# Original era: # bootcmd=run start_emmc_autoscript; run storeboot -# So you do: +# Então você faz: setenv bootcmd 'run start_autoscript; run start_emmc_autoscript; run storeboot' ``` -**Example 3 - Complex Bootcmd:** +**Exemplo 3 - Bootcmd Complexo:** ```bash -# Original was: +# Original era: # bootcmd=if test -n ${upgrade_step}; then echo BOOT_STEP equals $upgrade_step; setenv upgrade_step; fi; run storeboot -# So you do: +# Então você faz: setenv bootcmd 'run start_autoscript; if test -n ${upgrade_step}; then echo BOOT_STEP equals $upgrade_step; setenv upgrade_step; fi; run storeboot' ``` -#### Final step - Save & Verify Changes +#### Passo Final - Salve e Verifique as Alterações ```bash saveenv reset ``` -Interrupt U-Boot again and verify variables were saved: +Interrompa o U-Boot novamente e verifique se as variáveis foram salvas: ```bash printenv bootcmd ``` -**Success indicators:** -- Variables were saved → Bootloader is writable and modifications should work -- Variables weren't saved → Read-only bootloader; cannot apply this method +**Indicadores de Sucesso:** +- Variáveis foram salvas → Bootloader é gravável e as modificações devem funcionar +- Variáveis não foram salvas → Bootloader somente leitura; não é possível aplicar este método --- From d20fc049a5b55cbfb35cc37362c757f46d8204ab Mon Sep 17 00:00:00 2001 From: pedrohrigolin Date: Thu, 12 Mar 2026 22:20:28 -0300 Subject: [PATCH 5/8] Add multilingual support: English version (README.en.md) --- README.en.md | 221 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 221 insertions(+) create mode 100644 README.en.md diff --git a/README.en.md b/README.en.md new file mode 100644 index 0000000..c6dd6b6 --- /dev/null +++ b/README.en.md @@ -0,0 +1,221 @@ +# Amlogic boot scripts for Armbian + +**Language / Idioma:** [English](README.en.md) | [🟢 Português](README.md) + +## Table of Contents +- [Overview](#overview) +- [Setup](#setup) +- [Supported Devices](#supported-devices) +- [Advanced - Bootloader Customization](#advanced---bootloader-customization) + +## Overview + +The Armbian images for Amlogic TV Boxes use secondary, chain loaded u-boot blobs to boot mainline kernel images. +The vendor u-boot bootloaders can however boot mainline Linux perfectly without them. So they are not needed. + +All it takes are some simple modifications of some of the Armbian u-boot scripts. + +## Setup +assumption: you have vendor u-boot (the one that came with the box) running on eMMC. If you don't, you can just restore the stock Android image with Amlogic USB Burning tool. + ++ **Step 1:** Download latest Armbian for s9xxx-box, let's use [bookworm minimal](https://dl.armbian.com/aml-s9xx-box/Bookworm_current_minimal) ++ **Step 2:** Burn the image to a USB flash drive ++ **Step 3:** Copy the modified boot scripts (**[aml_autoscript](https://github.com/projetotvbox/amlogic-bootscripts-Armbian/blob/main/aml_autoscript)**, **[s905_autoscript](https://github.com/projetotvbox/amlogic-bootscripts-Armbian/blob/main/s905_autoscript)**, **[emmc_autoscript](https://github.com/projetotvbox/amlogic-bootscripts-Armbian/blob/main/emmc_autoscript)** ) to the fat partition on the USB drive. Overwrite the existing files. ++ **Step 4:** If you have a GXBB (S905) or GXL (S905X/W/L) soc, you also need **[gxl-fixup.scr](https://github.com/projetotvbox/amlogic-bootscripts-Armbian/blob/main/gxl-fixup.scr)** ++ **Step 5:** Add an armbianEnv.txt file with the following content (file is also on github): +```bash +extraargs=earlycon=meson,0xfe07a000 console=ttyS0,921600n8 rootflags=data=writeback rw no_console_suspend consoleblank=0 fsck.fix=yes fsck.repair=yes net.ifnames=0 watchdog.stop_on_reboot=0 pd_ignore_unused clk_ignore_unused rootdelay=5 +bootlogo=false +verbosity=7 +usbstoragequirks=0x2537:0x1066:u,0x2537:0x1068:u +console=both + +# DTB file for this tvbox +# fdtfile=amlogic/meson-gxl-s905x-nexbox-a95x.dtb +fdtfile=amlogic/meson-sm1-x96-air-gbit.dtb + +# set this to the UUID of the root partition (value can be found +# in /extlinux/extlinux.conf after APPEND root= or with blkid) +rootdev=UUID=92139c84-3871-41d7-a3f2-e8a943cbfa87 + +# Enable ONLY for gxbb (S905) / gxl (S905X/L/W) to create fake u-boot header +#soc_fixup=gxl- +``` ++ **Step 6:** Change *fdtfile* to the DTB for your box. ++ **Step 7:** (optional since version 3:) Change *rootdev* to the right UUID for the rootfs for your image or change to /dev/sda2 when booting from USB or /dev/mmcblk0p2 when booting from SDCARD ++ **Step 8:** Only if your box has a GXBB (S905) or GXL (S905X/W/L) soc, uncomment the line *soc_fixup=gxl-* ++ **Step 9:** Power off the the box. ++ **Step 10:** Put the USB disk in your box. ++ **Step 11:** Push the reset button and hold the button ++ **Step 12:** power up your box while holding the reset button for approx 7 seconds. ++ **Step 13:** If you're lucky, it will now boot Armbian with a mainline kernel. Without any secondary u-boot blobs. + +## Supported Devices + +**✅ Fully Tested & Working:** +- S905X, S905W, S912, S905X2, S922X, S905X3, S905X4 (HTV H8) + +**⚠️ Partial Support:** +- S905: Boots only on first attempt (known limitation) + +**❓ Untested:** +- S905W2: Likely compatible but untested (not currently supported by Armbian kernel) + +All used files and source files can be found on [Github](https://github.com/projetotvbox/amlogic-bootscripts-Armbian). + +--- + +## Advanced - Bootloader Customization + +### ⚠️ Disclaimer & Prerequisites + +**DISCLAIMER:** Modifying your device's bootloader can result in a bricked device. Any damage or data loss is your sole responsibility. Proceed only if you understand the risks. + +**Required Prerequisites:** + +- **Functional ARM Linux System:** Armbian, Debian, or Ubuntu ARM running from USB/SD on your Amlogic device + - Necessary to access internal eMMC and run analysis/extraction commands + - System must boot correctly to provide shell access + +- **Serial TTL Adapter (3.3V UART):** High-quality USB serial adapter + - ⚠️ **CRITICAL:** Use 3.3V only. 5V will damage the device! + - Requires soldering skills to connect TX/RX/GND to the board + +- **Serial Terminal Software:** PuTTY, Minicom, or picocom + +- **Patience & Methodology:** Follow each step carefully + +### 🔒 Mandatory: Backup Your eMMC + +Before ANY experiment, create a complete backup: + +```bash +# Bit-by-bit backup with compression (saves space) +sudo dd if=/dev/mmcblkX bs=1M status=progress | gzip -c > backup_emmc_full.img.gz + +# To restore in case of disaster: +# gunzip -c backup_emmc_full.img.gz | sudo dd of=/dev/mmcblkX bs=1M status=progress +``` + +Why gzip? A 16GB backup becomes 2-4GB, saving significant space. + +### Checking Vendor Bootloader Support + +#### Step 1: Connect Serial Cable +Solder TX, RX, GND to your device's UART pads and connect to your PC. + +#### Step 2: Open Serial Console +Using picocom as example: + +```bash +# Find your serial device +ls -la /dev/ttyUSB* + +# Connect at 115200 baud (adjust if different) +picocom -b 115200 /dev/ttyUSB0 + +# Or with minicom: +minicom -D /dev/ttyUSB0 -b 115200 +``` + +#### Step 3: Interrupt U-Boot +Power on the device and quickly press `Ctrl+C` or `Enter` to interrupt U-Boot before it boots. + +#### Step 4: Check Bootloader Variables +Once in U-Boot console, type: + +```bash +printenv bootcmd +``` + +Expected output should be similar to: +``` +bootcmd=run start_autoscript; run storeboot +``` + +Check for related variables: +```bash +printenv start_usb_autoscript +printenv start_mmc_autoscript +printenv start_emmc_autoscript +``` + +**Note:** Variable names may differ slightly. Look for patterns like `start_*_autoscript`. + +### Modifying Vendor Bootloader (Advanced Users Only) + +If your bootloader is writable and you want to force script support, execute these commands in U-Boot console: + +```bash +setenv start_autoscript 'if mmcinfo; then run start_mmc_autoscript; fi; if usb start; then run start_usb_autoscript; fi; run start_emmc_autoscript' +setenv start_emmc_autoscript 'if fatload mmc 1 1020000 emmc_autoscript; then setenv devtype "mmc"; setenv devnum 1; autoscr 1020000; fi;' +setenv start_mmc_autoscript 'if fatload mmc 0 1020000 s905_autoscript; then setenv devtype "mmc"; setenv devnum 0; autoscr 1020000; fi;' +setenv start_usb_autoscript 'for usbdev in 0 1 2 3; do if fatload usb ${usbdev} 1020000 s905_autoscript; then setenv devtype "usb"; setenv devnum 0; autoscr 1020000; fi; done' +setenv bootdelay 1 +``` + +#### ⚠️ CRITICAL: Setting bootcmd - Preserve Your Original Command + +**DO NOT simply use `run start_autoscript; run storeboot`** - This is generic and may brick your device if your original bootcmd was different! + +**Step-by-step approach:** + +1. **First, WRITE DOWN your original bootcmd:** + ```bash + printenv bootcmd + # Write down the EXACT output here: + # _________________________________ + ``` + +2. **Then set bootcmd to preserve it:** + ```bash + setenv bootcmd 'run start_autoscript; [PASTE YOUR ORIGINAL BOOTCMD HERE]' + ``` + +**Examples from real devices:** + +**Example 1 - Generic Amlogic Box:** +```bash +# Original was: +# bootcmd=run storeboot + +# So you do: +setenv bootcmd 'run start_autoscript; run storeboot' +``` + +**Example 2 - Different Vendor (HTV H8):** +```bash +# Original was: +# bootcmd=run start_emmc_autoscript; run storeboot + +# So you do: +setenv bootcmd 'run start_autoscript; run start_emmc_autoscript; run storeboot' +``` + +**Example 3 - Complex Bootcmd:** +```bash +# Original was: +# bootcmd=if test -n ${upgrade_step}; then echo BOOT_STEP equals $upgrade_step; setenv upgrade_step; fi; run storeboot + +# So you do: +setenv bootcmd 'run start_autoscript; if test -n ${upgrade_step}; then echo BOOT_STEP equals $upgrade_step; setenv upgrade_step; fi; run storeboot' +``` + +#### Final step - Save & Verify Changes + +```bash +saveenv +reset +``` + +Interrupt U-Boot again and verify variables were saved: + +```bash +printenv bootcmd +``` + +**Success indicators:** +- Variables were saved → Bootloader is writable and modifications should work +- Variables weren't saved → Read-only bootloader; cannot apply this method + +--- From 13be5a804d9a9e9e2c23e4683102d612bbd233c9 Mon Sep 17 00:00:00 2001 From: pedrohrigolin Date: Sun, 15 Mar 2026 17:17:56 -0300 Subject: [PATCH 6/8] fix readme --- README.en.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.en.md b/README.en.md index c6dd6b6..14bbb48 100644 --- a/README.en.md +++ b/README.en.md @@ -1,6 +1,6 @@ # Amlogic boot scripts for Armbian -**Language / Idioma:** [English](README.en.md) | [🟢 Português](README.md) +**Language / Idioma:** [🟢 English](README.en.md) | [Português](README.md) ## Table of Contents - [Overview](#overview) From d3a16776c8e88fb07dcf9ff153d278f6cf8c8d07 Mon Sep 17 00:00:00 2001 From: pedrohrigolin Date: Thu, 4 Jun 2026 16:58:21 -0300 Subject: [PATCH 7/8] update readme --- README.en.md | 11 +++++++++++ README.md | 11 +++++++++++ 2 files changed, 22 insertions(+) diff --git a/README.en.md b/README.en.md index 14bbb48..6646c3d 100644 --- a/README.en.md +++ b/README.en.md @@ -41,6 +41,17 @@ rootdev=UUID=92139c84-3871-41d7-a3f2-e8a943cbfa87 # Enable ONLY for gxbb (S905) / gxl (S905X/L/W) to create fake u-boot header #soc_fixup=gxl- ``` +> ⚠️ **Note: the `armbianEnv.txt` above is a starting point, not a universal configuration.** +> +> The file provided works for many devices, but it may not work out of the box for yours. Different TV boxes, SoCs, and Armbian versions may require different parameters — especially the `extraargs` line. +> +> **Before replacing the file**, compare it against the original `armbianEnv.txt` that comes with the Armbian image and merge carefully. Key things to watch for: +> - Parameters present in the original that are absent here may be required for your specific hardware. +> - The `extraargs` line varies the most between SoCs and may need to be adapted or extended. +> - When in doubt, start from the original file and apply only the changes you understand. +> +> If the system fails to boot, restoring the original `armbianEnv.txt` is usually the first step to diagnose the issue. + + **Step 6:** Change *fdtfile* to the DTB for your box. + **Step 7:** (optional since version 3:) Change *rootdev* to the right UUID for the rootfs for your image or change to /dev/sda2 when booting from USB or /dev/mmcblk0p2 when booting from SDCARD + **Step 8:** Only if your box has a GXBB (S905) or GXL (S905X/W/L) soc, uncomment the line *soc_fixup=gxl-* diff --git a/README.md b/README.md index 7a60b75..a04e803 100644 --- a/README.md +++ b/README.md @@ -41,6 +41,17 @@ rootdev=UUID=92139c84-3871-41d7-a3f2-e8a943cbfa87 # Ativar APENAS para gxbb (S905) / gxl (S905X/L/W) para criar cabeçalho u-boot falso #soc_fixup=gxl- ``` +> ⚠️ **Atenção: o `armbianEnv.txt` acima é um ponto de partida, não uma configuração universal.** +> +> O arquivo fornecido funciona para muitos dispositivos, mas não necessariamente para o seu. Diferentes boxes, SoCs e versões do Armbian podem exigir parâmetros distintos — especialmente na linha `extraargs`. +> +> **Antes de substituir o arquivo**, compare-o com o `armbianEnv.txt` original que vem na imagem do Armbian e mescle com cuidado. Pontos de atenção: +> - Parâmetros presentes no original que estão ausentes aqui podem ser necessários para o seu hardware. +> - A linha `extraargs` é a que mais varia entre SoCs e pode precisar de adaptação. +> - Em caso de dúvida, parta do arquivo original e aplique apenas as alterações que você compreende. +> +> Se o sistema não inicializar, restaurar o `armbianEnv.txt` original é geralmente o primeiro passo para diagnosticar o problema. + + **Passo 6:** Altere *fdtfile* para o DTB da sua box. + **Passo 7:** (opcional desde a versão 3:) Altere *rootdev* para o UUID correto do rootfs para sua imagem ou mude para /dev/sda2 quando inicializar do USB ou /dev/mmcblk0p2 quando inicializar do SDCARD + **Passo 8:** Apenas se sua box tiver um SoC GXBB (S905) ou GXL (S905X/W/L), descomente a linha *soc_fixup=gxl-* From 2b22a28c1dcb07eb4cafe572397092eaf56ef9d1 Mon Sep 17 00:00:00 2001 From: pedrohrigolin Date: Fri, 5 Jun 2026 21:14:50 -0300 Subject: [PATCH 8/8] update readme and armbianEnv.txt --- README.en.md | 305 +++++++++++++++++++++++++++++++----------------- README.md | 307 ++++++++++++++++++++++++++++++++----------------- armbianEnv.txt | 4 +- 3 files changed, 405 insertions(+), 211 deletions(-) diff --git a/README.en.md b/README.en.md index 6646c3d..b3bf734 100644 --- a/README.en.md +++ b/README.en.md @@ -1,4 +1,4 @@ -# Amlogic boot scripts for Armbian +# Amlogic Boot Scripts for Armbian **Language / Idioma:** [🟢 English](README.en.md) | [Português](README.md) @@ -6,23 +6,78 @@ - [Overview](#overview) - [Setup](#setup) - [Supported Devices](#supported-devices) -- [Advanced - Bootloader Customization](#advanced---bootloader-customization) +- [Advanced Troubleshooting — Bootloader Modification](#advanced-troubleshooting--bootloader-modification) +- [How It Works Internally](#how-it-works-internally) + +--- ## Overview -The Armbian images for Amlogic TV Boxes use secondary, chain loaded u-boot blobs to boot mainline kernel images. -The vendor u-boot bootloaders can however boot mainline Linux perfectly without them. So they are not needed. +Armbian images for Amlogic TV Boxes normally rely on secondary u-boot blobs to boot the mainline kernel. In practice, these are unnecessary: the factory u-boot that came with your box is already capable of doing this on its own. All it takes are a few modifications to the Armbian boot scripts. + +> **Prerequisite:** the vendor u-boot must be running on eMMC. If your box was reflashed with a different bootloader, restore the stock Android image using the [Amlogic USB Burning Tool](https://androidmtk.com/download-amlogic-usb-burning-tool) before continuing. -All it takes are some simple modifications of some of the Armbian u-boot scripts. +--- ## Setup -assumption: you have vendor u-boot (the one that came with the box) running on eMMC. If you don't, you can just restore the stock Android image with Amlogic USB Burning tool. -+ **Step 1:** Download latest Armbian for s9xxx-box, let's use [bookworm minimal](https://dl.armbian.com/aml-s9xx-box/Bookworm_current_minimal) -+ **Step 2:** Burn the image to a USB flash drive -+ **Step 3:** Copy the modified boot scripts (**[aml_autoscript](https://github.com/projetotvbox/amlogic-bootscripts-Armbian/blob/main/aml_autoscript)**, **[s905_autoscript](https://github.com/projetotvbox/amlogic-bootscripts-Armbian/blob/main/s905_autoscript)**, **[emmc_autoscript](https://github.com/projetotvbox/amlogic-bootscripts-Armbian/blob/main/emmc_autoscript)** ) to the fat partition on the USB drive. Overwrite the existing files. -+ **Step 4:** If you have a GXBB (S905) or GXL (S905X/W/L) soc, you also need **[gxl-fixup.scr](https://github.com/projetotvbox/amlogic-bootscripts-Armbian/blob/main/gxl-fixup.scr)** -+ **Step 5:** Add an armbianEnv.txt file with the following content (file is also on github): +### Step 1 — Download the Armbian image + +Download the latest Armbian for s9xxx-box. We recommend [bookworm minimal](https://dl.armbian.com/aml-s9xx-box/Bookworm_current_minimal). + +--- + +### Step 2 — Prepare the installation media + +Flash the image to the USB drive using **[balenaEtcher](https://etcher.balena.io/)** — the simplest option — or via command line: + +```bash +sudo dd if=Armbian_*.img of=/dev/sdX bs=4M status=progress conv=fsync +``` + +> ⚠️ Replace `/dev/sdX` with your USB drive. Use `lsblk` or `fdisk -l` to confirm the correct device. With `dd`, writing to the wrong device will erase its data without any confirmation prompt. + +Mount the FAT partition of the USB drive and replace the boot scripts with the modified ones, overwriting the existing files: + +- **[aml_autoscript](https://github.com/projetotvbox/amlogic-bootscripts-Armbian/blob/main/aml_autoscript)** +- **[s905_autoscript](https://github.com/projetotvbox/amlogic-bootscripts-Armbian/blob/main/s905_autoscript)** +- **[emmc_autoscript](https://github.com/projetotvbox/amlogic-bootscripts-Armbian/blob/main/emmc_autoscript)** +- **[gxl-fixup.scr](https://github.com/projetotvbox/amlogic-bootscripts-Armbian/blob/main/gxl-fixup.scr)** *(only if your SoC is GXBB/S905 or GXL/S905X/W/L)* + +> **Compiling your own images or preparing multiple USB drives?** You can modify the `.img` file directly before flashing, avoiding the need to edit each drive individually. Mount the image with `losetup`: +> +> ```bash +> sudo losetup -fP Armbian_*.img +> lsblk | grep loop # identify the device and the FAT partition (usually loopXp1) +> sudo mount /dev/loop0p1 /mnt/armbian_boot +> ``` +> +> Copy the scripts normally to `/mnt/armbian_boot/` and **continue through the next steps as usual**, editing `armbianEnv.txt` and other parameters with the image still mounted. Only after completing all configurations, unmount and flash: +> +> ```bash +> sudo umount /mnt/armbian_boot +> sudo losetup -d /dev/loop0 +> sudo dd if=Armbian_*.img of=/dev/sdX bs=4M status=progress conv=fsync +> ``` + +--- + +### Step 3 — Configure `armbianEnv.txt` + +The `armbianEnv.txt` file controls essential boot parameters. Before editing, back up the original: + +```bash +sudo cp /mnt/your_usb/armbianEnv.txt /mnt/your_usb/armbianEnv.txt.bak +``` + +Edit with nano or your preferred editor: + +```bash +sudo nano /mnt/your_usb/armbianEnv.txt +``` + +**Reference content:** + ```bash extraargs=earlycon=meson,0xfe07a000 console=ttyS0,921600n8 rootflags=data=writeback rw no_console_suspend consoleblank=0 fsck.fix=yes fsck.repair=yes net.ifnames=0 watchdog.stop_on_reboot=0 pd_ignore_unused clk_ignore_unused rootdelay=5 bootlogo=false @@ -34,32 +89,77 @@ console=both # fdtfile=amlogic/meson-gxl-s905x-nexbox-a95x.dtb fdtfile=amlogic/meson-sm1-x96-air-gbit.dtb -# set this to the UUID of the root partition (value can be found -# in /extlinux/extlinux.conf after APPEND root= or with blkid) -rootdev=UUID=92139c84-3871-41d7-a3f2-e8a943cbfa87 +# set this to the UUID of the root partition (value can be found with blkid or in fstab) +#rootdev=UUID=92139c84-3871-41d7-a3f2-e8a943cbfa87 +# or use the default partition label: +#rootdev=LABEL=ROOTFS # Enable ONLY for gxbb (S905) / gxl (S905X/L/W) to create fake u-boot header #soc_fixup=gxl- ``` -> ⚠️ **Note: the `armbianEnv.txt` above is a starting point, not a universal configuration.** -> -> The file provided works for many devices, but it may not work out of the box for yours. Different TV boxes, SoCs, and Armbian versions may require different parameters — especially the `extraargs` line. + +> ⚠️ **This file is a starting point, not a universal configuration.** > -> **Before replacing the file**, compare it against the original `armbianEnv.txt` that comes with the Armbian image and merge carefully. Key things to watch for: -> - Parameters present in the original that are absent here may be required for your specific hardware. -> - The `extraargs` line varies the most between SoCs and may need to be adapted or extended. -> - When in doubt, start from the original file and apply only the changes you understand. +> The content above works for many devices, but may not work for yours. Different TV boxes, SoCs, and Armbian versions may require different parameters — especially the `extraargs` line. > -> If the system fails to boot, restoring the original `armbianEnv.txt` is usually the first step to diagnose the issue. +> **Before replacing the file**, compare it against the original `armbianEnv.txt` from the Armbian image and merge carefully. Parameters present in the original and absent here may be required for your hardware. When in doubt, start from the original and apply only the changes you understand. If the system fails to boot, restoring the backup (`armbianEnv.txt.bak`) is the first step to diagnose the issue. + +--- + +### Step 4 — Set the correct `fdtfile` + +Change the `fdtfile` line to the DTB that matches your box. Available files can be found in `/boot/dtb/amlogic/` inside the Armbian image. + +--- + +### Step 5 — Set `rootdev` *(optional since version 3)* + +By default, `rootdev` is commented out and the system uses the `ROOTFS` label automatically. If you need to specify it manually: + +| Media | Value | +|-------|-------| +| USB flash drive | `/dev/sda2` | +| SD card | `/dev/mmcblk0p2` | +| By UUID *(recommended)* | `UUID=` | +| By label | `LABEL=ROOTFS` | + +**How to get the root partition UUID:** + +With the system running from the USB drive or SD card, run: + +```bash +blkid +``` + +Expected output: + +``` +/dev/sda2: UUID="92139c84-3871-41d7-a3f2-e8a943cbfa87" TYPE="ext4" PARTUUID="..." +``` + +Copy the `UUID=` value of the root partition (usually `sda2` or `mmcblk0p2`) and paste it into `armbianEnv.txt`. The UUID can also be found in `/etc/fstab` or in the original `armbianEnv.txt` from the image, if already filled in. + +--- + +### Step 6 — Enable SoC fixup *(GXBB/GXL only)* + +If your box uses a GXBB (S905) or GXL (S905X/W/L) SoC, uncomment the line: + +``` +soc_fixup=gxl- +``` + +--- -+ **Step 6:** Change *fdtfile* to the DTB for your box. -+ **Step 7:** (optional since version 3:) Change *rootdev* to the right UUID for the rootfs for your image or change to /dev/sda2 when booting from USB or /dev/mmcblk0p2 when booting from SDCARD -+ **Step 8:** Only if your box has a GXBB (S905) or GXL (S905X/W/L) soc, uncomment the line *soc_fixup=gxl-* -+ **Step 9:** Power off the the box. -+ **Step 10:** Put the USB disk in your box. -+ **Step 11:** Push the reset button and hold the button -+ **Step 12:** power up your box while holding the reset button for approx 7 seconds. -+ **Step 13:** If you're lucky, it will now boot Armbian with a mainline kernel. Without any secondary u-boot blobs. +### Step 7 — Boot from USB + +1. Power off the box. +2. Insert the USB drive. +3. Press and **hold** the reset button. +4. Power on the box and keep holding for approximately **7 seconds**. +5. If everything is correct, Armbian will boot with a mainline kernel — without any secondary u-boot blobs. + +--- ## Supported Devices @@ -72,161 +172,158 @@ rootdev=UUID=92139c84-3871-41d7-a3f2-e8a943cbfa87 **❓ Untested:** - S905W2: Likely compatible but untested (not currently supported by Armbian kernel) -All used files and source files can be found on [Github](https://github.com/projetotvbox/amlogic-bootscripts-Armbian). +All files and source files are available on [Github](https://github.com/projetotvbox/amlogic-bootscripts-Armbian). --- -## Advanced - Bootloader Customization +## Advanced Troubleshooting — Bootloader Modification -### ⚠️ Disclaimer & Prerequisites - -**DISCLAIMER:** Modifying your device's bootloader can result in a bricked device. Any damage or data loss is your sole responsibility. Proceed only if you understand the risks. - -**Required Prerequisites:** +> ⚠️ **This section is for cases where the scripts simply do not work.** If the main method worked, you do not need this. +> +> Some devices have factory bootloaders that do not support running external scripts by default. In those cases, it is possible to modify the bootloader variables directly via serial console to force that support. This is a low-level procedure with a real risk of bricking the device. **Proceed only if you know what you are doing.** -- **Functional ARM Linux System:** Armbian, Debian, or Ubuntu ARM running from USB/SD on your Amlogic device - - Necessary to access internal eMMC and run analysis/extraction commands - - System must boot correctly to provide shell access - -- **Serial TTL Adapter (3.3V UART):** High-quality USB serial adapter - - ⚠️ **CRITICAL:** Use 3.3V only. 5V will damage the device! - - Requires soldering skills to connect TX/RX/GND to the board - -- **Serial Terminal Software:** PuTTY, Minicom, or picocom - -- **Patience & Methodology:** Follow each step carefully +### Prerequisites -### 🔒 Mandatory: Backup Your eMMC +- **Functional ARM Linux system:** Armbian, Debian, or Ubuntu ARM running from USB/SD on the Amlogic device — required to access eMMC and the shell. +- **Serial TTL adapter (3.3V UART):** ⚠️ **Use 3.3V only. 5V will damage the device.** Requires soldering TX/RX/GND pads on the board. +- **Serial terminal software:** PuTTY, Minicom, or picocom. -Before ANY experiment, create a complete backup: +### 🔒 Back Up eMMC Before Anything Else ```bash -# Bit-by-bit backup with compression (saves space) +# Compressed backup (a 16GB backup becomes 2-4GB) sudo dd if=/dev/mmcblkX bs=1M status=progress | gzip -c > backup_emmc_full.img.gz -# To restore in case of disaster: +# To restore: # gunzip -c backup_emmc_full.img.gz | sudo dd of=/dev/mmcblkX bs=1M status=progress ``` -Why gzip? A 16GB backup becomes 2-4GB, saving significant space. +### Checking Bootloader Support -### Checking Vendor Bootloader Support +#### Step 1: Connect the serial cable +Solder TX, RX, and GND to the device's UART pads and connect to your PC. -#### Step 1: Connect Serial Cable -Solder TX, RX, GND to your device's UART pads and connect to your PC. - -#### Step 2: Open Serial Console -Using picocom as example: +#### Step 2: Open the serial console ```bash -# Find your serial device ls -la /dev/ttyUSB* -# Connect at 115200 baud (adjust if different) picocom -b 115200 /dev/ttyUSB0 - -# Or with minicom: +# or: minicom -D /dev/ttyUSB0 -b 115200 ``` #### Step 3: Interrupt U-Boot Power on the device and quickly press `Ctrl+C` or `Enter` to interrupt U-Boot before it boots. -#### Step 4: Check Bootloader Variables -Once in U-Boot console, type: +#### Step 4: Check bootloader variables ```bash printenv bootcmd ``` -Expected output should be similar to: +Expected output: ``` bootcmd=run start_autoscript; run storeboot ``` -Check for related variables: +Also check: ```bash printenv start_usb_autoscript printenv start_mmc_autoscript printenv start_emmc_autoscript ``` -**Note:** Variable names may differ slightly. Look for patterns like `start_*_autoscript`. +> Variable names may differ slightly. Look for patterns like `start_*_autoscript`. -### Modifying Vendor Bootloader (Advanced Users Only) +### Modifying the Variables -If your bootloader is writable and you want to force script support, execute these commands in U-Boot console: +If the bootloader is writable, run in the U-Boot console: ```bash setenv start_autoscript 'if mmcinfo; then run start_mmc_autoscript; fi; if usb start; then run start_usb_autoscript; fi; run start_emmc_autoscript' setenv start_emmc_autoscript 'if fatload mmc 1 1020000 emmc_autoscript; then setenv devtype "mmc"; setenv devnum 1; autoscr 1020000; fi;' setenv start_mmc_autoscript 'if fatload mmc 0 1020000 s905_autoscript; then setenv devtype "mmc"; setenv devnum 0; autoscr 1020000; fi;' setenv start_usb_autoscript 'for usbdev in 0 1 2 3; do if fatload usb ${usbdev} 1020000 s905_autoscript; then setenv devtype "usb"; setenv devnum 0; autoscr 1020000; fi; done' +setenv upgrade_step 2 setenv bootdelay 1 ``` -#### ⚠️ CRITICAL: Setting bootcmd - Preserve Your Original Command - -**DO NOT simply use `run start_autoscript; run storeboot`** - This is generic and may brick your device if your original bootcmd was different! +#### ⚠️ Setting `bootcmd` — Preserve the Original Command -**Step-by-step approach:** +**Do not simply use `run start_autoscript; run storeboot`** without checking your original `bootcmd` first. A generic command may brick your device if the original was different. -1. **First, WRITE DOWN your original bootcmd:** +1. **Write down the original `bootcmd`:** ```bash printenv bootcmd - # Write down the EXACT output here: - # _________________________________ ``` -2. **Then set bootcmd to preserve it:** +2. **Set it while preserving the original:** ```bash - setenv bootcmd 'run start_autoscript; [PASTE YOUR ORIGINAL BOOTCMD HERE]' + setenv bootcmd 'run start_autoscript; [YOUR ORIGINAL BOOTCMD HERE]' ``` -**Examples from real devices:** +**Real device examples:** -**Example 1 - Generic Amlogic Box:** ```bash -# Original was: -# bootcmd=run storeboot - -# So you do: +# Example 1 — Generic Amlogic box (original: run storeboot) setenv bootcmd 'run start_autoscript; run storeboot' -``` - -**Example 2 - Different Vendor (HTV H8):** -```bash -# Original was: -# bootcmd=run start_emmc_autoscript; run storeboot -# So you do: +# Example 2 — HTV H8 (original: run start_emmc_autoscript; run storeboot) setenv bootcmd 'run start_autoscript; run start_emmc_autoscript; run storeboot' -``` - -**Example 3 - Complex Bootcmd:** -```bash -# Original was: -# bootcmd=if test -n ${upgrade_step}; then echo BOOT_STEP equals $upgrade_step; setenv upgrade_step; fi; run storeboot -# So you do: +# Example 3 — Complex bootcmd +# Original: if test -n ${upgrade_step}; then echo BOOT_STEP equals $upgrade_step; setenv upgrade_step; fi; run storeboot setenv bootcmd 'run start_autoscript; if test -n ${upgrade_step}; then echo BOOT_STEP equals $upgrade_step; setenv upgrade_step; fi; run storeboot' ``` -#### Final step - Save & Verify Changes +#### Save and verify ```bash saveenv reset ``` -Interrupt U-Boot again and verify variables were saved: +Interrupt U-Boot again and confirm: ```bash printenv bootcmd ``` -**Success indicators:** -- Variables were saved → Bootloader is writable and modifications should work -- Variables weren't saved → Read-only bootloader; cannot apply this method +- **Variables saved** → writable bootloader, modifications applied successfully. +- **Variables not saved** → read-only bootloader; this method cannot be applied. + +--- + +## How It Works Internally + +For those who want to understand what happens under the hood — the role of each file in the boot chain. + +### `aml_autoscript` — The Route Injector + +Runs **only once**, at the moment you force recovery mode (by holding the reset button while powering on). It rewrites the factory U-Boot environment variables via `saveenv`, establishing a new boot order: SD card → USB → eMMC, redirecting the flow to the scripts below. + +### `s905_autoscript` — The External Media Loader + +Runs every time the board powers on with a USB drive or SD card connected. It reads `armbianEnv.txt`, loads the Kernel, DTB, and Initrd into RAM, prepares the `bootargs`, and hands control to the Kernel to start the operating system. + +### `emmc_autoscript` — The Internal Storage Loader + +Functionally identical to the previous script, but triggered when no bootable USB drive or SD card is connected. It points to the physical address of eMMC memory (`devnum 1`) and mounts the root filesystem from the internal partition. + +### `gxl-fixup.scr` — The Fake Header Hack *(GXBB/GXL only)* + +The factory bootloaders of GXBB (S905) and GXL (S905X/W/L) families only accept kernels in the legacy `uImage` format (using `bootm`). Modern Armbian uses the `Image` format (using `booti`), which those bootloaders simply refuse. + +Instead of compiling legacy-format kernels, the script solves this at runtime: + +1. Replaces the standard boot routine (`cmd_do_boot`). +2. Uses `mw.l` to write directly into memory a **fake** legacy u-boot header at address `0x1ffffc0`, just before the Kernel. +3. Injects a valid CRC into the fake header (`cmd_hdr_crc`). +4. Fires `bootm` — the bootloader sees the fake header, believes it's dealing with a valid `uImage`, and boots the modern Linux kernel normally. + +> **Restriction:** the Kernel file cannot exceed **32MB** in size. + +This is why Step 6 instructs you to uncomment `soc_fixup=gxl-` for these SoCs: without this hack, the original bootloader would stall at boot. --- diff --git a/README.md b/README.md index a04e803..446ccca 100644 --- a/README.md +++ b/README.md @@ -6,23 +6,78 @@ - [Visão Geral](#visão-geral) - [Configuração](#configuração) - [Dispositivos Suportados](#dispositivos-suportados) -- [Avançado - Personalização do Bootloader](#avançado---personalização-do-bootloader) +- [Solução de Problemas Avançada — Modificação do Bootloader](#solução-de-problemas-avançada--modificação-do-bootloader) +- [Como Funciona Internamente](#como-funciona-internamente) + +--- ## Visão Geral -As imagens do Armbian para TV Boxes Amlogic usam blobs secundários de u-boot carregados em cadeia para inicializar imagens do kernel mainline. -Os bootloaders u-boot do fabricante, no entanto, podem inicializar o Linux mainline perfeitamente sem eles. Portanto, eles não são necessários. +As imagens do Armbian para TV Boxes Amlogic normalmente dependem de blobs secundários de u-boot para inicializar o kernel mainline. Na prática, eles não são necessários: o bootloader u-boot que veio de fábrica com a sua box já é capaz de fazer isso. Tudo que é preciso são algumas modificações nos scripts de boot do Armbian. + +> **Pré-requisito:** o u-boot do fabricante deve estar rodando na eMMC. Se sua box foi reflashada com outro bootloader, restaure a imagem Android original com a ferramenta [Amlogic USB Burning Tool](https://androidmtk.com/download-amlogic-usb-burning-tool) antes de continuar. -Tudo o que é necessário são algumas modificações simples em alguns dos scripts u-boot do Armbian. +--- ## Configuração -Pressuposição: você tem o u-boot do fabricante (o que veio com a box) rodando na eMMC. Se não, você pode restaurar a imagem Android original com a ferramenta Amlogic USB Burning. -+ **Passo 1:** Baixe a versão mais recente do Armbian para s9xxx-box, vamos usar [bookworm minimal](https://dl.armbian.com/aml-s9xx-box/Bookworm_current_minimal) -+ **Passo 2:** Grave a imagem em um pendrive USB -+ **Passo 3:** Copie os scripts de boot modificados (**[aml_autoscript](https://github.com/projetotvbox/amlogic-bootscripts-Armbian/blob/main/aml_autoscript)**, **[s905_autoscript](https://github.com/projetotvbox/amlogic-bootscripts-Armbian/blob/main/s905_autoscript)**, **[emmc_autoscript](https://github.com/projetotvbox/amlogic-bootscripts-Armbian/blob/main/emmc_autoscript)** ) para a partição FAT no pendrive. Sobrescreva os arquivos existentes. -+ **Passo 4:** Se você tem um SoC GXBB (S905) ou GXL (S905X/W/L), você também precisa de **[gxl-fixup.scr](https://github.com/projetotvbox/amlogic-bootscripts-Armbian/blob/main/gxl-fixup.scr)** -+ **Passo 5:** Adicione um arquivo armbianEnv.txt com o seguinte conteúdo (o arquivo também está no github): +### Passo 1 — Baixe a imagem do Armbian + +Baixe a versão mais recente do Armbian para s9xxx-box. Recomendamos a [bookworm minimal](https://dl.armbian.com/aml-s9xx-box/Bookworm_current_minimal). + +--- + +### Passo 2 — Prepare a mídia de instalação + +Grave a imagem no pendrive usando o **[balenaEtcher](https://etcher.balena.io/)** — a opção mais simples — ou via linha de comando: + +```bash +sudo dd if=Armbian_*.img of=/dev/sdX bs=4M status=progress conv=fsync +``` + +> ⚠️ Substitua `/dev/sdX` pelo seu pendrive. Use `lsblk` ou `fdisk -l` para confirmar o dispositivo correto. Com `dd`, gravar no dispositivo errado apaga os dados sem confirmação. + +Monte a partição FAT do pendrive e substitua os scripts de boot pelos modificados, sobrescrevendo os existentes: + +- **[aml_autoscript](https://github.com/projetotvbox/amlogic-bootscripts-Armbian/blob/main/aml_autoscript)** +- **[s905_autoscript](https://github.com/projetotvbox/amlogic-bootscripts-Armbian/blob/main/s905_autoscript)** +- **[emmc_autoscript](https://github.com/projetotvbox/amlogic-bootscripts-Armbian/blob/main/emmc_autoscript)** +- **[gxl-fixup.scr](https://github.com/projetotvbox/amlogic-bootscripts-Armbian/blob/main/gxl-fixup.scr)** *(apenas se o seu SoC for GXBB/S905 ou GXL/S905X/W/L)* + +> **Compilando imagens próprias ou preparando múltiplos pendrives?** É possível modificar a imagem `.img` diretamente antes de gravar, evitando ter que editar cada pendrive individualmente. Para isso, monte a imagem com `losetup`: +> +> ```bash +> sudo losetup -fP Armbian_*.img +> lsblk | grep loop # identifique o dispositivo e a partição FAT (geralmente loopXp1) +> sudo mount /dev/loop0p1 /mnt/armbian_boot +> ``` +> +> Copie os scripts normalmente para `/mnt/armbian_boot/` e **prossiga pelos próximos passos normalmente**, editando o `armbianEnv.txt` e os demais parâmetros com a imagem ainda montada. Só ao final, após concluir todas as configurações, desmonte e grave: +> +> ```bash +> sudo umount /mnt/armbian_boot +> sudo losetup -d /dev/loop0 +> sudo dd if=Armbian_*.img of=/dev/sdX bs=4M status=progress conv=fsync +> ``` + +--- + +### Passo 3 — Configure o `armbianEnv.txt` + +O `armbianEnv.txt` controla parâmetros essenciais do boot. Antes de editar, faça um backup do arquivo original: + +```bash +sudo cp /mnt/seu_pendrive/armbianEnv.txt /mnt/seu_pendrive/armbianEnv.txt.bak +``` + +Edite com nano ou o editor de sua preferência: + +```bash +sudo nano /mnt/seu_pendrive/armbianEnv.txt +``` + +**Conteúdo de referência:** + ```bash extraargs=earlycon=meson,0xfe07a000 console=ttyS0,921600n8 rootflags=data=writeback rw no_console_suspend consoleblank=0 fsck.fix=yes fsck.repair=yes net.ifnames=0 watchdog.stop_on_reboot=0 pd_ignore_unused clk_ignore_unused rootdelay=5 bootlogo=false @@ -34,32 +89,77 @@ console=both # fdtfile=amlogic/meson-gxl-s905x-nexbox-a95x.dtb fdtfile=amlogic/meson-sm1-x96-air-gbit.dtb -# defina isto para o UUID da partição raiz (o valor pode ser encontrado -# em /extlinux/extlinux.conf depois de APPEND root= ou com blkid) -rootdev=UUID=92139c84-3871-41d7-a3f2-e8a943cbfa87 +# defina isto para o UUID da partição raiz (o valor pode ser encontrado com blkid ou no fstab) +#rootdev=UUID=92139c84-3871-41d7-a3f2-e8a943cbfa87 +# ou use o label padrão da partição: +#rootdev=LABEL=ROOTFS # Ativar APENAS para gxbb (S905) / gxl (S905X/L/W) para criar cabeçalho u-boot falso #soc_fixup=gxl- ``` -> ⚠️ **Atenção: o `armbianEnv.txt` acima é um ponto de partida, não uma configuração universal.** -> -> O arquivo fornecido funciona para muitos dispositivos, mas não necessariamente para o seu. Diferentes boxes, SoCs e versões do Armbian podem exigir parâmetros distintos — especialmente na linha `extraargs`. + +> ⚠️ **Este arquivo é um ponto de partida, não uma configuração universal.** > -> **Antes de substituir o arquivo**, compare-o com o `armbianEnv.txt` original que vem na imagem do Armbian e mescle com cuidado. Pontos de atenção: -> - Parâmetros presentes no original que estão ausentes aqui podem ser necessários para o seu hardware. -> - A linha `extraargs` é a que mais varia entre SoCs e pode precisar de adaptação. -> - Em caso de dúvida, parta do arquivo original e aplique apenas as alterações que você compreende. +> O conteúdo acima funciona para muitos dispositivos, mas pode não funcionar para o seu. Diferentes boxes, SoCs e versões do Armbian podem exigir parâmetros distintos — especialmente a linha `extraargs`. > -> Se o sistema não inicializar, restaurar o `armbianEnv.txt` original é geralmente o primeiro passo para diagnosticar o problema. +> **Antes de substituir**, compare com o `armbianEnv.txt` original da imagem e mescle com cuidado. Parâmetros presentes no original e ausentes aqui podem ser necessários para o seu hardware. Em caso de dúvida, parta do original e aplique apenas as alterações que você compreende. Se o sistema não inicializar, restaurar o backup (`armbianEnv.txt.bak`) é o primeiro passo para diagnosticar. + +--- + +### Passo 4 — Ajuste o `fdtfile` + +Altere a linha `fdtfile` para o DTB correspondente à sua box. Os arquivos disponíveis estão em `/boot/dtb/amlogic/` dentro da imagem do Armbian. + +--- + +### Passo 5 — Ajuste o `rootdev` *(opcional desde a versão 3)* + +Por padrão, `rootdev` está comentado e o sistema usa o label `ROOTFS` automaticamente. Se precisar especificar manualmente: + +| Mídia | Valor | +|-------|-------| +| Pendrive USB | `/dev/sda2` | +| Cartão SD | `/dev/mmcblk0p2` | +| Por UUID *(recomendado)* | `UUID=` | +| Por label | `LABEL=ROOTFS` | + +**Como obter o UUID da partição raiz:** + +Com o sistema rodando a partir do pendrive ou SD, execute: + +```bash +blkid +``` + +Saída esperada: + +``` +/dev/sda2: UUID="92139c84-3871-41d7-a3f2-e8a943cbfa87" TYPE="ext4" PARTUUID="..." +``` + +Copie o valor `UUID=` da partição raiz (geralmente `sda2` ou `mmcblk0p2`) e cole no `armbianEnv.txt`. O UUID também pode ser encontrado em `/etc/fstab` ou no `armbianEnv.txt` original da imagem, se já estiver preenchido. + +--- + +### Passo 6 — Ative o SoC fixup *(apenas GXBB/GXL)* + +Se sua box usar um SoC GXBB (S905) ou GXL (S905X/W/L), descomente a linha: + +``` +soc_fixup=gxl- +``` + +--- -+ **Passo 6:** Altere *fdtfile* para o DTB da sua box. -+ **Passo 7:** (opcional desde a versão 3:) Altere *rootdev* para o UUID correto do rootfs para sua imagem ou mude para /dev/sda2 quando inicializar do USB ou /dev/mmcblk0p2 quando inicializar do SDCARD -+ **Passo 8:** Apenas se sua box tiver um SoC GXBB (S905) ou GXL (S905X/W/L), descomente a linha *soc_fixup=gxl-* -+ **Passo 9:** Desligue a box. -+ **Passo 10:** Coloque o disco USB na sua box. -+ **Passo 11:** Pressione o botão reset e mantenha pressionado -+ **Passo 12:** Ligue a box enquanto mantém o botão reset pressionado por aproximadamente 7 segundos. -+ **Passo 13:** Se você tiver sorte, agora ele inicializará o Armbian com um kernel mainline. Sem nenhum blob u-boot secundário. +### Passo 7 — Inicialize pelo pendrive + +1. Desligue a box. +2. Insira o pendrive USB. +3. Pressione e **mantenha pressionado** o botão reset. +4. Ligue a box e continue segurando por aproximadamente **7 segundos**. +5. Se tudo estiver correto, o Armbian iniciará com kernel mainline — sem nenhum blob u-boot secundário. + +--- ## Dispositivos Suportados @@ -72,161 +172,158 @@ rootdev=UUID=92139c84-3871-41d7-a3f2-e8a943cbfa87 **❓ Não Testado:** - S905W2: Provavelmente compatível mas não testado (não suportado atualmente pelo kernel do Armbian) -Todos os arquivos usados e arquivos de origem podem ser encontrados no [Github](https://github.com/projetotvbox/amlogic-bootscripts-Armbian). +Todos os arquivos e fontes estão disponíveis no [Github](https://github.com/projetotvbox/amlogic-bootscripts-Armbian). --- -## Avançado - Personalização do Bootloader +## Solução de Problemas Avançada — Modificação do Bootloader -### ⚠️ Aviso Legal & Pré-requisitos - -**AVISO:** Modificar o bootloader do seu dispositivo pode resultar em um dispositivo travado (brick). Qualquer dano ou perda de dados é de sua responsabilidade exclusiva. Proceda apenas se entender os riscos. - -**Pré-requisitos Obrigatórios:** +> ⚠️ **Esta seção é para casos onde os scripts simplesmente não funcionam.** Se o método principal funcionou, você não precisa disso. +> +> Alguns dispositivos possuem bootloaders de fábrica que não suportam a execução de scripts externos por padrão. Nesses casos, é possível modificar as variáveis do bootloader diretamente via console serial para forçar esse suporte. Trata-se de um procedimento de baixo nível, com risco real de brick. **Prossiga apenas se souber o que está fazendo.** -- **Sistema ARM Linux Funcional:** Armbian, Debian ou Ubuntu ARM rodando a partir de USB/SD no seu dispositivo Amlogic - - Necessário para acessar a eMMC interna e executar comandos de análise/extração - - O sistema deve inicializar corretamente para fornecer acesso shell - -- **Adaptador Serial TTL (3.3V UART):** Adaptador série USB de alta qualidade - - ⚠️ **CRÍTICO:** Use apenas 3.3V. 5V danificará o dispositivo! - - Requer habilidades de soldagem para conectar TX/RX/GND na placa - -- **Software de Terminal Serial:** PuTTY, Minicom ou picocom - -- **Paciência e Metodologia:** Siga cada passo cuidadosamente +### Pré-requisitos -### 🔒 Obrigatório: Faça Backup da sua eMMC +- **Sistema ARM Linux funcional:** Armbian, Debian ou Ubuntu ARM rodando a partir de USB/SD no dispositivo — necessário para acessar a eMMC e o shell. +- **Adaptador Serial TTL (3.3V UART):** ⚠️ **Use apenas 3.3V. 5V danificará o dispositivo.** Requer solda nos pads TX/RX/GND da placa. +- **Software de terminal serial:** PuTTY, Minicom ou picocom. -Antes de QUALQUER experimento, crie um backup completo: +### 🔒 Faça Backup da eMMC Antes de Qualquer Coisa ```bash -# Backup bit-a-bit com compressão (economiza espaço) +# Backup com compressão (um backup de 16GB vira 2-4GB) sudo dd if=/dev/mmcblkX bs=1M status=progress | gzip -c > backup_emmc_full.img.gz -# Para restaurar em caso de desastre: +# Para restaurar: # gunzip -c backup_emmc_full.img.gz | sudo dd of=/dev/mmcblkX bs=1M status=progress ``` -Por que gzip? Um backup de 16GB se torna 2-4GB, economizando espaço significativo. +### Verificando o Suporte do Bootloader -### Verificando o Suporte do Bootloader do Fabricante +#### Passo 1: Conectar o cabo serial +Solde TX, RX e GND nos pads UART do dispositivo e conecte ao PC. -#### Passo 1: Conectar Cabo Serial -Solde TX, RX, GND nos pads UART do seu dispositivo e conecte ao seu PC. - -#### Passo 2: Abrir Console Serial -Usando picocom como exemplo: +#### Passo 2: Abrir o console serial ```bash -# Encontre seu dispositivo serial ls -la /dev/ttyUSB* -# Conecte a 115200 baud (ajuste se diferente) picocom -b 115200 /dev/ttyUSB0 - -# Ou com minicom: +# ou: minicom -D /dev/ttyUSB0 -b 115200 ``` -#### Passo 3: Interromper U-Boot -Ligue o dispositivo e pressione rapidamente `Ctrl+C` ou `Enter` para interromper o U-Boot antes de inicializar. +#### Passo 3: Interromper o U-Boot +Ligue o dispositivo e pressione rapidamente `Ctrl+C` ou `Enter` para interromper o U-Boot antes de ele inicializar. -#### Passo 4: Verificar Variáveis do Bootloader -Uma vez no console do U-Boot, digite: +#### Passo 4: Verificar as variáveis do bootloader ```bash printenv bootcmd ``` -A saída esperada deve ser semelhante a: +Saída esperada: ``` bootcmd=run start_autoscript; run storeboot ``` -Verifique as variáveis relacionadas: +Verifique também: ```bash printenv start_usb_autoscript printenv start_mmc_autoscript printenv start_emmc_autoscript ``` -**Nota:** Os nomes das variáveis podem ser ligeiramente diferentes. Procure por padrões como `start_*_autoscript`. +> Os nomes das variáveis podem variar. Procure por padrões como `start_*_autoscript`. -### Modificando Bootloader do Fabricante (Apenas Usuários Avançados) +### Modificando as Variáveis -Se seu bootloader é gravável e você quer forçar o suporte a scripts, execute esses comandos no console do U-Boot: +Se o bootloader for gravável, execute no console do U-Boot: ```bash setenv start_autoscript 'if mmcinfo; then run start_mmc_autoscript; fi; if usb start; then run start_usb_autoscript; fi; run start_emmc_autoscript' setenv start_emmc_autoscript 'if fatload mmc 1 1020000 emmc_autoscript; then setenv devtype "mmc"; setenv devnum 1; autoscr 1020000; fi;' setenv start_mmc_autoscript 'if fatload mmc 0 1020000 s905_autoscript; then setenv devtype "mmc"; setenv devnum 0; autoscr 1020000; fi;' setenv start_usb_autoscript 'for usbdev in 0 1 2 3; do if fatload usb ${usbdev} 1020000 s905_autoscript; then setenv devtype "usb"; setenv devnum 0; autoscr 1020000; fi; done' +setenv upgrade_step 2 setenv bootdelay 1 ``` -#### ⚠️ CRÍTICO: Configurando bootcmd - Preserve Seu Comando Original - -**NÃO use simplesmente `run start_autoscript; run storeboot`** - Isto é genérico e pode danificar seu dispositivo se seu bootcmd original foi diferente! +#### ⚠️ Configurando o `bootcmd` — Preserve o Comando Original -**Abordagem passo-a-passo:** +**Não use simplesmente `run start_autoscript; run storeboot`** sem antes verificar o seu `bootcmd` original. Um comando genérico pode danificar seu dispositivo se o original for diferente. -1. **Primeiro, ANOTE seu bootcmd original:** +1. **Anote o `bootcmd` original:** ```bash printenv bootcmd - # Anote a saída EXATA aqui: - # _________________________________ ``` -2. **Então configure bootcmd para preservá-lo:** +2. **Configure preservando o original:** ```bash - setenv bootcmd 'run start_autoscript; [COLE SEU BOOTCMD ORIGINAL AQUI]' + setenv bootcmd 'run start_autoscript; [SEU BOOTCMD ORIGINAL AQUI]' ``` -**Exemplos de dispositivos reais:** +**Exemplos reais:** -**Exemplo 1 - Box Amlogic Genérica:** ```bash -# Original era: -# bootcmd=run storeboot - -# Então você faz: +# Exemplo 1 — Box Amlogic genérica (original: run storeboot) setenv bootcmd 'run start_autoscript; run storeboot' -``` - -**Exemplo 2 - Fabricante Diferente (HTV H8):** -```bash -# Original era: -# bootcmd=run start_emmc_autoscript; run storeboot -# Então você faz: +# Exemplo 2 — HTV H8 (original: run start_emmc_autoscript; run storeboot) setenv bootcmd 'run start_autoscript; run start_emmc_autoscript; run storeboot' -``` - -**Exemplo 3 - Bootcmd Complexo:** -```bash -# Original era: -# bootcmd=if test -n ${upgrade_step}; then echo BOOT_STEP equals $upgrade_step; setenv upgrade_step; fi; run storeboot -# Então você faz: +# Exemplo 3 — bootcmd complexo +# Original: if test -n ${upgrade_step}; then echo BOOT_STEP equals $upgrade_step; setenv upgrade_step; fi; run storeboot setenv bootcmd 'run start_autoscript; if test -n ${upgrade_step}; then echo BOOT_STEP equals $upgrade_step; setenv upgrade_step; fi; run storeboot' ``` -#### Passo Final - Salve e Verifique as Alterações +#### Salve e verifique ```bash saveenv reset ``` -Interrompa o U-Boot novamente e verifique se as variáveis foram salvas: +Interrompa o U-Boot novamente e confirme: ```bash printenv bootcmd ``` -**Indicadores de Sucesso:** -- Variáveis foram salvas → Bootloader é gravável e as modificações devem funcionar -- Variáveis não foram salvas → Bootloader somente leitura; não é possível aplicar este método +- **Variáveis salvas** → bootloader gravável, modificações aplicadas com sucesso. +- **Variáveis não salvas** → bootloader somente leitura; este método não é aplicável. + +--- + +## Como Funciona Internamente + +Para quem quer entender o que acontece por baixo dos panos — o papel de cada arquivo na cadeia de boot. + +### `aml_autoscript` — O Injetor de Nova Rota + +Executado **apenas uma vez**, no momento em que você força o modo de recuperação (segurando o botão reset ao ligar). Ele reescreve as variáveis de ambiente do U-Boot de fábrica via `saveenv`, estabelecendo uma nova ordem de boot: SD card → USB → eMMC, redirecionando o fluxo para os scripts abaixo. + +### `s905_autoscript` — O Carregador de Mídia Externa + +Executado toda vez que a placa liga com pendrive ou SD card conectado. Lê o `armbianEnv.txt`, carrega o Kernel, DTB e Initrd para a RAM, prepara os `bootargs` e passa o controle para o Kernel inicializar o sistema. + +### `emmc_autoscript` — O Carregador da Memória Interna + +Idêntico ao anterior em função, mas acionado quando não há pendrive ou SD inicializável conectado. Aponta para o endereço físico da eMMC (`devnum 1`) e monta a raiz do sistema a partir da partição interna. + +### `gxl-fixup.scr` — O Hack do Cabeçalho Falso *(apenas GXBB/GXL)* + +Os bootloaders de fábrica das famílias GXBB (S905) e GXL (S905X/W/L) só aceitam kernels no formato legado `uImage` (comando `bootm`). O Armbian moderno usa o formato `Image` (comando `booti`), que esses bootloaders simplesmente recusam. + +Em vez de compilar kernels legados, o script resolve isso em tempo de execução: + +1. Substitui a rotina de boot padrão (`cmd_do_boot`). +2. Usa `mw.l` para escrever diretamente na memória um cabeçalho u-boot legado **falso** no endereço `0x1ffffc0`, logo antes do Kernel. +3. Injeta um CRC válido no cabeçalho (`cmd_hdr_crc`). +4. Dispara `bootm` — o bootloader vê o cabeçalho falso, acredita estar lidando com um `uImage` legítimo e inicializa o kernel moderno normalmente. + +> **Restrição:** o arquivo do Kernel não pode ultrapassar **32MB**. + +É por isso que o Passo 6 instrui a descomentar `soc_fixup=gxl-` nesses SoCs: sem esse hack, o bootloader travaria na inicialização. --- diff --git a/armbianEnv.txt b/armbianEnv.txt index f9ff5db..1a047d0 100644 --- a/armbianEnv.txt +++ b/armbianEnv.txt @@ -11,7 +11,7 @@ fdtfile=amlogic/meson-sm1-x96-air-gbit.dtb # set this to the UUID of the root partition (value can be found in /extlinux/extlinux.conf after APPEND root= or with blkid) #rootdev=UUID=92139c84-3871-41d7-a3f2-e8a943cbfa87 # or use the default partition label: -#rootdev=LABEL=armbi_root +#rootdev=LABEL=ROOTFS # Enable ONLY for gxbb (S905) / gxl (S905X/L/W) to create fake u-boot header -#soc_fixup=gxl- \ No newline at end of file +#soc_fixup=gxl-