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 conR_SUPPLY;5V*entregan 5 V conR_SUPPLY;GND*entregan 0 V conR_SUPPLY. La placa siempre está alimentada (USB). Es una fuente para el resto del circuito.RSTes 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, 21son de entrada y salida. Con la salida habilitada: push-pull a 3.3 V o 0 V a través deR_STRONG. Con la salida deshabilitada: alta impedancia, más una pull-up de 45 k a 3.3 V cuandoFUN_WPUestá activo en IO_MUX, o una pull-down de 45 k cuandoFUN_WPDestá 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.mdsección 1);GPIO9lee alto cuando nada lo sostiene, por la pull-up de la placa junto al botón BOOT. - Los GPIO
0a4tambié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.mdsección 1). - Los pines
18/19funcionan además como USB D-/D+ y20/21como 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 deINT_ENAy el bit 0 deINT_RAW. - Machine external interrupt (
mip.MEIP, cause 11): GPIO (GPIO_STATUS_REGnon-zero) or UART0 (UART_INT_ST_REGnon-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_aftercon 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 undelayMicrosecondsde 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(0x7E0to0x7E2, user views0x800to0x802, the one ESP-IDF'sesp_cpu_get_cycle_countreads), all read without trapping and count one per 160 MHz cycle, which is one per instruction.mpccrcounts from reset (mpcerandmpcmrread 1); a write sets it, andmpcmrbit 0 clear holds it. None of them advance while the core is parked inwfi. 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; conmtvec = 0eso 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 deprobe(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_SARADCexcepto0x00y0x04. Es decir,FSM_WAITen 0x0C,ONETIME_SAMPLEen 0x38 y las posiciones de sus campos,1_DATA_STATUSen 0x44, los cuatro registros de interrupción en 0x64 a 0x70, yAPB_ADC_CLKM_CONFen 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_out0aledc_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.