Skip to content

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

Open
Bl00d-B0b wants to merge 1 commit into
libretiny-eu:masterfrom
Bl00d-B0b:soc-ambd
Open

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

Conversation

@Bl00d-B0b

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

Copy link
Copy Markdown

Adds AmebaD (RTL8720D) SoC support: image model, flash map (measured from a BW16 4 MB factory dump), and a complete UART flasher.

Flasher

Protocol confirmed against the working BK7231GUIFlashTool implementation (RTLFlasher.cs) and bench-verified end-to-end on an Ai-Thinker BW16 KIT driven from a Raspberry Pi:

  • classic-generation RAM flashloader upload (KM0 SRAM 0x82000 @ 115200), with loader-resident detection via its RAM signature so re-runs skip the upload
  • baud negotiation (CMD_USB) after the loader is up — verified at 115200 / 460800 / 921600 with byte-identical reads; 460800 is the default (~2.5x faster than 115200; 921600 adds nothing, the loader-side SPI read dominates)
  • flash read: loader command 0x20, answered as an unprompted XMODEM-1K stream with 8-bit checksums, ACK-paced, CMD_CRC (32-bit LE dword sum) verified
  • flash write: sector erase + XMODEM write addressed through the XIP window (0x08000000 | offset) + CMD_CRC verify; the loader drops to 115200 after every flash write and is renegotiated, mirroring the reference tool
  • stale-transfer recovery (CAN) so an interrupted run never wedges the next one

Bench results (BW16 KIT, RTL8720D, 4 MB XMC flash)

  • full 4 MB dump: byte-identical to a reference dump taken with BK7231GUIFlashTool
  • speed matrix 115200/460800/921600: identical md5 at every rate
  • 16 KB erase+write+verify+readback: byte-identical
  • full 4 MB image write: CMD_CRC pass, readback identical, firmware boots and is reachable on WiFi ~10 s after reset

Generations

This PR supports the classic RTL8720D generation (KM0 SRAM loader at 0x82000 @ 115200), bench-verified on the BW16 KIT. The DA/E generations are out of scope: their official flashloaders implement an entirely different protocol (ameba-rtos flash tools) and belong in a separate effort.

@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
Bl00d-B0b force-pushed the soc-ambd branch 2 times, most recently from 8b3b303 to 10e59d2 Compare August 18, 2026 08:47
@Bl00d-B0b
Bl00d-B0b marked this pull request as ready for review August 18, 2026 08:47
@Bl00d-B0b

Bl00d-B0b commented Aug 18, 2026

Copy link
Copy Markdown
Author

@NonPIayerCharacter closing the loop on the loader-generation question with bench data — and with ltchiptool now doing the whole job natively, no external flasher involved anymore.

The Ai-Thinker BW16 KIT here works through the classic path: this PR's own flasher uploads the bundled imgtool flashloader to KM0 SRAM 0x82000 at 115200, negotiates CMD_USB up to 921600 (460800 default; beyond that the loader-side SPI read dominates), and runs the full cycle end-to-end from a Raspberry Pi: full 4 MB dump, full 4 MB write with CMD_CRC verification and identical readback, and the flashed firmware boots and joins WiFi ~10 s after reset. BK7231GUIFlashTool served only as the protocol reference, plus one reference dump the native read was validated against byte-for-byte.

Two protocol details worth recording for anyone touching this next: the loader streams reads unprompted (no XMODEM initiation byte, 8-bit checksums), and flash writes must be addressed through the XIP window (0x08000000 | offset) — raw offsets sweep the loader's own RAM at 0x82000, which keeps ACKing while programming nothing. It also drops to 115200 after every flash write and needs renegotiation.

So the PR ships the classic path as the working default, and keeps the DA/DX/E constants (0x3000A020 @ 460800) documented plus the RTL8721DA_Stub binary bundled for a follow-up once it can be verified on DA-generation hardware — the split you described. When the bkflasher_stub custom-stub direction lands an AmebaD target, the SocInterface here can switch loader binaries without protocol changes. Undrafted on the strength of the bench results; details in the PR body.

@Bl00d-B0b
Bl00d-B0b force-pushed the soc-ambd branch 2 times, most recently from 1de32a8 to 4a9e1d7 Compare August 18, 2026 08:59
@NonPIayerCharacter

Copy link
Copy Markdown

DA/E should be dropped entirely, at least for now.
Their official flashloaders implement entirely different protocol.
Tools and protocol are open-source though.
https://github.com/Ameba-AIoT/ameba-rtos/tree/master/tools/ameba/Flash

If a switch to bkflasher_stub flashloaders is considered, then they should be recompiled without miniz and kv. It would drastically reduce their size at no cost, considering that neither of them would be used by ltchiptool.

@Bl00d-B0b
Bl00d-B0b force-pushed the soc-ambd branch 2 times, most recently from f392655 to 85f1077 Compare August 18, 2026 10:19
@Bl00d-B0b

Copy link
Copy Markdown
Author

Done in 85f1077: DA/E dropped entirely — the RTL8721DA stub binary, its constants and all mentions are gone; the PR now covers only the classic generation, with the docstring pointing at the ameba-rtos flash tools for whoever takes DA/E on. Noted on bkflasher_stub: if this SoC moves to those loaders, a miniz/kv-free rebuild it is.

One find while doing this: the repo-wide *.bin gitignore had silently kept the flashloader binary out of the earlier pushes — the classic imgtool flashloader is now force-added and actually part of the diff.

Image model, flash map measured from a BW16 4MB factory dump, and the complete UART flasher: classic-generation RAM flashloader (KM0 SRAM 0x82000 @ 115200), loader-resident detection, baud negotiation up to 921600, XMODEM read (loader streams unprompted, 8-bit checksums), erase + XIP-window-addressed XMODEM write, and CMD_CRC dword-sum verification. Bench-verified end-to-end on a BW16 KIT from a Raspberry Pi: full 4MB dump byte-identical to a reference dump, full 4MB write + checksum + readback, firmware boots. DA/DX/E-generation stub constants documented for follow-up.
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