diff --git a/README.md b/README.md index 1cc020f..ac720f4 100644 --- a/README.md +++ b/README.md @@ -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. diff --git a/docs/snagrecover.md b/docs/snagrecover.md index 363cf6a..6491ef3 100644 --- a/docs/snagrecover.md +++ b/docs/snagrecover.md @@ -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 @@ -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 diff --git a/src/snagrecover/50-snagboot.rules b/src/snagrecover/50-snagboot.rules index a3b64cd..36abf91 100644 --- a/src/snagrecover/50-snagboot.rules +++ b/src/snagrecover/50-snagboot.rules @@ -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" diff --git a/src/snagrecover/config.py b/src/snagrecover/config.py index b41e7d1..18bbb4e 100644 --- a/src/snagrecover/config.py +++ b/src/snagrecover/config.py @@ -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 diff --git a/src/snagrecover/firmware/firmware.py b/src/snagrecover/firmware/firmware.py index 3dee89f..74bdce1 100644 --- a/src/snagrecover/firmware/firmware.py +++ b/src/snagrecover/firmware/firmware.py @@ -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 @@ -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 @@ -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}") diff --git a/src/snagrecover/recoveries/th1520.py b/src/snagrecover/recoveries/th1520.py new file mode 100644 index 0000000..49acdf1 --- /dev/null +++ b/src/snagrecover/recoveries/th1520.py @@ -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") diff --git a/src/snagrecover/supported_socs.yaml b/src/snagrecover/supported_socs.yaml index b32b00e..b989f6f 100644 --- a/src/snagrecover/supported_socs.yaml +++ b/src/snagrecover/supported_socs.yaml @@ -92,6 +92,8 @@ tested: family: amlogic iq9075: family: qcom + th1520: + family: th1520 untested: a10: family: sunxi diff --git a/src/snagrecover/templates/th1520-beaglev-ahead.yaml b/src/snagrecover/templates/th1520-beaglev-ahead.yaml new file mode 100644 index 0000000..d6b580d --- /dev/null +++ b/src/snagrecover/templates/th1520-beaglev-ahead.yaml @@ -0,0 +1,2 @@ +u-boot: + path: u-boot-with-spl.bin diff --git a/src/snagrecover/utils.py b/src/snagrecover/utils.py index 49bcf9f..e93758b 100644 --- a/src/snagrecover/utils.py +++ b/src/snagrecover/utils.py @@ -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}") diff --git a/tests/recovery_th1520.py b/tests/recovery_th1520.py new file mode 100644 index 0000000..f113332 --- /dev/null +++ b/tests/recovery_th1520.py @@ -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()