ESP32-S2/S3 support

[wnienhaus]

This PR adds support for the ULP-FSM (not ULP RISC-V) of the ESP32-S2 and ESP32-S3.

(Note, the ESP32-S2 and S3 have the same ULP-FSM, so we don't distinguish between them in the implementation).

The entire instruction set of the ULP-FSM of the ESP32-S2 is supported, including the new load and store instructions to allow loading from or storing to the upper 16-bits of memory locations.

Use the -c command line argument when assembling or disassembling. Use -c esp32 (or omit the -c option) to select the original ESP32. Use -c esp32s2 to select the ESP32-S2/S3. Refer to the documentation in docs/disassembler.rst for more detail.

Please note: the latest release of MicroPython to date is 1.20, which does not enable the ULP on ESP32-S2/S3 devices. This is fixed already, but we need to wait for the next release to have the fix in an official version. To test this on a real device, use a recent nightly build of Micropython and flash that to your device.

This PR resolves #85 .

(The easiest way to review this PR is commit-by-commit. Each commit is one independent change.)

[wnienhaus]

There are some parts of the implementation I am currently not 100% happy with:

1. Having both disassemble.py (cli tool) and decode{,_s2}.py (not cli tools) under tools.
   • I did consider having those files under esp32_ulp
   • but that would mean they get included in the upip package (soon mip) by default
   • and I didnt want those files on the device by default when one installs the package (maybe that's a weird choice?).
2. Having two intentional bugs to match what Espressif's assembler (binutils-gdb/esp32ulp-elf-as) does.
   • This makes our comparison tests pass, but is still wrong (based on my understanding).
   • I reported both issues along with fixes to Espressif (here and here), but they haven't responded at all, and I wonder if they will give any attention to the ULP-FSM at all, now that the ULP RISC-V exists.
   • I was considering making our implementation correct and adjusting the tests somehow to account for the difference, but for now it is how it is.
3. That opcode.py and opcode_s2.py share (duplicate) a lot of non-cpu specific code, such as parsing register numbers or evaluating expressions. It was like that before, so for now it's the same, but it could divided up more nicely.

@ThomasWaldmann @dpgeorge @mattytrentini - if you have time and want to take a look at this PR, i'd appreciate it.

[wnienhaus]

One thing I noticed is that the S2 and S3 have different peripheral register addresses for similar things, different from the original ESP32 and also different between each other. That means that (most likely) our blink.py example will not work on an ESP32-S2/S3 even if the assembled ULP code has the right binary format.

I will test this on my S2 and S3 and add examples for the specific versions and add a mention of this detail into the documentation.

[ftylitak]

Hello all,

first of all thank you @wnienhaus for this usefull PR. We were in need of a Pulse Count implementation in ULP for ESP32S3 so based on this PR we changed the required addressed and it worked. (we were not sure whether to send a PR on wnienhaus:s2s3_support or on this main repo so we decided to just write this post as a description of the solution.)

The changes can be found in the last two commits of the following repo which has this PR merged and has as addition the specifics for ESP32S3:

• https://github.com/insighio/micropython-esp32-ulp

In a nutshell, opcodes_s3.py and soc_s3.py were added and assemble.py was updated to identify cpu=esp32s3.

Also here is the exampel code used to test the Pulse Counter on ESP32S3 on GPIO 4.

https://github.com/insighio/micropython-esp32-ulp/blob/master/examples/pulse_counter_esp32s3.py

We are based on micropython 1.19.1 so we made changes in the code of micropython to enable ULP for ESP32S3.
Though the most important note that we can make is that ESP32S3 closes down all RTC Peripherals upon deepsleep. Thus the user needs to instruct the ESP32S3 to keep the RTC IO powered on when in deepsleep and this instruction must executed every time the device wakes up from deep sleep.

For this reason, we added one more function in the ULP module which initializes the GPIO port, defines it as Input, enables Pull Down and instructs to keep RTC peripherals powered on when in deep sleep. This is called every time the device wakes up from deep sleep or else the counting of the edges stops.

The call to this function: https://github.com/insighio/micropython-esp32-ulp/blob/90fe843783ac63acf6224bd3e9e11b3522ce5469/examples/pulse_counter_esp32s3.py#L117-L124

And the function itself in custom micropython branch:
https://github.com/insighio/micropython/blob/33b18e0b67f73f27affff86acc796539a14f8b07/ports/esp32/esp32_ulp.c#L115-L131

In this way, we have a functioning Pulse Counter. Though our tests, by setting the ulp.set_wakeup_period from 20.000 to 100 we are reliably reading 100 pulses per second.

Hope all the above are helpfull. Thanks one again.

[wnienhaus]

@ftylitak Thank you so much for that feedback and testing this PR. Great to know that it works for you.

I have been working slowly on improving the PR to add support for the S2 and S3 peripheral register addresses. I just pushed that work to this PR.

I took a different approach than you for supporting the S3. Since the S2 and S3 have the same binary format on the ULP-FSM (in order words opcode_s2.py and opcode_s3.py would be identical in all ways except the peripheral register addresses accepted), I decided to keep having only the esp32s2 cpu for both the S2 and S3 and make this clear in the documentation. This also aligns with how Espressif does this in their binutils-gdb/esp32-ulp-as assembler, which only has cpu options esp32 and esp32s2 and they use the esp32s2 also for the S3.

That choice did lead me to something I am not 100% happy with, but thought it might be overall positive nonetheless, namely that opcode_s2 now accepts peripheral register addresses from any of the ESP32 variants. The reason is that what ends up in the actual processor instruction is a relative offset, relative to the base address of the specific variant. Thus within the instruction, it doesn't matter what the real input address was. And since especially across the S2 and S3 most of the relative offsets are actually the same, this "feature" allows assembly code with register addresses in the S2 range to work unmodified for the S3 (actually the binary would even be the same). You can see in the examples I added that I now only need 1 example for the s2/s3 combined rather than 2 examples.

I am not sure what you think of this. You took the alternative of adding a new cpu esp32s3. Perhaps this is the clearer approach? That way one doesn't need to even know that the S2 and S3 are binary compatible? On the other hand that feels useful knowledge to me, because one can reuse code and binaries.

Feel free to rebase onto what I just pushed. Note that commit 2aff8a1 contains an important fix for ST instructions with labels.

---

Small comment on your Micropython patch: That function is specific to your need and would not be good in MicroPython in general (e.g. it hard codes the direction to input, etc).

However, it might not even be needed, because so far I have always managed to do all that initialisation inside the ULP code, given that it also has access to the peripheral registers, which are configured by the rtc_gpio_* functions of the ESP-IDF. It requires a bit of digging in the ESP-IDF, to find which registers are set by those higher level function, but so far it worked.

What might not work (I am still busy testing), is enabling power of the RTC peripherals from ULP code (especially once deep_sleep has already been entered). So perhaps that is the "generic" function that would be useful in MicroPython, i.e. this part:

 // instruct to keep RTC peripherals powered on after when in deep sleep esp_sleep_pd_config(ESP_PD_DOMAIN_RTC_PERIPH, ESP_PD_OPTION_ON);

[ftylitak]

@wnienhaus great comments.

Indeed our modification in the Micropython branch is too specific. Those parts of setting the direction of the input etc were added there in the beginning as testing because we were not getting any results (plus we did not have much knowledge on the ULP so it was a bit of testing here and there). In the end we have found the RTC peripheral power on, it all started working though we did not take a step back to use the ULP code for the rest.
Also, the initialization of the GPIO was a direct copy of the setup procedure of the ESP-IDF example that we took as reference for testing.
https://github.com/espressif/esp-idf/tree/master/examples/system/ulp/ulp_fsm/ulp

The interesting part is that the ESP-IDF example does not use esp_sleep_pd_config though it works. So, may be it is a setting of Micropython that affects the power of the RTC peripherals.

Regading to this project (micropython-esp32-ulp) we wil rebase to your changes.

[wnienhaus]

Thanks for that input. It should help me resolve my current problem: readgpio_s2.py doesnt work on either the S2 or S3 - GPIO input is always 0.

Very interesting that the ESP-IDF example does not use the esp_sleep_pd_config - I hadnt noticed yet. Because readgpio_s2.py runs without entering deepsleep, I didnt think esp_sleep_pd_config would make a different (i'd assume the RTC peripherals are on, while the entire device is on), but I was going to try that next.

So I will actually try your approach next (how you patched MicroPython), given that it works for you, and then see if that makes readgpio_s2.py work for me. Assuming that it will, I can then narrow down from there to figure out which of those rtc_gpio_* statements actually makes the difference, and then see whether doing the same from ULP code would also work.

[wnienhaus]

@ftylitak So, it turns out it's actually the "IO MUX clock gate" that needs to be enabled, which the ESP-IDF does as part of rtc_gpio_init for the S2 and S3 (not the original ESP32).

rtc_gpio_init calls rtcio_hal_function_select here, which is mapped to a variant-specific rtcio_ll_function_select implementation here, which for the s3 is this one, the IO MUX clock gate is enabled here, like this:

SENS.sar_peri_clk_gate_conf.iomux_clk_en = 1;

When I create a MicroPython function in esp32_ulp.c that executes that same 1 line (instead of the full rtc_gpio_init as in your (@ftylitak) patch) and I run that before starting my readgpio_s2.py ULP program, everything works (note I select mux RTC, input-enable and pulldown/pullups from within the ULP code, so that all works as intended from the ULP). Without running that 1 line, I cannot read GPIO input.

I tried doing the equivalent with WRITE_RTC_FIELD(SENS_SAR_PERI_CLK_GATE_CONF_REG, SENS_IOMUX_CLK_EN, 1) from within the ULP code (inspired by the ESP-IDF example here), but it doesn't have any effect. Maybe it has no effect in the ESP-IDF example either, because they already run rtc_gpio_init before starting the ULP code. But given that this example code exists, I wonder if we stumbled upon a bug in the chip. (Someone else also ran into this problem: see).

One "simple" fix could be to patch MicroPython to set this flag everytime esp32.ULP.run() is called, but I guess there is a reason this is off-by-default, and someone might want to keep it off in some applications (perhaps it saves some power).

The other, perhaps "more correct" option could be to simply expose the rtc_gpio_init function as e.g. esp32.ULP.rtc_gpio_init(pin_number) - without additionally setting direction, configuring pullups/pulldowns, hold, etc - as those things all can be done from within the ULP code.

Anyway, just reporting my findings so far. Will still think a bit more about this.

(@ftylitak - if you have some time, it would be interesting to know whether this single line is enough to make your use case work, also in deepsleep, because i have not tested with deepsleep yet.)

[wnienhaus]

So, I finally have made progress. It turns out the issue with failing to write to the SENS_SAR_PERI_CLK_GATE_CONF_REG register was due to a bug in our assembler, which already existed in our original ESP32 implementation. The bug was in how we translated peripheral register addresses (see commit which fixes it: 520a7f7)

This issue also once existed in the ESP-IDF, which is where we got the incorrect translation logic from. After asking Espressif (espressif/esp-idf#12158) about not being able to write to the SENS_SAR_PERI_CLK_GATE_CONF_REG register they pointed me to their fix (espressif/esp-idf#11652), which was exactly what we needed.

I have now added the fix to this PR and added working examples (all tested on a real device) to the examples/ directory. Those examples end in _s2 or _s3 (where no _s3 example exists the s2 example also works on the s3).

So we don't need any changes to MicroPython after all! I am happy.

cc: @ftylitak

[wnienhaus]

Now that the examples work on real devices (S2 and S3) and because I have tested this quite extensively by now, I will proceed to merge this. Any further improvements can follow in future PRs.