ESP32 instruction set or assembly (ASM) programming docs?

[jens.alfke]

I'm looking for documentation of the ESP32 instruction set, for assembly language programming. I've found some old (2010) Xtensa ISA docs, but their designs are so configurable that it's not much use for a specific CPU.

I've seen two threads from a few years ago asking about this, and replies from Espressif saying that the ISA docs are somehow under NDA from Xtensa and they were trying to get permission to post them. But this never got resolved, apparently.

🤯 Is it just me, or is it crazy for there to be a CPU you can buy but whose instruction set you aren't allowed to know? I've been exposed to assembly language since I was a teenager exploring my Apple II, when I was crazy enough to hand-assemble 6502 instructions and type in the hex opcodes. I haven't written much assembly since then, but I've certainly had to know it well enough to read it when debugging C/C++ code for 68000, PowerPC, x86 and ARM.

(At the moment, I'm interested because I'm considering implementing a FORTH interpreter for ESP32. This requires a small but intricate core of assembly code to bootstrap it, before the rest of it can be implemented in FORTH.)

I don't suppose anyone's looked into the source code of GCC's code-generator module for ESP32? Given enough work, the instruction set could be figured out by reading that carefully... 🧐

--Jens

[mikronauts]

Yes, this is very frustrating. I have a similar issue if I want to try to port the VM for my basic compiler.

You could write it in C, once it works save assembly code, edit, assmble it, make sure it still works.

Using old docs, improve and replace, keep re-testing.

This sucks, but until proper docs show up...

btw, gcc generated code would not use all possible best instruction so there would be a big performance hit anyway.

[jens.alfke]

You could write it in C, once it works save assembly code, edit, assmble it, make sure it still works

I haven't looked — is there actually an assembler/disassembler in the toolchain?

Of course, trying to learn a completely new instruction set by reading disassembly is not my idea of fun, or even my idea of a productive use of time. Though I can imagine someone like teenage-me attacking the problem just for the challenge...

PS: Modern optimizing C compilers can generate code that's often more efficient than hand assembly, at least for x86 and ARM. But the ESP32 back-end may not be well enough tuned to reach those levels.

[technosf]

I have an Xtensa ASM project, built with ESP-IDF, wrapped for Arduino:

https://github.com/technosf/ESPxRGB

Can't remember where I found the doc for Xtensa (on a new computer ), just google Xtensa LX6 instruction set. The problem is not the ASM, but the setting up and entry and exit routines to execute it.

Fun! Looking forward to another excuse to use it - it's not 6502, but still cool

[sraposo]

Hello, all.

I´m considering migrate some products from present platform to ESP32 and, since then are time-critical, a machine level code is mandatory. But this seemingly total lack of support from Espressif on assembly coding is making me pessimistic on ESP32. I´ve been looking for some documentation on that but I failed miserably...

Has anybody been successful?

[ESP_Sprite]

The status, unfortunately, is that at this moment we're not at liberty to hand out the details of the Xtensa ISA. I know that some people have gotten it by looking online for documents that were leaked, while others have gotten the details by signing a NDA with Cadence themselves. It should also be possible to figure out the ISA by looking at the toolchain or the included assembly files in ESP-IDF, if you so desire.

For what it's worth, the ESP32-C3 will have a RiscV ISA which is fully documented. If that chip fits your specs, you could decide to wait until that is released.

[sraposo]

ESP_Sprite, thanks for replying.

Well, it´s quite frustrating to know that ESP32, due support information lack, is not viable for some professional applications. It seems a well featured product, but it also seems Espressif aimed hobbyist market.

According to page at https://www.espressif.com/en/news/ESP32_C3 , this new product is pretty modest compared to ESP32. Ok, it´s a alternative and economic option for certain applications that do not demand so much resources.

It´s a pity Espressif has developed a powerful product that can´t be fully useful considering its capabilities.

[ESP_Sprite]

Well, it´s quite frustrating to know that ESP32, due support information lack, is not viable for some professional applications. It seems a well featured product, but it also seems Espressif aimed hobbyist market.

As a counterpoint to that, very few professionals seem to require writing stuff in assembly nowadays, and the ones who do generally have no issue getting into an NDA with Cadence. It's the hobbyist market we're hearing the most complaints from. Don't get me wrong, we do take that market seriously, and it's one of the reasons we have attempted to make this information open, and also one of the reasons why the -C3 is RiscV instead.

[sraposo]

ESP_Sprite,

My company develops and produces ignition controllers for ICEs, so they have to work in very short cycles, requiring a very fast and efficient firmware, so we cannot write codes in any high level programming language since we will get dependent of compiler optimization efficacy. We struggle to save machine cycles, to cut down instructions. That´s why we need to write our code in assembly.
A simple C++ code to make a digital output invert its state running on a ESP-room-32 with a 240 MHz clock showed us how so much code overhead wasted processor power.

If we can get the necessary information to develop comfortably the low-level code we need, please tell us how we can get it.

Regards

[ESP_Sprite]

Just to set things straight, I can entirely imagine your specific situation may require assembly-level writing of code, and I would love to hand over the ISA documents if it were ours to hand over. My comment was solely directed against your 'hobbyist' qualification of our chips, while in my experience not having publicly-available documents seem to mostly affect those hobbyists and very few professionals. It seems you're one of the exceptions, and I can entirely understand your issue here.

As I said, you would need to contact Cadence and ask them what is necessary to get the documents and tools for the Xtensa ISA, which likely requires signing a NDA. I unfortunately know little more than that. You could try contacting my business colleagues at sales@espressif.com, who may have a bit more insight in the process.

(Also, directed at your c++-to-twiddle-an-io example, just to set expectations: don't assume you'll get an 120MHz GPIO waveform when you re-write that in assembly. On the ESP32, GPIO is routed via the APB bus and it will take the hardware multiple APB cycles to set/clear a GPIO bit. We have 'fast GPIO' options in the -S2 and -C3 to get around this limit, but the ESP32 does not have that.)