Referencia

Contrato de la placa ESP32-C3 (Fase 2)

Los periféricos, el mapa de memoria y el tiempo del DevKitM-1.

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 El ESP32-C3 y la página de la placa.

The first microcontroller in Mokxi. One kernel component (esp32c3 in crates/parts) wraps a SoC model (crates/esp32c3) built on the RV32IMC core (crates/rv32-core). Firmware is a plain RV32 ELF that talks to the peripherals below at their real ESP32-C3 addresses, so a program built for Mokxi also runs on a real board. Running vendor ESP-IDF or Arduino-core binaries is out of scope for Phase 2: they need the ROM, the clock tree, the cache and the interrupt matrix, none of which are modeled.

El tipo del catálogo es esp32c3 (la placa ESP32-C3-DevKitM-1). Tres agentes compilan contra este archivo: el SoC y el componente (Rust), el entorno de ejecución del firmware y los ejemplos (C, clang), el aspecto visual de la placa y el monitor serie (TypeScript). Cámbialo solo editando primero este archivo.

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

En el orden físico de los dos headers de 15 pines del DevKitM-1 (vista superior, conector USB abajo):

Header izquierdo (de arriba abajo): GND, 3V3, 3V3b, 2, 3, RST, GNDb, 0, 1, 10, 4, 5, 6, 7, 8 Header derecho (de arriba abajo): 5V, 5Vb, GNDc, GNDd, 9, 18, 19, 20, 21, NC1, NC2, NC3, NC4, NC5, NC6

Los nombres duplicados llevan un sufijo con letra porque los nombres de pines del catálogo son únicos. Los pines NC* están presentes para que el header se dibuje completo; están en alta impedancia y nunca se leen.

Eléctrica:

  • 3V3* entregan 3.3 V con R_SUPPLY; 5V* entregan 5 V con R_SUPPLY; GND* entregan 0 V con R_SUPPLY. La placa siempre está alimentada (USB). Es una fuente para el resto del circuito.
  • RST es una entrada con una pull-up interna de 10 k a 3.3 V; si se lleva por debajo de 1.65 V mantiene la CPU en reset; al soltarlo, el programa se reinicia desde el punto de entrada.
  • Los GPIO 0..10, 18, 19, 20, 21 son de entrada y salida. Con la salida habilitada: push-pull a 3.3 V o 0 V a través de R_STRONG. Con la salida deshabilitada: alta impedancia, más una pull-up de 45 k a 3.3 V cuando FUN_WPU está activo en IO_MUX, o una pull-down de 45 k cuando FUN_WPD está activo. La entrada lee el voltaje de la red contra 1.65 V (la mitad de 3.3 V); Unknown lee 0, y una entrada flotante lee ruido, como en el Uno (docs/uno.md sección 1); GPIO9 lee alto cuando nada lo sostiene, por la pull-up de la placa junto al botón BOOT.
  • Los GPIO 0 a 4 también son los canales 0 a 4 del ADC1: el voltaje de la red en esos cinco pines se lee como voltaje además de contra el umbral, así que un potenciómetro, un joystick o un divisor en uno de ellos es una entrada analógica real (sección 3.5). Un pin al que nada sujeta vaga, como lo hace una entrada flotante (docs/uno.md sección 1).
  • Los pines 18/19 funcionan además como USB D-/D+ y 20/21 como UART0 RX/TX en la placa real; aquí son GPIO normales. Los bytes de UART0 van al canal del host (sección 4), no a los pines.

2. Mapa de memoria (direcciones reales del ESP32-C3)

región dirección tamaño notas
SRAM, bus de instrucciones 0x4037_C000 400 KB una RAM, dos vistas
SRAM, bus de datos 0x3FC7_C000 400 KB los mismos bytes: DRAM = IRAM - 0x0070_0000
IROM (flash code) 0x4200_0000 up to 1,310,720 bytes read-only, section 2.1
DROM (flash constants) 0x3C00_0000 up to 1,310,720 bytes read-only, section 2.1
GPIO 0x6000_4000 4 KB sección 3.1
IO_MUX 0x6000_9000 4 KB sección 3.2
UART0 0x6000_0000 4 KB sección 3.3
SYSTIMER 0x6002_3000 4 KB sección 3.4
APB_SARADC 0x6004_0000 4 KB sección 3.5
LEDC 0x6001_9000 4 KB sección 3.7
buzón de red de Mokxi 0x6FFF_E000 4 KB sección 3.8. No es del chip: es un bloque propio de Mokxi, donde un C3 real no tiene nada

Los 400 KB completos son RAM (los chips reales reservan la parte superior para datos de ROM y el caché; no se modela). Cualquier otra cosa es una falta de acceso (el núcleo genera una trap; el componente la cuenta, véase la sección 5). Los registros de periféricos sin mapear dentro de un bloque mapeado leen 0 e ignoran las escrituras, con un contador para diagnóstico.

2.1 Flash. A real ESP32-C3 runs almost all of a sketch from flash through the cache: code is read at IROM and const data at DROM, and the Arduino IDE's default partition ("Default 4MB with spiffs") gives the sketch 1,310,720 bytes of it. That is the room a sketch has here, counted as the IDE counts it (code, constants, startup code and the initial values of the variables), and the number the editor prints after a build. firmware/link.ld keeps the startup code and the trap entry in SRAM through the instruction view and puts every other function in the code window and every constant in the constants window; the variables and the stack take the SRAM from the end of the startup code up. The windows are read-only views of the loaded image, not a cache: no misses, no timing (a fetch from flash costs what one from SRAM costs), and a store to one faults. RISC-V calls through AUIPC and JALR, which reach 2 GB, so no literal pools or long-call tricks are needed. The upload build (link-hw.ld) is loaded into RAM by the ROM and keeps the 400 KB SRAM as its room.

Firmware ELF: loadProgram takes an ELF32 little-endian RISC-V executable. Every PT_LOAD segment must fall inside SRAM through either view or inside one of the two flash windows. Entry is the ELF entry point; the CPU resets with pc = entry, sp = top of SRAM data view (0x3FCE_0000), all other registers zero, mtvec = 0. A load at run time resets the board.

3. Registros de periféricos (subconjunto, offsets reales, posiciones de bits reales)

Los registros son de 32 bits y alineados a palabra. El acceso de media palabra y de byte a un registro no es compatible (se trata como un acceso de palabra de la palabra alineada, que es lo que hace el chip en las lecturas; las escrituras más angostas escriben la palabra completa con el valor angosto, que no es un comportamiento real, así que el firmware no debe hacerlo).

3.1 GPIO (0x6000_4000)

offset nombre bits
0x04 GPIO_OUT_REG bit n = nivel del GPIO n con la salida habilitada
0x08 GPIO_OUT_W1TS_REG escribir 1 activa bits de OUT
0x0C GPIO_OUT_W1TC_REG escribir 1 borra bits de OUT
0x20 GPIO_ENABLE_REG bit n = driver de salida del GPIO n activado
0x24 GPIO_ENABLE_W1TS_REG activar
0x28 GPIO_ENABLE_W1TC_REG borrar
0x3C GPIO_IN_REG bit n = nivel de entrada del GPIO n (requiere FUN_IE)
0x44 GPIO_STATUS_REG estado de interrupción, bit n
0x4C GPIO_STATUS_W1TC_REG borrar
0x74 + 4n GPIO_PINn_REG bit 2 PAD_DRIVER (1 = drenaje abierto), bits 7..9 INT_TYPE (0 apagado, 1 flanco de subida, 2 flanco de bajada, 3 cualquiera, 4 nivel bajo, 5 nivel alto)
0x554 + 4n GPIO_FUNCn_OUT_SEL_CFG_REG bits 0..7 OUT_SEL: 128 = el pin sigue el bit n de GPIO_OUT_REG (el valor de arranque usado aquí); 45 a 50 = los canales de baja velocidad 0 a 5 de LEDC lo controlan (sección 3.7); cualquier otro valor no es compatible y se trata como 128

Los índices de señal 45 a 50 no están verificados: son lo que este modelo implementa para ledc_ls_sig_out0 a ledc_ls_sig_out5, elegidos para que la matriz GPIO tenga dónde ponerlos, y no una fila citada de la tabla de señales de periféricos del manual. Un pin que controla un canal LEDC sigue necesitando su driver de salida activado en GPIO_ENABLE_REG, que es lo que activa gpio_set_direction antes de cambiar la matriz; el canal decide el nivel y GPIO_ENABLE decide si el pin controla algo.

Solo existen los bits 0..21. Drenaje abierto: salida alta significa alta impedancia. Las interrupciones de GPIO activan GPIO_STATUS_REG y levantan la línea de interrupción externa (sección 3.6).

3.2 IO_MUX (0x6000_9000)

offset nombre bits
0x04 + 4n IO_MUX_GPIOn_REG bit 7 FUN_WPD pull-down, bit 8 FUN_WPU pull-up, bit 9 FUN_IE habilitación de entrada, bits 12..14 MCU_SEL (1 = GPIO, el único valor compatible; valor de arranque 1 aquí en cada pin para que el firmware sin ajustes simplemente funcione)

3.3 UART0 (0x6000_0000)

offset nombre bits
0x00 UART_FIFO_REG escritura: mete un byte a TX; lectura: saca un byte de RX (0 cuando está vacío)
0x04 UART_INT_RAW_REG bit 0 RXFIFO_FULL, bit 1 TXFIFO_EMPTY, bit 8 RXFIFO_TOUT
0x08 UART_INT_ST_REG sin máscara y habilitado
0x0C UART_INT_ENA_REG
0x10 UART_INT_CLR_REG escribe 1 para limpiar
0x14 UART_CLKDIV_REG bits 0..11 la parte entera del divisor, bits 20..23 CLKDIV_FRAG sus dieciseisavos, del reloj del núcleo (el baudrate solo afecta el ritmo de TX en la sección 5; se guarda, se lee de vuelta)
0x1C UART_STATUS_REG bits 0..9 RXFIFO_CNT, bits 16..25 TXFIFO_CNT
0x20 UART_CONF0_REG se guarda, se lee de vuelta; el bit 17 RXFIFO_RST y el bit 18 TXFIFO_RST limpian los FIFO (TRM v1.4 registro 26.9)
0x24 UART_CONF1_REG bits 0..8 RXFIFO_FULL_THRHD, bits 9..17 TXFIFO_EMPTY_THRHD
0x78 UART_CLK_CONF_REG bits 20..21 SCLK_SEL (1 el reloj APB de 80 MHz, 3 el cristal de 40 MHz; 2, RC_FAST, se toma como el cristal), bits 12..19 SCLK_DIV_NUM: el reloj del núcleo es la fuente dividida entre SCLK_DIV_NUM + 1. Tras el reset, el cristal, sin dividir, así que CLKDIV 347 da 115 274 baudios. Los valores fraccionarios SCLK_DIV_A/SCLK_DIV_B se guardan, no se modelan

El runtime programa un baudrate como lo hace uart_ll_set_baudrate de ESP-IDF: el reloj APB, preescalado por el SCLK_DIV_NUM + 1 más pequeño que baje el divisor de 4096, y el divisor a un dieciseisavo, de modo que 1200 y 9600 baudios son exactos en vez de recortados a 4095.

FIFOs are 128 bytes. TX bytes leave the FIFO at the configured baud (default 115200: one byte per 86.8 us) into the host channel; a full TX FIFO drops bytes (real behavior). RX bytes arrive from the host channel instantly. RXFIFO_TOUT raises when RX has data and no byte arrived for 10 byte times.

3.4 SYSTIMER (0x6002_3000)

Contador libre de 52 bits a 16 MHz, un comparador conectado a la interrupción de temporizador de la CPU.

offset nombre bits
0x04 SYSTIMER_UNIT0_OP_REG bit 30 UPDATE: escribir 1 fija el conteo en VALUE_HI/LO; el bit 29 VALUE_VALID lee 1 una vez fijado
0x40 SYSTIMER_UNIT0_VALUE_HI_REG bits 0..19, bits 32..51 del conteo fijado
0x1C SYSTIMER_TARGET0_HI_REG bits 0..19
0x20 SYSTIMER_TARGET0_LO_REG
0x34 SYSTIMER_TARGET0_CONF_REG bit 30 PERIOD_MODE, bits 0..25 PERIOD
0x44 SYSTIMER_UNIT0_VALUE_LO_REG bits 0..31 del conteo retenido
0x50 SYSTIMER_COMP0_LOAD_REG escribe 1 para cargar el objetivo
0x64 SYSTIMER_INT_ENA_REG bit 0
0x68 SYSTIMER_INT_RAW_REG bit 0
0x6C SYSTIMER_INT_CLR_REG bit 0
0x70 SYSTIMER_INT_ST_REG bit 0

El temporizador siempre está en marcha. El conteo se deriva del tiempo del kernel: count = now_ps / 62_500. Nunca se desvía del circuito.

Verificado registro por registro contra el Manual de referencia técnica del ESP32-C3 v1.4, sección 10.6 (resumen de registros) y los registros 10.2, 10.14 a 10.17. Una versión anterior de este modelo colocaba el comparador 0 en 0x50 a 0x5C, que en el C3 son los estrobos de carga COMP0_LOAD a COMP2_LOAD y UNIT0_LOAD; esa distribución nunca fue la del chip, y el entorno de ejecución y sus imágenes se reconstruyeron cuando se corrigió.

3.5 APB_SARADC (0x6004_0000)

ADC1 en modo de una sola conversión: la ruta que toman el controlador adc_oneshot de ESP-IDF y el analogRead del núcleo de Arduino, y nada más. Los canales 0 a 4 son GPIO 0 a GPIO 4; el ADC2 no está modelado (en una C3 real se comparte con la radio, y aquí no hay radio).

La dirección base del bloque es la del chip. Los offsets de esta tabla marcados como "sin verificar" no se tomaron de una página del manual de referencia técnica: son lo que implementa este modelo, elegidos para coincidir con la forma de la ruta de una sola conversión, y el firmware compilado aquí coincide con el modelo, coincida o no con el silicio. 0x00 y 0x04 son del manual; el resto de los registros de una sola conversión son los no verificados, y un programa que deba funcionar sin cambios en una DevKitM-1 debería verificarlos primero contra el manual.

offset nombre bits
0x00 APB_SARADC_CTRL_REG bits 7..14 SAR_CLK_DIV: divisor del reloj SAR. Se guarda y se lee de vuelta; el tiempo de conversión aquí es fijo
0x04 APB_SARADC_CTRL2_REG se guarda, se lee de vuelta. Las rutas de disparo por temporizador y de DMA no están modeladas
0x0C APB_SARADC_FSM_WAIT_REG se guarda, se lee de vuelta (offset sin verificar)
0x38 APB_SARADC_ONETIME_SAMPLE_REG bits 23..24 ONETIME_ATTEN, bits 25..28 ONETIME_CHANNEL, bit 29 ONETIME_START, bit 30 SAR2_ONETIME_SAMPLE (se guarda, no convierte nada), bit 31 SAR1_ONETIME_SAMPLE (offset y posiciones de campo sin verificar)
0x44 APB_SARADC_1_DATA_STATUS_REG bits 0..16 ADC1_DATA: la última conversión del ADC1, de doce bits (offset sin verificar)
0x64 APB_SARADC_INT_ENA_REG se guarda; ninguna línea llega al núcleo (offset sin verificar)
0x68 APB_SARADC_INT_RAW_REG bit 31 ADC1_DONE (offset sin verificar)
0x6C APB_SARADC_INT_ST_REG en bruto y habilitado (offset sin verificar)
0x70 APB_SARADC_INT_CLR_REG escribe 1 para limpiar, el mismo bit (offset sin verificar)
0x78 APB_SARADC_APB_ADC_CLKM_CONF_REG se guarda, se lee de vuelta (offset sin verificar)

One conversion: write ONETIME_SAMPLE with SAR1_ONETIME_SAMPLE, the channel and the attenuation, write it again with ONETIME_START up, wait for ADC1_DONE in INT_RAW, read APB_SARADC_1_DATA_STATUS_REG, clear the flag and drop ONETIME_START. A conversion starts on the write that raises ONETIME_START with ADC1 taking part, and takes a fixed 5 us. The real figure depends on the SAR clock and the FSM's counts and is a few microseconds; firmware waits for it either way, since the result does not appear early.

El resultado es de doce bits, round(4095 x Vin / Vfull), acotado, del voltaje de la red en el momento en que empezó la conversión. ONETIME_ATTEN elige la escala completa, con las cifras nominales que cita la hoja de datos:

ONETIME_ATTEN atenuación escala completa
0 0 dB 1.1 V
1 2.5 dB 1.5 V
2 6 dB 2.2 V
3 11 dB la curva de la parte real, saturando en unos 2.9 V

Los primeros tres son las rectas nominales. 11 dB (12 dB en el ESP-IDF actual), el valor predeterminado del núcleo de Arduino, sigue la curva en bruto de un componente típico (CURVE_11DB en crates/esp32c3/src/adc.rs): casi lineal a lo largo del rango efectivo de 0 a 2500 mV de la hoja de datos (3650 a 2.5 V), y luego hasta 4095 en unos 2.9 V (la gente reporta de 2.8 a 3.0 V en unidades reales). Así, un potenciómetro entre los 3.3 V del riel lee 4095 en el último décimo de su recorrido, y un divisor a la mitad del riel lee unos 2410, no 2048. La calibración de eFuse de una unidad mueve eso unos pocos puntos porcentuales, que no está modelada; analogReadMilliVolts invierte la misma curva. Un canal sin nada en su pin vaga, como lo hace una entrada flotante (docs/uno.md sección 1).

ADC1_DONE se puede sondear y limpiar, que es lo que hace la ruta de una sola conversión, pero no llega a mip: el ADC no está en la línea de interrupción externa (sección 3.6). Tampoco lo están el controlador digital, la tabla de patrones de DMA, los filtros, los monitores de umbral ni los canales de temperatura interna y VDD.

3.6 Interrupciones

Modo máquina de RISC-V, mtvec directo o vectorizado según lo que admite el núcleo. Líneas:

  • Interrupción de temporizador de máquina (mip.MTIP, causa 7): objetivo 0 del SYSTIMER cuando el bit 0 de INT_ENA y el bit 0 de INT_RAW.
  • Machine external interrupt (mip.MEIP, cause 11): GPIO (GPIO_STATUS_REG non-zero) or UART0 (UART_INT_ST_REG non-zero). Firmware reads the two status registers to find out which. The real interrupt matrix is not modeled.

wfi detiene el núcleo hasta que haya alguna línea pendiente.

3.7 LEDC (0x6001_9000)

El controlador PWM de LED, grupo de baja velocidad, que es el único grupo que tiene este chip: cuatro temporizadores y seis canales. Este es el bloque detrás de analogWrite, ledcAttach y ledcWrite.

A timer is a free-running counter of 2^DUTY_RES counts clocked at 80 MHz divided by CLK_DIV, which is a Q10.8 fixed-point number of APB clocks per count, so

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

y 5 kHz a ocho bits es DUTY_RES 8 con CLK_DIV 16000, exacto. Un canal elige un temporizador, un conteo de inicio HPOINT y un ciclo útil, y su salida está en alto desde HPOINT durante DUTY >> 4 conteos, con envolvimiento en la parte superior del período. Así, un ciclo útil de 0 es un bajo sólido y uno de 2^DUTY_RES un alto sólido, sin ningún flanco, y por eso el núcleo de Arduino convierte ledcWrite(pin, 255) a ocho bits en un ciclo útil de 256 en lugar de dejar una muesca de un conteo en cada período.

Verified: the base address, every offset in the table below and every bit it names, against the ESP32-C3 Technical Reference Manual v1.4, section 32.5 (register summary) and registers 32.1 to 32.13.

offset nombre bits
0x00 + 0x14n LEDC_CHn_CONF0_REG bits 0..1 TIMER_SEL, bit 2 SIG_OUT_EN, bit 3 IDLE_LV (el nivel que se mantiene con el generador de salida apagado), bit 4 PARA_UP (se guarda; un ciclo útil escrito aquí surte efecto de inmediato)
0x04 + 0x14n LEDC_CHn_HPOINT_REG bits 0..13 HPOINT: el conteo en el que empieza el pulso del canal
0x08 + 0x14n LEDC_CHn_DUTY_REG bits 0..18 DUTY: el ancho del pulso en dieciseisavos de conteo
0x0C + 0x14n LEDC_CHn_CONF1_REG el hardware de desvanecimiento del ciclo útil: se guarda, se lee de vuelta y no desvanece nada
0x10 + 0x14n LEDC_CHn_DUTY_R_REG el ciclo útil tal como está, solo lectura
0xA0 + 8n LEDC_TIMERn_CONF_REG bits 0..3 DUTY_RES (1 to 14; 0 is a timer nobody has configured and it counts nothing), bits 4..21 CLK_DIV (Q10.8 APB clocks per count), bit 22 PAUSE, bit 23 RST, bit 25 PARA_UP (stored); bit 24 is reserved. TRM v1.4 register 32.7. The C3 has no per-timer TICK_SEL: the clock is chosen for all four timers in LEDC_CONF_REG. An earlier version of this model used the classic ESP32's layout here (five resolution bits and the divider from bit 5). The manual's reset value has RST set; here the register powers up as 0
0xA4 + 8n LEDC_TIMERn_VALUE_REG el contador, solo lectura
0xC0 LEDC_INT_RAW_REG bit n = el temporizador n se desbordó
0xC4 LEDC_INT_ST_REG sin máscara y habilitado
0xC8 LEDC_INT_ENA_REG se guarda; ninguna línea llega al núcleo
0xCC LEDC_INT_CLR_REG escribe 1 para limpiar
0xD0 LEDC_CONF_REG bits 0..1 APB_CLK_SEL (1 = el reloj APB de 80 MHz, la única fuente modelada), bit 31 CLK_EN (se guarda)
0xFC LEDC_DATE_REG un sello de versión, solo lectura

Configurar un canal es lo que hacen ledc_timer_config y ledc_channel_config: escribir LEDC_CONF_REG, escribir el DUTY_RES y el CLK_DIV del temporizador, escribir el CONF0 del canal con su temporizador y el SIG_OUT_EN, escribir HPOINT y DUTY, activar el bit GPIO_ENABLE del pad y apuntar su GPIO_FUNCn_OUT_SEL_CFG_REG a 45 + channel.

El contador no avanza por pasos: es una función cerrada del tiempo simulado, y lo mismo vale para el tiempo de su próximo flanco. Por eso un núcleo estacionado en wfi no cuesta nada mientras corre un PWM, y al componente de la placa solo se le despierta para los flancos y para nada más.

No está modelado: el grupo de alta velocidad (este chip no lo tiene), el hardware de desvanecimiento del ciclo útil, el contador de desbordamiento propio de un canal, las fuentes de reloj distintas de APB y la línea de interrupción del LEDC hacia la matriz de interrupciones. LEDC_INT_RAW_REG se puede consultar y limpiar pero nunca llega a mip, igual que el ADC1_DONE del ADC no llega (sección 3.6).

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

Este bloque no es del ESP32-C3. Todas las demás direcciones de este documento son del chip, citadas del manual de referencia técnica, y una imagen compilada contra él corre en un DevKitM-1 real. Este es propio de Mokxi: la red simulada de crates/net, mapeada en una dirección que la pieza real deja sin mapear, para que una imagen que la use falle en el silicio en vez de leer el registro de algún otro periférico. Esa falla es la respuesta honesta, porque lo que hay detrás de este bloque no existe en el chip.

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: solo Bluetooth LE, como en el chip real, así que los comandos de Classic ponen BT_ERR. Tampoco hay una radio detrás de ellos; 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 Perros guardianes de los grupos de temporizadores, reinicios de RTC_CNTL y el monitor de pila (0x6001_F000, 0x6002_0000, 0x6000_8000, 0x600C_E000)

El perro guardián principal de cada grupo de temporizadores (crates/esp-common/src/mwdt.rs): WDTCONFIG0..5, WDTFEED y la clave WDTWPROTECT, cuatro etapas, cada una con su acción (una interrupción, un reinicio de CPU o un reinicio del sistema), el preescalador sobre el reloj APB de 80 MHz o, con WDT_USE_XTAL, el cristal de 40 MHz, y una configuración escrita que surte efecto en WDT_CONF_UPDATE_EN. El bit del perro guardián en TIMG_INT_ENA/RAW/ST/CLR (bit 1) genera la interrupción externa de la máquina, como lo hacen GPIO y UART0 (sección 3.6). Una etapa de reinicio reinicia el chip con el reloj activo y RTC_CNTL_RESET_STATE_REG indicando el motivo (7 u 8 para un reinicio del sistema, 0xB o 0x11 para un reinicio de CPU); la RAM se recarga desde la imagen, RTC_CNTL_STORE0..7 conservan sus valores, y RTC_CNTL_SW_SYS_RST y RTC_CNTL_SW_PROCPU_RST en RTC_CNTL_OPTIONS0_REG también lo reinician (causas 3 y 0xC).

El runtime ejecuta el perro guardián de tareas de ESP-IDF sobre el perro guardián del grupo de temporizadores 0, como lo hace ESP-IDF (firmware/src/main.cpp): tics de 500 µs, etapa 0 una interrupción al agotarse el tiempo y etapa 1 un reinicio del sistema al doble, iniciado antes de setup() a 5 s con un pánico, vigilando la tarea idle del núcleo 0. 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 perro guardián del grupo de temporizadores 1 está modelado igual y nada en el runtime lo arma: el perro guardián de interrupciones no se simula.

ASSIST_DEBUG's stack monitor (SP_MIN, SP_MAX, INTR_ENA, INTR_RAW, SP_PC; the region monitors are not modeled): while it is on, an instruction that would move sp outside the bounds does not retire and the board reports "firmware crashed at pc=…, stack overflow: the stack ran out of RAM (SP=…)". The runtime points SP_MIN at the top of the heap, which malloc moves, and SP_MAX at the top of RAM, so runaway recursion stops at the heap instead of running down through the program in the RAM it shares. Narrower bounds reach the core at its next pass and wider ones at once, so neither costs a sketch anything it would notice: a tight loop ran at 154 to 159 MIPS before the check and 164 to 175 after, the same within the noise of the machine.

4. Canal del host

host = "utf-8 bytes on UART0". readHost devuelve los bytes de TX de UART0 conforme salen de la FIFO; writeHost empuja bytes a la FIFO de RX de UART0 (el desbordamiento descarta, como en el chip). El monitor serie muestra los bytes como texto, decodificando UTF-8 y tratando \n como fin de línea (\r se ignora).

5. Modelo de tiempo

La CPU corre a 160 MHz con una instrucción por ciclo. El componente ejecuta en porciones: en cada despertar ejecuta SLICE_NS * 160 instrucciones (SLICE_NS = 10 us, o sea 1600 instrucciones) y luego programa el próximo despertar, con estas reglas:

  • Las escrituras a periféricos que cambian un pin (GPIO OUT o ENABLE, las resistencias de pull de IO_MUX) manejan el pin en el momento en que empezó la porción más el conteo de instrucciones hasta entonces dividido entre 160 MHz. Usa drive_after con ese retardo para que dos conmutaciones dentro de una misma porción conserven su separación. Las lecturas de GPIO_IN ven el nivel del pin según el inicio de la porción.
  • La comparación del temporizador y el ritmo del UART se evalúan contra ese mismo tiempo dentro de la porción, así que micros() es monótono y un delayMicroseconds de espera activa es preciso a una instrucción.
  • Cycle counters: rdcycle/cycle (0xC00, 0xC80), mcycle/mcycleh (0xB00, 0xB80) and the ESP32-C3's own performance counter, mpcer/mpcmr/mpccr (0x7E0 to 0x7E2, user views 0x800 to 0x802, the one ESP-IDF's esp_cpu_get_cycle_count reads), all read without trapping and count one per 160 MHz cycle, which is one per instruction. mpccr counts from reset (mpcer and mpcmr read 1); a write sets it, and mpcmr bit 0 clear holds it. None of them advance while the core is parked in wfi.
  • wfi: el componente deja de ejecutar ciclos y programa un despertar en el más pronto entre el objetivo del temporizador y un evento del UART; un cambio en un pin GPIO lo despierta de inmediato.
  • Fallas de acceso: el núcleo salta con trampa a mtvec; con mtvec = 0 eso vuelve a caer en trampa indefinidamente. El componente cuenta las trampas y después de 1000 trampas consecutivas sin avance se detiene y reporta "firmware crashed at pc=…, mcause=…" a través de probe (ver abajo) y del canal del host (una línea).

Probe: 1 when running, 0 when halted (no program, in reset, or crashed), 0.5 while parked in wfi. Poke: 1 = press the BOOT button (GPIO 9 low while held), 0 = release; 2 = press RST, 3 = release RST. The UI gives the board interaction: 'hold' on its RST button region only if the visual supports region-specific interaction; for Phase 2 the whole board is not interactive, and BOOT/RST are wired to pushbuttons by users if they want them.

6. Runtime de firmware (firmware/)

A freestanding C and C++ runtime built with clang (--target=riscv32-unknown-elf -march=rv32imc -mabi=ilp32) and lld, no libc, no GPL: crt0.S (stack, .data copy, .bss clear, trap vector, main), esp32c3.h (the registers above as macros), arduino.h with pinMode, digitalWrite, digitalRead, analogRead (one-shot ADC1 on GPIO 0..4, twelve bits, with analogReadResolution, analogSetAttenuation and analogSetPinAttenuation), analogWrite and the ledcAttach/ledcWrite pair (LEDC, section 3.7: eight bits at 1 kHz on any GPIO by default, with analogWriteResolution and analogWriteFrequency, and a channel allocated to a pin the first time it is written to), delay, delayMicroseconds, millis, micros, Serial.begin/print/println/write/available/read (a small C++ Print class with integer, float, string and char overloads), attachInterrupt for GPIO. The sketch is setup() and loop(). build.sh compiles every example under firmware/examples/ to web/public/firmware/<name>.elf, which the UI ships. Examples: blink (GPIO 8, the DevKitM-1 LED pin, 500 ms), button (GPIO 9 with pull-up lights GPIO 8), serial (prints millis() once a second and echoes what it receives), fade (bit-banged PWM on GPIO 8 for a breathing LED), counter (74HC595 driven on GPIO 4 = DS, 5 = SHCP, 6 = STCP, counting on eight LEDs), interrupt (attachInterrupt on GPIO 9 counts presses and prints the count), pwmfade (the same breathing LED as fade, on analogWrite rather than by hand, so the core sleeps through it), servo (an SG90 swept end to end by a 50 Hz LEDC channel on GPIO 4).

The board's code in the editor is not compiled in Phase 2 (see docs/compile-options.md); the UI offers the built-in examples and an ELF upload.

7. Lo que este modelo sabe con certeza, y lo que no

Tres grupos, con el mismo orden que usa la sección 7 de docs/esp32c6.md. Existe porque un modelo de placa que adivina silenciosamente una dirección es peor que uno que dice que no lo sabía.

Taken from the technical reference manual, and run through by real firmware. UART0_BASE = 0x6000_0000, GPIO_BASE = 0x6000_4000, IOMUX_BASE = 0x6000_9000, SYSTIMER_BASE = 0x6002_3000, APB_SARADC_BASE = 0x6004_0000 and LEDC_BASE = 0x6001_9000, with every register offset inside the GPIO, IO_MUX, UART0, SYSTIMER and LEDC blocks. Checked against the ESP32-C3 Technical Reference Manual v1.4 while the ESP32-S3 was being added: the SYSTIMER comparator 0 offsets (section 10.6: TARGET0_HI 0x1C, TARGET0_LO 0x20, TARGET0_CONF 0x34, COMP0_LOAD 0x50), LEDC_TIMERn_CONF_REG's fields (register 32.7), LEDC's interrupt and global registers (registers 32.3 and 32.9 to 32.13) and UART_CONF0_REG's FIFO resets (register 26.9). The first two and the last were wrong here before that check and were corrected, with the runtime's images rebuilt. The GPIO range 0 to 21, ADC1's channel map (channel n is GPIO n for n in 0 to 4), the 400 KB of SRAM at two views 0x0070_0000 apart, and the 16 MHz SYSTIMER tick. Each of those blocks is driven by a test that loads a real ELF and runs it: crates/esp32c3/tests/firmware.rs for GPIO, UART0 and SYSTIMER, and tests/examples.rs's pwmfade and servo for LEDC.

Creído, no verificado. Nombrados así, registro por registro, en las secciones 3.1 y 3.5, y repetidos aquí para que la lista esté en un solo lugar:

  • Cada offset de registro de una sola toma dentro de APB_SARADC excepto 0x00 y 0x04. Es decir, FSM_WAIT en 0x0C, ONETIME_SAMPLE en 0x38 y las posiciones de sus campos, 1_DATA_STATUS en 0x44, los cuatro registros de interrupción en 0x64 a 0x70, y APB_ADC_CLKM_CONF en 0x78. Son lo que este modelo implementa, elegidos para coincidir con la forma de la ruta de una sola toma, no filas citadas de una página del manual.
  • Los índices de señal 45 a 50 de la matriz GPIO para ledc_ls_sig_out0 a ledc_ls_sig_out5, elegidos para que la matriz tenga dónde ponerlos.

El firmware construido para este documento coincide con el modelo, coincida o no con el silicio. Si se lleva una imagen a un DevKitM-1 real, se deberían verificar primero esos #defines en firmware/include/esp32c3.h contra el manual.

Modelado, pero no sujeto a los números del manual. Comportamientos más que direcciones:

  • El ADC a 11 dB es la curva de un componente típico, no la de esta unidad. La saturación en alrededor de 2.9 V y la ganancia por encima del rango efectivo de 2.5 V están (sección 3.5); la variación de unidad a unidad que la calibración de eFuse corrige y el ruido de conversión no. Las otras atenuaciones son las rectas nominales (1.1 V, 1.5 V, 2.2 V).
  • Una instrucción es un ciclo a 160 MHz. No hay esperas de pipeline, no hay caché (no existe caché), no hay esperas de flash ni contención de bus, así que el conteo de instrucciones es el reloj. Un C3 real ejecutando desde flash es más lento y menos uniforme que esto.
  • Los pines son tres estados y un umbral. Push-pull a 3.3 V, alta impedancia, o una resistencia de pull interno de 45 kΩ, leída contra la mitad de la alimentación, sin histéresis, sin ajuste de fuerza de manejo, sin tiempo de subida y sin límite de corriente. Un pin sin manejar lee 0 en lugar de flotar hacia algún valor.
  • La placa es una fuente de alimentación ideal: 3V3 y 5V con impedancia de riel para siempre, así que nada se apaga por caída de tensión. El arranque dura un microsegundo, donde un C3 real pasa decenas de milisegundos en su ROM de arranque.
  • Un segmento es de 10 µs, y el SoC y el circuito se encuentran en los límites de los segmentos o en lo que sea que el chip esté esperando.

Ausentes a propósito. Se dejaron fuera en lugar de inventarse, porque la disposición de registros no es algo que este modelo pueda reproducir con honestidad: Bluetooth LE (sin radio, y sin pretender tenerla), SPI, I2C, I2S, RMT, USB Serial/JTAG, los temporizadores de los grupos de temporizadores (sus perros guardianes son los de la sección 3.9), la matriz de interrupciones completa (la sección 3.6 dice qué la sustituye), el ADC2 y la tabla de patrones DMA del SAR ADC, el controlador digital, los filtros, los monitores de umbral y los eFuses de calibración, el grupo de alta velocidad del LEDC y su hardware de desvanecimiento de ciclo útil y su línea de interrupción hacia el núcleo, el PMU y el árbol de reloj, la caché, la ROM y la memoria flash. Por eso los binarios de ESP-IDF y del núcleo de Arduino del fabricante no corren aquí, y el firmware construido para este documento sí.

WiFi: simulado, ver docs/wifi.md. It was in the list above until September 2026, as "absent: WiFi in every form". It is not absent any more and it is not modeled either: there is no radio and no 802.11, and what there is instead is section 3.8's mailbox (a block this chip does not have, at an address it leaves unmapped) with a network written in software behind it. docs/wifi.md es el contrato de lo que esa red hace y, con más detalle, de lo que no hace.

Preguntas

Does it do WiFi?

WiFi simulado, sí. Tu sketch usa las llamadas reales de Arduino (WiFi.begin, HTTPClient, WebServer) y la placa se conecta, descarga y sirve, pero debajo no hay radio ni 802.11. Con la sesión iniciada, puedes activar Internet real en el panel de Nube. La sección 3.8 y la página de WiFi simulado tienen el contrato.

¿Mi firmware funcionará en un DevKitM-1 real?

Sí. El modelo se basa en el mapa de memoria y los desplazamientos de registros reales para todo lo que implementa, así que una compilación desde aquí no es específica de Mokxi.