Referência

Contrato da placa ESP32-C3 (Fase 2)

Os periféricos, o mapa de memória e o timing do DevKitM-1.

Esta é a referência de engenharia do modelo: o que ele implementa, registrador por registrador, para quem escreve firmware para ele. Para usar a placa no editor, comece por O ESP32-C3 e página da 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.

O tipo no catálogo é esp32c3 (a placa ESP32-C3-DevKitM-1). Três agentes trabalham contra este arquivo: o SoC e o componente (Rust), o runtime de firmware e os exemplos (C, clang), o visual da placa e o monitor serial (TypeScript). Mude-o apenas editando este arquivo primeiro.

1. Pinos da placa (ordem do catálogo)

Na ordem física dos dois conectores de 15 pinos do DevKitM-1 (vista de cima, conector USB embaixo):

Conector esquerdo (de cima para baixo): GND, 3V3, 3V3b, 2, 3, RST, GNDb, 0, 1, 10, 4, 5, 6, 7, 8 Conector direito (de cima para baixo): 5V, 5Vb, GNDc, GNDd, 9, 18, 19, 20, 21, NC1, NC2, NC3, NC4, NC5, NC6

Nomes duplicados recebem um sufixo de letra porque os nomes de pinos do catálogo são únicos. Os pinos NC* existem para que o conector seja desenhado completo; eles ficam em alta impedância e nunca são lidos.

Elétrico:

  • 3V3* fornece 3,3 V em R_SUPPLY; 5V* fornece 5 V em R_SUPPLY; GND* fornece 0 V em R_SUPPLY. A placa está sempre alimentada (USB). Ela é uma fonte para o resto do circuito.
  • RST é uma entrada com pull-up interno de 10 k para 3,3 V; se for levado abaixo de 1,65 V, mantém a CPU em reset; soltá-lo reinicia o programa a partir do ponto de entrada.
  • GPIO 0..10, 18, 19, 20, 21 são inout. Com saída habilitada: push-pull a 3,3 V ou 0 V através de R_STRONG. Com saída desabilitada: alta impedância, mais um pull-up de 45 k para 3,3 V quando FUN_WPU está definido em IO_MUX, ou um pull-down de 45 k quando FUN_WPD está definido. A entrada lê a tensão do nó em relação a 1,65 V (metade de 3,3 V); Unknown lê 0, e uma entrada flutuante lê ruído, como no Uno (docs/uno.md seção 1); GPIO9 lê alto quando nada o segura, pelo pull-up da placa ao lado do botão BOOT.
  • GPIO 0 a 4 também são os canais 0 a 4 do ADC1: a tensão do nó nesses cinco pinos é lida como tensão e também em relação ao limiar, então um potenciômetro, um joystick analógico ou um divisor em um deles é uma entrada analógica de verdade (seção 3.5). Um pino que nada segura vagueia, como uma entrada flutuante faz (docs/uno.md seção 1).
  • Os pinos 18/19 também funcionam como USB D-/D+ e 20/21 como UART0 RX/TX na placa real; aqui eles são GPIO comuns. Os bytes da UART0 vão para o canal do host (seção 4), não para os pinos.

2. Mapa de memória (endereços reais do ESP32-C3)

região endereço tamanho notas
SRAM, barramento de instruções 0x4037_C000 400 KB uma RAM, duas visões
SRAM, barramento de dados 0x3FC7_C000 400 KB mesmos 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 seção 3.1
IO_MUX 0x6000_9000 4 KB seção 3.2
UART0 0x6000_0000 4 KB seção 3.3
SYSTIMER 0x6002_3000 4 KB seção 3.4
APB_SARADC 0x6004_0000 4 KB seção 3.5
LEDC 0x6001_9000 4 KB seção 3.7
caixa de correio de rede do Mokxi 0x6FFF_E000 4 KB seção 3.8. Não é do chip: bloco próprio do Mokxi, onde um C3 real não tem nada

Os 400 KB inteiros são RAM (chips reais reservam o topo para dados da ROM e o cache; não modelado). Qualquer outro endereço é uma falha de acesso (o core faz uma trap; o componente conta, veja a seção 5). Registradores de periféricos não mapeados dentro de um bloco mapeado leem 0 e ignoram escritas, com um 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. Registradores de periféricos (subconjunto, offsets reais, posições de bits reais)

Os registradores têm 32 bits e são alinhados por palavra. Acesso de meia palavra e de byte a um registrador não é suportado (tratado como um acesso de palavra da palavra alinhada, que é o que o chip faz para leituras; escritas mais estreitas gravam a palavra inteira a partir do valor estreito, não é um comportamento real, então o firmware não deve fazer isso).

3.1 GPIO (0x6000_4000)

offset nome bits
0x04 GPIO_OUT_REG bit n = nível do GPIO n com a saída habilitada
0x08 GPIO_OUT_W1TS_REG escreva 1 para definir bits de OUT
0x0C GPIO_OUT_W1TC_REG escreva 1 para limpar bits de OUT
0x20 GPIO_ENABLE_REG bit n = driver de saída do GPIO n ligado
0x24 GPIO_ENABLE_W1TS_REG definir
0x28 GPIO_ENABLE_W1TC_REG limpar
0x3C GPIO_IN_REG bit n = nível de entrada do GPIO n (precisa de FUN_IE)
0x44 GPIO_STATUS_REG status de interrupção, bit n
0x4C GPIO_STATUS_W1TC_REG limpar
0x74 + 4n GPIO_PINn_REG bit 2 PAD_DRIVER (1 = open drain), bits 7..9 INT_TYPE (0 desligado, 1 borda de subida, 2 borda de descida, 3 qualquer, 4 nível baixo, 5 nível alto)
0x554 + 4n GPIO_FUNCn_OUT_SEL_CFG_REG bits 0..7 OUT_SEL: 128 = o pad segue o bit n de GPIO_OUT_REG (o valor de boot usado aqui); 45 a 50 = os canais de baixa velocidade 0 a 5 do LEDC o controlam (seção 3.7); qualquer outro valor não é suportado e é tratado como 128

Os índices de sinal 45 a 50 não são verificados: são o que este modelo implementa para ledc_ls_sig_out0 até ledc_ls_sig_out5, escolhidos para que a matriz GPIO tenha onde colocá-los, e não uma linha citada da tabela de sinais de periféricos do manual. Um pad controlado por um canal LEDC ainda precisa do driver de saída ligado em GPIO_ENABLE_REG, que é o que gpio_set_direction define antes de a matriz ser trocada; o canal decide o nível e GPIO_ENABLE decide se o pad controla algo ou não.

Somente os bits 0..21 existem. Open drain: saída alta significa alta impedância. As interrupções de GPIO definem GPIO_STATUS_REG e levantam a linha de interrupção externa (seção 3.6).

3.2 IO_MUX (0x6000_9000)

offset nome bits
0x04 + 4n IO_MUX_GPIOn_REG bit 7 FUN_WPD pull-down, bit 8 FUN_WPU pull-up, bit 9 FUN_IE habilitação de entrada, bits 12..14 MCU_SEL (1 = GPIO, o único valor suportado; valor de boot 1 aqui para todos os pinos, para que firmware cru simplesmente funcione)

3.3 UART0 (0x6000_0000)

offset nome bits
0x00 UART_FIFO_REG escrita: empurra um byte para TX; leitura: remove um byte de RX (0 quando vazio)
0x04 UART_INT_RAW_REG bit 0 RXFIFO_FULL, bit 1 TXFIFO_EMPTY, bit 8 RXFIFO_TOUT
0x08 UART_INT_ST_REG raw e habilitado
0x0C UART_INT_ENA_REG
0x10 UART_INT_CLR_REG escreva 1 para limpar
0x14 UART_CLKDIV_REG bits 0..11 a parte inteira do divisor, bits 20..23 CLKDIV_FRAG os seus dezesseis avos, do clock do core (o baud afeta apenas o ritmo do TX na seção 5; armazenado, lido de volta)
0x1C UART_STATUS_REG bits 0..9 RXFIFO_CNT, bits 16..25 TXFIFO_CNT
0x20 UART_CONF0_REG armazenado, lido de volta; bit 17 RXFIFO_RST, bit 18 TXFIFO_RST limpam as FIFOs (TRM v1.4 registrador 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 o clock APB de 80 MHz, 3 o cristal de 40 MHz; 2, RC_FAST, é tomado como o cristal), bits 12..19 SCLK_DIV_NUM: o clock do core é a fonte dividida por SCLK_DIV_NUM + 1. Ao sair do reset, o cristal, sem divisão, então CLKDIV 347 dá 115 274 baud. Os fracionários SCLK_DIV_A/SCLK_DIV_B são armazenados, não modelados

O runtime programa uma taxa de baud como o uart_ll_set_baudrate do ESP-IDF faz: o clock APB, pré-escalonado pelo menor SCLK_DIV_NUM + 1 que traga o divisor para baixo de 4096, e o divisor até um dezesseis avos, então 1200 e 9600 baud são exatos em vez de limitados 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 livre de 52 bits a 16 MHz, um comparador ligado à interrupção de timer da CPU.

offset nome bits
0x04 SYSTIMER_UNIT0_OP_REG bit 30 UPDATE: escreva 1 para travar a contagem em VALUE_HI/LO; bit 29 VALUE_VALID lê 1 depois de travado
0x40 SYSTIMER_UNIT0_VALUE_HI_REG bits 0..19, bits 32..51 da contagem travada
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 da contagem travada
0x50 SYSTIMER_COMP0_LOAD_REG escreva 1 para carregar o alvo
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

O timer está sempre rodando. A contagem é derivada do tempo do kernel: contagem = now_ps / 62_500. Ela nunca diverge do circuito.

Verificado registro por registro contra o ESP32-C3 Technical Reference Manual v1.4, seção 10.6 (resumo de registros) e os registros 10.2, 10.14 a 10.17. Uma versão anterior deste modelo colocava o comparador 0 em 0x50 a 0x5C, que no C3 são os strobes de carregamento COMP0_LOAD a COMP2_LOAD e UNIT0_LOAD; esse layout nunca foi o do chip, e o runtime e suas imagens foram reconstruídos quando isso foi corrigido.

3.5 APB_SARADC (0x6004_0000)

ADC1 em modo one-shot: o caminho que o driver adc_oneshot do ESP-IDF e o analogRead do core do Arduino usam, e nada mais. Os canais 0 a 4 são os GPIO 0 a GPIO 4; o ADC2 não é modelado (num C3 real ele é compartilhado com o rádio, e não há rádio aqui).

O endereço base do bloco é o do chip. Os deslocamentos desta tabela marcados como "não verificados" não foram tirados de uma página do manual técnico: são o que este modelo implementa, escolhidos para corresponder ao formato do caminho one-shot, e o firmware compilado aqui concorda com o modelo, concorde ele ou não com o silício. 0x00 e 0x04 são os do manual; o restante dos registros one-shot são os não verificados, e um programa que precise rodar sem alterações num DevKitM-1 deveria conferi-los com o manual primeiro.

offset nome bits
0x00 APB_SARADC_CTRL_REG bits 7..14 SAR_CLK_DIV: divisor do clock SAR. Armazenado e lido de volta; o tempo de conversão aqui é fixo
0x04 APB_SARADC_CTRL2_REG armazenado, lido de volta. Os caminhos por trigger de timer e por DMA não são modelados
0x0C APB_SARADC_FSM_WAIT_REG armazenado, lido de volta (deslocamento não verificado)
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 (armazenado, não converte nada), bit 31 SAR1_ONETIME_SAMPLE (deslocamento e posições de campo não verificados)
0x44 APB_SARADC_1_DATA_STATUS_REG bits 0..16 ADC1_DATA: a última conversão do ADC1, com doze bits (deslocamento não verificado)
0x64 APB_SARADC_INT_ENA_REG armazenado; nenhuma linha chega ao núcleo (deslocamento não verificado)
0x68 APB_SARADC_INT_RAW_REG bit 31 ADC1_DONE (deslocamento não verificado)
0x6C APB_SARADC_INT_ST_REG raw e habilitado (deslocamento não verificado)
0x70 APB_SARADC_INT_CLR_REG escreva 1 para limpar, mesmo bit (deslocamento não verificado)
0x78 APB_SARADC_APB_ADC_CLKM_CONF_REG armazenado, lido de volta (deslocamento não verificado)

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.

O resultado tem doze bits, round(4095 x Vin / Vfull), com limites, da tensão do nó no momento em que a conversão começou. ONETIME_ATTEN escolhe a escala cheia, nos valores nominais que o data sheet cita:

ONETIME_ATTEN atenuação escala cheia
0 0 dB 1.1 V
1 2.5 dB 1.5 V
2 6 dB 2.2 V
3 11 dB a curva do componente real, saturando em cerca de 2.9 V

Os três primeiros são as retas nominais. 11 dB (12 dB no ESP-IDF atual), o padrão do core do Arduino, segue a curva raw de um componente típico (CURVE_11DB em crates/esp32c3/src/adc.rs): quase linear ao longo da faixa efetiva de 0 a 2500 mV do datasheet (3650 a 2.5 V), e depois até 4095 em cerca de 2.9 V (pessoas relatam 2.8 a 3.0 V em unidades reais). Então um potenciômetro no trilho de 3.3 V lê 4095 no último décimo do curso, e um divisor na metade do trilho lê cerca de 2410, não 2048. A calibração de eFuse de uma unidade move isso alguns por cento, o que não é modelado; analogReadMilliVolts inverte a mesma curva. Um canal sem nada no pino vagueia, como faz uma entrada flutuante (docs/uno.md seção 1).

ADC1_DONE pode ser consultado e limpo, que é o que o caminho one-shot faz, mas ele não chega a mip: o ADC não está na linha de interrupção externa (seção 3.6). Também não estão o controlador digital, a tabela de padrões DMA, os filtros, os monitores de limiar ou os canais internos de temperatura e VDD.

3.6 Interrupções

Modo máquina do RISC-V, mtvec direto ou vetorizado, conforme o núcleo suporta. Linhas:

  • Interrupção de timer da máquina (mip.MTIP, causa 7): alvo 0 do SYSTIMER quando o bit 0 de INT_ENA e o 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 estaciona o núcleo até que qualquer linha fique pendente.

3.7 LEDC (0x6001_9000)

O controlador de PWM para LEDs, grupo de baixa velocidade, que é o único grupo que este chip tem: quatro timers e seis canais. Este é o bloco por trás de analogWrite, ledcAttach e 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)

e 5 kHz em oito bits é DUTY_RES 8 com CLK_DIV 16000, exatamente. Um canal escolhe um timer, uma contagem inicial HPOINT e um duty, e sua saída fica alta a partir de HPOINT por DUTY >> 4 contagens, dando a volta no topo do período. Então um duty de 0 é um nível baixo contínuo e um duty de 2^DUTY_RES um nível alto contínuo, sem nenhuma borda, e é por isso que o core do Arduino transforma ledcWrite(pin, 255) em oito bits num duty de 256 em vez de deixar um entalhe de uma contagem a 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 nome bits
0x00 + 0x14n LEDC_CHn_CONF0_REG bits 0..1 TIMER_SEL, bit 2 SIG_OUT_EN, bit 3 IDLE_LV (o nível mantido com o gerador de saída desligado), bit 4 PARA_UP (armazenado; um duty escrito aqui faz efeito na hora)
0x04 + 0x14n LEDC_CHn_HPOINT_REG bits 0..13 HPOINT: a contagem em que o pulso do canal começa
0x08 + 0x14n LEDC_CHn_DUTY_REG bits 0..18 DUTY: a largura do pulso em dezesseis avos de contagem
0x0C + 0x14n LEDC_CHn_CONF1_REG o hardware de fade de duty: armazenado, lido de volta, e não faz nenhum fade
0x10 + 0x14n LEDC_CHn_DUTY_R_REG o duty como está, somente leitura
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 o contador, somente leitura
0xC0 LEDC_INT_RAW_REG bit n = o timer n transbordou
0xC4 LEDC_INT_ST_REG raw e habilitado
0xC8 LEDC_INT_ENA_REG armazenado; nenhuma linha chega ao core
0xCC LEDC_INT_CLR_REG escreva 1 para limpar
0xD0 LEDC_CONF_REG bits 0..1 APB_CLK_SEL (1 = o clock APB de 80 MHz, a única fonte modelada), bit 31 CLK_EN (armazenado)
0xFC LEDC_DATE_REG um carimbo de versão, somente leitura

Configurar um canal é o que ledc_timer_config e ledc_channel_config fazem: escreva LEDC_CONF_REG, escreva o DUTY_RES e o CLK_DIV do timer, escreva o CONF0 do canal com o seu timer e o SIG_OUT_EN, escreva HPOINT e DUTY, defina o bit GPIO_ENABLE do pad e aponte o seu GPIO_FUNCn_OUT_SEL_CFG_REG para 45 + channel.

O contador não avança em passos: ele é uma função fechada do tempo simulado, e o mesmo vale para o instante da sua próxima borda. Por isso, um núcleo parado em wfi não custa nada enquanto um PWM roda, e o componente da placa só é acordado para as bordas e para nada mais.

Não modelado: o grupo de alta velocidade (este chip não tem nenhum), o hardware de duty-fade, o contador de overflow do próprio canal, fontes de clock outras que a APB e a linha de interrupção do LEDC rumo à matriz de interrupções. LEDC_INT_RAW_REG pode ser consultado e limpo, mas nunca chega ao mip, exatamente como o ADC1_DONE do ADC não chega (seção 3.6).

3.8 Caixa de correio de rede do Mokxi (0x6FFF_E000)

Este bloco não é do ESP32-C3. Todo outro endereço neste documento é do chip, citado do manual de referência técnica, e uma imagem construída com base nele roda num DevKitM-1 de verdade. Este aqui é do próprio Mokxi: a rede simulada de crates/net, mapeada num endereço que o componente real deixa sem mapear, para que uma imagem que o use falhe no silício em vez de ler o registrador de algum outro periférico. Essa falha é a resposta honesta, porque a coisa por trás deste bloco não existe no chip.

Aqui não há rádio, nem 802.11, nem internet real. Nada no modelo transmite, escaneia, associa, criptografa ou abre um socket: uma senha é comparada como string, um nome que não está sob .mokxi não resolve, e as três origens que a rede serve são funções em crates/net/src/http.rs. A caixa de correio tem a forma da costura real em vez de uma ficção sobre um MAC: num ESP32 real o hardware de WiFi é um blob binário fechado com uma interface de comandos, e o WiFi.h do Arduino acaba do outro lado de um destes. docs/wifi.md é o contrato do que está por trás dele; esta seção é apenas os registradores.

Um registrador de comando, um registrador de status, um anel de 4096 bytes em cada sentido e um bit de interrupção. Escrever em NET_CMD_REG executa o comando; um comando que leva tempo simulado levanta BUSY e o limpa, com DONE em NET_INT_RAW_REG, quando termina.

offset nome bits
0x00 NET_ID_REG lê 0x494B4F4D, e nada mais o faz. Um sketch que quer saber se está no Mokxi lê isto; no silício o acesso falha
0x04 NET_CMD_REG escreva um código de comando (tabela abaixo); a escrita o executa
0x08 NET_ARG_REG uma palavra de argumento, lida de volta: a porta para LISTEN, o status 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 o que o último comando respondeu
0x14 NET_INT_RAW_REG bit 0 DONE, bit 1 EVENT
0x18 NET_INT_ENA_REG os mesmos dois bits
0x1C NET_INT_CLR_REG escreva 1 para limpar, os mesmos dois bits
0x20 NET_TX_LEN_REG bytes preparados no anel de saída
0x24 NET_TX_DATA_REG escrita: empurra um byte (bits 0..7) para o anel de saída
0x28 NET_RX_LEN_REG bytes aguardando no anel de entrada
0x2C NET_RX_DATA_REG leitura: retira um byte do anel de entrada, 0 quando está vazio
0x30 NET_RING_LEN_REG capacidade de cada anel em bytes, para o firmware não precisar fixar 4096
0x40 NET_BT_CMD_REG Bluetooth: escreva um código de comando Bluetooth (docs/bluetooth.md); a escrita o executa
0x44 NET_BT_ARG_REG Bluetooth: uma palavra de argumento, lida de volta; um evento deixa seu número aqui
0x48 NET_BT_RESULT_REG Bluetooth: o que o último comando Bluetooth respondeu
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 no seu próprio anel de saída
0x54 NET_BT_TX_DATA_REG Bluetooth: escrita: empurra um byte para esse anel
0x58 NET_BT_RX_LEN_REG Bluetooth: bytes aguardando no seu próprio anel de entrada
0x5C NET_BT_RX_DATA_REG Bluetooth: leitura: retira um byte, 0 quando está vazio

Os oito registradores NET_BT_ são a metade Bluetooth do bloco, com anéis próprios: só Bluetooth LE, como no chip real, então os comandos do Classic setam BT_ERR. Também não há rádio por trás deles; docs/bluetooth.md é o contrato deles.

STATE é onde está a estação: 0 ociosa, 1 iniciando, 2 conectando, 3 conectada, 4 falhou, 5 rede inexistente. NET_CMD_STATUS transforma a mesma coisa no código wl_status_t do Arduino que um sketch lê de WiFi.status().

NET_CMD_REG nome o que faz
0 NOP nada
1 RESET desconecta, zera ambos os anéis, descarta qualquer requisição
2 CONNECT o anel de saída contém ssid\0password; levanta BUSY por um a três segundos
3 DISCONNECT descarta a associação e o endereço
4 STATUS NET_RESULT_REG = o código wl_status_t
5 IP NET_RESULT_REG = o endereço obtido, primeiro octeto no byte menos significativo
6 RSSI NET_RESULT_REG = o sinal em dBm, com sinal estendido
7 SSID o anel de entrada recebe o nome do ponto de acesso
8 MAC o anel de entrada recebe os seis bytes de MAC da placa
9 REQUEST o anel de saída contém method\0url\0headers\0body; levanta BUSY
10 POLL NET_RESULT_REG = 0 em andamento, depois o status HTTP, ou um erro negativo com ERR ativo; o corpo chega no anel de entrada
11 LISTEN escuta na porta em NET_ARG_REG
12 ACCEPT NET_RESULT_REG = 1 e o anel de entrada contém method\0path\0query\0body, ou 0 quando nada está aguardando
13 REPLY responde à requisição aceita com o status em NET_ARG_REG; o anel de saída contém content-type\0body
14 STOP para de escutar
15 WL_GPIO_SET controla os próprios GPIOs do componente sem fio a partir de NET_ARG_REG. Não nesta placa: o rádio deste componente não tem esse pino, então ele define ERR e não controla nada. É o caminho que o LED embutido de um Pico W percorre (docs/picow.md seção 3.8)
16 WL_GPIO_GET lê de volta, e o mesmo ERR aqui
17 BLYNK uma operação no servidor Blynk simulado, a operação em NET_ARG_REG e seus campos no anel de saída; respondida de imediato em NET_RESULT_REG, com ERR ativo, sem passar pela rede (docs/wifi.md, "Blynk")
19 ETH Ethernet com fio (firmware/include/ETH.h), a operação em NET_ARG_REG: 1 levanta o enlace por um cabo simulado, sem SSID e sem senha, conectado 1,5 s depois com o mesmo lease; 2 coloca 1 em NET_RESULT_REG quando o enlace é (ou foi por último) o com fio. Há um único enlace: STATUS, IP e toda requisição o leem de que forma ele tenha subido
20 SOFTAP o soft AP (crates/net/src/softap.rs, docs/wifi.md), a operação em NET_ARG_REG: 1 o levanta (o anel de saída ssid\0password\0 e o byte de canal; NET_RESULT_REG 1, ou 0 com ERR para um nome vazio ou uma senha de um a sete caracteres), 2 o derruba, 3 o configura (endereço, gateway e máscara de rede, quatro bytes cada), 4 seu endereço (0 enquanto estiver derrubado), 5 as estações conectadas, 6 as entradas, saídas e o bit de ativo que o runtime transforma em eventos, 7 e 8 um servidor DNS de portal cativo iniciando (o nome, um byte zero, o endereço) e parando, 9 seu nome no anel de entrada, 10 o endereço do telefone, 11 o Host da requisição sendo servida no anel de entrada. A única estação é o telefone do painel Web

Os códigos negativos de POLL: -1 o nome não resolve, -2 a estação não está associada, -3 https:// e o TLS não são simulados, -4 um corpo maior que o anel, -5 uma URL que esta rede não consegue interpretar, -6 já há uma requisição em andamento. firmware/include/HTTPClient.h os transforma nos códigos no formato Arduino que um sketch compara, e docs/wifi.md lista o mapeamento.

Temporização, toda ela própria deste modelo e toda declarada em docs/wifi.md: uma associação leva entre um e três segundos, decidida a partir do SSID para que uma aula leve o mesmo tempo nas duas vezes; uma senha errada vira WL_CONNECT_FAILED após cinco segundos; uma requisição a uma origem simulada volta 60 ms depois; uma requisição ao próprio servidor do sketch que o sketch nunca responde é fechada pela rede com um 504 após dez segundos.

3.9 Watchdogs dos grupos de timer, resets do RTC_CNTL e o monitor de pilha (0x6001_F000, 0x6002_0000, 0x6000_8000, 0x600C_E000)

O watchdog principal de cada grupo de timers (crates/esp-common/src/mwdt.rs): WDTCONFIG0..5, WDTFEED e a chave WDTWPROTECT, quatro estágios, cada um com sua ação (uma interrupção, um reset de CPU ou um reset de sistema), o prescaler no clock APB de 80 MHz ou, com WDT_USE_XTAL, o cristal de 40 MHz, e uma configuração escrita que passa a valer em WDT_CONF_UPDATE_EN. O bit do watchdog em TIMG_INT_ENA/RAW/ST/CLR (bit 1) gera a interrupção externa da máquina, como GPIO e UART0 fazem (seção 3.6). Um estágio de reset reinicia o chip com o clock ligado e RTC_CNTL_RESET_STATE_REG dizendo o porquê (7 ou 8 para um reset de sistema, 0xB ou 0x11 para um reset de CPU); a RAM é recarregada da imagem, RTC_CNTL_STORE0..7 mantêm seus valores, e RTC_CNTL_SW_SYS_RST e RTC_CNTL_SW_PROCPU_RST em RTC_CNTL_OPTIONS0_REG também a reiniciam (causas 3 e 0xC).

O runtime roda o task watchdog do ESP-IDF no watchdog do grupo de timer 0, como o ESP-IDF faz (firmware/src/main.cpp): ticks de 500 µs, estágio 0 uma interrupção no timeout e estágio 1 um reset do sistema no dobro disso, iniciado antes do setup() com 5 s e um panic, observando a tarefa idle do núcleo 0. A interrupção imprime as linhas do ESP-IDF ("E (…) task_wdt: Task watchdog got triggered. …", as tarefas, "Aborting.", a linha de abort e "Rebooting..."), deixa a pista ESP_RST_TASK_WDT do ESP-IDF no registrador de armazenamento do RTC e reinicia a CPU pelo reset por software, então esp_reset_reason() retorna 6 depois. esp_task_wdt_*, enableLoopWDT() e enable/disableCore0WDT() atuam sobre ele. O watchdog do grupo de timer 1 é modelado do mesmo jeito e nada no runtime o arma: o interrupt watchdog não é simulado.

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 do host

host = "bytes utf-8 na UART0". readHost devolve os bytes TX da UART0 conforme saem do FIFO; writeHost empurra bytes para o FIFO RX da UART0 (estouro descarta, como no chip). O monitor serial mostra os bytes como texto, decodificando UTF-8 e tratando \n como fim de linha (\r ignorado).

5. Modelo de tempo

A CPU roda a 160 MHz com uma instrução por ciclo. O componente executa em fatias: a cada acordar ele roda SLICE_NS * 160 instruções (SLICE_NS = 10 us, ou seja, 1600 instruções) e então agenda o próximo acordar, com estas regras:

  • Escritas em periféricos que mudam um pino (GPIO OUT ou ENABLE, pulls do IO_MUX) dirigem o pino no instante do início da fatia mais a contagem de instruções até agora dividida por 160 MHz. Use drive_after com esse atraso para que duas alternâncias dentro de uma mesma fatia mantenham o espaçamento. Leituras de GPIO_IN veem o nível do pino no início da fatia.
  • A comparação do timer e o ritmo da UART são avaliados contra o mesmo tempo dentro da fatia, então micros() é monótono e um delayMicroseconds em espera ocupada é preciso até uma instrução.
  • 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: o componente para de fatiar e agenda um acordar no mais cedo entre o alvo do timer e um evento de UART; uma mudança de pino GPIO o acorda na hora.
  • Falhas de acesso: o núcleo faz trap para o mtvec; com mtvec = 0 isso gera trap para sempre. O componente conta os traps e, depois de 1000 traps consecutivos sem progresso, ele para e relata "firmware crashed at pc=…, mcause=…" pelo probe (veja abaixo) e pelo canal do host (uma linha).

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 do 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. O que este modelo sabe com certeza, e o que não sabe

Três grupos, a mesma ordenação que a seção 7 de docs/esp32c6.md usa. Ela existe porque um modelo de placa que adivinha silenciosamente um endereço é pior do que um que diz que não sabia.

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.

Acreditado, não verificado. Nomeado assim, registrador por registrador, nas seções 3.1 e 3.5, e repetido aqui para que a lista fique em um só lugar:

  • Todo offset de registrador de disparo único dentro do APB_SARADC exceto 0x00 e 0x04. Ou seja FSM_WAIT em 0x0C, ONETIME_SAMPLE em 0x38 e suas posições de campos, 1_DATA_STATUS em 0x44, os quatro registradores de interrupção em 0x64 a 0x70, e APB_ADC_CLKM_CONF em 0x78. São o que este modelo implementa, escolhidos para combinar com o formato do caminho de disparo único, não linhas copiadas de uma página do manual.
  • Os índices de sinal 45 a 50 da matriz GPIO para ledc_ls_sig_out0 a ledc_ls_sig_out5, escolhidos para que a matriz tenha onde colocá-los.

O firmware compilado para este documento concorda com o modelo, concorde ele ou não com o silício. Uma imagem levada a um DevKitM-1 real deve primeiro conferir esses #defines em firmware/include/esp32c3.h com o manual.

Modelado, mas não comprometido com os números do manual. Comportamentos em vez de endereços:

  • O ADC a 11 dB é a curva de um componente típico, não desta unidade. A saturação em cerca de 2,9 V e o ganho acima da faixa efetiva de 2,5 V estão lá (seção 3.5); a variação de unidade para unidade que a calibração de eFuse corrige e o ruído de conversão não estão. As outras atenuações são as retas nominais (1,1 V, 1,5 V, 2,2 V).
  • Uma instrução é um ciclo a 160 MHz. Não há gargalos de pipeline, não há cache (não existe cache), não há ciclos de espera de flash e não há contenção de barramento, então a contagem de instruções é o clock. Um C3 real rodando da flash é mais lento e menos uniforme que isto.
  • Os pads são três estados e um limiar. Push-pull a 3,3 V, alta impedância, ou um pull interno de 45 kΩ, lidos contra metade da alimentação, sem histerese, sem ajuste de força de acionamento, sem tempo de subida e sem limite de corrente. Um pino não acionado lê 0 em vez de flutuar para algum valor.
  • A placa é uma fonte ideal: 3V3 e 5V na impedância do trilho para sempre, então nada sofre brownout. A inicialização é um microssegundo, onde um C3 real gasta dezenas de milissegundos em sua boot ROM.
  • Uma fatia dura 10 µs, e o SoC e o circuito se encontram nos limites de fatia ou no que quer que o chip esteja esperando.

Ausentes de propósito. Deixados de fora em vez de inventados, porque o layout de registradores não é algo que este modelo possa reproduzir com honestidade: Bluetooth LE (sem rádio, e sem fingir ter um), SPI, I2C, I2S, RMT, USB Serial/JTAG, os temporizadores dos grupos de timer (seus watchdogs são os da seção 3.9), a matriz de interrupções completa (a seção 3.6 diz o que faz as vezes dela), o ADC2 e a tabela de padrões DMA do SAR ADC, controlador digital, filtros, monitores de limiar e eFuses de calibração, o grupo de alta velocidade do LEDC e o hardware de duty-fade e sua linha de interrupção até o núcleo, a PMU e a árvore de clock, o cache, a ROM e a flash. É por isso que binários do ESP-IDF e do core Arduino do fabricante não rodam aqui, e firmware compilado para este documento roda.

WiFi: simulado, veja 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 é o contrato do que essa rede faz e, em mais detalhe, do que ela não faz.

Perguntas

Does it do WiFi?

WiFi simulado, sim. Seu sketch usa as chamadas reais do Arduino (WiFi.begin, HTTPClient, WebServer) e a placa conecta, busca e serve, mas não há rádio nem 802.11 por baixo. Logado, você pode ativar Internet real no painel Cloud. A seção 3.8 e a página WiFi simulado têm o contrato.

Meu firmware roda num DevKitM-1 de verdade?

Sim. O modelo usa o mapa de memória real e os offsets de registradores reais para tudo o que implementa, então uma compilação daqui não é específica do Mokxi.