[Proposal] New porting for Ameba-RTOS: Current status and upstreaming guidance

[wangbaizhe]

Hi MicroPython Team,

I am currently working on porting MicroPython to the Ameba-RTOS (Realtek Ameba series) platform. I’ve made some significant progress and would like to share the current status and seek some guidance on the eventual upstreaming process.

Current Status
REPL: Working fine via UART.
File System: LittleFS / VFS integration is functional.
Network: WiFi station/AP modes and Socket support are working.
Peripherals: GPIO, PWM, I2C, and SPI are currently under development/porting.

Questions for Upstreaming
As I aim to eventually submit this as a Pull Request to the main MicroPython repository, I would like to know:
1.Preparation Checklist: Is there a specific checklist or documentation for new ports before they are considered for upstreaming?
2.Testing Requirements: What mandatory tests should I run? Should I focus on the tests/ directory in the root, and are there specific network/stress tests required for new RTOS-based ports?

I am committed to maintaining this port and following the community’s coding standards. Any feedback or pointers to existing documentation would be greatly appreciated!

Best regards
wangbaizhe
Email: penn_wang@realsil.com.cn

[peterhinch]

A starting point is to read the contributor guidelines.

[Josverl]

Other likely relevant pages on the Wiki are:

• https://github.com/micropython/micropython/wiki/MicroPython-New-Port-Development-Guide
• https://github.com/micropython/micropython/wiki/Adding-Board-Profiles

[wangbaizhe]

Thanks @peterhinch and @Josverl — I've read all three: the Contributor Guidelines, the New Port Development Guide, and Adding Board Profiles. I'm on board with the expectations (linear history / sign-off / PR template
/ code conventions), and I'll make sure everything is properly read and tested before I submit.

I'd like to aim for getting this port into the main tree, and I'm prepared to maintain it long-term. A few questions:

1. What's the bar for accepting a new SoC family port into the main repo?

2. Testing — is running the standard test suite over serial (run-tests.py) sufficient for an RTOS-based port, or are there network/stress requirements I should plan for?

3. How would you suggest staging the work? I've already implemented a fair amount:

   • Core runtime + REPL over UART, soft reset
   • Filesystem: internal flash block device + LittleFS/VFS
   • Networking: network.WLAN (STA + AP) and BSD sockets
   • machine: Pin (GPIO), Timer; _thread via FreeRTOS
   • In progress: PWM, I2C, SPI

   Given that, would you prefer a minimal first PR (core + REPL + one board) with peripherals following incrementally, or some other approach?

4. Documentation — for the docs on docs.micropython.org, am I right that this is just adding a docs// folder (general.rst / quickref.rst / tutorial) in the same PR flow, plus a board thumbnail PR to
   micropython-media for the download page?

[mattytrentini]

My advice would be to contribute a minimal port first. Initialise the micro, get the runtime working, REPL over UART, one (preferably readily available) board definition...and little else! The only other additions I'd consider would be Serial/USB for the REPL and, maybe, machine.Pin. Defer everything else and get the basics reviewed thoroughly.

The bar has recently been lowered to allow new ports with the definition of support tiers. One of the reasons to create these tiers was so that it is easier to accept a port that is new and not as complete as some of the mature ports.

Port-specific docs can come later, with the exception of the board image which will need to be a separate PR in micropython-media.

Are you aware of the previous effort to port to the Ameba? The repo is here and the last commit was a few years ago, but there may be some useful code to check out.

[wangbaizhe]

Hi, thanks for your reply.

1. I'd like to confirm: apart from submitting a PR on GitHub, is there any
   other business-related matter required?

2. I've already run some tests (basics, micropython, misc, extmod, stress,
   thread, float). The results are on par with esp32, except for extmod
   which I'm still working on.

3. I'll use the previous Ameba port as a reference.

We'll discuss internally on when and how to submit the first PR.

Thanks.

[mattytrentini]

Sorry, I missed this - and can see you've raised the PR already, congrats!

I don't think there are any other significant business matters; as long as the code in this repository is released MIT I think we're ok. SDKs can be licensed differently but must also be sufficiently open; I see ameba-rtos is Apache, which I believe is fine.

You should also look at this comment which outlines additional guidance about new port development. (And thanks for the inadvertent reminder; we need to condense that guidance and reproduce it in the contributor guidelines!)

Testing looks in good shape for this stage of the PR.

[wangbaizhe]

Dear @mattytrentini , following your advice I've submitted a minimal port as a first PR: #19394

It brings up the interpreter and REPL over LOGUART, with one board definition (PKE8721DAF / RTL8721DAF). Filesystem, networking, machine module, and threading are all deferred to follow-up PRs. CI builds and passes.

Just wondering - how long does a first review typically take for a new port like this?

[mattytrentini]

Hi there, happy to see the PR!

The first review can take some time - and releasing v1.29 is the priority at the moment so it's probably not going to happen until after that goes out the door.

I've given @dpgeorge a heads-up that you've submitted this new port - and it's great that the PR is small and focused. A cursory look suggests it's in good shape though I'm sure Damien will request that the ameba-rtos sdk is added as a submodule, which is how most (all?) the other ports operate. MicroPython will selectively bring in port dependencies based on the contents of the GIT_SUBMODULES env var (grep to see how other ports do this) for each port.

Would you expect the PR to work on the RTL8722DM? I have both an AMB21 and AMB23 that I could test on if that would work...and I'd be happy to give one to Damien when he's able to review it; it's much easier to accept a PR when it's possible to test it...

[wangbaizhe]

Hi @mattytrentini

Thanks again for the guidance on submitting a minimal port first — a few follow-ups:

1. Is there a rough estimate for when v1.29 will ship? Just want to plan around it.
2. Follow-up PR strategy: once the interpreter/REPL PR is reviewed, should the remaining functionality (WiFi/socket, machine peripherals, filesystem, OTA/threading) be submitted as one PR per feature area, or
   grouped into fewer, larger PRs?
3. Re: the testing offer — thanks for offering to test on AMB21/AMB23. The current porting plan doesn't include those two boards. If you'd like to get a PKE8721DAF for testing, it's available here:
   https://aiot.realmcu.com/en/center/hardware/detail/56?theme_id=5 — if it's not purchasable from your region, let me know and I'll find another way.

Thanks,

[Josverl]

If you'd like to get a PKE8721DAF for testing

Also on aliexpress

[mattytrentini]

1. Keep an eye on the v1.29 milestone. It was scheduled for mid July but has slipped out to the start of August.
2. It's been done both ways. I'd suggest smaller groups of PRs so they're easier to review. So maybe I2C/SPI/I2S would come up next, WiFi/networking after that etc. Try to consider the challenges for the reviewer, so don't make them too large!
3. I'll take a look, thanks.