ESP32: assembler, aBelle and WiFi over the USB cable

What Asmonite does with the ESP32

Connect and start

1. Plug in the board. A board with an ESP32 and a USB serial chip (CP2102 or CP2104, CH340, CH9102, CH343, FTDI). In the Device Manager it shows as a COM port. Windows brings the driver of most of these chips, else it comes from the maker of the chip.
2. Test the connection. Debug > Debug targets > ESP32 > Test the connection shows the COM port, the MAC address and the flash, for example "flash 4 MB (Boya, JEDEC id 68 40 16)". The flash chip tells its size itself, as with esptool flash_id.
3. Start. Open examples\esp32\blink_ram.asm and press F7: Asmonite puts the chip into the download mode, loads the program and stops at _start. F7 and F8 take a step, F9 runs, F5 sets a breakpoint, Debug > Pause stops.

The download mode. The boot ROM waits for commands on UART0 when GPIO 0 is low at a reset. The boards do that over the lines DTR and RTS of the USB serial chip; Asmonite does it as esptool does and checks the first line of the boot ROM after each reset. On some boards that takes many attempts, because the capacitor at EN is too small. If the board does not get there within 10 seconds, Asmonite asks you to hold BOOT down. A capacitor of about 10 µF between EN and GND fixes it for good.

921600 baud. Big transfers go eight times as fast as at 115200: the flash over the boot ROM, a program of 16 KB or more under the debugger, files of 16 KB or more. Asmonite checks the rate with a short exchange and falls back to 115200 if the board does not manage it. A program of 98 KB loads in a little over 6 seconds. Before the program runs, the rate is 115200 again. The environment variable ASMONITE_ESP_BAUD sets another rate.

The same program in assembly and aBelle

The LED at GPIO 2 blinks: set the pin up as a GPIO, make it an output, then switch it on and off in a loop. Files: examples\esp32\blink_ram.asm and examples\abelle\esp32\blink.abel (shortened).

.target esp32
.arch xtensa
.imagebase 0x40080000     ; IRAM

lit_gpio:  dd 0x3FF44000      ; the GPIO registers
lit_half:  dd 20000000        ; half a second at 40 MHz
    ...
_start:
    l32r  a2, lit_gpio
    ...                        ; IO_MUX, output select
    movi  a3, 4                ; 1 << 2: GPIO 2
    s32i  a3, a2, 0x24         ; an output
    l32r  a7, lit_half
loop:
    s32i  a3, a2, 0x08         ; on
    call0 wait
    s32i  a3, a2, 0x0C         ; off
    call0 wait
    j     loop
wait:
    rsr   a9, ccount
wait_more:
    rsr   a10, ccount
    sub   a10, a10, a9
    bltu  a10, a7, wait_more
    ret

target "esp32"

gpio:  u32[0x140] at 0x3FF44000
iomux: u32[64]    at 0x3FF49000
def ets_delay_us(us: u32) at 0x40008534  # ROM

def main():
    iomux[0x40 / 4] = 0x2800   # GPIO 2 as a GPIO
    gpio[0x538 / 4] = 0x100    # a simple output
    gpio[0x24 / 4] = 1 << 2    # an output
    while True:
        gpio[0x08 / 4] = 1 << 2  # on
        ets_delay_us(500000)
        gpio[0x0C / 4] = 1 << 2  # off
        ets_delay_us(500000)

Xtensa loads a 32-bit constant with l32r from a word in front of the code; ccount counts the cycles of the core. In aBelle the registers are an array at their address, and a function of the ROM is made known with at and its address. Both programs lie in the IRAM from 0x40080000 on, and the debugger goes through both line by line: in the assembly instruction by instruction, in aBelle line by line of the source, with the variables under the mouse and in the window Watch.

Debugging without JTAG

F9 or F7 puts the chip into the download mode, the boot ROM loads Asmonite's debug monitor (a little over 2 KB at 0x4009E000), and the monitor loads the program and starts it at _start. It points VECBASE at its own vector table: break 1,15 (a breakpoint), the step of ICOUNT and every exception land there. It saves the registers and answers Asmonite's commands over UART0. It has the handlers of the register windows, so a chain of calls with call4, call8 and call12 deeper than the 64 registers hold works too.

Pause and stop. Debug > Pause stops a running program where it is, also in an endless loop. For that Asmonite sends a byte over UART0; the monitor routes the interrupt of the UART to the NMI of the core, above the interrupt level 5 the program runs at. Stop (Ctrl+F2) ends the session at once.

Exceptions. An illegal instruction, a load from an address without memory or a byte store into the IRAM stops the program at the instruction, with the cause in the output window. The core reads and writes the IRAM in words of 32 bits only: l32i and s32i work, l8ui and s8i do not.

Data in the DRAM: .data

Texts, tables and buffers go behind .data: these lines land in the DRAM from 0x3FFB0000 on, where the core reads and writes bytes, halfwords and words. .code switches back to the code.

lit_text: dd text           ; the address in the DRAM, for l32r

_start:
    l32r  a3, lit_text
    l8ui  a2, a3, 0           ; a byte of the text
    ...

.data
text:   db 'Hello, world!', 13, 10, 0
buffer: resb 64             ; room, filled with zeros when it is loaded

The debugger writes the bytes of .data into the DRAM after the code; a program for the flash has them as a second segment of the image, which the boot ROM copies at every start. The stack starts at 0x3FFC0000 and grows down; data that reach into it are an error.

RAM, flash and the serial output

A program that the boot ROM starts from the flash has to switch off the watchdogs itself, else the chip resets after a few seconds; examples\esp32\blink_flash.asm shows how with a few lines at _start.

The tab Serial. What the program writes into UART0 comes out at the COM port, at 115200 baud. Under the debugger the monitor shares the port with the program, and the output shows in the tab Serial next to the output window. Without the debugger the tab is a small terminal: Connect, an input line and Reset, which resets the chip over RTS without closing the port. Otherwise the terminal leaves the lines DTR and RTS off, so that a program in the RAM is not gone when the port opens.

The console and its files

examples\esp32\console.asm makes the board a small computer with a file system in the flash, from 2 MB to the end of the flash: 2 MB on a flash of 4 MB, 6 MB on one of 8 MB. Any terminal program works with it (ls, cat, put, rm, df, format, run, load, boot, help), and Debug > ESP32 Board Files shows its files in a window.

A program for F9 fits into the console as it is: its code may take 0x40080000..0x40097FFF, its data 0x3FFB0000..0x3FFCFFFF. The console does not run under the debugger, because the debug monitor takes every byte on UART0 as a pause.

The WiFi

The WiFi of the ESP32 is in libraries of Espressif without source. Asmonite links them once with its own linker into a fixed file, wlan.rom, and brings a small service, wlansvc, which starts them and offers simple functions to programs. No ESP-IDF is needed for it.

1. Set it up once per board. Debug > ESP32 Board Files (the console in the flash, the file system formatted), then Install WiFi: the part for the flash (330 KB at 0x100000) goes into the flash over the boot ROM, wlan.rom and wlansvc into the files. This takes about 25 seconds.
2. Enter the network. In examples\abelle\esp32\inc\network.abel enter the name and the password of your network (empty for an open network, else WPA2, 2.4 GHz).
3. Start. Open for example ntp.abel and press F9. The program loads the service from the files of the board itself at its first WiFi call, with F9 as with run ntp in the console or as the autostart.

Debugging while the WiFi runs. The service and the WiFi run on the second core of the ESP32, the program on the first. The debugger stops the first one only: while the program stands at a breakpoint, the station stays connected, and what comes in waits in a buffer of the service (6 frames). So you can go through a DHCP exchange or a TCP connection line by line.

The functions are in inc\wifi.abel, inc\net.abel and inc\tcp.abel, written in aBelle: you can read DHCP, DNS, ARP, ICMP, UDP, TCP and mDNS there and follow them in the debugger.

The examples

In examples\esp32 are the examples in assembly: blink, hello_uart (each for the RAM and the flash), clock (the core at 80, 160 and 240 MHz) and the console. In examples\abelle\esp32 are the examples in aBelle: blink, hello_uart, chipinfo, clock, timer, dice, reaction, sieve, temperature, and for the WiFi scan, dhcp, dns, ping, wol, arpscan, ntp, udpecho, httpget, webserver and telnetd. The registers they use are in their comments, with the source.

All examples with a description →

How the memory is used

When something does not work

What is not (yet) there

• The debugger stops the first core only; the WiFi uses the second.
• The program must not change VECBASE, use UART0 for input, switch on interrupts above level 5 or switch off the CPU interrupt 14: the monitor needs them.
• The WiFi only as a station (no access point of its own), open networks and WPA2 (no WPA3, no Enterprise), one TCP connection at a time, no HTTPS, no Bluetooth.
• While the WiFi runs, write nothing into the flash (no upload): Reset Board first.
• Not yet: own programs in the external flash (through the cache) or in the PSRAM.
• The WiFi is there for the original ESP32 only so far, not for the ESP32-S3 and the ESP32-C3.

Next