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 A ESP32 DevKit V1 e página da placa.
A ESP32 DevKit V1 é a placa DOIT de trinta pinos em torno de um módulo ESP32-WROOM-32: um Xtensa LX6 a 240 MHz, o primeiro componente aqui que não é RISC-V, nem AVR, nem Arm. Um componente do kernel (esp32 em crates/parts) envolve um modelo de SoC ESP32 (crates/esp32) sobre um interpretador Xtensa (crates/xtensa-core). Este documento é o contrato, e ele prevalece sobre qualquer comentário no código.
O tipo no catálogo é esp32. A string program do catálogo é elf32 xtensa lx6 esp32.
Leia a seção 6 primeiro se você vai levar uma compilação daqui para o silício real. Ela diz, endereço por endereço, quais números vieram do ESP32 Technical Reference Manual e quais são convicção deste modelo, e lista o que não está aqui de forma alguma: o segundo núcleo, o cache, o flash, a PSRAM e os dois rádios, entre outros. Nada é adivinhado em silêncio.
Um sketch para esta placa compila no navegador com clang-v3, a compilação em wasm do fork de LLVM da Espressif (-mcpu=esp32), publicada em 28/09/2026 e verificada neste simulador (docs/compile.md). Um exemplo intocado ainda executa seu ELF pré-compilado de web/public/firmware/esp32/, que o GCC da Espressif compila. A seção 7 tem os detalhes.
1. Pinos da placa (ordem do catálogo)
Vista de cima, o conector micro-USB embaixo, o módulo WROOM-32 e sua antena de PCB em cima. A placa tem 51,5 x 28,3 mm e seus dois conectores de 15 pinos ficam a 22,86 mm (0,9 polegada) de distância, o que permite que uma DOIT DevKit V1 atravesse uma protoboard sobrando uma fileira de furos livre de cada lado. O visual a desenha nesse tamanho.
A DevKitC de 38 pinos da Espressif é a outra placa que as pessoas chamam de "uma ESP32 DevKit", e seus conectores ficam a uma polegada inteira de distância: numa protoboard ela não deixa nenhuma fileira livre. Esta é a placa DOIT de trinta pinos.
Conector esquerdo, de cima para baixo (15 furos): EN, VP, VN, D34, D35, D32, D33, D25, D26, D27, D14, D12, GND, D13, VIN.
Conector direito, de cima para baixo (15 furos): D23, D22, TX0, RX0, D21, D19, D18, D5, TX2, RX2, D4, D0, D2, D15, 3V3.
30 pinos. Dn é o GPIO n. VP é o GPIO 36 e VN é o GPIO 39: os pinos SENSOR_VP e SENSOR_VN do conversor, que a serigrafia nomeia pela função. TX0/RX0 são os GPIO 1 e 3, a UART do console; TX2/RX2 são os GPIO 17 e 16. EN é o chip enable, que é o reset desta placa. VIN é o trilho de 5 V do USB. Nomes duplicados levariam uma letra, porque os nomes de pinos no catálogo são únicos; esta placa não tem nenhum.
Os GPIO 6 a 11 não estão em nenhum dos conectores. Eles são o flash SPI (SD_CLK, SD_DATA0..3 e SD_CMD), e o programa está executando a partir deles. Uma placa que deixasse um sketch acioná-los seria uma placa que se brickaria sozinha, então eles não são pinos aqui. crates/parts/src/parts/esp32.rs tem um teste que se recusa a deixá-los aparecer em um conector.
Os GPIO 34 a 39 não têm driver de saída. Neste componente eles são entradas e nada mais: sem push-pull, sem open drain, e também sem pull-up ou pull-down internos. pinMode(34, OUTPUT) escreve em GPIO_ENABLE1_REG, o bit não permanece, e o pino fica em alta impedância. Quatro dos seis estão no conector (D34, D35, VP, VN). O modelo conta cada tentativa e o componente da placa relata a contagem através de probe (seção 5), porque este é o erro que custa a um dono de ESP32 uma tarde inteira, e um simulador que deixasse passar estaria ensinando a coisa errada.
Dois pinos carregam algo na placa:
- O GPIO 2 tem um LED azul, e é um LED comum em um pad comum: o nível do pad é a lâmpada, nada decodifica nada. Ele também é um pino de strapping, então o estado do LED numa DevKit real antes de
pinModerodar varia entre placas. - O GPIO 0 é o botão BOOT, ativo em nível baixo. Ele está no conector direito como
D0, então também pode ser ligado;pokeo conecta ao terra na placa.
Elétrico: cada GPIO com driver de saída aciona em push-pull a 3,3 V através de R_STRONG, fica em alta impedância, ou faz pull-up ou pull-down através de 45 k. Uma entrada lê nível alto a 1,65 V (metade da alimentação de I/O); um nó disputado (Unknown) lê 0, e um flutuante lê ruído, como na Uno (docs/uno.md seção 1). GPIO0 lê nível alto quando nada o segura, pelo pull-up da própria DevKit ao lado do botão BOOT. 3V3 fornece 3,3 V em R_SUPPLY, VIN fornece 5 V, GND fornece 0 V. EN carrega um pull-up de 10 k para 3,3 V e puxá-lo abaixo de 1,65 V mantém o núcleo em reset. Os 100 nF ao lado desse resistor numa DevKit real são o power-on reset da placa e não são modelados, então EN aqui é apenas o resistor.
A ordem exata da serigrafia dos dois conectores é a leitura que este modelo faz do pinout do DOIT DevKit V1. Os números de GPIO são os do chip e são os que o firmware depende; a posição deles no conector é o que um diagrama depende. Se as fileiras de um DevKit específico estiverem em ordem diferente (e elas variam entre as placas de 30 e de 36 pinos), um circuito desenhado aqui precisaria ser religado numa mesa, e nada mais mudaria.
2. Mapa de memória
| IRAM (instruções) | 128 KB em 0x4008_0000 a 0x4009_FFFF |
| IROM (flash code) | 0x400D_0000, read-only, up to 1,310,720 bytes, section 2.1 |
| DROM (flash constants) | 0x3F40_0000, read-only, up to 1,310,720 bytes, section 2.1 |
| DRAM (dados) | 192 KB em 0x3FFB_0000 a 0x3FFD_FFFF |
| topo da pilha | 0x3FFE_0000 |
| DPORT | 0x3FF0_0000, seção 3.7 |
| UART0 | 0x3FF4_0000, seção 3.3 |
| matriz de GPIO | 0x3FF4_4000, seção 3.1 |
| SENS | 0x3FF4_8800, seção 3.5 |
| IO_MUX | 0x3FF4_9000, seção 3.2 |
| LEDC | 0x3FF5_9000, seção 3.6 |
| Timer group 0 | 0x3FF5_F000, seção 3.4 |
Cada bloco de periférico tem 4 KB aqui.
Two windows, not one, and that is the shape of this chip. The ESP32 has three internal SRAMs, two of which are visible through both the instruction bus and the data bus at different addresses, and SRAM1's 32 KB blocks appear in the opposite order through the two. That alias is not modeled. What is modeled is the pair ESP-IDF itself uses and keeps apart: IRAM for code, DRAM for data. The vectors, the exception entry and the startup code go in the 128 KB at 0x4008_0000; the rest of the code and the constants run from flash (section 2.1); .data, .bss and the stack go in the 192 KB at 0x3FFB_0000. A program that tries to read its own .text through the data bus is refused rather than served, because on the real part that read would have come back through the other window with the blocks in a different order.
Every PT_LOAD segment must land inside one of those two ranges or one of the two flash windows; anything else is refused with the offending address in the message, and the chip is left with no program.
2.1 Flash: code and constants
A real ESP32 runs almost all of a sketch from flash through the cache: code is read at IROM (0x400D_0000) and const data at DROM (0x3F40_0000), and the Arduino IDE's default partition table ("Default 4MB with spiffs") gives the sketch 1,310,720 bytes (0x14_0000) of it. That is the room a sketch has here, and the number the editor prints after a build ("Sketch uses N bytes ... Maximum is 1,310,720 bytes"). It counts what the IDE counts: code, literals, constants, the startup code and the initial values of the variables.
What is modeled: two read-only windows over the loaded image. A fetch or a read from either costs what a fetch from IRAM costs, which is the speed of a warm cache; there is no cache to miss and no MMU, and docs/esp32.md section 6 still says so. A store to a flash window faults, as it does on the chip. The code window shares one buffer with the instruction RAM (so a fetch is one range check whichever it is in), which means the unmapped 192 KB between them reads as zeros here, where the chip would fault; a jump into it still stops the core, since an all-zero word is an illegal instruction.
The link script (firmware/esp32/link.ld) puts .text.vectors, .text.exception, .text.start and anything marked .iram in the instruction RAM and every other function in the code window. Its literal pools sit in front of their own functions, because L32R only reaches 256 KB backwards, and every call out of the startup code goes through a register, because CALL4 and CALL8 reach 128 KB. Global variables are still limited by the data RAM (192 KB here); a program over it is refused with "no room for the stack".
O núcleo reinicia com o pc no ponto de entrada do ELF e todos os registradores de endereço em zero. Não há boot ROM aqui: as dezenas de milissegundos que um ESP32 real gasta no loader de primeira etapa, as leituras de flash, a árvore de clock e a configuração do cache estão todas ausentes, e firmware/esp32/crt0.S deixa explícito o estado que quer em vez de assumir o que uma ROM teria deixado.
3. Registradores de periféricos
Apenas o subconjunto abaixo está implementado. Qualquer outra coisa dentro de um bloco mapeado de 4 KB lê 0 e conta como acesso perdido; qualquer coisa fora de todos os blocos é uma falta de acesso.
3.1 Matriz de GPIO (0x3FF4_4000)
Quarenta pinos, então todo registrador com um bit por pino vem em duas metades: o simples cobre GPIO 0 a 31 e o 1 cobre GPIO 32 a 39 nos oito bits baixos.
| offset | registrador |
|---|---|
0x00 |
GPIO_BT_SELECT_REG |
0x04 |
GPIO_OUT_REG |
0x08 |
GPIO_OUT_W1TS_REG |
0x0C |
GPIO_OUT_W1TC_REG |
0x10 |
GPIO_OUT1_REG |
0x14 |
GPIO_OUT1_W1TS_REG |
0x18 |
GPIO_OUT1_W1TC_REG |
0x20 |
GPIO_ENABLE_REG |
0x24 |
GPIO_ENABLE_W1TS_REG |
0x28 |
GPIO_ENABLE_W1TC_REG |
0x2C |
GPIO_ENABLE1_REG |
0x30 |
GPIO_ENABLE1_W1TS_REG |
0x34 |
GPIO_ENABLE1_W1TC_REG |
0x38 |
GPIO_STRAP_REG |
0x3C |
GPIO_IN_REG |
0x40 |
GPIO_IN1_REG |
0x44 |
GPIO_STATUS_REG |
0x48 |
GPIO_STATUS_W1TS_REG |
0x4C |
GPIO_STATUS_W1TC_REG |
0x50 |
GPIO_STATUS1_REG |
0x54 |
GPIO_STATUS1_W1TS_REG |
0x58 |
GPIO_STATUS1_W1TC_REG |
0x88 + 4n |
GPIO_PINn_REG |
0x530 + 4n |
GPIO_FUNCn_OUT_SEL_CFG_REG |
Conferido contra o manual de referência técnica: o endereço base do bloco e cada offset desta tabela.
GPIO_PINn_REG, bit 2 PAD_DRIVER, torna o pad open drain; os bits 7..9 INT_TYPE escolhem o que levanta a interrupção do pino (0 desligado, 1 borda de subida, 2 borda de descida, 3 qualquer borda, 4 nível baixo, 5 nível alto); o bit 13 PIN_INT_ENA, bit do núcleo PRO, permite que o pino chegue à matriz.
GPIO_FUNCn_OUT_SEL_CFG_REG em 256 faz o pad seguir GPIO_OUT. De 71 a 78 entregam o pad aos canais de alta velocidade do LEDC, 0 a 7. Qualquer outro valor seleciona um periférico que não é modelado, e o modelo trata como 256 em vez de inventar um nível. Um pad que um canal do LEDC está dirigindo ainda precisa do driver de saída ligado em GPIO_ENABLE.
Não verificado: os índices de sinal da matriz de GPIO 71 a 78 para ledc_hs_sig_out0 a ledc_hs_sig_out7. A tabela de sinais da matriz não é algo que este modelo possa citar de volta, e o número existe em exatamente dois lugares (OUT_SEL_LEDC_HS_SIG em crates/esp32/src/map.rs e GPIO_FUNC_OUT_SEL_LEDC_HS em firmware/esp32/include/esp32.h), então o modelo e o runtime concordam porque ambos leem a mesma constante, não porque algum dos dois conferiu. GPIO_FUNC_OUT_SEL_GPIO = 256 é do manual.
GPIO_STRAP_REG lê de volta 0b1101: GPIO 0, 2 e 5 em alto, todo o resto em baixo, que é como um WROOM-32 sai de fábrica. Aqui é uma constante, não um registro do que os pinos estavam fazendo no reset.
Os seis pinos sem driver de saída (GPIO 34 a 39) aceitam escritas no bit ENABLE1 e o mantêm em zero, e o modelo conta a tentativa (seção 1, seção 5).
3.2 IO_MUX (0x3FF4_9000)
IO_MUX_PIN_CTRL_REG em 0x00, depois um registrador por pad. Bit 7 FUN_WPD, bit 8 FUN_WPU, bit 9 FUN_IE, bits 12..14 MCU_SEL, dos quais 2 é GPIO simples nesta parte. Um pad só chega a GPIO_IN_REG com o buffer de entrada ativado, que é o que o hardware faz.
O IO_MUX do ESP32 não é indexado pelo número de GPIO. Os registradores estão na ordem de pads do encapsulamento, e o mapeamento de GPIO para pad é uma tabela no manual. A tabela deste modelo é:
| GPIO | offset | GPIO | offset | GPIO | offset | GPIO | offset |
|---|---|---|---|---|---|---|---|
| 0 | 0x44 |
10 | 0x58 |
20 | 0x78 |
32 | 0x1C |
| 1 | 0x88 |
11 | 0x5C |
21 | 0x7C |
33 | 0x20 |
| 2 | 0x40 |
12 | 0x38 |
22 | 0x80 |
34 | 0x14 |
| 3 | 0x84 |
13 | 0x3C |
23 | 0x8C |
35 | 0x18 |
| 4 | 0x48 |
14 | 0x30 |
24 | 0x90 |
36 | 0x04 |
| 5 | 0x6C |
15 | 0x34 |
25 | 0x24 |
37 | 0x08 |
| 6 | 0x60 |
16 | 0x4C |
26 | 0x28 |
38 | 0x0C |
| 7 | 0x64 |
17 | 0x50 |
27 | 0x2C |
39 | 0x10 |
| 8 | 0x68 |
18 | 0x70 |
28..31 | nenhum | ||
| 9 | 0x54 |
19 | 0x74 |
Acreditado em vez de verificado. A tabela é a leitura que este modelo faz da ordem dos pads, e não uma página citada. Ela está em dois lugares, IOMUX_INDEX em crates/esp32/src/map.rs e mokxi_iomux_index[] em firmware/esp32/src/gpio.c, então modelo e runtime concordam entre si, concordem ou não com o silício. GPIO 28 a 31 não existem nesta parte e não têm registrador.
Todo pad liga aqui com FUN_IE | (2 << 12): GPIO simples com o buffer de entrada ligado. Os valores de reset por pad do manual são diferentes (os pinos de strapping e de flash sobem com pulls), e este modelo dá a todos os pinos o mesmo estado neutro, para que um programa que só escreve GPIO_ENABLE e GPIO_OUT se comporte igual em todos os pinos. A seção 6 repete isso como aproximação, não como endereço.
3.3 UART0 (0x3FF4_0000)
| offset | registrador |
|---|---|
0x00 |
UART_FIFO_REG |
0x04 |
UART_INT_RAW_REG |
0x08 |
UART_INT_ST_REG |
0x0C |
UART_INT_ENA_REG |
0x10 |
UART_INT_CLR_REG |
0x14 |
UART_CLKDIV_REG |
0x1C |
UART_STATUS_REG |
0x20 |
UART_CONF0_REG |
0x24 |
UART_CONF1_REG |
Verificado: a base e cada offset, os dois bits de reset de FIFO e a largura das duas contagens de FIFO abaixo. É a mesma IP de UART do ESP32-C3 e do ESP8266, registro por registro, e é por isso que crates/esp32/src/uart.rs e crates/esp8266/src/uart.rs são o mesmo arquivo duplicado.
Duas FIFOs de 128 bytes. UART_CONF0_REG, bit 17 RXFIFO_RST e bit 18 TXFIFO_RST, as esvaziam: o ESP32 Technical Reference Manual (v5.8), registrador 19.9 UART_CONF0_REG, coloca TXFIFO_RST no bit 18 e RXFIFO_RST no bit 17. Uma versão anterior deste modelo e de firmware/esp32/include/esp32.h tinha os dois trocados. O Serial.begin do runtime ativa e depois limpa os dois bits juntos, então o valor escrito é o mesmo de qualquer jeito e as imagens dele não foram afetadas.
UART_CONF1_REG bits 0..6 são RXFIFO_FULL_THRHD e bits 8..14 TXFIFO_EMPTY_THRHD, ambos 96 no reset (registro 19.10); uma versão anterior deste modelo tinha campos de nove bits em 0 e 9, e o runtime nunca escreve no registro. UART_CLKDIV_REG bits 0..19 são a parte inteira do divisor (registro 19.6; a parte fracionária em bits 20..23 não é modelada). O divisor divide o clock APB de 80 MHz e reseta para 694, que é 115 274 baud: perto o suficiente de 115200 para um monitor não se importar, e exatamente o que o número dá. O ritmo de transmissão antes lia apenas doze bits dele, então Serial.begin(9600), cujo divisor é 8333, enviava bytes cerca de 59 vezes rápido demais; agora lê os vinte.
UART_STATUS_REG bits 0..7 são RXFIFO_CNT e bits 16..23 TXFIFO_CNT (registro 19.8). Os bits 8..11 e 24..27 acima deles são as máquinas de estado do receptor e do transmissor (ST_URX_OUT, ST_UTX_OUT). O modelo retorna as duas contagens nessas posições e 0 nos bits das máquinas de estado, já que não executa nenhuma das duas. O runtime lê oito bits, como o manual dá os campos. Um runtime anterior lia dez, o que aqui dava os mesmos números porque os bits acima valem 0, mas no silício pegaria dois bits de ST_UTX_OUT: a contagem de transmissão leria 256 ou mais enquanto um byte estava no fio, e Serial.write, que espera espaço no FIFO, esperaria para sempre. As imagens foram reconstruídas quando isso foi corrigido, e crates/esp32/tests/contract.rs mantém as máscaras do cabeçalho iguais às do modelo.
Os bytes saem do FIFO de transmissão na taxa de baud, não instantaneamente. Sem isso um programa que imprime em loop esvazia seu FIFO tão rápido quanto o enche, TXFIFO_CNT nunca sobe, e o firmware que o confere antes de escrever nunca precisa esperar. Com isso uma porta de 115 200 baud carrega 11 520 bytes por segundo aqui exatamente como numa mesa, e crates/esp32/tests/runtime.rs mede o intervalo entre dois bytes do exemplo serial contra os 86.8 us que um byte leva.
3.3a UART1 (0x3FF5_0000) e UART2 (0x3FF6_E000)
O bloco de registros da UART0 mais duas vezes, em REG_UART_BASE(1) e REG_UART_BASE(2) do ESP-IDF, com os mesmos offsets. Verificado contra o soc/esp32/register/soc/uart_reg.h do ESP-IDF: as bases, os offsets e os campos abaixo. Diferente da UART0, elas não estão ligadas a nenhum canal do host: chegam ao circuito apenas pela matriz GPIO (seção 3.1), um bit por vez.
- Roteamento pela matriz. No
GPIO_FUNCn_OUT_SEL_CFG_REGo sinal 17 éU1TXD, 198 éU2TXD;GPIO_FUNCm_IN_SEL_CFG_REG(em0x130 + 4m, 256 deles) para o sinal 17 éU1RXDe para 198U2RXD, comSIG_IN_SEL(bit 7) pegando o GPIO emIN_SEL(bits 0..5) eIN_INV_SEL(bit 6) invertendo-o. Os números são dogpio_sig_map.hdo ESP-IDF. OINV_SEL(bit 9) doOUT_SELinverte a saída. Um sinal comSIG_IN_SELlimpo vem do seu pad IO_MUX no chip; esse caminho não é modelado (a linha lê ociosa), e o runtime roteia todo pino pela matriz, o que também funciona em todo pino no silício. - O quadro.
UART_CONF0_REGPARITY/PARITY_EN(bits 0 e 1),BIT_NUM(2..3, cinco a oito bits) eSTOP_BIT_NUM(4..5: um, um e meio, dois). No chip dois bits de parada precisam da solução alternativaRS485_CONF.DL1_ENdo ESP-IDF; aquiSTOP_BIT_NUM3 é simplesmente dois.RXD_INV(19) eTXD_INV(22) invertem as linhas,ERR_WR_MASK(26) impede que bytes com erro de enquadramento ou paridade entrem no FIFO. - O clock.
TICK_REF_ALWAYS_ON(bit 27, definido no reset) divide o clock APB de 80 MHz; limpo, oREF_TICKde 1 MHz, que o ESP-IDF usa até 250 000 baud.UART_CLKDIV_REGtem a parte inteira em bits 0..19 e dezesseis avos emCLKDIV_FRAG, bits 20..23, ambos modelados: 9600 baud a partir doREF_TICKé 104 e 2/16, um bit de 104.125 us, 9603.8 baud, como no chip. - FIFOs e limiares. 128 bytes em cada direção. Um byte começa no momento em que o registrador de deslocamento está livre e o próximo segue seu último bit de parada sem intervalo (
tx_idle_num0, como o ESP-IDF define).TXFIFO_CNTconta os bytes ainda esperando, não o que está saindo, eST_UTX_OUT(24..27) eST_URX_OUT(8..11) informam o slot em que cada máquina de estado está, 0 quando ociosa. O bit 15 doSTATUSé a linha de recepção e o bit 31 a de transmissão. - Recepção. Uma queda numa linha ociosa inicia um quadro; o bit de início é conferido no meio dele (um glitch é ignorado), cada outro bit é amostrado no meio do seu slot e o byte chega no meio do bit de parada. O core roda até uma fatia à frente do circuito, então o receptor só amostra tempo que o circuito já informou.
- Interrupções.
RXFIFO_FULL(bit 0) eTXFIFO_EMPTY(1) contra os limiares doCONF1,PARITY_ERR(2),FRM_ERR(3),RXFIFO_OVF(4),RXFIFO_TOUT(8) eTX_DONE(14), nas fontes 35 e 36 da matriz de interrupção.RX_TOUT_ENeRX_TOUT_THRHD(bits 31 e 24..30 doCONF1) definem o timeout nas unidades que ouart_ll_set_rx_toutdo ESP-IDF escreve: oito tempos de bit por unidade a partir do APB, um oitavo de um a partir doREF_TICK. - Não modelado: controle de fluxo por hardware e software, RS-485, IrDA, autobaud, break, o bit de loopback, o detector de comandos AT e os bits de habilitação de clock e reset do
DPORT(ambas as UARTs estão sempre com clock). Seus registros ficam soltos.
Uma UART que o programa nunca escreve não custa nada ao simulador: nenhuma delas é olhada em nenhum caminho até que um registro seu seja escrito, e crates/esp32/src/bus.rs tem um teste que diz isso.
Os Serial1 e Serial2 do runtime (firmware/esp32/src/uartn.c) controlam essas portas do mesmo jeito que o core arduino-esp32 3.x e o driver do ESP-IDF fazem; docs/help/boards/esp32-devkit.md explica o que o sketch vê.
3.4 Grupo de timers 0, timer 0 (0x3FF5_F000)
O contador de 64 bits por trás de micros() e millis().
| offset | registrador |
|---|---|
0x00 |
TIMG_T0CONFIG_REG |
0x04 |
TIMG_T0LO_REG |
0x08 |
TIMG_T0HI_REG |
0x0C |
TIMG_T0UPDATE_REG |
0x10 |
TIMG_T0ALARMLO_REG |
0x14 |
TIMG_T0ALARMHI_REG |
0x18 |
TIMG_T0LOADLO_REG |
0x1C |
TIMG_T0LOADHI_REG |
0x20 |
TIMG_T0LOAD_REG |
0x98 |
TIMG_INT_ENA_TIMERS_REG |
0x9C |
TIMG_INT_RAW_TIMERS_REG |
0xA0 |
TIMG_INT_ST_TIMERS_REG |
0xA4 |
TIMG_INT_CLR_TIMERS_REG |
Verificado: o endereço base do bloco. Acreditado em vez de verificado: todo offset nesta tabela. A base é do manual; o layout dentro dela é deste modelo, e é o mesmo em crates/esp32/src/map.rs e firmware/esp32/include/esp32.h.
T0CONFIG bit 31 EN, bit 30 INCREASE, bit 29 AUTORELOAD, bits 13..28 DIVIDER, bit 10 ALARM_EN. O runtime define DIVIDER como 80, o que dá um tick por microssegundo a partir do clock APB de 80 MHz.
A leitura é travar-e-ler, como o hardware exige: escreva T0UPDATE, depois leia T0HI e T0LO. O contador não é contado. Ele é o tempo simulado dividido pelo divisor, como o SYSTIMER do C3 é, então não há nada contra o que ele possa derivar, e o firmware que fica em espera ocupada em micros() mede exatamente o tempo que o resto do circuito viu passar.
O alarme está implementado e TIMG_INT_RAW sobe quando o contador passa por ele, mas nenhuma linha de interrupção sai deste bloco. Nada o roteia para a matriz de interrupções. O tick de milissegundos do modelo vem do CCOMPARE0 do próprio core (seção 4), que é um registrador do core ligado a uma interrupção de CPU fixa e, portanto, não depende de nenhum endereço que este modelo tivesse que adivinhar. TIMG_INT_ST ainda pode ser consultado e limpo.
O timer 1 do grupo de timers 0 e todo o grupo de timers 1 estão ausentes; o watchdog do grupo de timers 0 é o da seção 3.9.
3.5 SENS: ADC1, one shot (0x3FF4_8800)
ADC1 em modo one-shot: o caminho adc1_get_raw e o analogRead do core do Arduino passam por este componente, e nada mais.
| offset | registrador | bits |
|---|---|---|
0x00 |
SENS_SAR_READ_CTRL_REG |
armazenado, lido de volta; o tempo de conversão aqui é fixo |
0x34 |
SENS_SAR_ATTEN1_REG |
dois bits de atenuação por canal, o canal n nos bits 2n..2n+1 |
0x54 |
SENS_SAR_MEAS_START1_REG |
bits 0..15 MEAS1_DATA_SAR (o resultado, somente leitura), bit 16 MEAS1_DONE_SAR, bit 17 MEAS1_START_SAR, bit 18 MEAS1_START_FORCE, bits 19..26 SAR1_EN_PAD (um bit por canal), bit 31 SAR1_EN_PAD_FORCE |
Verificado: o endereço base. Acreditado em vez de verificado: os três offsets e todas as posições de bits neles. Eles são a leitura que este modelo faz do bloco SENS, no mesmo sentido em que a seção 3.5 de docs/esp32c3.md marca os próprios offsets SAR do C3. O firmware compilado aqui concorda com o modelo, concorde ele ou não com o silício.
Uma conversão: coloque a atenuação em ATTEN1, defina START_FORCE e EN_PAD_FORCE, coloque o bit do canal em SAR1_EN_PAD, levante MEAS1_START_SAR, espere MEAS1_DONE_SAR, leia o dado. Uma conversão leva um tempo simulado fixo de 5 us, pelo qual o firmware realmente espera.
Oito canais, e no ESP32 eles não são os GPIO n:
| canal | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 |
|---|---|---|---|---|---|---|---|---|
| GPIO | 36 | 37 | 38 | 39 | 32 | 33 | 34 | 35 |
O canal 0 é o SENSOR_VP e o canal 3 é o SENSOR_VN; 37 e 38 não são conectados num WROOM-32, então os quatro que o DevKit expõe como números comuns são os canais 4 a 7. Essa tabela é do manual.
O resultado são doze bits da tensão do nó no momento em que a conversão começou. Com 0, 2.5 e 6 dB é a reta nominal do datasheet, round(4095 x Vin / Vfull) limitada, com escala cheia de 1.1 V, 1.5 V e 2.2 V. Com 11 dB, o padrão do core do Arduino, é a curva bruta do componente real (CURVE_11DB em crates/esp32/src/adc.rs): 0 até cerca de 80 mV, quase linear no meio, curvando para cima perto do topo e saturando em 4095 a partir de cerca de 3.15 V. A escala cheia nominal de 3.9 V não é o que uma leitura bruta faz; o datasheet só promete precisão de 150 a 2450 mV com 11 dB, e a contagem bruta de um componente típico se esgota bem antes de 3.9 V. Assim, um potenciômetro ligado ao trilho de 3.3 V lê de 0 a 4095, chegando a 4095 um pouco antes do fim do curso, metade do trilho (1.65 V) lê cerca de 1890, e map(analogRead(pin), 0, 4095, 0, 180) gira um servo até o fim. Os pontos são o ajuste de quarta ordem amplamente usado para ESP32s medidos, invertido; a calibração eFuse de uma unidade os desloca alguns por cento, e isso não é modelado. analogReadMilliVolts inverte a mesma curva, como faz a calibração do core, então lê cerca de 1650 a 1.65 V. Um canal sem nada no seu pino flutua, como faz uma entrada flutuante (docs/uno.md seção 1).
A função de transferência do conversor real curva nas duas pontas e é corrigida pela curva de calibração do eFuse. Nada disso é modelado: este é uma reta. A seção 6 o lista como aproximação.
O ADC2 (que num ESP32 real é compartilhado com o WiFi), o caminho de DMA e tabela de padrões, o controlador digital, os eFuses de calibração, a referência interna, o sensor de toque e o sensor de efeito Hall estão todos ausentes.
3.6 LEDC, o grupo de alta velocidade (0x3FF5_9000)
O controlador de PWM por LED. O grupo de alta velocidade é o que ledcSetup, ledcAttachPin e ledcWrite alcançam com os canais 0 a 7, e é o que o analogWrite usa aqui: quatro timers e oito canais.
| offset | registrador | bits |
|---|---|---|
0x00 + 0x14n |
LEDC_HSCHn_CONF0_REG |
bits 0..1 TIMER_SEL, bit 2 SIG_OUT_EN, bit 3 IDLE_LV, bit 4 PARA_UP (armazenado; um duty escrito aqui faz efeito imediatamente) |
0x04 + 0x14n |
LEDC_HSCHn_HPOINT_REG |
bits 0..19 HPOINT: a contagem em que o pulso começa |
0x08 + 0x14n |
LEDC_HSCHn_DUTY_REG |
bits 0..24 DUTY: a largura do pulso em dezesseis avos de contagem |
0x0C + 0x14n |
LEDC_HSCHn_CONF1_REG |
o hardware de fade de duty: armazenado, lido de volta, e não faz nenhum fade |
0x10 + 0x14n |
LEDC_HSCHn_DUTY_R_REG |
o duty como está, somente leitura |
0x140 + 8n |
LEDC_HSTIMERn_CONF_REG |
bits 0..4 DUTY_RES, de 1 a 20 bits (0 é um timer que ninguém configurou e não conta nada), bits 5..22 CLK_DIV, bit 23 PAUSE, bit 24 RST |
0x144 + 8n |
LEDC_HSTIMERn_VALUE_REG |
o contador, somente leitura |
0x180 |
LEDC_INT_RAW_REG |
bit n = o timer n fez overflow |
0x184 |
LEDC_INT_ST_REG |
raw e habilitado |
0x188 |
LEDC_INT_ENA_REG |
armazenado; nenhuma linha chega ao core |
0x18C |
LEDC_INT_CLR_REG |
escreva 1 para limpar |
0x190 |
LEDC_CONF_REG |
bits 0..1 APB_CLK_SEL, 1 = o clock APB de 80 MHz, a única fonte modelada |
0x1FC |
LEDC_DATE_REG |
lê 0x1605_3100 |
Verificado: o endereço base do bloco. Acreditado em vez de verificado: todo o layout interno dele: o stride de canal, o bloco de timers em 0x140, e os registradores de interrupção e configuração a partir de 0x180.
Um timer conta 2^DUTY_RES contagens a 80 MHz dividido por CLK_DIV, um número Q10.8 de clocks APB por contagem:
f = 80e6 / ((CLK_DIV / 256) * 2^DUTY_RES)
então 5 kHz com 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. Um duty de 0 é um nível baixo contínuo e um duty de 2^DUTY_RES << 4 é um nível alto contínuo sem nenhuma borda, e é por isso que o core do Arduino transforma ledcWrite(pin, 255) com oito bits num duty de 256 em vez de 255, que deixaria um vale de uma contagem a cada período.
Um canal chega a um pad pela matriz de GPIO: defina o bit GPIO_ENABLE do pad e aponte o GPIO_FUNCn_OUT_SEL_CFG_REG dele para 71 + channel (seção 3.1, e esse índice é o não verificado).
O contador não é avançado passo a passo: é uma função fechada do tempo simulado, e o mesmo vale para o instante da sua próxima borda. Um core parado em waiti portanto não custa nada enquanto um PWM roda, e a placa é acordada para as bordas e para mais nada. crates/esp32/tests/runtime.rs mede o período do exemplo fade contra os 1 ms de 1 kHz dentro de 5 us.
Não modelado: o grupo de baixa velocidade (o ESP32 tem um, com seus próprios quatro timers, oito canais e um clock lento; nada no runtime o usa), o hardware de fade de duty, o contador de overflow próprio de um canal, fontes de clock que não sejam o APB, e a linha do LEDC para a matriz de interrupções: LEDC_INT_RAW_REG pode ser consultado e limpo, mas nunca chega ao core.
3.7 DPORT e a matriz de interrupções (0x3FF0_0000)
No ESP32, um periférico não tem uma interrupção de CPU fixa. Ele tem um número de fonte, e o registrador de mapa da matriz para essa fonte diz qual das 32 interrupções do core ela levanta. É por isso que o attachInterrupt aqui são três escritas em vez de uma: configurar o pino, rotear a fonte, desmascarar a interrupção de CPU.
| offset | registrador |
|---|---|
0x104 + 4n |
DPORT_PRO_..._INTR_MAP_REG para a fonte n |
96 fontes. Um registrador de mapa guarda um número de interrupção da CPU em seus cinco bits baixos; uma fonte mapeada para 0 levanta a interrupção 0, que nada habilita, então nada acontece, que é o que o hardware também faz e é como uma fonte é desligada.
Verificado: DPORT_BASE = 0x3FF0_0000. Acreditado em vez de verificado: o offset do array de mapa 0x104, e os dois números de fonte que este modelo roteia:
| fonte | número |
|---|---|
| GPIO | 22 |
| UART0 | 34 |
| UART1 | 35 |
| UART2 | 36 |
Os da UART1 e da UART2 são verificados contra a ordem do soc/esp32/include/soc/interrupts.h do ESP-IDF, que também põe GPIO em 22 e UART0 em 34. Somente estas fontes, e o watchdog do grupo de timers 0 (seção 3.9), alcançam algo. Todo outro registrador de mapa é armazenado e lido de volta e não roteia nada, porque nada mais neste modelo levanta uma interrupção. O resto do DPORT (o controle de cache e MMU, os registradores de controle da CPU APP, os portões de clock e reset dos periféricos, a arbitragem de DMA) está ausente.
3.8 Caixa de correio de rede do Mokxi (0x3FEF_E000)
Este bloco não é do ESP32. Todo outro endereço neste documento é do chip, citado do manual de referência técnica, e uma imagem compilada contra ele é uma imagem para um WROOM-32 real. Este é do próprio Mokxi: a rede simulada de crates/net, no vão que o barramento de dados deixa entre as janelas de memória externa (que terminam em 0x3FBF_FFFF) e a janela de periféricos (que começa no DPORT, 0x3FF0_0000), uma faixa que o chip reserva e na qual não responde nada, de modo que uma imagem que a use falha no silício em vez de ler o registrador de outro periférico. Essa falha é a resposta honesta, porque a coisa por trás deste bloco não existe no chip.
O bloco não levanta nenhuma interrupção. Toda outra fonte aqui chega ao núcleo pela matriz de interrupções da seção 3.7, e um número de fonte da matriz é do chip; não há número honesto para dar a um periférico que o chip não tem, então a caixa de correio não recebe nenhum. NET_INT_RAW_REG ainda pode ser lido, o firmware faz polling, e um núcleo parado em waiti ainda é acordado quando a rede tem algo a dizer, do mesmo jeito que é acordado para uma borda de PWM.
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 para que um callback Bluetooth nunca toque num corpo HTTP: Bluetooth Classic e LE, ambos presentes no ESP32 clássico. 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 Watchdog do grupo de timers 0 e resets do RTC_CNTL (0x3FF5_F048, 0x3FF4_8000)
O watchdog principal do grupo de timers 0, como o do C3 (docs/esp32c3.md seção 3.9), mas com o layout do ESP32: uma escrita tem efeito imediato, o bit de interrupção é o bit 2 de TIMG_INT_* (0x98..0xA4), e ele chega ao núcleo pela matriz de interrupções como origem 16 (o runtime o mapeia para a interrupção 17 da CPU). RTC_CNTL (0x3FF4_8000, os dois kilobytes abaixo de SENS): RTC_CNTL_RESET_STATE_REG em 0x34, os registradores de armazenamento em 0x4C..0x58 e 0xB0..0xBC, e os dois resets por software. O grupo de timers 1 não é modelado.
O runtime executa o watchdog de tarefas do ESP-IDF sobre o watchdog do grupo de timers 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 dele, iniciado antes de setup() em 5 s com um panic, observando a tarefa de idle do núcleo 0. O sketch roda no núcleo 1, cuja tarefa de idle não é observada a menos que ele peça (enableCore1WDT()), então um loop que nunca cede a execução continua rodando, como na placa. 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 dica ESP_RST_TASK_WDT do ESP-IDF no registrador de armazenamento do RTC e reseta a CPU pelo reset de software, então esp_reset_reason() diz 6 depois. esp_task_wdt_*, enableLoopWDT() e enable/disableCore0WDT() atuam sobre ele. O watchdog do grupo de timers 1 é modelado da mesma forma e nada no runtime o arma: o watchdog de interrupção não é simulado.
4. O núcleo: qual ABI, e como uma interrupção chega
crates/xtensa-core é um interpretador Xtensa LX escrito a partir da referência Xtensa Instruction Set Architecture e das codificações que as toolchains da Espressif produzem. Nada nele é derivado do QEMU, do ESP-IDF, dos cores do Arduino ou de qualquer outro emulador. O xtensa-esp32-elf-as foi usado como se usa um instrumento de bancada (montar uma instrução, ler a codificação de volta, escrever o decodificador contra o que saiu), e crates/xtensa-core/tests/encoding.rs guarda essas medições, de modo que o decodificador pode ser conferido contra a evidência, e não contra uma tabela que alguém digitou.
A ABI com janela de registradores, e não havia escolha. O xtensa-esp32-elf-gcc emite entry, call8 e retw.n, e não tem nenhuma opção -mabi=call0. Então a configuração LX6 aqui tem sessenta e quatro registradores de endereço físicos e a janela de registradores, com ENTRY, RETW, ROTW, MOVSP, L32E/S32E e as exceções de overflow e underflow da janela por seus próprios vetores. (O LX106 do ESP8266 tem dezesseis registradores e não tem janela, então seu compilador emite call0; a seção 4 de docs/esp8266.md é a outra metade disto.)
What the LX6 configuration has that the LX106 does not: hardware divide (QUOS, QUOU, REMS, REMU), the 32-bit high multiply, MIN/MAX, SEXT, CLAMPS, the zero-overhead loop (LOOP, LOOPNEZ, LOOPGTZ) and the two atomic loads. Each of those differences was put to the assembler of the toolchain that builds for that chip; the encodings that came back are in tests/encoding.rs.
Modelado: leituras e escritas em todas as larguras com a exceção de alinhamento, todo o conjunto de desvios e desvios condicionais, CALL0/CALL4/CALL8/CALL12 e suas formas indiretas, L32R, MOVI, as instruções de densidade (.n), a ALU inteira, MUL16/MULL/MULUH/MULSH, os registradores especiais e WAITI.
Vetores. VECBASE é um registrador especial e a tabela é a do ISA:
deslocamento a partir de VECBASE |
vetor |
|---|---|
0x000 |
WindowOverflow4 |
0x040 |
WindowUnderflow4 |
0x080 |
WindowOverflow8 |
0x0C0 |
WindowUnderflow8 |
0x100 |
WindowOverflow12 |
0x140 |
WindowUnderflow12 |
0x300 |
KernelException (PS.UM zerado) |
0x340 |
UserException (PS.UM definido), e toda interrupção de nível 1, com EXCCAUSE 4 |
0x3C0 |
DoubleException (PS.EXCM já definido) |
Qual dos três manipuladores de overflow é usado é decidido por quão larga é a moldura sendo despejada, não por quanto a janela girou para alcançá-la: WindowOverflow4 despeja por a5, 8 por a9 e 12 por a13, e esses são os ponteiros de pilha uma, duas e três janelas adiante. Um CALL8 escreve a8 antes de o ENTRY do chamado sequer rodar, então a regra de overflow vale no acesso ao registrador e não apenas no ENTRY. Ambos eram bugs que o firmware desta placa encontrou, e ambos estão corrigidos no core.
Interrupções. INTENABLE faz a máscara; PS.INTLEVEL faz o controle. Apenas o nível 1 é modelado: níveis de interrupção acima de um, a NMI e a interrupção de debug não são. As interrupções de nível 1 são 0 a 10, 12, 13, 17 e 18, máscara 0x0006_37FF. Verificado contra o ESP32 Technical Reference Manual (v5.8), tabela 8.3-2 "CPU Interrupts": 19, 20 e 21 são disparadas por nível em nível 2, então não estão na máscara. Uma versão anterior deste modelo as incluía (0x003E_37FF), o que teria despachado uma linha de nível 2 no nível 1; crates/xtensa-core/tests/interrupts.rs agora mantém a máscara fiel à tabela. O runtime só habilita 6 e 13 (seção 7), ambos nível 1 na mesma tabela, então nenhum firmware dependia da máscara antiga.
CCOUNT e CCOMPARE. O LX6 tem três comparadores. Qual interrupção de CPU cada um levanta é considerado:
| comparador | interrupção de CPU |
|---|---|
CCOMPARE0 |
6 |
CCOMPARE1 |
15 |
CCOMPARE2 |
16 |
Verificado contra a mesma tabela 8.3-2, cujas interrupções internas 6, 15 e 16 são "Timer.0", "Timer.1" e "Timer.2". A tabela também coloca 15 no nível 3 e 16 no nível 5, então apenas CCOMPARE0 é usado aqui. O runtime usa CCOMPARE0 e a interrupção de CPU 6 para seu tick, que é a que toda port Xtensa usa.
Um WSR em um CCOMPARE é o que arma o comparador, e escrevê-lo também limpa a interrupção pendente. Essa é a regra do hardware e é a regra aqui. Dois detalhes do modelo, ambos deliberados e ambos porque o tempo simulado não é um clock de passos:
- O hardware real levanta a interrupção no único ciclo em que
CCOUNTé igual ao comparador e a mantém até o comparador ser escrito de novo. Aqui a comparação é "atingiu ou passou", porque um core estacionado emWAITIpara de concluir instruções enquanto o tempo continua andando e, de outro modo, pularia direto o único ciclo que importa. Para um manipulador que define o próximo prazo (que é todo uso deste registrador), os dois se comportam igual. - Um prazo que já passou não é armado. Um manipulador leva várias centenas de ciclos, então um comparador definido para "agora" já está no passado antes de o manipulador retornar, dispara de novo imediatamente, e o programa interrompido recebe uma instrução por vez. Três segundos de
blinkcustavam 200 milhões de instruções antes dessa regra e menos de meio milhão depois dela.
MOVSP não levanta a exceção Alloca aqui; ele faz o que a exceção e seu manipulador fazem juntos. No hardware MOVSP gera trap quando a janela do chamador já foi despejada (WINDOWSTART limpo para WINDOWBASE - 1 para - 3), e o manipulador copia a do chamador a0..a3, a área de salvamento base nos 16 bytes abaixo do ponteiro de pilha antigo, para abaixo do novo antes da mudança. Este modelo faz essa cópia no lugar e então move (crates/xtensa-core/src/cpu.rs, movsp). O código depende disso: o clang-v3 cerca toda chamada que passa argumentos na pilha com movsp a1, a8, e antes de a cópia ser feita um sketch que chamava WiFi.scanNetworks() (oito argumentos com this) travava no window underflow na volta. O mesmo valia para qualquer setup() longo que chamasse sprintf com mais de seis argumentos após prints suficientes para transbordar seu chamador: imprimia tudo, depois exccause=9 em WindowUnderflow8 quando setup() retornava (no ESP32 e no S3; o C3 e o Pico não têm janela). crates/xtensa-core/tests/alloca.rs roda CALL8 e CALL12 quadros que cada um move seu ponteiro de pilha para baixo e de volta para cima com MOVSP em volta de uma chamada, em cada profundidade de 0 a 40, e web/src/compile/xtensa-movsp.test.ts roda os sketches nas duas placas.
The FPU is modeled. The ESP32's single-precision coprocessor runs on this model (crates/xtensa-core/tests/fpu.rs): the loads and stores (LSI, SSI, LSX, SSX and their post-incrementing forms), ADD.S, SUB.S, MUL.S, the fused MADD.S, MSUB.S and MADDN.S, the conversions (FLOAT.S, UFLOAT.S, TRUNC.S, UTRUNC.S, ROUND.S, FLOOR.S, CEIL.S), the compares into the boolean registers with BT, BF, MOVT and MOVF, the conditional moves, WFR, RFR, FCR and FSR, and the division and square-root steps libgcc's __divsf3 and newlib's sqrtf are built from, which return the correctly rounded IEEE answer. Arithmetic rounds to nearest whatever FCR says and sets no FSR flags. On this bare-metal model the coprocessor is on from reset, as there is no OS to turn it on at first use; the system model (docs/micropython-esp32.md) still waits for CPENABLE. So a float in an example built by Espressif's GCC through firmware/esp32/build.sh runs and prints the right number, and the browser's soft-float builds (-Xclang -target-feature -Xclang -fp, calls into mokxi_float.c) are unchanged.
5. Modelo de tempo, probe, poke e o canal do host
A CPU roda a 240 MHz, uma instrução por ciclo, e o barramento de periféricos a 80 MHz. 240 MHz não é um número inteiro de picossegundos por ciclo, então o tempo da instrução k é recalculado como ps_for(k) = k * 12500 / 3 em vez de acumulado (como o do Blue Pill e o do XIAO são), e uma fatia de 2400 instruções é exatamente 10 us.
Dentro de uma fatia a contagem de instruções é o clock: uma leitura de timer, um byte de UART e uma mudança de pino acontecem na instrução que as causou, não no fim da fatia. O componente da placa transforma isso em chamadas de drive_after nos mesmos deslocamentos, então duas escritas separadas por quatro instruções ficam realmente 16,7 ns distantes no nó. RSR.CCOUNT lê o mesmo clock.
Um core estacionado em WAITI não custa nada: a placa pede para ser acordada no mais cedo entre o próximo prazo de CCOMPARE e a próxima borda de LEDC, e uma mudança de pino ou um byte do host também o acordam.
Uma leitura das entradas após uma escrita nas saídas espera pelo circuito. O core roda uma fatia à frente do circuito, e GPIO_IN_REG guarda os níveis amostrados quando a fatia começou. Então, depois que uma escrita de GPIO ou IO_MUX moveu um pad em uma fatia, um load de GPIO_IN_REG ou GPIO_IN1_REG não é respondido: o barramento retorna BusError::Retry, o xtensa-core para o core antes dessa instrução sem nada dela feito, a fatia termina ali, a placa coloca a mudança no nó, e a próxima fatia amostra as entradas e roda a leitura. Uma varredura de teclado (ativar uma coluna, ler as linhas) e um fio de um pino para outro leem o que o circuito fez da escrita. As placas AVR param antes de tal leitura da mesma forma.
probe é uma máscara de bits, não um nível, porque esta placa tem quatro coisas que vale a pena mencionar:
| bit | significado |
|---|---|
| 1 | rodando |
| 2 | parado em waiti |
| 4 | o LED azul no GPIO 2 está aceso |
| 8 | o firmware tentou transformar um dos GPIO 34 a 39 em saída e foi recusado |
0 significa sem programa, mantido em reset ou travado. O bit 8 não depende de rodando: um programa que já foi recusado numa saída continua recusado, e a placa segue informando isso.
poke: 1 mantém BOOT (GPIO 0 em nível baixo), 0 solta; 2 mantém EN, 3 solta.
O canal do host. host_write coloca bytes no FIFO de recepção da UART0 (o que não cabe nos seus 128 bytes fica retido e chega com um tempo de byte de intervalo conforme o sketch lê, do mesmo jeito que os bytes de uma placa real escorram na taxa de baud para o buffer circular do core do Arduino, em vez de serem descartados); host_read retira os bytes que saíram do seu FIFO de transmissão. Isso é o Serial num sketch e o monitor serial na interface. Os bytes são UTF-8 do ponto de vista da interface e opacos para o modelo. O soquete micro-USB de um DevKit vai para um conversor CP2102 ou CH340 nesta porta; o conversor em si não é modelado, e nem o auto-reset por DTR/RTS.
Travamento. 1000 traps consecutivos sem progresso e o núcleo é declarado travado e parado, com o local onde morreu registrado.
6. Do que este modelo tem certeza, e do que não tem
Três grupos, e depois um quarto para as aproximações que não são sobre endereços. Esta seção existe porque um modelo de placa que adivinha silenciosamente um endereço é pior do que um que diz que não sabia.
Extraído do manual de referência técnica
DPORT_BASE 0x3FF0_0000, UART0_BASE 0x3FF4_0000, GPIO_BASE 0x3FF4_4000, SENS_BASE 0x3FF4_8800, IOMUX_BASE 0x3FF4_9000, LEDC_BASE 0x3FF5_9000 e TIMG0_BASE 0x3FF5_F000. Todo offset de registro dentro da matriz de GPIO e dentro da UART0, e o RXFIFO_RST do UART_CONF0_REG (bit 17) e o TXFIFO_RST (bit 18) do registro 19.9, os contadores de oito bits RXFIFO_CNT e TXFIFO_CNT do UART_STATUS_REG (registro 19.8), os limiares do UART_CONF1_REG (registro 19.10) e o divisor de vinte bits do UART_CLKDIV_REG (registro 19.6). A máscara de interrupção de CPU nível 1 0x0006_37FF (0 a 10, 12, 13, 17 e 18) e as interrupções CCOMPARE 6, 15 e 16, ambas da tabela 8.3-2 (seção 4). A janela de IRAM em 0x4008_0000 e a janela de DRAM em 0x3FFB_0000. GPIO_FUNC_OUT_SEL = 256 para "seguir o GPIO_OUT". O valor 2 de MCU_SEL para GPIO simples. O mapa de canais do ADC1: os canais 0 a 7 são os GPIO 36, 37, 38, 39, 32, 33, 34, 35. Os quarenta GPIOs, com os 6 a 11 sendo da flash e os 34 a 39 sem driver de saída. O LED azul no GPIO 2 e o botão BOOT no GPIO 0. Os offsets de vetor do Xtensa e os números de EXCCAUSE, que são da ISA, não do chip.
Acreditado, não verificado
- A tabela de ordem de pads do IO_MUX (seção 3.2). Os registros estão em ordem de pad e esta é a leitura deste modelo sobre qual é o pad de cada GPIO.
- Os offsets de registro do grupo de timers 0 (seção 3.4). A base é do manual; o layout dentro dela, não.
- O layout do bloco LEDC (seção 3.6): o passo entre canais, o bloco de timer em
0x140e os registros de interrupção e configuração. A base é do manual. - Os offsets e posições de bits do SENS (seção 3.5).
DPORT_INTR_MAP= 0x104, e os dois números de origem, GPIO 22 e UART0 34 (seção 3.7).- Os índices de sinal 71 a 78 da matriz de GPIO para os canais de alta velocidade 0 a 7 do LEDC (seção 3.1). Esta é a afirmação mais fraca do documento.
Todos eles estão nomeados num lugar que o firmware lê (firmware/esp32/include/esp32.h), então uma imagem levada para silício real tem uma lista curta de #defines para conferir. crates/esp32/tests/contract.rs prende esse cabeçalho e o crates/esp32/src/map.rs aos mesmos números, então as duas metades não conseguem se afastar; isso não torna nenhuma das duas certa.
Modelado, mas não com os números do manual
Estas são aproximações em vez de endereços, e um sketch consegue ver todas elas:
- Os campos de máquina de estados do
UART_STATUS_REGleem 0 (seção 3.3). No silícioST_URX_OUTeST_UTX_OUTse movem enquanto um byte está no fio; o runtime lê só as contagens de oito bits, então não vê a diferença. - O ADC a 11 dB é a curva de um componente típico, não desta unidade. A leitura bruta segue um ajuste a ESP32s medidos (seção 3.5): a zona morta na base, a curva no topo e a saturação em cerca de 3,15 V estão lá, a variação de unidade para unidade que a calibração de eFuse corrige, não. As outras atenuações são as retas nominais.
- Cada pad liga igual (seção 3.2): GPIO simples, buffer de entrada ligado, sem pull-up. O manual dá valores de reset diferentes para os pinos de strapping e de flash.
GPIO_STRAP_REGé uma constante,0b1101, não um registro do estado dos pinos no momento do reset.- Uma conversão leva exatamente 5 us e uma borda do LEDC cai no picossegundo exato. O componente real tem jitter e nenhum dos dois números vem de datasheet.
ENé só um pull-up de 10 k. O capacitor de 100 nF de power-on reset ao lado dele não é modelado, então umENque é apenas solto volta instantaneamente aqui.- Não há ROM de boot, nem árvore de clock. Um ESP32 real passa dezenas de milissegundos num carregador de primeira etapa antes da primeira instrução de um sketch; aqui o
POWER_ONé 1 us, o núcleo está a 240 MHz e o clock da APB a 80 MHz desde a primeira instrução, e não há nada com que configurar. CCOMPAREcompara "atingiu ou passou", e um prazo no passado não é armado (seção 4).MOVSPnunca gera Alloca; ele mesmo cria a cópia da área de salvamento da base do handler (seção 4).- As duas janelas de RAM não são espelhadas. No componente real a mesma SRAM é visível pelos dois barramentos em endereços diferentes, com os blocos da SRAM1 na ordem oposta (seção 2).
Ausente de propósito
Cada um destes foi deixado de fora em vez de inventado:
- O segundo núcleo. O ESP32 tem dois núcleos Xtensa LX6, PRO e APP, e aqui só o núcleo PRO roda. Não há
DPORT_APPCPU_CTRL, nem interrupção entre núcleos, nem FreeRTOS para escalonar entre eles. Um sketch escrito para oloop()único do core do Arduino nunca percebe; qualquer coisa que inicie uma tarefa no núcleo 1 não vai rodar. - The cache, the MMU and flash. Code and constants are read from two fixed, read-only windows (section 2.1); there is no flash device, no MMU and no cache to miss, so a fetch from flash is as fast as one from IRAM.
PSRAMlikewise. - WiFi e Bluetooth, em toda forma: sem rádio, sem pilha, sem
WiFi.h, nem um stub que falhe educadamente. - O RTC, sua memória lenta, o coprocessador ULP, o deep sleep e a unidade de gerenciamento de energia.
- O ADC2, o DMA e o controlador digital do SAR, as eFuses de calibração, a referência interna, o sensor de toque e o sensor de efeito Hall.
- O grupo de baixa velocidade do LEDC e seu hardware de duty com fade.
- O grupo de timers 1, o timer 1 do grupo de timers 0, o watchdog do RTC e o watchdog de interrupção.
- I2C, SPI, I2S, RMT, o contador de pulsos, o PWM de motor, SDIO, Ethernet, o controlador CAN e os aceleradores AES, SHA, RSA e RNG.
- A matriz de interrupções além das fontes da seção 3.7, e todo nível de interrupção da CPU acima de um.
É por isso que binários do ESP-IDF do fabricante e do core do Arduino não rodam aqui, e firmware compilado para este documento roda.
As imagens das duas placas Xtensa também não são intercambiáveis. A string program do catálogo é elf32 xtensa lx6 esp32 aqui e elf32 xtensa lx106 esp8266 no NodeMCU, e a diferença é real e não apenas burocrática: este core usa a ABI com janelas e aquele não tem uma janela para usá-la, então uma imagem compilada para uma falha na outra em vez de simplesmente se comportar mal.
7. Runtime do firmware (firmware/esp32/)
An Arduino-shaped runtime: setup() and loop(), pinMode, digitalWrite, digitalRead, shiftOut, analogRead (with analogReadResolution, analogSetAttenuation and analogSetPinAttenuation), analogWrite and the ledcAttach/ledcWrite/ledcRead family, millis, micros, micros64, delay, delayMicroseconds, attachInterrupt, Serial, Serial1 and Serial2, map, random. No Arduino core, no ESP-IDF, no libc.
Os construtores estáticos saem de .ctors aqui, não de .init_array. O GCC 8.4 da Espressif é configurado sem --enable-initfini-array e não tem -fuse-init-array, então o construtor de um objeto global vai parar em .ctors onde todas as outras toolchains deste repositório emitem .init_array. link.ld coleta os dois no único intervalo que crt0.S percorre. Sem isso, um sketch com um objeto global (WebServer server(80) em wifilamp) compilaria, rodaria e encontraria seus membros zerados. Os dois são percorridos numa única passada e .ctors não é invertido, porque a ordem em que os construtores rodam entre unidades de tradução é indefinida em C++ e um sketch não deve depender disso.
LED_BUILTIN is 2. The core has no BOOT_BUTTON: the BOOT button is GPIO 0, so sketches use 0. A0 is 36, and A3 to A7 are 39, 32, 33, 34 and 35, which is what the DevKit's own analog pins are called.
analogRead é o ADC1 em modo one-shot (seção 3.5), doze bits a 11 dB por padrão. analogWrite(pin, 0..255) é oito bits a 1 kHz em qualquer GPIO com driver de saída, e anexa um canal de alta velocidade livre do LEDC na primeira vez que é chamado; ledcAttach(pin, frequency, bits) é o que um sketch quer quando a frequência importa, e canais que pedem a mesma frequência e resolução compartilham um dos quatro timers. mokxi_pin_is_input_only(pin) está lá para um sketch poder perguntar antes de ser recusado.
millis() e micros() vêm do temporizador 0 do grupo de temporizadores 0, com um tique por microssegundo (seção 3.4). delayMicroseconds() abaixo de 50 us conta o CCOUNT, 240 ciclos por microssegundo, então nunca fica mais curto do que o pedido (contar o temporizador de microssegundos poderia fazer delayMicroseconds(10) demorar 9,01 us, o que um HC-SR04 ignoraria como trigger); 50 us ou mais entra em espera como delay(). delay() coloca o núcleo em espera em CCOMPARE0 em vez de girar num laço, então um segundo de blink custa ao núcleo menos de meio milhão de instruções dos 240 milhões de ciclos que o relógio contou. attachInterrupt são três escritas em vez de uma, porque um periférico chega ao núcleo pela matriz de interrupções (seção 3.7).
Serial1 e Serial2 são src/uartn.c na UART1 e UART2 (seção 3.3a), roteados pela matriz de GPIO para os pinos que begin(baud, config, rx, tx) ou setPins() indicar, com os padrões do arduino-esp32 3.x quando nenhum é dado (GPIO 26 e 27 para Serial1, 4 e 25 para Serial2). Ele se comporta como o driver do ESP-IDF se comporta sob o core: REF_TICK até 250 000 baud e APB acima disso, interrupção em RXFIFO_FULL (120 bytes) ou no timeout de recepção de um símbolo, que move a FIFO para um anel de setRxBufferSize() bytes (256), um bloco inteiro ou nada, com o bloco guardado à parte e as interrupções de recepção desligadas enquanto o anel está cheio e a interrupção de overflow esvaziando a FIFO nesse meio-tempo; available() conta só o anel. write() espera pela FIFO de 128 bytes e flush() até o transmissor ficar ocioso. As duas UARTs compartilham a interrupção 18 da CPU. onReceive() roda a partir de mokxi_uartn_events(), que delay(), yield() e o loop em main.cpp chamam (entre loop()s), porque não há tarefas do FreeRTOS. Não está lá: controle de fluxo, RS-485, IrDA, autobaud e um buffer de anel de TX.
Os exemplos incluídos são compilados pelo GCC da Espressif; o sketch de um usuário é compilado pelo clang. O ld.lld do LLVM upstream não consegue linkar Xtensa de jeito nenhum, então o navegador usa clang-v3, a versão wasm do fork de LLVM da Espressif, que compila todos os exemplos daqui com a lista de comandos do navegador (docs/compile.md). Os ELFs pré-compilados continuam sendo do GCC: eles são menores (docs/compile.md, "Code size") e nada precisa que eles mudem. deploy/fetch-xtensa.sh coloca xtensa-esp32-elf-gcc 8.4.0 em tools/xtensa/, que é ignorado pelo git: o GCC é GPL, e nada do que ele compila aqui linka contra libgcc ou qualquer outra parte da toolchain, então nenhum código GPL chega a um ELF distribuído. docs/compile.md tem a explicação completa e os passos restantes.
crt0.S carrega os seis handlers de overflow e underflow de janela em VECBASE, escritos a partir da referência da ISA em vez de tirados de qualquer fonte do fabricante, e dá ao frame raiz uma área de salvamento base própria: um overflow de janela do frame raiz executa l32e a0, a1, -12 para achar o ponteiro de pilha de quem o chamou e então escreve através dele, e o frame raiz não tem chamador, então um é construído sessenta e quatro bytes abaixo do topo da pilha. Sem isso, a primeira cadeia de chamadas profunda derrama por um ponteiro nulo.
A entrada de exceção não toca a1, e isso é uma questão de correção e não de arrumação: o handler roda na própria janela da função interrompida, e um overflow de janela de um frame mais antigo acha onde derramar lendo o ponteiro de pilha dessa janela. Mover a1 e todo frame mais antigo derrama no lugar errado e volta errado. Os registradores interrompidos vão para um bloco fixo em .bss em vez disso, o que é seguro sem lock porque o handler roda em INTLEVEL 1.
Linked against firmware/esp32/link.ld: the vectors and startup code in the 128 KB of IRAM, code in the flash code window, constants in the flash constants window, .data, .bss and the stack in the 192 KB of DRAM. A WROOM-32 has 4 MB of flash and an example should be a small part of it, so the build refuses an image with more than 64 KB loadable; the real ceiling the linker script enforces is the 1,310,720 bytes of the default app partition.
Cinco exemplos, cada um com um sketch que a interface mostra: blink (o LED da placa no GPIO 2 e um LED ligado no GPIO 4), button (um interruptor para o terra no GPIO 15 com o pull-up do próprio pad), serial (um tick por segundo e um eco do que você digita), fade (um LED no GPIO 4 no LEDC, oito bits a 1 kHz) e knob (um potenciômetro no GPIO 32, que é o canal 4 do ADC1, controlando o brilho de um LED no GPIO 4 com a leitura bruta impressa). O pzemmonitor, um medidor de energia PZEM-004T no Serial2 (GPIO 16 e 17) através da biblioteca PZEM004Tv30, é compilado pelo compilador do navegador em vez do GCC (seção 4) e é o projeto ESP32 PZEM-004T energy monitor.
crates/esp32/tests/runtime.rs inicializa esses cinco ELFs e mede em vez de apenas observar: o meio período do blink dentro de 5 ms de 500, o período do LEDC dentro de 5 us dos 1 ms de 1 kHz, millis() dentro de 60 ms do próprio relógio do kernel ao longo de cinco segundos, e nenhum par de bytes da UART0 mais próximo do que os 86.8 us de 115200 baud. Cada teste se pula sozinho quando as imagens não estão compiladas, então os testes do crate nunca dependem de ter o compilador cruzado.