Os arquivos de uma placa são compilados por um clang de verdade e um lld de verdade, rodando como WebAssembly dentro da página. Não há servidor de compilação, nada é enviado, e o ELF que sai é o mesmo tipo de imagem que firmware/build.sh produz: é o mesmo compilador dirigido pela mesma lista de comandos.
A prova de que isso funciona, com os números que justificaram construí-lo, está em proofs/compile/REPORT.md. Este documento explica como o produto faz isso.
A forma geral
web/src/compile/
asm-check.ts the AVR operand checks avr-as makes and LLVM's assembler does not
asm-help.ts plain-English help for an assembler or linker message
bundles.ts which toolchain and which runtime each board family needs
cache.ts the 74 MB download, and the Cache API entry that avoids it
client.ts the page's half: one worker, and the rule for "does this need building?"
diagnostics.ts clang's stderr -> { file, line, col, severity, message }
disasm.ts AVR and Thumb disassembly for the debugger, in llvm-objdump's spelling
hash.ts a cheap content hash for the two cache keys
protocol.ts the messages between the page and the worker
toolchain.ts the command list, and one wasm instantiation per tool run
wasi.ts a WASI preview 1 host with an in-memory filesystem
worker.ts the Web Worker that runs all of the above
web/src/ui/build-panel.ts the steps, the diagnostics and the one success line
web/scripts/bundle-runtime.mjs firmware/ -> web/public/firmware/runtime/<family>.json
Tudo, exceto o painel Compilação, roda no worker, então uma primeira compilação de quatro segundos nunca trava um quadro do canvas.
O que precisa chegar ao navegador
Duas coisas, de dois lugares.
The toolchain is one clang.wasm (clang, ld.lld and llvm-objcopy in a
single LLVM driver that dispatches on argv[0]) plus a bundle.json whose
/usr/include/... entries are clang's own resource headers, pruned to the ten a
freestanding build opens. Both come from the Cloudflare R2 bucket
mokxi-toolchain, served by the Worker at /toolchain/<version>/<file>. In
development deploy/fetch-toolchain.sh puts the same files under
web/public/toolchain/<version>/ (gitignored) and Vite serves the same paths,
so the client code is identical either way.
The runtime is our own firmware: the sources under firmware/src, the
headers, crt0.S and the linker script, together with the exact flags
firmware/build.sh compiles them with. It also carries firmware/lib, the
shared header-only drivers (mokxi_i2c.h, mokxi_ssd1306.h, mokxi_max7219.h,
and the rest): one copy, mounted at /firmware/lib for every family with
-I/firmware/lib on the command line, exactly where firmware/build.sh and
firmware/uno/build.sh already point their own -I at the same directory. A
sketch that includes one of these headers (every OLED, SPI display, WS2812,
tone or joystick example) compiles on any board because of this, not despite
it. web/scripts/bundle-runtime.mjs packs all of it into
web/public/firmware/runtime/<family>.json, which is committed. Regenerate it
whenever the firmware (including firmware/lib) changes:
node web/scripts/bundle-runtime.mjs # write the files
node web/scripts/bundle-runtime.mjs --check # fail if they are out of date
src/compile/bundles.test.ts roda a forma --check, então uma mudança em firmware/ que ninguém propagou derruba a suíte de testes, e não o build de um usuário.
Every family's firmware is in the tree now, so the script writes every
bundle.
It still holds the rule it was written with: a family whose firmware is not
there (the script looks for its link.ld) is skipped with a note, not an
error, so neither a developer's build nor CI fails while the next family is
being written. esp32c3 and uno name their sources explicitly, in the order
build.sh links them, and so does attiny, whose sources are the Uno's list
on a different -mmcu. pico, stm32, bluepill and microbit use
discover, which
reads the lists off the directory: every .S at the family root with crt0
first, then src/*.c, then src/*.cpp with main.cpp last, everything else
alphabetical, which is the order their build.sh links in, so nothing has had
to be pinned. Pin explicit lists in the script if a link order ever has to be
something else.
The ESP32, ESP32-S3 and ESP8266 bundles are written too. Their flags are the
clang translation of their GCC build.sh lists (see "Proven natively" below),
and they are what clang-v3 compiles in the browser.
A versão da toolchain é fixada por família de placa
A versão é uma propriedade da família, não do app, porque as duas compilações não são um compilador só: o clang-rv32-v1 foi configurado apenas com LLVM_TARGETS_TO_BUILD=RISCV, então ele consegue compilar para o ESP32-C3 e fisicamente não consegue compilar para o Uno. O clang-v2 é esse mesmo script de compilação com LLVM_TARGETS_TO_BUILD=RISCV;AVR;ARM (mesma estrutura, mesmo bucket, mesmo formato de URL), e toda família que compila hoje está fixada nele (DECISIONS.md, 2026-09-14: verificado nos três backends e enviado ao R2). A saída RISC-V dele é byte idêntica à do clang-rv32-v1, então o ESP32-C3 também passou a usá-lo e todas as placas desse tipo compartilham um único download. As famílias Xtensa estão fixadas no clang-v3 (XTENSA_TOOLCHAIN), publicado em 28/09/2026:
| família | programa do catálogo |
alvo | toolchain | pronto |
|---|---|---|---|---|
esp32c3 |
elf32 riscv32imc |
riscv32-unknown-elf -march=rv32imc -mabi=ilp32 |
clang-v2 |
sim |
c6 |
elf32 riscv32imc esp32c6 |
riscv32-unknown-elf -march=rv32imc -mabi=ilp32 |
clang-v2 |
sim |
uno |
elf32 avr atmega328p |
avr -mmcu=atmega328p |
clang-v2 |
sim |
nano |
elf32 avr atmega328p nano |
avr -mmcu=atmega328p |
clang-v2 |
sim |
mega2560 |
elf32 avr atmega2560 |
avr -mmcu=atmega2560 |
clang-v2 |
sim |
leonardo |
elf32 avr atmega32u4 |
avr -mmcu=atmega32u4 |
clang-v2 |
sim |
attiny |
elf32 avr attiny85 |
avr -mmcu=attiny85 |
clang-v2 |
sim |
pico |
elf32 arm rp2040 |
thumbv6m-none-eabi -mcpu=cortex-m0plus -mthumb |
clang-v2 |
sim |
xiao |
elf32 arm samd21 |
thumbv6m-none-eabi -mcpu=cortex-m0plus -mthumb |
clang-v2 |
sim |
stm32 |
elf32 arm stm32f411 |
thumbv7em-none-eabi -mcpu=cortex-m4 -mthumb -mfloat-abi=soft -mfpu=none |
clang-v2 |
sim |
bluepill |
elf32 arm stm32f103 |
thumbv7m-none-eabi -mcpu=cortex-m3 -mthumb -mfloat-abi=soft |
clang-v2 |
sim |
microbit |
elf32 arm nrf52833 |
thumbv7em-none-eabi -mcpu=cortex-m4 -mthumb -mfloat-abi=soft -mfpu=none |
clang-v2 |
sim |
unor4 |
elf32 arm ra4m1 |
thumbv7em-none-eabi -mcpu=cortex-m4 -mthumb -mfloat-abi=soft -mfpu=none |
clang-v2 |
sim |
esp32 |
elf32 xtensa lx6 esp32 |
xtensa-esp-elf -mcpu=esp32 -fintegrated-as |
clang-v3 |
sim |
esp32s3 |
elf32 xtensa lx7 esp32s3 |
xtensa-esp-elf -mcpu=esp32s3 -fintegrated-as |
clang-v3 |
sim |
esp8266 |
elf32 xtensa lx106 esp8266 |
xtensa-esp-elf -mcpu=esp8266 -fintegrated-as |
clang-v3 |
sim |
As três últimas linhas são a próxima seção. web/src/compile/bundles.ts é a lista da qual esta tabela é lida, e bundles.test.ts mantém as duas em sincronia.
As placas Xtensa, no clang-v3
O ESP32 clássico é um Xtensa LX6, o ESP8266 NodeMCU um Xtensa LX106 e o ESP32-S3 um Xtensa LX7. Os três compilam no navegador no clang-v3 desde 28/09/2026 ("Publicado e verificado" abaixo). Até então eles rodavam ELFs pré-compilados e diziam isso. O resto desta seção explica por que foi preciso um fork e o que a verificação encontrou.
Por que é uma toolchain separada (verificado em 27/09/2026):
- O
clang-v2não tem back end Xtensa. Ele foi construído comLLVM_TARGETS_TO_BUILD=RISCV;AVR;ARM(DECISIONS.md, 14/09/2026). O wasm que o navegador baixa fisicamente não consegue emitir um objeto Xtensa. - O LLVM upstream tem metade do que é necessário, e a metade errada. O Clang carrega um front end Xtensa desde o LLVM 20 (Phoronix), e o do LLVM 22
XtensaProcessors.tdsabeesp32eesp8266(upstreammainadicionaesp32s2eesp32s3). Mas old.lldupstream não tem nenhum alvo Xtensa: não existelld/ELF/Arch/Xtensa.cppnomainou emrelease/22.x, então nada upstream consegue linkar uma imagem de ESP32. O backend upstream também ainda emite pools de literais inline em.text, o que quebral32ro alinhamento sob-ffunction-sections(llvm/llvm-project#190204, aberto). O Xtensa ainda está emLLVM_ALL_EXPERIMENTAL_TARGETSupstream. - Espressif's fork has all of it.
esp-clang(espressif/llvm-project, mais recenteesp-22.1.4_20260825, LLVM 22.1.4, Apache-2.0 with LLVM exception) carries the Xtensa front end with-mcpu=esp32,esp8266,esp32s2andesp32s3, and anlld/ELF/Arch/Xtensa.cppthat handlesR_XTENSA_32,R_XTENSA_SLOT0_OP(L32R,CALL8, branches) and theDIFF/ASM_EXPANDrelocations. Xtensa is experimental there too, so it has to go inLLVM_EXPERIMENTAL_TARGETS_TO_BUILD;build-wasm-clang.shnow splits that out of the target list by itself. The fork does not carry the WASI portability commit, soproofs/compile/patches/llvm-wasi-portability.patch(the same commit clang-v2 is built with, from YoWASP) is applied on top. It applies cleanly toesp-22.1.4_20260825(one hunk at an offset of one line). That commit's WASIclose()returns a staleerrnoand fails clean writes ("IO failure on output stream: No such file or directory"), sobuild-wasm-clang.shalways appliesproofs/compile/patches/llvm-wasi-close-errno.patchafter it, on either tree. The clang-v2 served today predates that fix;ERRNO_RESET_HEADERandruntimeFilesinweb/src/compile/toolchain.tswork around it until it is rebuilt (docs/clang-v2-rebuild.mdhas the plan).
Então isto é um fork para acompanhar em vez de uma flag para adicionar, mas o fork é da própria Espressif, lançado a cada poucos meses, e sob a mesma licença do LLVM de onde vem o clang-v2.
Os ELFs pré-compilados ainda são compilados pelo GCC da Espressif, que o deploy/fetch-xtensa.sh coloca em tools/xtensa/: xtensa-esp32-elf-gcc 8.4.0 para o LX6, xtensa-esp32s3-elf-gcc 8.4.0 para o LX7 e xtensa-lx106-elf-gcc 8.4.0 para o LX106. O runtime do S3 reutiliza o crt0.S e o support64.c do ESP32 clássico: para o código que um compilador gera a partir de C, o LX7 é o LX6, e a saída do compilador do S3 para o mesmo programa de teste é byte a byte a do compilador do ESP32. Esse diretório está no gitignore. O GCC é GPL, e nada do que ele compila aqui faz link com libgcc (os runtimes são -nostdlib com seu próprio support.c, e o support32.c do ESP8266 fornece as divisões de 32 bits para as quais o LX106 não tem instrução), então nenhum código GPL chega a um ELF distribuído.
Comprovado nativamente
Antes de qualquer wasm existir, o lado do compilador é comprovado com a compilação nativa para Linux do mesmo fork (clang-esp-22.1.4_20260825-x86_64-linux-gnu.tar.xz, 411 MB, sha256 4700ed4e...eb0a1, descompacta para 2,7 GB com ld.lld dentro):
proofs/compile/xtensa/run-native.sh /some/scratch/dir
Ele busca esse release e roda proofs/compile/xtensa/plan.ts --native, que não transcreve nenhum comando: ele pega runtimeSteps e projectPlan de web/src/compile/toolchain.ts e os bundles de runtime versionados web/public/firmware/runtime/esp32.json, esp32s3.json e esp8266.json, então o que roda é a lista de comandos do navegador, com o crt0.S dividido nas etapas de pré-processamento e montagem, ld.lld chamado diretamente e llvm-objcopy com saída para stdout. Resultado em 27/09/2026:
- every example of every board compiles and links with
-Wall -Wextra -Werror: nine for the ESP32 (19 steps each), eleven for the ESP32-S3 (21 steps,rainbowandusbserialincluded) and nine for the ESP8266 (20 steps), about 1 s each natively; ld.lldresolve toda realocação (nos objetos do ESP32: 3.407R_XTENSA_32e 430R_XTENSA_SLOT0_OP);MOKXI_ESP32_ELF_DIR=... cargo test -p esp32 --test runtime --test wifi: 11 + 4 passaram;MOKXI_ESP32S3_ELF_DIR=... cargo test -p esp32s3 --test runtime --test wifi: 13 + 4 passaram;MOKXI_ESP8266_ELF_DIR=... cargo test -p esp8266 --test runtime --test wifi: 11 + 4 passaram. São os mesmos testes que os ELFs do GCC passam: meio período de 500 ms do blink, LEDC e PWM por software a 1 kHz,millis()contra o relógio do kernel, espaçamento de bits da UART0, o ADC, os quadros WS2812 do S3 no seu LED RGB (branco, depois o verde do arco-íris primeiro no fio) e seus pacotes USB seriais, conexão WiFi e a página web da lâmpada. As três variáveis de ambiente apenas apontam os testes existentes para outro diretório; um arquivo corrompido ali os faz entrar em pânico, então eles realmente carregaram o que foi compilado.
Três coisas que a comprovação encontrou, todas tratadas nos bundles:
-fintegrated-asé obrigatório. Para Xtensa, o driver da Espressif entrega um.sde arquivo para um montador GNU externo (xtensa-esp32-elf-clang-as) por padrão, que o WASI não consegue executar. Com-fintegrated-aso próprio montador do clang pega o crt0.S como escrito. Está nas flags de alvo da família, então a metade de montagem também recebe. A Espressif o desativa de propósito para entrada em assembly (EspBareMetal.cpp: "TODO: Add full support for Xtensa to integrated asm, LLVM-290, LLVM-291"), então não está completo para todo arquivo escrito à mão; está para os nossos dois arquivoscrt0.S, que é o que os testes do simulador mostram. É também por isso que os próprios arquivos.Se.sde um projeto não são oferecidos nas placas Xtensa: apenas.c,.cppe.inosão compilados ali, enquanto toda outra família também monta os próprios arquivos do projeto (veja Assembly abaixo). C e C++ sempre passam pelo montador integrado, neste fork como no upstream.- Nenhum aviso de multilib no wasm. A instalação nativa avisa que não tem multilib esp8266 (um erro sob
-Werror) porque seumultilib.yamlnão tem essa entrada.BareMetal::findMultilibssó lê ummultilib.yamlque existe, e o sistema de arquivos do wasm não tem nenhum, então só a execução nativa precisa de-Wno-missing-multilib, e sóplan.ts --nativea passa. - O
-mlongcallse o-mtext-section-literalsdo GCC vão embora. O Clang relata-mlongcallscomo argumento não usado, um erro sob-Werror. Sem-mtext-section-literalso clang emite.literal.<function>seções, que os três arquivoslink.ldjá colocam no início de.text, well insideL32R's 256 KB reach.
Tamanho do código, o segmento executável de todo exemplo contra a imagem GCC enviada (mesmas fontes, ambos -Os):
| placa | GCC, todos os exemplos | clang | por exemplo |
|---|---|---|---|
| ESP32 | 29.984 bytes | 37.760 bytes | +15% (fade) a +37% (wifilamp), +26% no total |
| ESP32-S3 | 41.584 bytes | 53.920 bytes | +18% (fade) a +38% (wifilamp), +30% no total |
| ESP8266 | 34.592 bytes | 49.104 bytes | +33% (button) a +49% (wifilamp), +42% no total |
Os dados ficam dentro de algumas dezenas de bytes para qualquer lado. A maior imagem clang é a do wifilamp do ESP8266, com 8.944 bytes de código, contra uma IRAM de 32 KB e o limite de 24 KB que seu elfcheck.py impõe aos exemplos, então o crescimento não custa nada que um sketch aqui notaria. Para onde os bytes vão não foi detalhado.
Publicado e verificado
- Compilado por
.github/workflows/clang-v3.yml, execução 36358476287 (tentativa 3,mainem4578344f):espressif/llvm-projectemesp-22.1.4_20260825comRISCV;AVR;ARM;Xtensa, ambos os patches WASI, depoisplan.ts --wasmpara as três placas e os testes do simulador sobre o que o wasm compilou. Artefatoclang-v3, sha256 do zipef27b7aa…3eafd;clang.wasmtem 80.735.841 bytes, sha2567546c54c07c392e231ea450f8e3aaa6680346ffeb08e13d97d970b26d88666e5. - Publicado em 28/09/2026: o artefato descompactado em
web/public/toolchain/clang-v3/, depoisdeploy/fetch-toolchain.sh --publish clang-v3.https://mokxi.com/toolchain/clang-v3/serveclang.wasm,bundle.jsoneinclude.tgzcom os tipos certos, os tamanhos certos e o mesmo sha256 do artefato. Obundle.jsonestá sem poda (16 MB, todos os headers de recurso do clang); só suas entradas/usr/includesão usadas, e podá-lo como foi feito com o do clang-v2 economizaria a maior parte desse download. - Verificado no Chromium (headless, contra
npm run devcom os arquivos publicados emweb/public/toolchain/clang-v3/): o editor real abriu um diagrama com seu próprio sketch, apertou Rodar e acompanhou o painel Compilação, o monitor serial e o LED. O sketch do ESP32 entrou no WiFi simulado (192.168.4.2) e piscou o GPIO 4; o sketch do ESP32-S3 piscou o GPIO 2 e imprimiu; o sketch do ESP8266 piscou o D1 e imprimiu uma divisão de 32 bits a cada loop; o próprio exemplo Blink do ESP8266, editado, compilou e piscou também. A primeira compilação de uma placa levou de 5 a 7 s incluindo o runtime, uma posterior cerca de 1,5 s. O ELF que a página compilou para o Blink do ESP8266 é byte a byte oproof/esp8266/blink.elfdo workflow. - A verificação do ESP8266 encontrou um bug no motor, corrigido na mesma mudança. O Blink do clang escreve seus pinos na mesma fatia em que estaciona, então o nó do pino se move dentro de um tempo que o núcleo já executou, e o componente da placa adiantou o núcleo estacionado antes do fim dessa fatia. O
CCOUNTandou para trás, a contagem de 64 bits de ciclos do runtime leu isso como um overflow de 2^32 ciclos, e todadelay()depois da primeira retornava imediatamente: o LED acendia e ficava aceso. O Blink do GCC nunca escreve um pino na fatia em que estaciona, por isso nenhum exemplo enviado o mostrou, e os testes nativos nunca o mostraram porque executam o SoC sem circuito. Os componentes de placa do ESP32, ESP32-S3 e ESP8266 agora nunca executam o núcleo antes do ponto onde sua última fatia terminou (ran_toemcrates/parts/src/parts/esp8266.rse seus dois irmãos), eblink_keeps_its_half_period_when_a_pin_moves_as_the_core_parkso garante (rode comMOKXI_ESP8266_ELF_DIRapontando para os ELFs do clang). - Ponto flutuante é soft float.
-mcpu=esp32e-mcpu=esp32s3ativam a FPU de precisão simples, que o modelo não tem, então a princípio uma multiplicação defloat, uma comparação ou oisnan(h) || isnan(t)do tutorial do DHT era compilado para uma instrução da FPU e a placa parava. Os bundles agora passam-Xclang -target-feature -Xclang -fp(o driver Xtensa não tem-mfloat-abi), então os floats viram chamadas paramokxi_float.ccomo em qualquer outra placa soft float e dão as respostas certas. O LX106 do ESP8266 não tem FPU para desligar e linka o mesmomokxi_float.c.
Próximos passos
- Decidir se toda família migra para clang-v3. Até lá, um usuário que compila para um ESP32 e qualquer outra placa mantém dois toolchains de mais de 75 MB no Cache API:
isStaleKey(cache.ts) mantém toda versão que uma família nomeia (TOOLCHAINS_IN_USE) e descarta a outra só quando o disco enche. Antes de 2026-10-17 ele descartava toda versão menos a em uso, então cada troca baixava 20 MB de novo e falhava offline. Migrar todas é uma string por família, como foi a migração para clang-v2, mas é LLVM 22.1.4 de um fork em vez de 22.1.0, então rodecrash.test.tse os testes de bibliotecas incluídas contra ele antes, e não presuma saída byte idêntica. - Verificar as bibliotecas incluídas nas famílias Xtensa.
firmware/libestá no include path delas como em toda placa, masstock-libraries.test.tsnão as lista, entãoServo.h,Wire.he o resto não são testados lá. - Podar o
bundle.jsonpara os cabeçalhos que uma compilação freestanding abre.
Nunca prometer uma compilação no navegador que não funciona: um botão de compilar que rodasse silenciosamente o binário de ontem seria a pior coisa deste produto.
clang-rv32-v1 ainda é o valor de RV32_TOOLCHAIN e nenhuma família o nomeia. Ele fica como caminho de volta: alterar a string toolchain de uma família é tudo o que há para lançar ou reverter uma versão, já que as URLs, a chave do cache de módulos e o cache de objetos em runtime derivam dela.
ready também não é código morto. Duas coisas precisam ser verdade antes que uma família possa carregá-lo, e bundles.test.ts verifica a segunda delas:
- O toolchain tem o back end, está publicado, e um sketch que ele compilou rodou no simulador.
- A família tem um bundle de runtime, o que significa que seu diretório de firmware existe e
bundle-runtime.mjsfoi executado.
Uma família que não está ready não é um erro: chooseProgram envia suas placas para o ELF pré-compilado de web/public/firmware/, o painel Compilação e a linha ao lado do seletor de placas dizem o porquê, e nada falha. Hoje nenhuma família segue esse caminho; as famílias Xtensa seguiam até o clang-v3 ser publicado.
O STM32 e o micro:bit são soft float de propósito: DECISIONS.md, 2026-09-14, deixa a FPU e o DSP do M4 fora do escopo até que uma placa M4F seja desejada, então nenhum dos runtimes pode emitir instruções VFP ou uma ABI hard float.
O que acontece quando você aperta Rodar
App.buildPrograms pergunta a chooseProgram (src/compile/client.ts) sobre cada placa e recebe uma de três respostas:
elf: rodar a imagem que o painel Firmware nomeia e não compilar nada. Um ELF enviado não foi compilado a partir destes arquivos; um exemplo incluído intocado já está compilado. Uma família cujo toolchain não está publicado também cai aqui.reuse: rodar o ELF já compilado exatamente a partir destes arquivos. A decisão é um hash de todo nome de arquivo e de cada byte nele, então um toque de tecla e um desfazer deixam você de volta emreuse.build: compilar e rodar o resultado.
Uma compilação que falha interrompe a execução: o botão fica em Rodar, o ELF anterior é descartado em vez de usado às escondidas, e os diagnósticos ficam no painel. O ELF compilado vive na memória só para a sessão. É um fato sobre esta sessão, não parte do documento, então nunca é salvo, exportado ou compartilhado.
A lista de comandos
Os mesmos quatorze comandos que firmware/build.sh executa, com duas diferenças que o WASI impõe (ambas resolvidas na prova de conceito):
-c crt0.Sfaz o clang querer dois trabalhos, um preprocessamento e uma montagem, e o clang desliga seu cc1 integrado assim que há mais de um, o que no WASI vira "unable to execute command: WASI does not support spawning subprocesses". As duas metades são listadas separadamente.- O link vai direto pelo
ld.lldem vez do driver do clang, então as flags de link do ESP32-C3 perdem os prefixos-Wl,.firmware/uno/build.shjá chamald.lldpelo mesmo motivo.
O sistema de arquivos que as ferramentas veem:
| caminho | o quê |
|---|---|
/usr/include |
cabeçalhos de recursos do clang, do bundle do toolchain |
/firmware para o ESP32-C3, /firmware/<family> para o resto |
nossos fontes de runtime, cabeçalhos, crt0.S, link.ld |
/firmware/lib |
os drivers compartilhados só de cabeçalho, mesmo caminho para toda família |
/project |
os arquivos da placa, com seus próprios nomes, então #include "pins.h" funciona |
/build |
objetos, o sketch encapsulado, o ELF |
Assembly
Arquivos .S e .s do próprio projeto também são compilados aqui, assim como o arduino-cli compila um .S ao lado de um sketch, e uma placa pode ser só assembly e nada mais.
Quatro peças, todas em web/src/compile/:
- O plano.
projectPlan(toolchain.ts) adiciona um par de passos para cada.S: um preprocessamento com o include path, o quote path e as defines do próprio sketch (então#include <avr/io.h>dá os nomes dos registradores e__ASSEMBLER__é definido), depois uma montagem da cópia preprocessada. São duas execuções pelo motivo queruntimeStepsjá dá:-c foo.Sfaz o clang querer dois trabalhos, e o clang desliga seu cc1 integrado assim que há mais de um, o que no WASI vira "unable to execute command: WASI does not support spawning subprocesses". Um.sé montado diretamente, sem passo de preprocessamento. Os marcadores# <line> "<file>"do preprocessador são preservados, então um diagnóstico e uma linha de DWARF ficam na linha da própria aba em vez da linha da cópia preprocessada, e é isso que permite ao depurador parar em uma linha de.S. O passo de montagem passa só as flags que o próprio assembler lê, mais-g -gdwarf-4. - As verificações de operandos.
asm-check.tslê todo arquivo.Se.sde AVR do projeto antes de qualquer ferramenta rodar, e reporta no formato próprio do clang,arquivo:linha:coluna: error:, de modo queparseDiagnosticse o painel de compilação não precisam saber de nada novo. Ele faz as verificações que oavr-asfaz e que o assembler AVR do LLVM silenciosamente não faz:ldi r16, 300(mantido como 0x2C),sbi PORTB, 1(um endereço de dados onde vai um endereço de E/S),add r16, 5(lido comoadd r16, r5),out PORTB, r16sem__SFR_OFFSET 0(um aviso: ele alcança um registrador diferente),ineoutacima de 63,sbiweadiwacima de 63, e um bit acima de 7. Um operando só é avaliado quando pode ser deduzido: números, os próprios.equ,.sete#defines do arquivo, e os nomes de registradores e bits do cabeçalho da placa lidos do pacote de runtime, através de_SFR_IO_ADDR(),lo8(),hi8()e dos operadores de C. Qualquer outra coisa fica para o assembler e o linker, que estão certos sobre essas. Um erro interrompe a compilação antes de uma ferramenta começar (plan.checkFailed). - O link, quando não há sketch.
isAssemblyProject(bundles.ts) é um projeto cujos arquivos são apenas assembly;assemblyLinkInputsdefine o que ele linka além de seus próprios objetos. Em uma placa AVR, isso é o objetocrt0.Sdo runtime e nada mais, que é o que ogcrt1.oda avr-libc é para oavr-gcc main.S: a tabela de vetores com cada__vector_<n>como umretiweak,r1zerado, a pilha em RAMEND,.datacopiado,.bsszerado e uma chamada aomaindo projeto. Um projeto cujo arquivo define sua própria seção.vectorsou o rótulo__vectors(definesVectors) não recebe nada, e o mesmo vale para toda placa ARM, onde o arquivo é a tabela de vetores. Nenhum core do Arduino em nenhum dos casos: semsetup(), sem o tick demillis(), semSerial. - O desassemblador.
disasm.tsé nosso, porque o LLVM do navegador carrega clang,ld.lldellvm-objcopye nenhumllvm-objdump. Ele lê os segmentos executáveis do ELF que o app já guarda, então a lista Desmontagem da aba Depurar e o botão de Passo de instrução não precisam de nenhuma ida e volta. O decodificador AVR cobre todo o conjunto de instruções; o decodificador Thumb cobre todas as codificações de 16 bits, oBL, e as formas Thumb-2 de 32 bits que um compilador ou um curso escrevem na maior parte, e mostra qualquer outra coisa como.inst.w 0x…em vez de um palpite errado. O texto é o dollvm-objdump, edisasm.test.tso mantém lá: cada instrução de compilações reais (os quatro projetos iniciais de assembly, e um sketch com matemática de ponto flutuante,Seriale pinos) para o Uno, o Mega, o Pico e o Black Pill tem que ler exatamente como ollvm-objdumpda máquina lê.
Quais placas oferecem um projeto de assembly sem core está em src/asm/boards.ts: o Uno, o Nano, o Pro Mini, o Pico e o STM32F411. Toda outra placa que compila ainda aceita abas .S junto de um sketch, exceto as placas Xtensa (veja acima). asm.test.ts compila e roda tudo isso no simulador.
Uma ferramenta que trava
clang e lld entram num caminho de abort em alguns erros fatais (um #include ausente, principalmente) que imprime o diagnóstico no stderr e então atinge unreachable em vez de chamar exit. Dentro do WASI isso aparece como um WebAssembly.RuntimeError de verdade, não um proc_exit, e de outra forma escaparia como uma rejeição não tratada sem diagnóstico nenhum anexado: uma queda, não um erro de compilação.
Toolchain.run (src/compile/toolchain.ts) captura exatamente isso: uma trava depois que a ferramenta já escreveu algo no stderr volta como um passo comum que falhou, result.trapped definido e result.code diferente de zero, com tudo o que foi escrito antes da trava ainda em result.err. runSteps (src/compile/worker.ts) então trata isso como qualquer outra saída diferente de zero: o que parseDiagnostics encontrou é o que o painel Compilação mostra, clicável como qualquer outro diagnóstico, e só cai para "o compilador travou (<tool> em <step>)" quando a trava não carregava nada a dizer. Cada execução de ferramenta já recebe sua própria WebAssembly.Instance nova a partir do único Module compilado (toolchainFor compila o módulo uma vez; Toolchain.run o instancia a cada chamada), então uma trava numa execução não deixa nada para a próxima. Não há instância para contaminar e nada aqui reinstancia o módulo por conta própria.
As abas .ino são unidas e embrulhadas do jeito que o Arduino IDE faz (src/compile/prototypes.ts): #include "arduino.h", depois a aba principal e as outras abas .ino em ordem alfabética, cada uma atrás de #line 1 "<tab>.ino", com um protótipo para cada função que as abas definem escrito logo antes da primeira função, cada um atrás de um #line apontando para sua definição, e um #line depois do bloco. Assim um sketch que chama uma função definida abaixo de loop() compila, e o compilador ainda relata um problema em sketch.ino:12:3 para o painel Compilação poder levar o editor até lá. Templates, membros de classe, qualquer coisa num namespace, uma função que o próprio sketch declara e uma função cuja assinatura menciona algo declarado mais abaixo não ganham protótipo; uma função dentro de blocos #if ganha seu protótipo dentro de uma cópia das mesmas condições; argumentos padrão vão para o protótipo e são apagados, coluna por coluna, da definição. .c compila como C11, .cpp/.cc/.ino como C++17; qualquer outra coisa é escrita em /project para os includes e não é compilada.
Os arquivos do usuário são compilados com as flags de aviso do runtime menos o -Werror (userWarnings em bundles.ts): avisos de -Wall -Wextra são relatados no painel Compilação, e um objeto em cache guarda seus avisos para serem mostrados de novo no próximo Rodar, mas um aviso não interrompe a compilação, como no Arduino IDE. O próprio runtime, e projectPlan(..., { strict: true }) (a prova Xtensa, os testes de bibliotecas originais e de módulos de comunicação), mantêm o -Werror, que é o que mantém o código e os exemplos do próprio Mokxi limpos de avisos.
O que é guardado em cache, e onde
| o quê | onde | chave | perdido quando |
|---|---|---|---|
bytes de clang.wasm |
Cache API, mokxi-toolchain-v1 |
/toolchain/<version>/clang.wasm |
nenhuma família usa mais a versão, o disco está cheio, o armazenamento é limpo |
| os arquivos objeto do runtime | Cache API, mesmo armazenamento | /toolchain/<version>/runtime/<family>-<bundle hash>.objects |
a versão muda, o firmware muda, o armazenamento é limpo |
o WebAssembly.Module compilado |
o worker, em memória | versão do toolchain | a página fecha |
| os arquivos objeto do runtime | o worker, em memória | versão do toolchain + família | a página fecha |
| o arquivo objeto de cada código-fonte do projeto | o worker, em memória | texto do código-fonte + o comando exato | a página fecha |
| o ELF compilado | o app, em memória | id da placa + assinatura do arquivo | a página fecha |
Os objetos de runtime são uma dúzia de arquivos de alguns kilobytes cada, empacotados em uma única entrada de cache em vez de uma dúzia (MOKO, um comprimento de cabeçalho, um índice JSON de pares [path, length], e depois os bytes um após o outro), então um acerto é um match e um arrayBuffer em vez de doze de cada. A chave carrega um hash do pacote de runtime exatamente como ele foi baixado, cada fonte, cabeçalho e flag nele, de modo que editar firmware/src/gpio.c e regenerar produz uma chave diferente em vez de um arquivo de objeto desatualizado. Qualquer coisa que não possa ser desempacotada é apagada e reconstruída, porque um blob que não conseguimos ler é pior que nenhum blob.
O que não é mais alcançável vai sendo descartado: toda entrada de um toolchain mais antigo, e um runtime de uma família cujas fontes avançaram. Uma família sobre a qual esta página não diz nada é deixada em paz: um usuário com um runtime de Uno em cache que passa o dia de hoje num ESP32-C3 o mantém.
Toda parte disso degrada graciosamente: sem Cache API, um cache que lança erro, um put que bate na cota: cada um significa "refazer o trabalho", nunca "sem compilador".
Medido
No Chromium 141 no contêiner de compilação, contra npm run dev em loopback (que serve o clang.wasm sem compressão, então o download é o caso pessimista; a produção o serve do R2 com Content-Encoding: br):
| clique até rodar | o que ele fez | |
|---|---|---|
| primeira compilação, fria | 6,1 a 7,8 s | download de 74 MB, WebAssembly.compile, 12 objetos de runtime, sketch, link, strip |
| segunda visita e seguintes | 1,5 a 1,8 s | nenhuma requisição de clang.wasm; runtime vindo da Cache API em 3 a 9 ms |
| editar e Rodar de novo, na mesma sessão | 0.21 s | sketch.ino 51 ms, link 10 ms, strip 5 ms |
| Rodar sem edição | nenhuma compilação | |
| o ELF | 1,5 KB | pisca o GPIO 8 na taxa que o sketch pede, no motor real a 1,00x |
Quatro visitas num mesmo perfil de navegador fizeram uma requisição de clang.wasm, e a segunda e todas as seguintes pularam o runtime inteiramente:
visit 1: 7758 ms Building… -> compiling the esp32c3 runtime… -> compiling your files…
crt0.S 124+54 ms | gpio.c 826 | time.c 454 | uart.c 195 | interrupt.c 148
| support.c 429 | format.c 483 | math.c 80 | print.cpp 498 | main.cpp 58
| sketch.ino 65 | link 39 | strip 11
visit 2: 1754 ms loading the compiler… -> compiling your files…
esp32c3 runtime (cached) 9 ms | sketch.ino 676 | link 35 | strip 11
visit 3: 1464 ms esp32c3 runtime (cached) 3 ms | sketch.ino 550 | link 43 | strip 11
visit 4: 1540 ms esp32c3 runtime (cached) 6 ms | sketch.ino 514 | link 38 | strip 14
O que sobra de uma visita de retorno são duas coisas, nenhuma delas o runtime: cerca de 0,7 s para ler os 74 MB de volta da Cache API e fazer compileStreaming, e cerca de 0,5 s para a primeira execução de ferramenta num módulo recém-compilado, que é o motor aquecendo; a segunda edição na mesma sessão são os 51 ms acima.
O painel Compilação mostra a porcentagem do download, cada passo com seu tempo, e uma linha no final: Built esp1.elf, 1.5 KB, 0.21 s.
O que o Worker precisa servir
/toolchain/<version>/<file> precisa vir do bucket R2 mokxi-toolchain (objetos <version>/<file>), com um Cache-Control longo (o caminho tem versão, então os objetos são imutáveis) e Content-Encoding: br para o wasm. A resposta precisa de Content-Type: application/wasm e um Content-Length: a barra de progresso do painel lê o comprimento, e WebAssembly.compileStreaming recusa qualquer coisa que não seja application/wasm.
O CMSIS e a HAL da ST nas placas STM32
A Nucleo-F411RE, a Black Pill e a Blue Pill também compilam código escrito para os cabeçalhos da própria ST: código de registradores que inclui stm32f4xx.h (ou stm32f1xx.h, ou o antigo stm32f10x.h) e projetos do STM32CubeIDE na HAL do STM32Cube. Os arquivos da ST são incluídos em firmware/stm32cube/ (veja o README dele para os commits e licenças originais) e empacotados por web/scripts/bundle-stm32cube.mjs em web/public/firmware/stm32cube/f4.json e f1.json, cerca de 0,47 e 0,40 MB com Brotli. Eles não estão nos pacotes do runtime nem no primeiro carregamento do editor: o worker busca um deles só quando um projeto inclui um dos cabeçalhos da ST, ou um main.h que ele não tem (wantsCube em src/compile/stm32cube.ts), e o mantém para a página.
cubePlan decide o resto, e projectPlan o segue:
- o pacote é montado em
/stm32cube, seus diretórios de include entram no caminho, com-DSTM32F411xEou-DSTM32F103xB,-DUSE_HAL_DRIVERquando a HAL é usada,-DUSE_FULL_LL_DRIVERquando a LL é, e-DMOKXI_ST_CMSIS, que faz o cabeçalho de placa do próprio runtime deferir ao da ST num sketch; - os módulos da HAL que o
stm32f?xx_hal_conf.hdo projeto habilita, os arquivos LL que ele inclui e o arquivo de sistema são compilados com-we ligados como membros de biblioteca, então uma primeira compilação com HAL compila cerca de uma dúzia de arquivos da ST (9 a 15 segundos no wasm do clang-v2 nos testes) e a próxima reutiliza seus objetos; - um projeto com seu próprio
main()é ligado bare (bareMetalLinkInputs): o código de inicialização e a tabela de vetores do runtime como estão, todo outro objeto de runtime como membro de biblioteca, emokxi_cube_bare.croteandoprintf()pelo_write()ou__io_putchar()do projeto. Um sketch mantém o core do Arduino, emokxi_cube_sketch.cfaz o tick da HAL virarmillis(); - o que faltar num projeto colado é escrito com os padrões do CubeIDE para a placa (
main.h, a configuração da HAL, o handler do SysTick, um arquivo MSP), o arquivo de inicialização da ST e osyscalls.cesysmem.cdo CubeIDE ficam de fora, e cada um desses é uma nota no log de compilação (ProjectPlan.notes); - um projeto que chama um periférico que o chip simulado não tem (SPI, I2C, DMA, o RTC e outros) recebe uma nota dizendo isso; a compilação ainda assim funciona.
Os chips simulados não têm interface de flash, controlador de energia nem região bit-band, e a HAL escreve os três em HAL_Init() e em todo SystemClock_Config() do CubeIDE. O construtor do pacote adiciona um include ao cabeçalho de dispositivo da ST (mokxi_cube_regs.h: FLASH e PWR viram RAM com o mesmo layout) e um ao stm32f?xx_hal.h (mokxi_cube_hal.h: as escritas bit-band das macros do RCC viram escritas comuns de registrador); os arquivos incorporados ficam inalterados. src/compile/stm32cube.test.ts compila e roda todo exemplo em firmware/stm32cube/examples/, e /learn/stm32-hal-register-code é a página para os usuários.
Limites
- C, C++ e assembly (
.Se.s, veja acima). Sem MicroPython e sem outra linguagem: o MicroPython do Pico e ummain.pyde Raspberry Pi rodam uma imagem de firmware em vez de passar por este caminho. - Um projeto é plano: os nomes de arquivo não carregam diretórios, então o caminho de include tem um diretório de profundidade.
- Uma placa cuja string
programdo catálogo não nomeia família nenhuma não tem família nenhuma, entãofamilyFornão encontra nada e ela roda seu ELF pré-compilado. Uma placa cuja família não estáreadyfaz o mesmo, com anoteda família mostrada no painel. - Uma visita de retorno ainda paga cerca de 0,7 s para tirar os 74 MB de volta da Cache API e compilá-los.
compileStreaminga partir de umaResponseem cache é o que permite ao motor reutilizar seu próprio cache de código, mas nada aqui pode tornar isso uma certeza. - Em desenvolvimento o toolchain é servido pelo Vite a partir de
web/public/toolchain/; em produção o Worker o serve do R2.worker/assets.tsresponde 404 para/toolchain/de propósito, então o middleware de dev emweb/vite.config.tsprecisa deixar esse prefixo em paz. Ele deixa, e quebrar isso é como o compilador acaba baixando a página 404.