Skip to content

[ambd] Add AmebaD (RTL8720D) SoC support - #98

Draft
Bl00d-B0b wants to merge 5 commits into
libretiny-eu:masterfrom
Bl00d-B0b:soc-ambd
Draft

[ambd] Add AmebaD (RTL8720D) SoC support#98
Bl00d-B0b wants to merge 5 commits into
libretiny-eu:masterfrom
Bl00d-B0b:soc-ambd

Conversation

@Bl00d-B0b

@Bl00d-B0b Bl00d-B0b commented Aug 9, 2026

Copy link
Copy Markdown

Adds soc/ambd for the realtek-ambd family (RTL8720DN/DM/DX, e.g. BW16), companion to the LibreTiny family port.

What's included

  • Image model (util/models.py): 32-byte section headers (81958711 signature, u32le length + load address, 16×0xFF pad), section-chain walk, OTA1 image packing. Verified byte-exact against BW16 factory dumps and post-OTA readbacks.
  • Flasher (util/ambdtool.py): ROM download protocol — CMD_USB/CMD_XMD phases, address-prefixed 1K-checksum XMODEM, RAM stub upload (per die generation: 0x3000A020 @ 460800 for DA/DX/E, 0x82000 KM0 SRAM @ 115200 for classic D) — constants taken from the working BK7231Flasher implementation and the vendored imgtool_flashloader_amebad.bin stub (4688 B, from the official Image_Tool).
  • Flash guide (flash.py): BW16 KIT pinout (LOG_TX/PA7, LOG_RX/PA8), download-mode entry.
  • Flash map: measured from a 4 MB BW16 factory dump (OTA1 @ 0x6000, vendor FTL @ 0x200000, OTA2 @ 0x206000).
  • soc/interface.py dispatch for the family.

Validation state

  • Image parsing/packing: round-trip proven against factory dumps; images built this way boot on hardware (16 firmware revisions flashed during the LibreTiny port bring-up).
  • ROM handshake: ACK exchange reproduced on bench at 115200.
  • Full write path: performed on bench with the reference implementations (BK7231Flasher, amebad_image_tool) using the same protocol; the ltchiptool-native write awaits a bench pass and this PR stays draft until then.

@Bl00d-B0b

Copy link
Copy Markdown
Author

@kuba2k2 companion to libretiny-eu/libretiny#403. Image model verified byte-exact against BW16 factory dumps and hardware OTA round-trips; ROM protocol reproduced on bench to the first ACK exchange. Stays draft until the native write path gets a bench pass — flashing currently works with the external tools listed in the description.

@NonPIayerCharacter

Copy link
Copy Markdown

On RTL8720D, entry point is at 0x82000, i.e. KM0 SRAM. 0x3000A020 is for DA/E KM4.
https://github.com/openshwprojects/BK7231GUIFlashTool/blob/8d81f51ff6740df18d2415c8a3df7062c2d602a6/BK7231Flasher/Flashers/RTLFlasher.cs#L233

That flasher will soon be removed though, all platforms with a possibility of RAM execution will be moved to custom stub implementation.
https://github.com/NonPIayerCharacter/bkflasher_stub

Baud rate is 460800 specifically for DA/E too. They have IWDT enabled in ROM, and our current stub implementation is too big to upload at 115200 baud without watchdog reset.

@Bl00d-B0b

Copy link
Copy Markdown
Author

That matches the bench here: the test unit reports arch RTL8720DX in the ROM banner, which explains why 0x3000A020 @ 460800 works on it. So the current constants cover the DA/DX/E generation and classic D needs 0x82000 (KM0 SRAM) @ 115200 — I'll parametrize the loader constants per die generation, unless the better move is to wait and target bkflasher_stub once the custom-stub direction stabilizes. Which would you prefer for this PR?

@Bl00d-B0b

Copy link
Copy Markdown
Author

Investigated both references. Verified in RTLFlasher.cs: classic RTL8720D uses the AmebaDFLoader binary uploaded to 0x82000; 0x3000A020 appears only in the DA/E flasher (RTLNFlasher.cs, RTL8721DA_Stub) — which is the path this PR ports, and the path our RTL8720DX bench unit has been flashed with all along. So the two generations differ in the loader binary itself, not just the entry point and baud, and classic-D support means vendoring AmebaDFLoader alongside the DA stub with a chip-generation switch. Given bkflasher_stub moves everything to the 0xA5 custom-stub protocol (which this port's ECR framing already speaks), the pragmatic split seems to be: land this PR scoped to DA/DX/E where it is bench-verified, and add classic D either via AmebaDFLoader or directly on a bkflasher_stub target once one exists for AmebaD. Happy to go either way.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants