Referencia

Contrato de la placa ESP32 DevKit (Boards Wave C)

La clásica ESP32 sobre un Xtensa LX6: la matriz GPIO, LEDC, ADC1, y un solo núcleo donde el chip tiene dos.

Esta es la referencia de ingeniería del modelo: qué implementa, registro por registro, para quienes escriben firmware sobre él. Para usar la placa en el editor, empieza por La ESP32 DevKit V1 y la página de la placa.

La ESP32 DevKit V1 es la placa DOIT de treinta pines alrededor de un módulo ESP32-WROOM-32: un Xtensa LX6 a 240 MHz, el primer componente aquí que no es RISC-V, ni AVR, ni Arm. Un componente del kernel (esp32 en crates/parts) envuelve un modelo de SoC ESP32 (crates/esp32) sobre un intérprete Xtensa (crates/xtensa-core). Este documento es el contrato, y prevalece sobre cualquier comentario en el código.

El tipo de catálogo es esp32. La cadena program del catálogo es elf32 xtensa lx6 esp32.

Lee primero la sección 6 si vas a llevar una compilación de aquí a silicio real. Dice, dirección por dirección, qué números salieron del ESP32 Technical Reference Manual y cuáles son creencia de este modelo, y lista lo que no está aquí en absoluto: el segundo núcleo, la caché, la flash, la PSRAM y ambas radios, entre otros. Nada se adivina en silencio.

Un sketch para esta placa se compila en el navegador con clang-v3, la compilación wasm del fork de LLVM de Espressif (-mcpu=esp32), publicada el 2026-09-28 y verificada en este simulador (docs/compile.md). Un ejemplo sin modificar todavía ejecuta su ELF precompilado de web/public/firmware/esp32/, que compilan las versiones GCC de Espressif. La sección 7 tiene los detalles.

1. Pines de la placa (orden del catálogo)

Vista superior, el conector micro-USB abajo, el módulo WROOM-32 y su antena PCB arriba. La placa mide 51.5 x 28.3 mm y sus dos headers de 15 pines están a 22.86 mm (0.9 pulgadas) de distancia, que es lo que permite que una DOIT DevKit V1 se monte a caballo sobre una protoboard dejando una fila de orificios libre a cada lado. La imagen la dibuja a ese tamaño.

La Espressif DevKitC de 38 pines es la otra placa que la gente quiere decir con "una ESP32 DevKit", y sus headers están a una pulgada completa de distancia: sobre una protoboard no deja ninguna fila libre. Esta es la placa DOIT de treinta pines.

Header izquierdo, de arriba abajo (15 orificios): EN, VP, VN, D34, D35, D32, D33, D25, D26, D27, D14, D12, GND, D13, VIN.

Header derecho, de arriba abajo (15 orificios): D23, D22, TX0, RX0, D21, D19, D18, D5, TX2, RX2, D4, D0, D2, D15, 3V3.

30 pines. Dn es el GPIO n. VP es el GPIO 36 y VN es el GPIO 39: los pines SENSOR_VP y SENSOR_VN del chip, que la serigrafía nombra por su función. TX0/RX0 son los GPIO 1 y 3, la UART de consola; TX2/RX2 son los GPIO 17 y 16. EN es la habilitación del chip, que es el reset de esta placa. VIN es el riel de 5 V del USB. Los nombres duplicados llevarían una letra, porque los nombres de pin del catálogo son únicos; esta placa no tiene ninguno.

Los GPIO 6 a 11 no están en ningún header. Son la flash SPI (SD_CLK, SD_DATA0..3 y SD_CMD), y el programa se está ejecutando desde ahí. Una placa que dejara que un sketch los manejara sería una placa que se brickea sola, así que aquí no son pines. crates/parts/src/parts/esp32.rs tiene una prueba que se niega a que aparezcan en un header.

Los GPIO 34 a 39 no tienen driver de salida. En este chip son entradas y nada más: sin push-pull, sin drenador abierto, y tampoco pull-up ni pull-down internos. pinMode(34, OUTPUT) escribe GPIO_ENABLE1_REG, el bit no se queda y el pin permanece en alta impedancia. Cuatro de los seis están en el header (D34, D35, VP, VN). El modelo cuenta cada intento y el componente de la placa reporta el conteo a través de probe (sección 5), porque este es el error que le cuesta a un dueño de ESP32 una tarde entera, y un simulador que lo dejara pasar estaría enseñando lo incorrecto.

Dos pines llevan algo en la placa:

  • El GPIO 2 tiene un LED azul, y es un LED común sobre un pad común: el nivel del pad es la lámpara, nada decodifica nada. También es un pin de strapping, así que el estado del LED de una DevKit real antes de que se ejecute pinMode varía entre placas.
  • El GPIO 0 es el botón BOOT, activo en bajo. Está en el header derecho como D0, así que también se puede cablear; poke lo pone a tierra en la placa.

Eléctrico: cada GPIO con driver de salida maneja push-pull a 3.3 V a través de R_STRONG, queda en alta impedancia, o sube o baja a través de 45 k. Una entrada lee alto a 1.65 V (la mitad del suministro de E/S); una red en disputa (Unknown) lee 0, y una flotante lee ruido, como en la Uno (docs/uno.md sección 1). GPIO0 lee alto cuando nada lo sostiene, por el pull-up propio de la DevKit junto al botón BOOT. 3V3 entrega 3.3 V a R_SUPPLY, VIN entrega 5 V, GND entrega 0 V. EN lleva un pull-up de 10 k hacia 3.3 V y llevarlo por debajo de 1.65 V mantiene el núcleo en reset. Los 100 nF junto a esa resistencia en una DevKit real son el reset de encendido de la placa y no se modelan, así que EN aquí es solo la resistencia.

El orden exacto del serigrafiado de los dos headers es la interpretación que hace este modelo del pinout de la DOIT DevKit V1. Los números de GPIO son los del chip y son de los que depende el firmware; su posición en el header es de lo que depende un diagrama. Si las filas de una DevKit en particular están ordenadas de otra manera (y sí varían entre las placas de 30 pines y las de 36), un circuito dibujado aquí tendría que recablearse en un banco de trabajo, y nada más cambiaría.

2. Mapa de memoria

IRAM (instrucciones) 128 KB en 0x4008_0000 a 0x4009_FFFF
IROM (flash code) 0x400D_0000, read-only, up to 1,310,720 bytes, section 2.1
DROM (flash constants) 0x3F40_0000, read-only, up to 1,310,720 bytes, section 2.1
DRAM (datos) 192 KB en 0x3FFB_0000 a 0x3FFD_FFFF
tope de la pila 0x3FFE_0000
DPORT 0x3FF0_0000, sección 3.7
UART0 0x3FF4_0000, sección 3.3
matriz de GPIO 0x3FF4_4000, sección 3.1
SENS 0x3FF4_8800, sección 3.5
IO_MUX 0x3FF4_9000, sección 3.2
LEDC 0x3FF5_9000, sección 3.6
Timer group 0 0x3FF5_F000, sección 3.4

Aquí cada bloque de periférico ocupa 4 KB.

Two windows, not one, and that is the shape of this chip. The ESP32 has three internal SRAMs, two of which are visible through both the instruction bus and the data bus at different addresses, and SRAM1's 32 KB blocks appear in the opposite order through the two. That alias is not modeled. What is modeled is the pair ESP-IDF itself uses and keeps apart: IRAM for code, DRAM for data. The vectors, the exception entry and the startup code go in the 128 KB at 0x4008_0000; the rest of the code and the constants run from flash (section 2.1); .data, .bss and the stack go in the 192 KB at 0x3FFB_0000. A program that tries to read its own .text through the data bus is refused rather than served, because on the real part that read would have come back through the other window with the blocks in a different order.

Every PT_LOAD segment must land inside one of those two ranges or one of the two flash windows; anything else is refused with the offending address in the message, and the chip is left with no program.

2.1 Flash: code and constants

A real ESP32 runs almost all of a sketch from flash through the cache: code is read at IROM (0x400D_0000) and const data at DROM (0x3F40_0000), and the Arduino IDE's default partition table ("Default 4MB with spiffs") gives the sketch 1,310,720 bytes (0x14_0000) of it. That is the room a sketch has here, and the number the editor prints after a build ("Sketch uses N bytes ... Maximum is 1,310,720 bytes"). It counts what the IDE counts: code, literals, constants, the startup code and the initial values of the variables.

What is modeled: two read-only windows over the loaded image. A fetch or a read from either costs what a fetch from IRAM costs, which is the speed of a warm cache; there is no cache to miss and no MMU, and docs/esp32.md section 6 still says so. A store to a flash window faults, as it does on the chip. The code window shares one buffer with the instruction RAM (so a fetch is one range check whichever it is in), which means the unmapped 192 KB between them reads as zeros here, where the chip would fault; a jump into it still stops the core, since an all-zero word is an illegal instruction.

The link script (firmware/esp32/link.ld) puts .text.vectors, .text.exception, .text.start and anything marked .iram in the instruction RAM and every other function in the code window. Its literal pools sit in front of their own functions, because L32R only reaches 256 KB backwards, and every call out of the startup code goes through a register, because CALL4 and CALL8 reach 128 KB. Global variables are still limited by the data RAM (192 KB here); a program over it is refused with "no room for the stack".

El núcleo se reinicia con el pc en el punto de entrada del ELF y todos los registros de direcciones en cero. Aquí no hay ROM de arranque: las decenas de milisegundos que un ESP32 real pasa en su cargador de primera etapa, las lecturas de flash, el árbol de relojes y la configuración de la caché están ausentes, y firmware/esp32/crt0.S hace explícito el estado que quiere en lugar de suponer lo que dejó una ROM.

3. Registros de periféricos

Solo se implementa el subconjunto de abajo. Cualquier otra cosa dentro de un bloque mapeado de 4 KB lee 0 y cuenta como acceso errante; cualquier cosa fuera de todo bloque es un fallo de acceso.

3.1 Matriz de GPIO (0x3FF4_4000)

Cuarenta pines, así que cada registro con un bit por pin viene en dos mitades: el normal cubre los GPIO 0 a 31 y el que lleva 1 cubre los GPIO 32 a 39 en sus ocho bits bajos.

offset registro
0x00 GPIO_BT_SELECT_REG
0x04 GPIO_OUT_REG
0x08 GPIO_OUT_W1TS_REG
0x0C GPIO_OUT_W1TC_REG
0x10 GPIO_OUT1_REG
0x14 GPIO_OUT1_W1TS_REG
0x18 GPIO_OUT1_W1TC_REG
0x20 GPIO_ENABLE_REG
0x24 GPIO_ENABLE_W1TS_REG
0x28 GPIO_ENABLE_W1TC_REG
0x2C GPIO_ENABLE1_REG
0x30 GPIO_ENABLE1_W1TS_REG
0x34 GPIO_ENABLE1_W1TC_REG
0x38 GPIO_STRAP_REG
0x3C GPIO_IN_REG
0x40 GPIO_IN1_REG
0x44 GPIO_STATUS_REG
0x48 GPIO_STATUS_W1TS_REG
0x4C GPIO_STATUS_W1TC_REG
0x50 GPIO_STATUS1_REG
0x54 GPIO_STATUS1_W1TS_REG
0x58 GPIO_STATUS1_W1TC_REG
0x88 + 4n GPIO_PINn_REG
0x530 + 4n GPIO_FUNCn_OUT_SEL_CFG_REG

Verificado contra el manual de referencia técnica: la dirección base del bloque y cada desplazamiento de esta tabla.

GPIO_PINn_REG, bit 2 PAD_DRIVER pone el pad en drenaje abierto; los bits 7..9 INT_TYPE eligen qué activa la interrupción del pin (0 apagado, 1 flanco de subida, 2 flanco de bajada, 3 cualquier flanco, 4 nivel bajo, 5 nivel alto); el bit 13 PIN_INT_ENA, bit para el núcleo PRO, permite que el pin llegue a la matriz.

GPIO_FUNCn_OUT_SEL_CFG_REG en 256 hace que el pad siga a GPIO_OUT. Los valores 71 a 78 lo entregan a los canales de alta velocidad 0 a 7 del LEDC. Cualquier otro valor selecciona un periférico que no está modelado, y el modelo lo trata como 256 en lugar de inventar un nivel. Un pad que está manejando un canal del LEDC sigue necesitando su controlador de salida activado en GPIO_ENABLE.

No verificado: los índices de señal de la matriz de GPIO 71 a 78 para ledc_hs_sig_out0 a ledc_hs_sig_out7. La tabla de señales de la matriz no es algo que este modelo pueda citar de vuelta, y el número vive en exactamente dos lugares (OUT_SEL_LEDC_HS_SIG en crates/esp32/src/map.rs y GPIO_FUNC_OUT_SEL_LEDC_HS en firmware/esp32/include/esp32.h), así que el modelo y el entorno de ejecución coinciden porque ambos leen la misma constante, no porque alguno lo haya comprobado. GPIO_FUNC_OUT_SEL_GPIO = 256 sí es del manual.

GPIO_STRAP_REG devuelve 0b1101: GPIO 0, 2 y 5 en alto, todo lo demás en bajo, que es como sale de fábrica un WROOM-32. Aquí es una constante, no un registro de lo que estaban haciendo los pines al reiniciarse.

Los seis pines sin controlador de salida (GPIO 34 a 39) aceptan escrituras en su bit ENABLE1 y lo mantienen en cero, y el modelo cuenta el intento (sección 1, sección 5).

3.2 IO_MUX (0x3FF4_9000)

IO_MUX_PIN_CTRL_REG en 0x00, y luego un registro por pad. Bit 7 FUN_WPD, bit 8 FUN_WPU, bit 9 FUN_IE, bits 12..14 MCU_SEL, de los cuales 2 es GPIO normal en este componente. Un pad solo llega a GPIO_IN_REG con su búfer de entrada activado, que es lo que hace el hardware.

El IO_MUX del ESP32 no está indexado por número de GPIO. Los registros están en el orden de pads del paquete y la correspondencia de GPIO a pad es una tabla del manual. La tabla de este modelo es:

GPIO offset GPIO offset GPIO offset GPIO offset
0 0x44 10 0x58 20 0x78 32 0x1C
1 0x88 11 0x5C 21 0x7C 33 0x20
2 0x40 12 0x38 22 0x80 34 0x14
3 0x84 13 0x3C 23 0x8C 35 0x18
4 0x48 14 0x30 24 0x90 36 0x04
5 0x6C 15 0x34 25 0x24 37 0x08
6 0x60 16 0x4C 26 0x28 38 0x0C
7 0x64 17 0x50 27 0x2C 39 0x10
8 0x68 18 0x70 28..31 ninguno
9 0x54 19 0x74

Más creído que verificado. La tabla es la interpretación que hace este modelo del orden de pads, no una página citada. Está en dos lugares, IOMUX_INDEX en crates/esp32/src/map.rs y mokxi_iomux_index[] en firmware/esp32/src/gpio.c, así que el modelo y el entorno de ejecución coinciden entre sí, coincidan o no con el silicio. Los GPIO 28 a 31 no existen en este componente y no tienen registro.

Aquí cada pad arranca en FUN_IE | (2 << 12): GPIO normal con el búfer de entrada activado. Los valores de reinicio por pad del manual difieren (los pines de strapping y de flash arrancan con resistencias pull), y este modelo les da a todos los pines el mismo estado neutral para que un programa que solo escriba GPIO_ENABLE y GPIO_OUT se comporte igual en todos los pines. La sección 6 repite esto como una aproximación, no como una dirección.

3.3 UART0 (0x3FF4_0000)

offset registro
0x00 UART_FIFO_REG
0x04 UART_INT_RAW_REG
0x08 UART_INT_ST_REG
0x0C UART_INT_ENA_REG
0x10 UART_INT_CLR_REG
0x14 UART_CLKDIV_REG
0x1C UART_STATUS_REG
0x20 UART_CONF0_REG
0x24 UART_CONF1_REG

Verificado: la base y cada desplazamiento, los dos bits de reinicio de FIFO y el ancho de los dos contadores de FIFO de abajo. Es la misma IP de UART que la del ESP32-C3 y la del ESP8266, registro por registro, y por eso crates/esp32/src/uart.rs y crates/esp8266/src/uart.rs son dos veces el mismo archivo.

Dos FIFO de 128 bytes. UART_CONF0_REG, bit 17 RXFIFO_RST y bit 18 TXFIFO_RST los vacían: el ESP32 Technical Reference Manual (v5.8), registro 19.9 UART_CONF0_REG, coloca TXFIFO_RST en el bit 18 y RXFIFO_RST en el bit 17. Una versión anterior de este modelo y de firmware/esp32/include/esp32.h los tenía intercambiados. El Serial.begin del entorno de ejecución activa y luego limpia ambos bits juntos, así que el valor que escribe es el mismo en cualquier caso y sus imágenes no se vieron afectadas.

UART_CONF1_REG los bits 0..6 son RXFIFO_FULL_THRHD y los bits 8..14 TXFIFO_EMPTY_THRHD, ambos 96 al reiniciar (registro 19.10); una versión anterior de este modelo tenía campos de nueve bits en 0 y 9, y el entorno de ejecución nunca escribe el registro. UART_CLKDIV_REG los bits 0..19 son la parte entera del divisor (registro 19.6; la parte fraccionaria en los bits 20..23 no está modelada). El divisor divide el reloj APB de 80 MHz y se restablece a 694, que son 115 274 baudios: lo bastante cerca de 115200 para que un monitor no lo note, y exactamente lo que da el número. El ritmo de transmisión antes solo leía doce bits del divisor, así que Serial.begin(9600), cuyo divisor es 8333, enviaba los bytes unas 59 veces demasiado rápido; ahora lee los veinte.

UART_STATUS_REG los bits 0..7 son RXFIFO_CNT y los bits 16..23 TXFIFO_CNT (registro 19.8). Los bits 8..11 y 24..27 encima de ellos son las máquinas de estados del receptor y del transmisor (ST_URX_OUT, ST_UTX_OUT). El modelo devuelve los dos contadores en esas posiciones y 0 en los bits de las máquinas de estados, ya que no ejecuta ninguna de las dos. El entorno de ejecución lee ocho bits, como el manual define los campos. Uno anterior leía diez, lo que aquí daba los mismos números porque los bits superiores leen 0, pero en el silicio habría tomado dos bits de ST_UTX_OUT: el conteo de transmisión marcaría 256 o más mientras un byte viajaba por la línea, y Serial.write, que espera espacio en la FIFO, esperaría para siempre. Las imágenes se recompilaron cuando eso se corrigió, y crates/esp32/tests/contract.rs mantiene las máscaras del header iguales a las del modelo.

Los bytes salen de la FIFO de transmisión al ritmo de los baudios, no al instante. Sin eso, un programa que imprime en un bucle vacía su FIFO tan rápido como la llena, TXFIFO_CNT nunca sube y el firmware que lo revisa antes de escribir nunca tiene que esperar. Con ello, un puerto de 115 200 baudios transmite 11 520 bytes por segundo aquí exactamente como en una mesa de trabajo, y crates/esp32/tests/runtime.rs mide la separación entre dos bytes del ejemplo serial contra los 86.8 us que toma un byte.

3.3a UART1 (0x3FF5_0000) y UART2 (0x3FF6_E000)

El bloque de registros de UART0 dos veces más, en REG_UART_BASE(1) y REG_UART_BASE(2) de ESP-IDF, con los mismos desplazamientos. Verificado contra soc/esp32/register/soc/uart_reg.h de ESP-IDF: las bases, los desplazamientos y los campos de abajo. A diferencia de UART0, no están conectados a ningún canal del host: llegan al circuito solo mediante la matriz GPIO (sección 3.1), un bit a la vez.

  • Enrutamiento por la matriz. La señal 17 de GPIO_FUNCn_OUT_SEL_CFG_REG es U1TXD, la 198 es U2TXD; GPIO_FUNCm_IN_SEL_CFG_REG (en 0x130 + 4m, 256 de ellos) para la señal 17 es U1RXD y para la 198 U2RXD, con SIG_IN_SEL (bit 7) tomando el GPIO en IN_SEL (bits 0..5) y IN_INV_SEL (bit 6) invirtiéndolo. Los números son los de gpio_sig_map.h de ESP-IDF. El INV_SEL (bit 9) de OUT_SEL invierte la salida. Una señal con SIG_IN_SEL en 0 proviene de su pad IO_MUX del chip; esa ruta no está modelada (la línea se lee inactiva), y el entorno de ejecución enruta cada pin por la matriz, que también funciona en todos los pines del silicio.
  • La trama. UART_CONF0_REG PARITY/PARITY_EN (bits 0 y 1), BIT_NUM (2..3, de cinco a ocho bits) y STOP_BIT_NUM (4..5: uno, uno y medio, dos). En el chip, dos bits de parada necesitan el rodeo RS485_CONF.DL1_EN de ESP-IDF; aquí STOP_BIT_NUM en 3 son simplemente dos. RXD_INV (19) y TXD_INV (22) invierten las líneas, ERR_WR_MASK (26) impide que los bytes con error de trama o paridad entren a la FIFO.
  • El reloj. TICK_REF_ALWAYS_ON (bit 27, activo al reiniciar) divide el reloj APB de 80 MHz; en 0, el REF_TICK de 1 MHz, que ESP-IDF admite hasta 250 000 baudios. UART_CLKDIV_REG tiene la parte entera en los bits 0..19 y los dieciseisavos en CLKDIV_FRAG, bits 20..23, ambos modelados: 9600 baudios desde REF_TICK son 104 y 2/16, un bit de 104.125 us, 9603.8 baudios, igual que en el chip.
  • FIFOs y umbrales. 128 bytes en cada dirección. Un byte comienza en cuanto el registro de desplazamiento queda libre y el siguiente sigue a su último bit de parada sin hueco (tx_idle_num en 0, como lo configura ESP-IDF). TXFIFO_CNT cuenta los bytes aún en espera, no el que va saliendo, y ST_UTX_OUT (24..27) y ST_URX_OUT (8..11) informan la ranura en que está cada máquina de estados, 0 cuando está inactiva. El bit 15 de STATUS es la línea de recepción y el bit 31 la de transmisión.
  • Recepción. Una caída en una línea inactiva inicia una trama; el bit de inicio se verifica en su punto medio (un glitch se ignora), cada bit restante se muestrea en medio de su ranura y el byte llega en el punto medio del bit de parada. El núcleo corre hasta un intervalo por delante del circuito, así que el receptor solo muestrea tiempo que el circuito ya ha reportado.
  • Interrupciones. RXFIFO_FULL (bit 0) y TXFIFO_EMPTY (1) contra los umbrales de CONF1, PARITY_ERR (2), FRM_ERR (3), RXFIFO_OVF (4), RXFIFO_TOUT (8) y TX_DONE (14), en las fuentes 35 y 36 de la matriz de interrupciones. RX_TOUT_EN y RX_TOUT_THRHD (bits 31 y 24..30 de CONF1) fijan el tiempo de espera en las unidades que escribe uart_ll_set_rx_tout de ESP-IDF: ocho tiempos de bit por unidad desde APB, un octavo de uno desde REF_TICK.
  • No modelado: control de flujo por hardware y por software, RS-485, IrDA, autobaud, break, el bit de bucle, el detector de comandos AT y los bits de habilitación de reloj y de reinicio del DPORT (ambos UART siempre tienen reloj). Sus registros quedan sueltos.

Un UART al que el programa nunca escribe no le cuesta nada al simulador: no se consulta en ninguna ruta hasta que se escribe uno de sus registros, y crates/esp32/src/bus.rs tiene una prueba que lo dice.

Los Serial1 y Serial2 del entorno de ejecución (firmware/esp32/src/uartn.c) manejan estos como lo hacen el núcleo arduino-esp32 3.x y el controlador de ESP-IDF; docs/help/boards/esp32-devkit.md dice lo que ve un sketch.

3.4 Grupo de temporizadores 0, temporizador 0 (0x3FF5_F000)

El contador de 64 bits detrás de micros() y millis().

offset registro
0x00 TIMG_T0CONFIG_REG
0x04 TIMG_T0LO_REG
0x08 TIMG_T0HI_REG
0x0C TIMG_T0UPDATE_REG
0x10 TIMG_T0ALARMLO_REG
0x14 TIMG_T0ALARMHI_REG
0x18 TIMG_T0LOADLO_REG
0x1C TIMG_T0LOADHI_REG
0x20 TIMG_T0LOAD_REG
0x98 TIMG_INT_ENA_TIMERS_REG
0x9C TIMG_INT_RAW_TIMERS_REG
0xA0 TIMG_INT_ST_TIMERS_REG
0xA4 TIMG_INT_CLR_TIMERS_REG

Verificado: la dirección base del bloque. Supuesto más que verificado: cada desplazamiento de esta tabla. La base es la del manual; la distribución interna es de este modelo, y es la misma en crates/esp32/src/map.rs y en firmware/esp32/include/esp32.h.

T0CONFIG bit 31 EN, bit 30 INCREASE, bit 29 AUTORELOAD, bits 13..28 DIVIDER, bit 10 ALARM_EN. El entorno de ejecución pone DIVIDER en 80, que es un pulso por microsegundo desde el reloj APB de 80 MHz.

La lectura es fijar y luego leer, como lo exige el hardware: escribe T0UPDATE, luego lee T0HI y T0LO. El contador no se cuenta. Es el tiempo simulado dividido por el divisor, como lo es el SYSTIMER del C3, así que no tiene nada contra qué desviarse y el firmware que espera activamente usando micros() mide exactamente el tiempo que el resto del circuito vio pasar.

La alarma está implementada y TIMG_INT_RAW se eleva cuando el contador la supera, pero ninguna línea de interrupción sale de este bloque. Nada la enruta hacia la matriz de interrupciones. El tic de milisegundos del modelo proviene del CCOMPARE0 del propio núcleo (sección 4), que es un registro del núcleo conectado a una interrupción de CPU fija y por tanto no depende de ninguna dirección que este modelo tuviera que adivinar. TIMG_INT_ST todavía se puede sondear y limpiar.

El temporizador 1 del grupo 0 y todo el grupo 1 están ausentes; el watchdog del grupo 0 es el de la sección 3.9.

3.5 SENS: ADC1, una sola conversión (0x3FF4_8800)

ADC1 en modo de una sola conversión: la ruta adc1_get_raw y el analogRead del núcleo Arduino usan esta parte, y nada más.

offset registro bits
0x00 SENS_SAR_READ_CTRL_REG se guarda, se lee de vuelta; el tiempo de conversión aquí es fijo
0x34 SENS_SAR_ATTEN1_REG dos bits de atenuación por canal, el canal n en los bits 2n..2n+1
0x54 SENS_SAR_MEAS_START1_REG bits 0..15 MEAS1_DATA_SAR (el resultado, solo lectura), bit 16 MEAS1_DONE_SAR, bit 17 MEAS1_START_SAR, bit 18 MEAS1_START_FORCE, bits 19..26 SAR1_EN_PAD (un bit por canal), bit 31 SAR1_EN_PAD_FORCE

Verificado: la dirección base. Creído más que verificado: los tres desplazamientos y todas las posiciones de bits dentro de ellos. Son la interpretación del modelo sobre el bloque SENS, en el mismo sentido en que la sección 3.5 de docs/esp32c3.md marca los desplazamientos SAR del propio C3. El firmware compilado aquí concuerda con el modelo, ya sea que concuerde o no con el silicio.

Una conversión: pon la atenuación en ATTEN1, activa START_FORCE y EN_PAD_FORCE, pon el bit del canal en SAR1_EN_PAD, activa MEAS1_START_SAR, espera MEAS1_DONE_SAR y lee el dato. Una conversión toma 5 us de tiempo simulado, algo que el firmware realmente espera.

Ocho canales, y en el ESP32 no son GPIO n:

canal 0 1 2 3 4 5 6 7
GPIO 36 37 38 39 32 33 34 35

El canal 0 es SENSOR_VP y el canal 3 es SENSOR_VN; 37 y 38 no están conectados en un WROOM-32, así que los cuatro que el DevKit expone como números ordinarios son los canales 4 a 7. Esa tabla es del manual.

El resultado son doce bits del voltaje neto en el momento en que comenzó la conversión. A 0, 2.5 y 6 dB es la línea recta nominal de la hoja de datos, round(4095 x Vin / Vfull) acotada, con escala completa de 1.1 V, 1.5 V y 2.2 V. A 11 dB, el valor predeterminado del núcleo de Arduino, es la curva cruda del componente real (CURVE_11DB en crates/esp32/src/adc.rs): 0 hasta unos 80 mV, casi lineal por la parte media, curvándose hacia arriba cerca del máximo y saturándose en 4095 a partir de unos 3.15 V. La escala completa nominal de 3.9 V no es lo que hace una lectura cruda; la hoja de datos solo promete precisión de 150 a 2450 mV a 11 dB, y la cuenta cruda de un componente típico se agota bastante antes de 3.9 V. Así, un potenciómetro conectado al riel de 3.3 V lee de 0 a 4095, llegando a 4095 un poco antes del final de su recorrido, medio riel (1.65 V) lee unos 1890, y map(analogRead(pin), 0, 4095, 0, 180) logra que un servo gire todo el recorrido. Los puntos son el ajuste de cuarto orden de uso común sobre ESP32s medidos, invertido; la calibración eFuse de una unidad los mueve unos puntos porcentuales, y eso no está modelado. analogReadMilliVolts invierte la misma curva, tal como lo hace la calibración del núcleo, así que lee unos 1650 a 1.65 V. Un canal sin nada conectado a su pin vaga, como lo hace una entrada flotante (docs/uno.md sección 1).

La función de transferencia del conversor real se curva en ambos extremos y se corrige con la curva de calibración eFuse. Nada de eso está modelado: esta es una línea recta. La sección 6 la lista como una aproximación.

El ADC2 (que un ESP32 real comparte con el WiFi), la ruta de DMA y tabla de patrones, el controlador digital, los eFuse de calibración, la referencia interna, el sensor táctil y el sensor de efecto Hall están todos ausentes.

3.6 LEDC, el grupo de alta velocidad (0x3FF5_9000)

El controlador LED PWM. El grupo de alta velocidad es el que alcanzan ledcSetup, ledcAttachPin y ledcWrite con los canales 0 a 7, y es el que analogWrite usa aquí: cuatro temporizadores y ocho canales.

offset registro bits
0x00 + 0x14n LEDC_HSCHn_CONF0_REG bits 0..1 TIMER_SEL, bit 2 SIG_OUT_EN, bit 3 IDLE_LV, bit 4 PARA_UP (se guarda; un ciclo útil escrito aquí surte efecto de inmediato)
0x04 + 0x14n LEDC_HSCHn_HPOINT_REG bits 0..19 HPOINT: la cuenta en la que comienza el pulso
0x08 + 0x14n LEDC_HSCHn_DUTY_REG bits 0..24 DUTY: el ancho del pulso en dieciseisavos de cuenta
0x0C + 0x14n LEDC_HSCHn_CONF1_REG el hardware de desvanecimiento del ciclo útil: se guarda, se lee de vuelta y no desvanece nada
0x10 + 0x14n LEDC_HSCHn_DUTY_R_REG el ciclo útil tal como está, solo lectura
0x140 + 8n LEDC_HSTIMERn_CONF_REG bits 0..4 DUTY_RES, de 1 a 20 bits (0 es un temporizador que nadie configuró y no cuenta nada), bits 5..22 CLK_DIV, bit 23 PAUSE, bit 24 RST
0x144 + 8n LEDC_HSTIMERn_VALUE_REG el contador, solo lectura
0x180 LEDC_INT_RAW_REG bit n = el temporizador n se desbordó
0x184 LEDC_INT_ST_REG sin máscara y habilitado
0x188 LEDC_INT_ENA_REG se guarda; ninguna línea llega al núcleo
0x18C LEDC_INT_CLR_REG escribe 1 para limpiar
0x190 LEDC_CONF_REG bits 0..1 APB_CLK_SEL, 1 = el reloj APB de 80 MHz, la única fuente modelada
0x1FC LEDC_DATE_REG lee 0x1605_3100

Verificado: la dirección base del bloque. Creído más que verificado: toda la distribución interna: el paso entre canales, el bloque de temporizadores en 0x140 y los registros de interrupción y configuración a partir de 0x180.

Un temporizador cuenta 2^DUTY_RES cuentas a 80 MHz dividido entre CLK_DIV, un número Q10.8 de relojes APB por cuenta:

f = 80e6 / ((CLK_DIV / 256) * 2^DUTY_RES)

así que 5 kHz a ocho bits es DUTY_RES 8 con CLK_DIV 16000, exactamente. Un canal elige un temporizador, una cuenta de inicio HPOINT y un ciclo útil, y su salida está en alto desde HPOINT durante DUTY >> 4 cuentas, dando la vuelta en la cima del período. Un ciclo útil de 0 es un bajo constante y un ciclo útil de 2^DUTY_RES << 4 es un alto constante sin ningún flanco, razón por la cual el núcleo Arduino convierte ledcWrite(pin, 255) a ocho bits en un ciclo útil de 256 en lugar de 255, que dejaría una muesca de una cuenta cada período.

Un canal llega a un pad mediante la matriz GPIO: activa el bit GPIO_ENABLE del pad y apunta su GPIO_FUNCn_OUT_SEL_CFG_REG a 71 + channel (sección 3.1, y ese índice es el no verificado).

El contador no avanza paso a paso: es una función cerrada del tiempo simulado, y lo mismo ocurre con el momento de su próximo flanco. Un núcleo estacionado en waiti por tanto no cuesta nada mientras corre un PWM, y la placa se despierta para los flancos y para nada más. crates/esp32/tests/runtime.rs mide el período del ejemplo fade contra el 1 ms de 1 kHz dentro de 5 us.

No modelado: el grupo de baja velocidad (el ESP32 tiene uno, con sus propios cuatro temporizadores, ocho canales y un reloj lento; nada en el runtime lo usa), el hardware de desvanecimiento del ciclo útil, el contador de desbordamiento propio de un canal, fuentes de reloj distintas de APB, y la línea del LEDC hacia la matriz de interrupciones: LEDC_INT_RAW_REG se puede sondear y limpiar pero nunca llega al núcleo.

3.7 DPORT y la matriz de interrupciones (0x3FF0_0000)

En el ESP32 un periférico no tiene una interrupción de CPU fija. Tiene un número de fuente, y el registro de mapa de la matriz para esa fuente indica cuál de las 32 interrupciones del núcleo activa. Por eso attachInterrupt aquí son tres escrituras en lugar de una: configurar el pin, enrutar la fuente, desenmascarar la interrupción de CPU.

offset registro
0x104 + 4n DPORT_PRO_..._INTR_MAP_REG para la fuente n

96 fuentes. Un registro de mapa guarda un número de interrupción de la CPU en sus cinco bits bajos; una fuente mapeada a 0 genera la interrupción 0, que nada habilita, así que no pasa nada, que es lo que también hace el hardware real y es la forma en que se desactiva una fuente.

Verificado: DPORT_BASE = 0x3FF0_0000. Supuesto más que verificado: el desplazamiento 0x104 del arreglo de mapa, y los dos números de fuente que este modelo enruta:

fuente número
GPIO 22
UART0 34
UART1 35
UART2 36

Los de UART1 y UART2 están verificados contra el orden de soc/esp32/include/soc/interrupts.h de ESP-IDF, que también pone GPIO en 22 y UART0 en 34. Solo estas fuentes, y el watchdog del grupo de temporizadores 0 (sección 3.9), llegan a algo. Todos los demás registros de mapa se guardan, se leen de vuelta y no enrutan nada, porque nada más en este modelo genera una interrupción. El resto de DPORT (el control de caché y MMU, los registros de control de la CPU APP, las compuertas de reloj y reinicio de los periféricos, la arbitrariedad de DMA) está ausente.

3.8 Buzón de red de Mokxi (0x3FEF_E000)

Este bloque no es del ESP32. Todas las demás direcciones en este documento son del chip, citadas del manual de referencia técnica, y una imagen compilada contra ellas es una imagen para un WROOM-32 real. Este es propio de Mokxi: la red simulada de crates/net, en el hueco que el bus de datos deja entre las ventanas de memoria externa (que terminan en 0x3FBF_FFFF) y la ventana de periféricos (que empieza en DPORT, 0x3FF0_0000), un rango que el chip reserva y en el que no responde nada, de modo que una imagen que lo use falla en silicio en lugar de leer el registro de otro periférico. Esa falla es la respuesta honesta, porque lo que está detrás de este bloque no existe en el chip.

El bloque no genera ninguna interrupción. Todas las demás fuentes de aquí llegan al núcleo a través de la matriz de interrupciones de la sección 3.7, y un número de fuente de la matriz es del chip; no hay un número honesto que darle a un periférico que el chip no tiene, así que el buzón no recibe ninguno. NET_INT_RAW_REG sigue pudiendo leerse, el firmware hace sondeo, y un núcleo estacionado en waiti sigue despertándose cuando la red tiene algo que decir, igual que se despierta por un flanco de PWM.

Aquí no hay radio, ni 802.11, ni internet real. Nada en el modelo transmite, escanea, asocia, cifra o abre un socket: una contraseña se compara como cadena, un nombre que no esté bajo .mokxi no se resuelve, y los tres orígenes que la red sirve son funciones en crates/net/src/http.rs. El buzón tiene la forma de la costura real en vez de una ficción sobre una MAC: en un ESP32 real el hardware de WiFi es un blob binario cerrado con una interfaz de comandos, y el WiFi.h de Arduino termina al otro lado de uno de estos. docs/wifi.md es el contrato de lo que hay detrás; esta sección son solo los registros.

Un registro de comandos, un registro de estado, un anillo de 4096 bytes en cada sentido y un bit de interrupción. Escribir NET_CMD_REG ejecuta el comando; un comando que tarda tiempo simulado activa BUSY y lo limpia, con DONE en NET_INT_RAW_REG, cuando termina.

offset nombre bits
0x00 NET_ID_REG lee 0x494B4F4D, y nada más lo hace. Un sketch que quiera saber si está en Mokxi lee esto; en silicio el acceso falla
0x04 NET_CMD_REG escribe un código de comando (tabla abajo); la escritura lo ejecuta
0x08 NET_ARG_REG una palabra de argumento, leída de vuelta: el puerto para LISTEN, el estado para REPLY
0x0C NET_STATUS_REG bit 0 BUSY, bit 1 ERR, bit 2 RX_READY, bit 3 LINK, bit 4 SERVE, bits 8..11 STATE
0x10 NET_RESULT_REG lo que respondió el último comando
0x14 NET_INT_RAW_REG bit 0 DONE, bit 1 EVENT
0x18 NET_INT_ENA_REG los mismos dos bits
0x1C NET_INT_CLR_REG escribe 1 para limpiar, los mismos dos bits
0x20 NET_TX_LEN_REG bytes preparados en el anillo de salida
0x24 NET_TX_DATA_REG escritura: empuja un byte (bits 0..7) al anillo de salida
0x28 NET_RX_LEN_REG bytes en espera en el anillo de entrada
0x2C NET_RX_DATA_REG lectura: saca un byte del anillo de entrada, 0 cuando está vacío
0x30 NET_RING_LEN_REG capacidad de cada anillo en bytes, para que el firmware no tenga que fijar 4096 a mano
0x40 NET_BT_CMD_REG Bluetooth: escribe un código de comando de Bluetooth (docs/bluetooth.md); la escritura lo ejecuta
0x44 NET_BT_ARG_REG Bluetooth: una palabra de argumento, leída de vuelta; un evento deja aquí su número
0x48 NET_BT_RESULT_REG Bluetooth: lo que respondió el último comando de Bluetooth
0x4C NET_BT_STATUS_REG bit 0 CLASSIC_ON, bit 1 CLASSIC_LINK, bit 2 EVENT, bit 3 BLE_ADV, bit 4 BLE_LINK, bit 5 BT_ERR, bit 8 HAS_CLASSIC, bit 9 HAS_BLE
0x50 NET_BT_TX_LEN_REG Bluetooth: bytes preparados en su propio anillo de salida
0x54 NET_BT_TX_DATA_REG Bluetooth: escritura: empuja un byte a ese anillo
0x58 NET_BT_RX_LEN_REG Bluetooth: bytes en espera en su propio anillo de entrada
0x5C NET_BT_RX_DATA_REG Bluetooth: lectura: saca un byte, 0 cuando está vacío

Los ocho registros NET_BT_ son la mitad Bluetooth del bloque, con anillos propios para que una devolución de llamada de Bluetooth nunca toque un cuerpo HTTP: Bluetooth Classic y LE, ambos presentes en el ESP32 clásico. Detrás de ellos tampoco hay radio; docs/bluetooth.md es su contrato.

STATE es dónde está la estación: 0 inactiva, 1 iniciando, 2 conectando, 3 conectada, 4 falló, 5 no existe esa red. NET_CMD_STATUS convierte lo mismo en el código wl_status_t de Arduino que un sketch lee de WiFi.status().

NET_CMD_REG nombre qué hace
0 NOP nada
1 RESET desconecta, descarta ambos anillos, descarta cualquier solicitud
2 CONNECT el anillo de salida contiene ssid\0password; activa BUSY de uno a tres segundos
3 DISCONNECT descarta la asociación y la dirección
4 STATUS NET_RESULT_REG = el código wl_status_t
5 IP NET_RESULT_REG = la dirección asignada, primer octeto en el byte bajo
6 RSSI NET_RESULT_REG = la señal en dBm, con signo extendido
7 SSID el anillo de entrada recibe el nombre del punto de acceso
8 MAC el anillo de entrada recibe los seis bytes MAC de la placa
9 REQUEST el anillo de salida contiene method\0url\0headers\0body; activa BUSY
10 POLL NET_RESULT_REG = 0 mientras está en curso, luego el estado HTTP, o un error negativo con ERR arriba; el cuerpo llega al anillo de entrada
11 LISTEN escucha en el puerto de NET_ARG_REG
12 ACCEPT NET_RESULT_REG = 1 y el anillo de entrada contiene method\0path\0query\0body, o 0 cuando no hay nada en espera
13 REPLY responde la solicitud aceptada con el estado en NET_ARG_REG; el anillo de salida contiene content-type\0body
14 STOP deja de escuchar
15 WL_GPIO_SET maneja los GPIO propios del componente inalámbrico desde NET_ARG_REG. No esta placa: la radio de este componente no tiene tal pin, así que pone ERR y no maneja nada. Es la ruta que sigue el LED integrado de una Pico W (docs/picow.md sección 3.8)
16 WL_GPIO_GET se leen de vuelta, y el mismo ERR aquí
17 BLYNK una operación en el servidor Blynk simulado, la operación en NET_ARG_REG y sus campos en el anillo de salida; se responde de inmediato en NET_RESULT_REG, con ERR arriba sin pasar por la red (docs/wifi.md, "Blynk")
19 ETH Ethernet por cable (firmware/include/ETH.h), la operación en NET_ARG_REG: 1 levanta el enlace por un cable simulado, sin SSID y sin contraseña, y se une 1.5 s después con el mismo contrato de arrendamiento; 2 pone 1 en NET_RESULT_REG cuando el enlace es (o fue por última vez) el cableado. Hay un solo enlace: STATUS, IP y cada petición lo leen sin importar cómo se levantó
20 SOFTAP el AP por software (crates/net/src/softap.rs, docs/wifi.md), la operación en NET_ARG_REG: 1 lo levanta (el anillo de salida ssid\0password\0 y el byte de canal; NET_RESULT_REG 1, o 0 con ERR por un nombre vacío o una contraseña de uno a siete caracteres), 2 lo baja, 3 lo configura (dirección, puerta de enlace y máscara de red, cuatro bytes cada una), 4 su dirección (0 mientras está inactivo), 5 las estaciones conectadas, 6 las conexiones, desconexiones y el bit de actividad que el entorno de ejecución convierte en eventos, 7 y 8 el servidor DNS del portal cautivo iniciándose (el nombre, un byte cero, la dirección) y deteniéndose, 9 su nombre hacia el anillo de entrada, 10 la dirección del celular, 11 el Host de la petición que se atiende hacia el anillo de entrada. La única estación es el celular del panel Web

Los códigos negativos de POLL: -1 el nombre no se resuelve, -2 la estación no está asociada, -3 https:// y TLS no se simula, -4 un cuerpo más largo que el anillo, -5 una URL que esta red no puede analizar, -6 ya hay una petición en curso. firmware/include/HTTPClient.h los convierte en los códigos con forma de Arduino con los que un sketch se compara, y docs/wifi.md lista la correspondencia.

Tiempos, todos propios de este modelo y todos indicados en docs/wifi.md: una asociación tarda entre uno y tres segundos, decididos a partir del SSID para que una lección tarde lo mismo las dos veces; una contraseña errónea se convierte en WL_CONNECT_FAILED a los cinco segundos; una petición a un origen simulado regresa 60 ms después; una petición al propio servidor del sketch que el sketch nunca responde la cierra la red con un 504 a los diez segundos.

3.9 El watchdog del grupo de timers 0 y los reinicios de RTC_CNTL (0x3FF5_F048, 0x3FF4_8000)

El watchdog principal del grupo de timers 0, como el del C3 (docs/esp32c3.md sección 3.9) pero con la disposición del ESP32: una escritura surte efecto de inmediato, el bit de interrupción es el bit 2 de TIMG_INT_* (0x98..0xA4), y llega al núcleo por la matriz de interrupciones como la fuente 16 (el entorno de ejecución la mapea a la interrupción 17 de la CPU). RTC_CNTL (0x3FF4_8000, los dos kilobytes debajo de SENS): RTC_CNTL_RESET_STATE_REG en 0x34, los registros de almacenamiento en 0x4C..0x58 y 0xB0..0xBC, y los dos reinicios por software. El grupo de timers 1 no se modela.

El entorno de ejecución corre el watchdog de tareas de ESP-IDF sobre el watchdog del grupo de timers 0, como lo hace ESP-IDF (firmware/src/main.cpp): tics de 500 µs, la etapa 0 una interrupción al agotarse el tiempo y la etapa 1 un reinicio del sistema al doble, iniciado antes de setup() a 5 s con un pánico, vigilando la tarea de reposo del núcleo 0. El sketch corre en el núcleo 1, cuya tarea de reposo no se vigila a menos que lo pida (enableCore1WDT()), así que un bucle que nunca cede sigue corriendo, como en la placa. La interrupción imprime las líneas de ESP-IDF ("E (…) task_wdt: Task watchdog got triggered. …", las tareas, "Aborting.", la línea de aborto y "Rebooting..."), deja la pista ESP_RST_TASK_WDT de ESP-IDF en el registro de almacenamiento del RTC y reinicia la CPU mediante el reinicio por software, así que esp_reset_reason() devuelve 6 después. esp_task_wdt_*, enableLoopWDT() y enable/disableCore0WDT() actúan sobre él. El watchdog del grupo de timers 1 se modela igual y nada en el entorno de ejecución lo arma: el watchdog de interrupciones no se simula.

4. El núcleo: qué ABI, y cómo llega una interrupción

crates/xtensa-core es un intérprete de Xtensa LX escrito a partir de la referencia Xtensa Instruction Set Architecture y de las codificaciones que producen las cadenas de herramientas de Espressif. Nada en él deriva de QEMU, de ESP-IDF, de los núcleos de Arduino ni de ningún otro emulador. xtensa-esp32-elf-as se usó como se usa un instrumento de banco de trabajo (ensamblar una instrucción, leer la codificación, escribir el decodificador contra lo que salió), y crates/xtensa-core/tests/encoding.rs conserva esas mediciones, de modo que el decodificador se puede verificar contra la evidencia y no contra una tabla que alguien tecleó.

La ABI con ventana de registros, y no hubo elección. xtensa-esp32-elf-gcc emite entry, call8 y retw.n, y no tiene para nada una opción -mabi=call0. Así que la configuración LX6 de aquí tiene sesenta y cuatro registros de direcciones físicos y la ventana de registros, con ENTRY, RETW, ROTW, MOVSP, L32E/S32E y las excepciones de desbordamiento y subdesbordamiento de la ventana por sus propios vectores. (El LX106 del ESP8266 tiene dieciséis registros y no tiene ventana, así que su compilador emite call0; la sección 4 de docs/esp8266.md es la otra mitad de esto.)

What the LX6 configuration has that the LX106 does not: hardware divide (QUOS, QUOU, REMS, REMU), the 32-bit high multiply, MIN/MAX, SEXT, CLAMPS, the zero-overhead loop (LOOP, LOOPNEZ, LOOPGTZ) and the two atomic loads. Each of those differences was put to the assembler of the toolchain that builds for that chip; the encodings that came back are in tests/encoding.rs.

Modelado: cargas y almacenamientos en todos los anchos con la excepción de alineación, todo el conjunto de saltos y saltos condicionales, CALL0/CALL4/CALL8/CALL12 y sus formas indirectas, L32R, MOVI, las instrucciones de densidad (.n), la ALU entera, MUL16/MULL/MULUH/MULSH, los registros especiales y WAITI.

Vectores. VECBASE es un registro especial y la tabla es la del ISA:

desplazamiento desde VECBASE vector
0x000 WindowOverflow4
0x040 WindowUnderflow4
0x080 WindowOverflow8
0x0C0 WindowUnderflow8
0x100 WindowOverflow12
0x140 WindowUnderflow12
0x300 KernelException (PS.UM en cero)
0x340 UserException (PS.UM en uno), y toda interrupción de nivel 1, con EXCCAUSE 4
0x3C0 DoubleException (PS.EXCM ya en uno)

Cuál de los tres manejadores de desbordamiento se toma lo decide qué tan ancho es el marco que se derrama, no qué tanto rotó la ventana para alcanzarlo: WindowOverflow4 derrama a través de a5, el de 8 a través de a9 y el de 12 a través de a13, y esos son los punteros de pila una, dos y tres ventanas más adelante. Un CALL8 escribe a8 antes de que el ENTRY de la función llamada llegue a ejecutarse, así que la regla de desbordamiento está en el acceso al registro y no solo en ENTRY. Ambos eran errores que el propio firmware de esta placa encontró, y ambos están corregidos en el núcleo.

Interrupciones. INTENABLE enmascara; PS.INTLEVEL filtra. Solo se modela el nivel 1: los niveles de interrupción mayores que uno, la NMI y la interrupción de depuración no. Las interrupciones de nivel 1 son 0 a 10, 12, 13, 17 y 18, máscara 0x0006_37FF. Verificado contra el ESP32 Technical Reference Manual (v5.8), tabla 8.3-2 "CPU Interrupts": 19, 20 y 21 son disparadas por nivel en nivel 2, así que no están en la máscara. Una versión anterior de este modelo las incluía (0x003E_37FF), lo que habría despachado una línea de nivel 2 en el nivel 1; crates/xtensa-core/tests/interrupts.rs ahora ajusta la máscara a la tabla. El runtime solo habilita 6 y 13 (sección 7), ambos de nivel 1 en la misma tabla, así que ningún firmware dependía de la máscara antigua.

CCOUNT y CCOMPARE. El LX6 tiene tres comparadores. Se supone que la interrupción de CPU que activa cada uno es:

comparador interrupción de CPU
CCOMPARE0 6
CCOMPARE1 15
CCOMPARE2 16

Verificado contra la misma tabla 8.3-2, cuyas interrupciones internas 6, 15 y 16 son "Timer.0", "Timer.1" y "Timer.2". La tabla también pone 15 en nivel 3 y 16 en nivel 5, así que aquí solo se toma CCOMPARE0. El runtime usa CCOMPARE0 y la interrupción de CPU 6 para su tick, que es la que usa todo port de Xtensa.

Un WSR a un CCOMPARE es lo que arma el comparador, y escribirlo también limpia la interrupción pendiente. Esa es la regla del hardware y es la regla aquí. Dos detalles del modelo, ambos deliberados y ambos porque el tiempo simulado no es un reloj escalonado:

  • El hardware real activa la interrupción en el único ciclo en que CCOUNT es igual al comparador y la mantiene hasta que se vuelve a escribir el comparador. Aquí la comparación es "ya alcanzó o pasó", porque un núcleo detenido en WAITI deja de retirar instrucciones mientras el tiempo sigue avanzando y de otro modo saltaría justo el único ciclo que importa. Para un manejador que fija el próximo vencimiento (que es todo uso de este registro), ambos se comportan igual.
  • Un vencimiento que ya pasó no queda armado. Un manejador tarda varios cientos de ciclos, así que un comparador fijado en "ahora" queda en el pasado antes de que el manejador regrese, se dispara de inmediato otra vez, y el programa interrumpido recibe una instrucción a la vez. Tres segundos de blink costaban 200 millones de instrucciones antes de esa regla y menos de medio millón después.

MOVSP no lanza la excepción Alloca aquí; hace lo que la excepción y su manejador hacen juntos. En el hardware MOVSP atrapa cuando la ventana del que llama ya se derramó (WINDOWSTART claro para WINDOWBASE - 1 a - 3), y el manejador copia la del que llama, a0..a3, el área de guardado base en los 16 bytes por debajo del puntero de pila antiguo, a por debajo del nuevo antes del movimiento. Este modelo hace esa copia en su lugar y luego mueve (crates/xtensa-core/src/cpu.rs, movsp). El código sí depende de ello: clang-v3 enmarca cada llamada que pasa argumentos por la pila con movsp a1, a8, y antes de que se hiciera la copia, un sketch que llamaba WiFi.scanNetworks() (ocho argumentos con this) se caía en el desbordamiento de ventana al regresar. Igual cualquier setup() largo que llamara sprintf con más de seis argumentos tras suficientes impresiones para derramar a su llamador: todo se imprimía, luego exccause=9 en WindowUnderflow8 cuando setup() regresaba (en el ESP32 y el S3; el C3 y el Pico no tienen ventana). crates/xtensa-core/tests/alloca.rs ejecuta CALL8 y CALL12 marcos que cada uno mueven su puntero de pila hacia abajo y hacia arriba con MOVSP alrededor de una llamada, a cada profundidad de 0 a 40, y web/src/compile/xtensa-movsp.test.ts ejecuta los sketches en ambas placas.

The FPU is modeled. The ESP32's single-precision coprocessor runs on this model (crates/xtensa-core/tests/fpu.rs): the loads and stores (LSI, SSI, LSX, SSX and their post-incrementing forms), ADD.S, SUB.S, MUL.S, the fused MADD.S, MSUB.S and MADDN.S, the conversions (FLOAT.S, UFLOAT.S, TRUNC.S, UTRUNC.S, ROUND.S, FLOOR.S, CEIL.S), the compares into the boolean registers with BT, BF, MOVT and MOVF, the conditional moves, WFR, RFR, FCR and FSR, and the division and square-root steps libgcc's __divsf3 and newlib's sqrtf are built from, which return the correctly rounded IEEE answer. Arithmetic rounds to nearest whatever FCR says and sets no FSR flags. On this bare-metal model the coprocessor is on from reset, as there is no OS to turn it on at first use; the system model (docs/micropython-esp32.md) still waits for CPENABLE. So a float in an example built by Espressif's GCC through firmware/esp32/build.sh runs and prints the right number, and the browser's soft-float builds (-Xclang -target-feature -Xclang -fp, calls into mokxi_float.c) are unchanged.

5. Modelo de tiempo, sonda, poke y el canal del host

La CPU corre a 240 MHz, una instrucción por ciclo, y el bus de periféricos a 80 MHz. 240 MHz no es un número entero de picosegundos por ciclo, así que el tiempo de la instrucción k se recalcula como ps_for(k) = k * 12500 / 3 en lugar de acumularse (a diferencia de como se hace en el Blue Pill y el XIAO), y una porción de 2400 instrucciones es exactamente 10 us.

Dentro de una porción, el conteo de instrucciones es el reloj: una lectura de temporizador, un byte de UART y un cambio de pin caen todos en la instrucción que los causó, no al final de la porción. El componente de placa convierte eso en llamadas a drive_after en los mismos desplazamientos, así que dos escrituras separadas por cuatro instrucciones realmente están 16.7 ns aparte en la red. RSR.CCOUNT lee ese mismo reloj.

Un núcleo detenido en WAITI no cuesta nada: la placa pide despertarse en el más temprano entre su próximo vencimiento de CCOMPARE y su próximo flanco de LEDC, y un cambio de pin o un byte del host también lo despiertan.

Una lectura de las entradas después de una escritura a las salidas espera al circuito. El núcleo corre una porción adelantado al circuito, y GPIO_IN_REG guarda los niveles muestreados cuando comenzó la porción. Así que, una vez que una escritura de GPIO o de IO_MUX movió un pad dentro de una porción, una carga de GPIO_IN_REG o GPIO_IN1_REG no se responde: el bus devuelve BusError::Retry, xtensa-core detiene el núcleo antes de esa instrucción sin haber hecho nada de ella, la porción termina ahí, la placa pone el movimiento en la red, y la siguiente porción muestrea las entradas y ejecuta la lectura. Un barrido de teclado (activar una columna, leer las filas) y un cable de un pin a otro leen ambos lo que el circuito hizo con la escritura. Las placas AVR se detienen antes de tal lectura de la misma forma.

probe es una máscara de bits, no un nivel, porque esta placa tiene cuatro cosas que valen la pena mencionar:

bit significado
1 en ejecución
2 estacionado en waiti
4 el LED azul del GPIO 2 está encendido
8 el firmware intentó hacer que uno de los GPIO 34 a 39 fuera una salida y se lo rechazaron

0 significa que no hay programa, que está retenido en reset o que se colgó. El bit 8 no depende de que esté en ejecución: un programa al que ya se le rechazó una salida sigue rechazado, y la placa sigue diciéndolo.

poke: 1 retiene BOOT (GPIO 0 en bajo), 0 lo libera; 2 retiene EN, 3 lo libera.

El canal del host. host_write pone bytes en el FIFO de recepción del UART0 (lo que no cabe en sus 128 bytes se retiene y va llegando con un byte de separación a medida que el sketch lee, igual que en una placa real los bytes van entrando a la velocidad de baudios en el búfer circular del núcleo de Arduino, en lugar de descartarse); host_read toma los bytes que ya salieron de su FIFO de transmisión. Eso es Serial en un sketch y el monitor serie en la interfaz. Para la interfaz los bytes son UTF-8 y para el modelo son opacos. El conector micro-USB de una DevKit va a un puente CP2102 o CH340 en este puerto; el puente en sí no está modelado, y el auto-reset por DTR/RTS tampoco.

Colapso. 1000 trampas consecutivas sin progreso y el núcleo se declara colapsado y se detiene, con registro del lugar donde murió.

6. De lo que este modelo está seguro, y de lo que no

Tres grupos, y luego un cuarto para las aproximaciones que no tienen que ver con direcciones. Esta sección existe porque un modelo de placa que adivina una dirección en silencio es peor que uno que dice que no lo sabía.

Tomado del manual de referencia técnica

DPORT_BASE 0x3FF0_0000, UART0_BASE 0x3FF4_0000, GPIO_BASE 0x3FF4_4000, SENS_BASE 0x3FF4_8800, IOMUX_BASE 0x3FF4_9000, LEDC_BASE 0x3FF5_9000 y TIMG0_BASE 0x3FF5_F000. Cada desplazamiento de registro dentro de la matriz GPIO y dentro del UART0, y el RXFIFO_RST del UART_CONF0_REG (bit 17) y el TXFIFO_RST (bit 18) del registro 19.9, el RXFIFO_CNT y el TXFIFO_CNT de ocho bits del UART_STATUS_REG (registro 19.8), los umbrales del UART_CONF1_REG (registro 19.10) y el divisor de veinte bits del UART_CLKDIV_REG (registro 19.6). La máscara de interrupciones de CPU de nivel 1 0x0006_37FF (0 a 10, 12, 13, 17 y 18) y las interrupciones CCOMPARE 6, 15 y 16, ambas de la tabla 8.3-2 (sección 4). La ventana de IRAM en 0x4008_0000 y la ventana de DRAM en 0x3FFB_0000. GPIO_FUNC_OUT_SEL = 256 para "seguir a GPIO_OUT". El valor 2 de MCU_SEL para GPIO simple. El mapa de canales del ADC1: los canales 0 a 7 son los GPIO 36, 37, 38, 39, 32, 33, 34, 35. Los cuarenta GPIO, que el 6 al 11 son de la flash y que el 34 al 39 no tienen controlador de salida. El LED azul del GPIO 2 y el botón BOOT del GPIO 0. Los desplazamientos de vectores de Xtensa y los números de EXCCAUSE, que son del ISA y no del chip.

Se cree, pero no está verificado

  • La tabla de orden de pads del IO_MUX (sección 3.2). Los registros están en orden de pads y esta es la lectura de este modelo sobre qué pad es cada GPIO.
  • Los desplazamientos de registros del grupo de temporizadores 0 (sección 3.4). La base es del manual; la disposición interna no.
  • La disposición del bloque LEDC (sección 3.6): el paso entre canales, el bloque de temporizadores en 0x140 y los registros de interrupción y configuración. La base es del manual.
  • Los desplazamientos y posiciones de bits del SENS (sección 3.5).
  • DPORT_INTR_MAP = 0x104, y los dos números de fuente, GPIO 22 y UART0 34 (sección 3.7).
  • Los índices de señal 71 a 78 de la matriz GPIO para los canales de alta velocidad 0 a 7 del LEDC (sección 3.1). Esta es la afirmación más débil del documento.

Todos ellos están nombrados en un lugar que el firmware lee (firmware/esp32/include/esp32.h), así que una imagen que se lleve a silicio real tiene una lista corta de #defines que revisar. crates/esp32/tests/contract.rs obliga a que ese header y crates/esp32/src/map.rs tengan los mismos números, de modo que las dos mitades no pueden divergir; eso no hace que ninguna de las dos tenga razón.

Modelado, pero no con los números del manual

Estas son aproximaciones en lugar de direcciones, y un sketch puede verlas todas:

  • Los campos de la máquina de estados del UART_STATUS_REG leen 0 (sección 3.3). En el silicio ST_URX_OUT y ST_UTX_OUT se mueven mientras hay un byte en el cable; el runtime solo lee los contadores de ocho bits, así que no ve la diferencia.
  • El ADC a 11 dB es la curva de un componente típico, no de esta unidad. La lectura cruda sigue un ajuste sobre ESP32s medidos (sección 3.5): ahí están la zona muerta de abajo, la curvatura de arriba y la saturación alrededor de 3.15 V; lo que falta es la variación entre unidades que corrige la calibración de eFuse. Las otras atenuaciones son las líneas rectas nominales.
  • Cada pad arranca igual (sección 3.2): GPIO simple, búfer de entrada activado, sin pull-up. El manual da valores de reset distintos a los pines de strapping y de flash.
  • GPIO_STRAP_REG es una constante, 0b1101, no un registro de lo que estaban haciendo los pines en el reset.
  • Una conversión tarda exactamente 5 us y un flanco del LEDC cae en el picosegundo exacto. La pieza real tiene jitter y ninguna de las dos cifras es un número de hoja de datos.
  • EN es solo un pull-up de 10 k. El capacitor de reset de encendido de 100 nF que está a su lado no está modelado, así que un EN que solo se libera, aquí regresa al instante.
  • No hay ROM de arranque ni árbol de relojes. Un ESP32 real pasa decenas de milisegundos en un cargador de primera etapa antes de la primera instrucción de un sketch; aquí POWER_ON es 1 us, el núcleo está a 240 MHz y el reloj APB a 80 MHz desde la primera instrucción, y no hay nada con qué configurarlos.
  • CCOMPARE compara con "alcanzado o superado", y un plazo en el pasado no se arma (sección 4).
  • MOVSP nunca genera Alloca; hace que el área de guardado de la base del manejador sea él mismo (sección 4).
  • No hay alias entre las dos ventanas de RAM. En la pieza real la misma SRAM es visible por ambos buses en direcciones distintas, con los bloques de la SRAM1 en orden inverso (sección 2).

Ausentes a propósito

Cada uno de estos se omitió en lugar de inventarse:

  • El segundo núcleo. El ESP32 tiene dos núcleos Xtensa LX6, PRO y APP, y aquí solo corre el núcleo PRO. No hay DPORT_APPCPU_CTRL, ni interrupción entre núcleos, ni FreeRTOS que los agende. Un sketch escrito para el loop() único del núcleo de Arduino no se entera; cualquier cosa que inicie una tarea en el núcleo 1 no correrá.
  • The cache, the MMU and flash. Code and constants are read from two fixed, read-only windows (section 2.1); there is no flash device, no MMU and no cache to miss, so a fetch from flash is as fast as one from IRAM. PSRAM likewise.
  • WiFi y Bluetooth, en todas sus formas: sin radio, sin pila, sin WiFi.h, ni siquiera un stub que falle con cortesía.
  • El RTC, su memoria lenta, el coprocesador ULP, el sueño profundo y la unidad de gestión de energía.
  • El ADC2, el DMA y el controlador digital del SAR, los eFuse de calibración, la referencia interna, el sensor táctil y el sensor de efecto Hall.
  • El grupo de baja velocidad del LEDC y su hardware de desvanecimiento de ciclo útil.
  • El grupo de temporizadores 1, el temporizador 1 del grupo de temporizadores 0, el watchdog del RTC y el watchdog de interrupciones.
  • I2C, SPI, I2S, RMT, el contador de pulsos, el PWM de motor, SDIO, Ethernet, el controlador CAN y los aceleradores AES, SHA, RSA y RNG.
  • La matriz de interrupciones más allá de las fuentes de la sección 3.7, y todo nivel de interrupción de la CPU por encima de uno.

Por eso los binarios de ESP-IDF del fabricante y de Arduino-core no funcionan aquí, y sí el firmware compilado para este documento.

Las imágenes de las dos placas Xtensa tampoco son intercambiables. La cadena program del catálogo es elf32 xtensa lx6 esp32 aquí y elf32 xtensa lx106 esp8266 en la NodeMCU, y la diferencia es real y no solo un asunto de registro: este núcleo usa el ABI con ventanas y aquel no tiene ninguna ventana con la que usarlo, así que una imagen compilada para una falla en la otra en lugar de comportarse mal en silencio.

7. Entorno de ejecución del firmware (firmware/esp32/)

An Arduino-shaped runtime: setup() and loop(), pinMode, digitalWrite, digitalRead, shiftOut, analogRead (with analogReadResolution, analogSetAttenuation and analogSetPinAttenuation), analogWrite and the ledcAttach/ledcWrite/ledcRead family, millis, micros, micros64, delay, delayMicroseconds, attachInterrupt, Serial, Serial1 and Serial2, map, random. No Arduino core, no ESP-IDF, no libc.

Los constructores estáticos salen de .ctors aquí, no de .init_array. El GCC 8.4 de Espressif está configurado sin --enable-initfini-array y no tiene -fuse-init-array, así que el constructor de un objeto global termina en .ctors donde todas las demás cadenas de herramientas de este repositorio lo emiten en .init_array. link.ld reúne ambos en el único rango crt0.S recorre. Sin eso, un sketch con un objeto global (WebServer server(80) en wifilamp) enlazaría, se ejecutaría y encontraría sus miembros en cero. Los dos se recorren en una sola pasada y .ctors no se invierte, porque el orden en que corren los constructores entre unidades de traducción no está especificado en C++ y un sketch no debe depender de él.

LED_BUILTIN is 2. The core has no BOOT_BUTTON: the BOOT button is GPIO 0, so sketches use 0. A0 is 36, and A3 to A7 are 39, 32, 33, 34 and 35, which is what the DevKit's own analog pins are called.

analogRead es una lectura única del ADC1 (sección 3.5), de doce bits a 11 dB por defecto. analogWrite(pin, 0..255) es de ocho bits a 1 kHz en cualquier GPIO con controlador de salida, y adjunta un canal de alta velocidad libre del LEDC la primera vez que se llama; ledcAttach(pin, frequency, bits) es lo que un sketch necesita cuando la frecuencia importa, y los canales que piden la misma frecuencia y resolución comparten uno de los cuatro temporizadores. mokxi_pin_is_input_only(pin) está ahí para que un sketch pueda preguntar antes de que se le rechace.

millis() y micros() vienen del temporizador 0 del grupo de temporizadores 0 con un tick por microsegundo (sección 3.4). delayMicroseconds() por debajo de 50 us cuenta CCOUNT, 240 ciclos por microsegundo, así que nunca es más corto de lo pedido (contar el temporizador de microsegundos podría hacer que delayMicroseconds(10) dure 9.01 us, que un HC-SR04 ignora como disparo); 50 us o más se estaciona como delay(). delay() estaciona el núcleo en CCOMPARE0 en lugar de girar en un bucle, así que un segundo de blink le cuesta al núcleo menos de medio millón de instrucciones de los 240 millones de ciclos que contó el reloj. attachInterrupt son tres escrituras en lugar de una, porque un periférico llega al núcleo a través de la matriz de interrupciones (sección 3.7).

Serial1 y Serial2 están en src/uartn.c sobre UART1 y UART2 (sección 3.3a), enrutados por la matriz GPIO a los pines que begin(baud, config, rx, tx) o setPins() indique, con los valores por defecto de arduino-esp32 3.x cuando no se dan (GPIO 26 y 27 para Serial1, 4 y 25 para Serial2). Se comporta como el controlador de ESP-IDF bajo el núcleo: REF_TICK hasta 250 000 baudios y APB por encima, una interrupción en RXFIFO_FULL (120 bytes) o el tiempo de espera de recepción de un símbolo que mueve la FIFO a un anillo de setRxBufferSize() bytes (256), todo un fragmento o nada, con el fragmento apartado y las interrupciones de recepción apagadas mientras el anillo está lleno y la interrupción de desbordamiento vaciando la FIFO mientras tanto; available() cuenta solo el anillo. write() espera a la FIFO de 128 bytes y flush() hasta que el transmisor está inactivo. Ambas UART comparten la interrupción 18 de la CPU. onReceive() corre desde mokxi_uartn_events(), que llaman delay(), yield() y el bucle en main.cpp (entre loop()), porque no hay tareas de FreeRTOS. No está: control de flujo, RS-485, IrDA, autobaud y un búfer de anillo de transmisión.

Los ejemplos incluidos los compila el GCC de Espressif; el sketch de un usuario lo compila clang. El ld.lld de LLVM oficial no puede enlazar Xtensa en absoluto, así que el navegador usa clang-v3, la versión wasm de la bifurcación de LLVM de Espressif, que compila todos los ejemplos de aquí con la lista de comandos del navegador (docs/compile.md). Los ELF precompilados siguen siendo de GCC: son más pequeños (docs/compile.md, "Code size") y nada necesita que cambien. deploy/fetch-xtensa.sh pone xtensa-esp32-elf-gcc 8.4.0 en tools/xtensa/, que está en gitignore: GCC es GPL, y nada de lo que compila aquí enlaza contra libgcc ni ninguna otra parte de la cadena de herramientas, así que ningún código GPL llega a un ELF distribuido. docs/compile.md tiene el relato completo y los pasos restantes.

crt0.S lleva los seis manejadores de desbordamiento y subdesbordamiento de ventana en VECBASE, escritos a partir de la referencia del ISA y no tomados de ninguna fuente del fabricante, y le da al marco raíz su propia área base de guardado: un desbordamiento de ventana del marco raíz ejecuta l32e a0, a1, -12 para encontrar el puntero de pila de quien lo llamó y luego escribe a través de él, y el marco raíz no tiene quien lo llame, así que se construye uno sesenta y cuatro bytes por debajo del tope de la pila. Sin él, la primera cadena de llamadas profundas se derrama a través de un puntero nulo.

La entrada de excepción no toca a1, y eso es cuestión de corrección y no de orden: el manejador corre en la propia ventana de la función interrumpida, y un desbordamiento de ventana de un marco más antiguo encuentra dónde derramarse leyendo el puntero de pila de esa ventana. Mover a1 y cada marco más antiguo se derrama en el lugar equivocado y regresa mal. Los registros interrumpidos van a un bloque fijo en .bss en su lugar, lo cual es seguro sin candado porque el manejador corre en INTLEVEL 1.

Linked against firmware/esp32/link.ld: the vectors and startup code in the 128 KB of IRAM, code in the flash code window, constants in the flash constants window, .data, .bss and the stack in the 192 KB of DRAM. A WROOM-32 has 4 MB of flash and an example should be a small part of it, so the build refuses an image with more than 64 KB loadable; the real ceiling the linker script enforces is the 1,310,720 bytes of the default app partition.

Cinco ejemplos, cada uno con un sketch que la interfaz muestra: blink (el LED de la placa en GPIO 2 y uno cableado en GPIO 4), button (un interruptor a tierra en GPIO 15 con el pull-up propio de la terminal), serial (un tick por segundo y un eco de lo que escribes), fade (un LED en GPIO 4 en LEDC, de ocho bits a 1 kHz) y knob (un potenciómetro en GPIO 32, que es el canal 4 del ADC1, atenuando un LED en GPIO 4 con la lectura cruda impresa). pzemmonitor, un medidor de energía PZEM-004T en Serial2 (GPIO 16 y 17) mediante la biblioteca PZEM004Tv30, lo compila el compilador del navegador en lugar de GCC (sección 4) y es el proyecto ESP32 PZEM-004T energy monitor.

crates/esp32/tests/runtime.rs arranca esos cinco ELF y mide en lugar de solo observar: el semiperiodo de blink dentro de 5 ms de 500, el periodo del LEDC dentro de 5 us de los 1 ms de 1 kHz, millis() dentro de 60 ms del reloj del propio kernel durante cinco segundos, y ningún par de bytes de UART0 más cercanos que los 86.8 us de 115200 baudios. Cada prueba se omite a sí misma cuando las imágenes no están compiladas, así que las pruebas del crate nunca dependen de tener el compilador cruzado.