Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,7 @@ Snagboot currently supports the following families of System-On-Chips (SoCs):
* [AMLogic](https://www.amlogic.com/#Products) series: G12A (eg S905D2), G12B (eg A311D), SM1 (eg S905D3) and series: GXL (eg S905D), GXM (eg S912), GXBB (eg S905), AXG (eg A113D)
* [Renesas](https://www.renesas.com/en/products/microcontrollers-microprocessors/rz-mpus) RZ/N1 series
* [Qualcomm](https://www.qualcomm.com/) [IQ9075](https://www.qualcomm.com/internet-of-things/products/iq9-series/iq-9075)
* [T-Head](https://www.t-head.cn/) TH1520, tested on [BeagleV-Ahead](https://www.beagleboard.org/boards/beaglev-ahead)

Please check [supported_socs.yaml](https://github.com/bootlin/snagboot/blob/main/src/snagrecover/supported_socs.yaml)
or run `snagrecover --list-socs` for a more precise list of supported SoCs.
Expand Down
27 changes: 27 additions & 0 deletions docs/snagrecover.md
Original file line number Diff line number Diff line change
Expand Up @@ -182,6 +182,14 @@ into Emergency Download mode"* in the reference [documentation](https://docs.qua

**Note:** The steps described in the reference documentation above are the same for both EVK and non-EVK boards, except for the DIP switch position. For the exact DIP switch position required to enable EDL mode on the IQ9075 EVK, refer to the board schematic. Other boards using this SoC may use a different method to enter EDL mode; refer to your board vendor's documentation.

### T-Head TH1520

The TH1520 ROM code has a USB download mode that exposes a Fastboot interface,
which is the one used by snagrecover. To enter it, hold the board's download
button (the USB button on the BeagleV-Ahead), connect the USB-C port to your
host PC, then release the button. A "T-HEAD USB download gadget" device
(`2345:7654`) should appear on your host system.

## Preparing recovery firmware

Snagrecover requires firmware binaries to successfully recover the board. Each
Expand Down Expand Up @@ -632,6 +640,25 @@ configuration:

**u-boot:** TBD: U-Boot support for Snagboot recovery is currently under upstream review. See the [patch series](https://marc.info/?l=u-boot&m=178577211945398&w=2) for more information.

configuration:
* path

### For T-Head TH1520 devices

[example](https://github.com/bootlin/snagboot/blob/main/src/snagrecover/templates/th1520-beaglev-ahead.yaml)

A single image holding U-Boot SPL, the DDR firmware, OpenSBI and U-Boot proper
is downloaded to internal RAM. SPL initializes the external RAM, then starts
OpenSBI and U-Boot proper, so no other boot stage is needed.

This is the `u-boot-with-spl.bin` image that U-Boot generates with binman when
building a TH1520 board with SPL support (it requires the DDR firmware and
OpenSBI's `fw_dynamic.bin`). Refer to the U-Boot board documentation for
details. The `u-boot-with-spl.bin` of the vendor BeagleBoard.org images is
also accepted.

**u-boot:** `u-boot-with-spl.bin`.

configuration:
* path

Expand Down
3 changes: 3 additions & 0 deletions src/snagrecover/50-snagboot.rules
Original file line number Diff line number Diff line change
Expand Up @@ -100,3 +100,6 @@ SUBSYSTEM=="usb", ATTRS{idVendor}=="045b", ATTRS{idProduct}=="0239", MODE="0660"

# Qualcomm rules
SUBSYSTEM=="usb", ATTRS{idVendor}=="05c6", ATTRS{idProduct}=="9008", MODE="0660", TAG+="uaccess"

# T-Head rules
SUBSYSTEM=="usb", ATTRS{idVendor}=="2345", ATTRS{idProduct}=="7654", MODE="0660", TAG+="uaccess"
1 change: 1 addition & 0 deletions src/snagrecover/config.py
Original file line number Diff line number Diff line change
Expand Up @@ -100,6 +100,7 @@
"amlogic": "1b8e:c003",
"rzn1": "045b:0239",
"qcom": "05c6:9008",
"th1520": "2345:7654",
}

recovery_config = {} # Global immutable config to be initialized with CLI args
Expand Down
30 changes: 30 additions & 0 deletions src/snagrecover/firmware/firmware.py
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,7 @@
# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.

import logging
import usb.core

logger = logging.getLogger("snagrecover")
from snagrecover.protocols import dfu
Expand Down Expand Up @@ -142,6 +143,33 @@ def rzn1_run(dev, fw_name: str, fw_blob: bytes):
logger.info("Done")


def th1520_run(dev, fw_name: str, fw_blob: bytes):
"""
The TH1520 ROM code exposes a standard Fastboot interface. A single
image holding SPL, OpenSBI and U-Boot proper is downloaded to the "ram"
pseudo-partition, then started with the "reboot" command.

The commands are sent exactly as the stock fastboot client sends
them, without a trailing NUL byte: whether the ROM code accepts one
is unknown.
"""
fb_cmd = Fastboot(dev)
logger.info("Downloading file...")
fb_cmd.send(fw_blob)
fb_cmd.cmd(b"flash:ram")
logger.info("Done")

logger.info("Starting firmware...")
# A failed write must be reported, but the ROM code may jump to SPL
# before its OKAY is read.
dev.write(fb_cmd.ep_out, b"reboot", timeout=fb_cmd.timeout)
try:
fb_cmd.cmd()
except usb.core.USBError as e:
logger.debug(f"No answer to the reboot command: {e}")
logger.info("Done")


def check_fw_blob(fw_blob: bytes):
"""
Do a quick sanity check on the firmware contents. If the file passed
Expand Down Expand Up @@ -246,6 +274,8 @@ def run_firmware(port, fw_name: str, subfw_name: str = ""):
from snagrecover.firmware.qcom_fw import qcom_run

qcom_run(port, fw_name, fw_blob)
elif soc_family == "th1520":
th1520_run(port, fw_name, fw_blob)
else:
raise Exception(f"Unsupported SoC family {soc_family}")
logger.info(f"Done installing firmware {fw_name}")
15 changes: 15 additions & 0 deletions src/snagrecover/recoveries/th1520.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
import logging

logger = logging.getLogger("snagrecover")
from snagrecover.firmware.firmware import run_firmware
from snagrecover.utils import get_usb
from snagrecover.config import recovery_config


def main():
usb_addr = recovery_config["usb_path"]
dev = get_usb(usb_addr)

# The image holds SPL, OpenSBI and U-Boot proper. SPL initializes the
# DDR then starts the rest, so there is only one stage to download.
run_firmware(dev, "u-boot")
2 changes: 2 additions & 0 deletions src/snagrecover/supported_socs.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -92,6 +92,8 @@ tested:
family: amlogic
iq9075:
family: qcom
th1520:
family: th1520
untested:
a10:
family: sunxi
Expand Down
2 changes: 2 additions & 0 deletions src/snagrecover/templates/th1520-beaglev-ahead.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
u-boot:
path: u-boot-with-spl.bin
4 changes: 4 additions & 0 deletions src/snagrecover/utils.py
Original file line number Diff line number Diff line change
Expand Up @@ -411,6 +411,10 @@ def get_recovery(soc_family: str):
from snagrecover.recoveries.qcom import main as qcom_recovery

return qcom_recovery
elif soc_family == "th1520":
from snagrecover.recoveries.th1520 import main as th1520_recovery

return th1520_recovery
else:
cli_error(f"unsupported board family {soc_family}")

Expand Down
74 changes: 74 additions & 0 deletions tests/recovery_th1520.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,74 @@
import unittest
from unittest.mock import MagicMock, patch

import usb.core

from snagrecover.config import recovery_config
from snagrecover.firmware.firmware import th1520_run
from snagrecover.protocols.fastboot import FastbootError

FW_BLOB = b"\x01\x02\x03\x04" * 16


class TestTh1520Run(unittest.TestCase):
def setUp(self) -> None:
recovery_config.clear()
self.fb = MagicMock()
self.dev = MagicMock()
patcher = patch("snagrecover.firmware.firmware.Fastboot", return_value=self.fb)
patcher.start()
self.addCleanup(patcher.stop)

def test_download_flash_then_start(self) -> None:
th1520_run(self.dev, "u-boot", FW_BLOB)

self.fb.send.assert_called_once_with(FW_BLOB)

# Commands must be sent without trailing NUL, as stock fastboot does
self.assertEqual(
[c.args for c in self.fb.cmd.call_args_list],
[(b"flash:ram",), ()],
)
self.dev.write.assert_called_once_with(
self.fb.ep_out, b"reboot", timeout=self.fb.timeout
)

def test_reboot_without_answer(self) -> None:
def cmd(packet=None, *args, **kwargs):
if packet is None:
raise usb.core.USBError("device disconnected")

self.fb.cmd.side_effect = cmd
th1520_run(self.dev, "u-boot", FW_BLOB)
self.assertEqual(self.fb.cmd.call_count, 2)

def test_reboot_write_failure_is_reported(self) -> None:
self.dev.write.side_effect = usb.core.USBError("transfer failed")
with self.assertRaises(usb.core.USBError):
th1520_run(self.dev, "u-boot", FW_BLOB)
# The answer to reboot is not read when the write failed
self.assertEqual(self.fb.cmd.call_count, 1)

def test_reboot_refused(self) -> None:
def cmd(packet=None, *args, **kwargs):
if packet is None:
raise FastbootError("Fastboot fail with message: b'denied'")

self.fb.cmd.side_effect = cmd
with self.assertRaises(FastbootError):
th1520_run(self.dev, "u-boot", FW_BLOB)

def test_flash_failure_is_reported(self) -> None:
def cmd(packet=None, *args, **kwargs):
if packet == b"flash:ram":
raise usb.core.USBError("transfer failed")

self.fb.cmd.side_effect = cmd
with self.assertRaises(usb.core.USBError):
th1520_run(self.dev, "u-boot", FW_BLOB)
self.assertEqual(self.fb.cmd.call_count, 1)
self.dev.write.assert_not_called()


if __name__ == "__main__":
unittest.main()
Loading