Các tệp của một bo mạch được biên dịch bằng clang thật và lld thật, chạy dưới dạng WebAssembly ngay trong trang. Không có build server, không có gì được tải lên, và file ELF tạo ra cùng loại với image mà firmware/build.sh tạo ra: cùng trình biên dịch, cùng danh sách lệnh.
Bằng chứng rằng cách này chạy được, cùng các con số chứng minh việc xây dựng nó, nằm ở proofs/compile/REPORT.md. Tài liệu này mô tả cách sản phẩm làm điều đó.
Cấu trúc chung
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
Tất cả trừ bảng biên dịch đều chạy trong worker, nên lần biên dịch đầu tiên kéo dài bốn giây không làm khựng nổi một khung hình nào của khung vẽ.
Những gì phải đến được trình duyệt
Hai thứ, từ hai nơi.
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 chạy dạng --check, nên thay đổi nào ở firmware/ mà không ai cập nhật theo sẽ làm hỏng bộ test chứ không phải bản build của người dùng.
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.
Phiên bản toolchain được ghim theo từng họ bo mạch
Phiên bản là một thuộc tính của họ, không phải của ứng dụng, vì hai bản build không phải là một trình biên dịch: clang-rv32-v1 được cấu hình chỉ với LLVM_TARGETS_TO_BUILD=RISCV, nên nó có thể biên dịch cho ESP32-C3 và về mặt kỹ thuật không thể biên dịch cho Uno. clang-v2 là cùng script build đó với LLVM_TARGETS_TO_BUILD=RISCV;AVR;ARM (cùng bố cục, cùng bucket, cùng dạng URL), và mọi họ hiện biên dịch được đều được ghim vào nó (DECISIONS.md, 2026-09-14: đã kiểm chứng trên cả ba backend và tải lên R2). Kết quả RISC-V của nó giống hệt từng byte so với clang-rv32-v1, nên ESP32-C3 cũng chuyển sang dùng nó và mọi bo mạch như vậy dùng chung một bản tải về. Các họ Xtensa được ghim vào clang-v3 (XTENSA_TOOLCHAIN), xuất bản ngày 2026-09-28:
| họ | chương trình catalog |
đích | bộ công cụ | sẵn sàng |
|---|---|---|---|---|
esp32c3 |
elf32 riscv32imc |
riscv32-unknown-elf -march=rv32imc -mabi=ilp32 |
clang-v2 |
có |
c6 |
elf32 riscv32imc esp32c6 |
riscv32-unknown-elf -march=rv32imc -mabi=ilp32 |
clang-v2 |
có |
uno |
elf32 avr atmega328p |
avr -mmcu=atmega328p |
clang-v2 |
có |
nano |
elf32 avr atmega328p nano |
avr -mmcu=atmega328p |
clang-v2 |
có |
mega2560 |
elf32 avr atmega2560 |
avr -mmcu=atmega2560 |
clang-v2 |
có |
leonardo |
elf32 avr atmega32u4 |
avr -mmcu=atmega32u4 |
clang-v2 |
có |
attiny |
elf32 avr attiny85 |
avr -mmcu=attiny85 |
clang-v2 |
có |
pico |
elf32 arm rp2040 |
thumbv6m-none-eabi -mcpu=cortex-m0plus -mthumb |
clang-v2 |
có |
xiao |
elf32 arm samd21 |
thumbv6m-none-eabi -mcpu=cortex-m0plus -mthumb |
clang-v2 |
có |
stm32 |
elf32 arm stm32f411 |
thumbv7em-none-eabi -mcpu=cortex-m4 -mthumb -mfloat-abi=soft -mfpu=none |
clang-v2 |
có |
bluepill |
elf32 arm stm32f103 |
thumbv7m-none-eabi -mcpu=cortex-m3 -mthumb -mfloat-abi=soft |
clang-v2 |
có |
microbit |
elf32 arm nrf52833 |
thumbv7em-none-eabi -mcpu=cortex-m4 -mthumb -mfloat-abi=soft -mfpu=none |
clang-v2 |
có |
unor4 |
elf32 arm ra4m1 |
thumbv7em-none-eabi -mcpu=cortex-m4 -mthumb -mfloat-abi=soft -mfpu=none |
clang-v2 |
có |
esp32 |
elf32 xtensa lx6 esp32 |
xtensa-esp-elf -mcpu=esp32 -fintegrated-as |
clang-v3 |
có |
esp32s3 |
elf32 xtensa lx7 esp32s3 |
xtensa-esp-elf -mcpu=esp32s3 -fintegrated-as |
clang-v3 |
có |
esp8266 |
elf32 xtensa lx106 esp8266 |
xtensa-esp-elf -mcpu=esp8266 -fintegrated-as |
clang-v3 |
có |
Ba dòng cuối là phần tiếp theo. web/src/compile/bundles.ts là danh sách mà bảng này đọc từ đó, và bundles.test.ts giữ chúng đồng bộ.
Các bo mạch Xtensa, trên clang-v3
ESP32 cổ điển là Xtensa LX6, ESP8266 NodeMCU là Xtensa LX106 và ESP32-S3 là Xtensa LX7. Cả ba đều biên dịch trong trình duyệt trên clang-v3 từ ngày 2026-09-28 ("Published and checked" bên dưới). Trước đó chúng chạy các ELF dựng sẵn và nói rõ điều đó. Phần còn lại của mục này giải thích tại sao cần một fork, và bằng chứng đã tìm thấy gì.
Tại sao đây là một bộ công cụ riêng (đã kiểm tra 2026-09-27):
clang-v2không có backend Xtensa. Nó được build vớiLLVM_TARGETS_TO_BUILD=RISCV;AVR;ARM(DECISIONS.md, 2026-09-14). File wasm mà trình duyệt tải về về mặt kỹ thuật không thể phát sinh object Xtensa.- LLVM upstream có một nửa những gì cần, và là nửa sai. Clang đã có front end Xtensa từ LLVM 20 (Phoronix), và của LLVM 22
XtensaProcessors.tdđã biếtesp32vàesp8266(upstreammainthêmesp32s2vàesp32s3). Nhưng upstreamld.lldkhông có đích Xtensa nào cả: không cólld/ELF/Arch/Xtensa.cpptrênmainhoặc trênrelease/22.x, nên không gì upstream có thể link một ảnh ESP32. Backend upstream cũng vẫn phát sinh literal pool ngay trong.text, làm hỏngl32rcăn lưới dưới-ffunction-sections(llvm/llvm-project#190204, vẫn mở). Xtensa vẫn ở trạng tháiLLVM_ALL_EXPERIMENTAL_TARGETSupstream. - Espressif's fork has all of it.
esp-clang(espressif/llvm-project, mới nhấtesp-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).
Vậy đây là một fork cần theo dõi hơn là một cờ cần thêm, nhưng fork là của chính Espressif, phát hành vài tháng một lần, và có cùng giấy phép với LLVM mà clang-v2 đến từ.
Các ELF dựng sẵn vẫn được build bằng GCC của Espressif, mà deploy/fetch-xtensa.sh đặt vào tools/xtensa/: xtensa-esp32-elf-gcc 8.4.0 cho LX6, xtensa-esp32s3-elf-gcc 8.4.0 cho LX7 và xtensa-lx106-elf-gcc 8.4.0 cho LX106. Runtime của S3 dùng lại crt0.S và support64.c của ESP32 cổ điển: với code mà trình biên dịch phát sinh từ C thì LX7 chính là LX6, và kết quả của trình biên dịch S3 cho cùng chương trình thử nghiệm giống hệt từng byte với trình biên dịch ESP32. Thư mục đó bị gitignore. GCC thuộc GPL, và không gì nó build ở đây link với libgcc (các runtime là -nostdlib với support.c riêng, và support32.c của ESP8266 cung cấp các phép chia 32-bit mà LX106 không có lệnh cho), nên không có code GPL nào lọt vào một ELF đã xuất bản.
Chứng minh trên bản native
Trước khi có wasm, phía trình biên dịch được chứng minh bằng bản build native Linux của cùng fork đó (clang-esp-22.1.4_20260825-x86_64-linux-gnu.tar.xz, 411 MB, sha256 4700ed4e...eb0a1, giải nén ra 2.7 GB có cả ld.lld):
proofs/compile/xtensa/run-native.sh /some/scratch/dir
Nó lấy bản phát hành đó, rồi chạy proofs/compile/xtensa/plan.ts --native, không sao chép bất kỳ lệnh nào: nó lấy runtimeSteps và projectPlan từ web/src/compile/toolchain.ts và các gói runtime đã commit web/public/firmware/runtime/esp32.json, esp32s3.json và esp8266.json, nên cái được chạy là danh sách lệnh của trình duyệt, crt0.S tách thành hai phần tiền xử lý và assemble, ld.lld được gọi trực tiếp, llvm-objcopy xuất ra stdout. Kết quả ngày 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.lldgiải quyết mọi relocation (trong các object ESP32: 3,407R_XTENSA_32và 430R_XTENSA_SLOT0_OP);MOKXI_ESP32_ELF_DIR=... cargo test -p esp32 --test runtime --test wifi: 11 + 4 passed;MOKXI_ESP32S3_ELF_DIR=... cargo test -p esp32s3 --test runtime --test wifi: 13 + 4 passed;MOKXI_ESP8266_ELF_DIR=... cargo test -p esp8266 --test runtime --test wifi: 11 + 4 passed. Đây là chính các test mà các ELF GCC đã vượt qua: nửa chu kỳ 500 ms của blink, LEDC và PWM phần mềm ở 1 kHz,millis()so với đồng hồ kernel, khoảng cách bit UART0, ADC, các khung WS2812 trên LED RGB của S3 (trắng, rồi xanh lá của rainbow ra trước trên dây) và các gói USB serial của nó, kết nối WiFi và trang web của bóng đèn. Ba biến môi trường chỉ trỏ các test sẵn có sang một thư mục khác; một file hỏng ở đó khiến chúng panic, nên chúng thực sự đã tải những gì vừa build.
Ba điều mà lần chứng minh này phát hiện, tất cả đã được xử lý trong các bundle:
-fintegrated-aslà bắt buộc. Với Xtensa, driver Espressif mặc định giao một.sfile cho một trình assemble GNU bên ngoài (xtensa-esp32-elf-clang-as) theo mặc định, thứ mà WASI không thể khởi chạy. Với-fintegrated-astrình assemble riêng của clang nhận crt0.S đúng như viết. Nó nằm trong target flags của họ, nên phần assemble cũng nhận được nó. Espressif cố ý tắt nó với đầu vào assembly (EspBareMetal.cpp: "TODO: Add full support for Xtensa to integrated asm, LLVM-290, LLVM-291"), nên nó không hoàn chỉnh với mọi file viết tay; nhưng với cả haicrt0.Sfile của chúng ta thì có, như các test của trình mô phỏng cho thấy. Đây cũng là lý do các.Svà.sfile riêng của một dự án không được hỗ trợ trên các bo mạch Xtensa: chỉ.c,.cppvà.inođược biên dịch ở đó, trong khi mọi họ khác đều assemble cả các file riêng của dự án (xem Assembly bên dưới). C và C++ luôn đi qua trình assemble tích hợp, trong fork này cũng như upstream.- Không có cảnh báo multilib trong wasm. Bản cài native cảnh báo rằng nó không có multilib esp8266 (thành lỗi dưới
-Werror) vìmultilib.yamlcủa nó không có mục này.BareMetal::findMultilibschỉ đọc mộtmultilib.yamlnếu tồn tại, và filesystem của wasm không có file nào, nên chỉ lần chạy native cần-Wno-missing-multilib, và chỉplan.ts --nativetruyền nó. -mlongcallsvà-mtext-section-literalscủa GCC bị bỏ đi. Clang báo-mlongcallslà đối số không dùng tới, thành lỗi dưới-Werror. Không có-mtext-section-literalsthì clang phát sinh các.literal.<function>section, mà cả balink.ldfile đã đặt ở đầu.text, well insideL32R's 256 KB reach.
Kích thước code, phân đoạn thực thi của mọi ví dụ so với image GCC đóng gói (cùng nguồn, cả hai đều -Os):
| bo mạch | GCC, mọi ví dụ | clang | mỗi ví dụ |
|---|---|---|---|
| ESP32 | 29,984 bytes | 37,760 bytes | +15% (fade) đến +37% (wifilamp), +26% tổng thể |
| ESP32-S3 | 41,584 bytes | 53,920 bytes | +18% (fade) đến +38% (wifilamp), +30% tổng thể |
| ESP8266 | 34,592 bytes | 49,104 bytes | +33% (button) đến +49% (wifilamp), +42% tổng thể |
Dữ liệu chênh nhau chỉ vài chục byte mỗi bên. Image clang lớn nhất là wifilamp của ESP8266 với 8,944 bytes code, so với IRAM 32 KB và giới hạn 24 KB mà elfcheck.py của nó áp cho các ví dụ, nên mức tăng này không ảnh hưởng gì mà một sketch ở đây để ý được. Chưa phân tích xem các byte đi đâu.
Xuất bản và kiểm tra
- Build bởi
.github/workflows/clang-v3.yml, lần chạy 36358476287 (lần thử 3,maintại4578344f):espressif/llvm-projecttạiesp-22.1.4_20260825vớiRISCV;AVR;ARM;Xtensa, cả hai bản vá WASI, rồiplan.ts --wasmcho cả ba bo mạch và các test của trình mô phỏng trên sản phẩm wasm vừa build. Artifactclang-v3, sha256 của zip làef27b7aa…3eafd;clang.wasmnặng 80,735,841 bytes, sha2567546c54c07c392e231ea450f8e3aaa6680346ffeb08e13d97d970b26d88666e5. - Xuất bản ngày 2026-09-28: artifact được giải nén vào
web/public/toolchain/clang-v3/, rồideploy/fetch-toolchain.sh --publish clang-v3.https://mokxi.com/toolchain/clang-v3/phục vụclang.wasm,bundle.jsonvàinclude.tgzvới đúng kiểu, đúng độ dài và cùng sha256 với artifact.bundle.jsonchưa được cắt bớt (16 MB, mọi resource header của clang); chỉ các mục/usr/includecủa nó được dùng, và việc cắt bớt như bundle.json của clang-v2 sẽ tiết kiệm phần lớn lượng tải xuống đó. - Kiểm tra trong Chromium (headless, với
npm run devvà các file đã xuất bản trongweb/public/toolchain/clang-v3/): trình soạn thảo thật mở một sơ đồ với sketch của nó, nhấn Chạy, và theo dõi bảng biên dịch, serial monitor và LED. Sketch ESP32 tham gia WiFi mô phỏng (192.168.4.2) và nhấp nháy GPIO 4; sketch ESP32-S3 nhấp nháy GPIO 2 và in; sketch ESP8266 nhấp nháy D1 và in một phép chia 32-bit mỗi vòng lặp; ví dụ Blink riêng của ESP8266, sau khi chỉnh sửa, cũng build và nhấp nháy. Lần build đầu của một bo mạch mất 5 đến 7 giây kể cả runtime, lần sau khoảng 1.5 giây. ELF mà trang build ra cho Blink của ESP8266 giống hệt từng byte vớiproof/esp8266/blink.elfcủa workflow. - Lần kiểm tra ESP8266 phát hiện một lỗi engine, đã sửa trong cùng thay đổi. Blink của clang ghi các chân trong cùng slice mà nó park, nên đường nối của chân di chuyển bên trong khoảng thời gian mà core đã chạy xong, và linh kiện bo mạch đã đẩy core đang park tới trước khi slice đó kết thúc.
CCOUNTchạy lùi, bộ đếm chu kỳ 64-bit của runtime đọc đó là tràn 2^32 chu kỳ, và mọidelay()sau lần đầu trả về ngay lập tức: LED sáng và sáng mãi. Blink của GCC không bao giờ ghi chân trong slice nó park, đó là lý do không ví dụ đóng gói nào thể hiện điều này, và các test native cũng không thấy vì chúng chạy SoC không kèm mạch. Các linh kiện bo mạch ESP32, ESP32-S3 và ESP8266 giờ không bao giờ chạy core sớm hơn điểm kết thúc slice cuối của nó (ran_totrongcrates/parts/src/parts/esp8266.rsvà hai file anh em), vàblink_keeps_its_half_period_when_a_pin_moves_as_the_core_parksgiữ vững điều đó (chạy vớiMOKXI_ESP8266_ELF_DIRtrỏ vào các ELF clang). - Dấu phẩy động dùng soft float.
-mcpu=esp32và-mcpu=esp32s3bật FPU đơn độ chính xác, mà mô hình không có, nên lúc đầu phép nhânfloat, phép so sánh hoặcisnan(h) || isnan(t)trong bài hướng dẫn DHT được biên dịch thành lệnh FPU và bo mạch bị treo. Giờ các bundle truyền-Xclang -target-feature -Xclang -fp(trình điều khiển Xtensa không có-mfloat-abi), nên float chuyển thành các lời gọi vàomokxi_float.cnhư trên mọi bo mạch soft float khác và cho kết quả đúng. LX106 của ESP8266 không có FPU để tắt và cũng liên kết cùng filemokxi_float.c.
Các bước tiếp theo
- Quyết định xem liệu mọi họ có chuyển sang clang-v3 hay không. Cho đến khi đó, người dùng biên dịch cho ESP32 và một bo mạch khác sẽ giữ hai bộ công cụ hơn 75 MB trong Cache API:
isStaleKey(cache.ts) giữ mọi phiên bản mà một họ nêu tên (TOOLCHAINS_IN_USE) và chỉ bỏ bản kia khi đĩa đầy. Trước 2026-10-17 nó bỏ mọi phiên bản trừ bản đang dùng, nên mỗi lần chuyển là tải lại 20 MB và thất bại khi ngoại tuyến. Chuyển hết chỉ là một chuỗi cho mỗi họ, như lần chuyển sang clang-v2, nhưng đây là LLVM 22.1.4 từ một fork chứ không phải 22.1.0, nên hãy chạycrash.test.tsvà các kiểm thử thư viện có sẵn với nó trước, và đừng coi kết quả đầu ra là giống hệt từng byte. - Kiểm tra các thư viện có sẵn trên các họ Xtensa.
firmware/libnằm trên đường dẫn include của chúng như trên mọi bo mạch, nhưngstock-libraries.test.tskhông liệt kê chúng, nênServo.h,Wire.hvà các thư viện còn lại chưa được kiểm thử ở đó. - Cắt bớt
bundle.jsonchỉ còn các header mà một bản build freestanding mở.
Không bao giờ tuyên bố có biên dịch trong trình duyệt khi nó không hoạt động: một nút biên dịch lặng lẽ chạy tệp nhị phân của hôm qua sẽ là điều tệ nhất trong sản phẩm này.
clang-rv32-v1 vẫn là giá trị của RV32_TOOLCHAIN và không họ nào nêu tên nó. Nó ở lại như lối quay lui: tăng chuỗi toolchain của một họ là toàn bộ việc triển khai hoặc rollback một bản build, vì các URL, khóa cache mô-đun và cache đối tượng lúc chạy đều gắn vào nó.
ready cũng không phải mã chết. Hai điều kiện phải đúng thì một họ mới mang được nó, và bundles.test.ts kiểm tra điều kiện thứ hai:
- Bộ công cụ có back end, đã được xuất bản, và một sketch nó build đã chạy trên trình mô phỏng.
- Họ đó có một bundle runtime, nghĩa là thư mục firmware của nó tồn tại và
bundle-runtime.mjsđã được chạy.
Một họ không ready không phải là lỗi: chooseProgram gửi các bo mạch của nó đến ELF dựng sẵn từ web/public/firmware/, bảng biên dịch và dòng bên cạnh ô chọn bo mạch nói rõ lý do, và không có gì hỏng. Hôm nay không họ nào đi theo hướng đó; các họ Xtensa từng vậy cho đến khi clang-v3 được phát hành.
STM32 và micro:bit là soft float có chủ đích: DECISIONS.md, 2026-09-14, để FPU và DSP của M4 ngoài phạm vi cho đến khi cần một bo M4F, nên không runtime nào được phát lệnh VFP hay ABI hard-float.
Điều gì xảy ra khi bạn nhấn Chạy
App.buildPrograms hỏi chooseProgram (src/compile/client.ts) về từng bo mạch, và nhận một trong ba câu trả lời:
elf: chạy tệp image mà bảng Firmware nêu tên và không biên dịch gì. Một ELF tải lên không được build từ các tệp này; một ví dụ dựng sẵn chưa đụng đến đã được build sẵn. Một họ có bộ công cụ chưa xuất bản cũng rơi vào đây.reuse: chạy ELF đã build từ đúng các tệp này. Quyết định là một hash của mọi tên tệp và mọi byte trong đó, nên một phím gõ và một lần hoàn tác đưa bạn quay lạireuse.build: biên dịch, rồi chạy kết quả.
Một bản build thất bại dừng lượt chạy: nút giữ nguyên ở Chạy, ELF trước đó bị bỏ thay vì âm thầm dùng, và chẩn đoán vẫn nằm trong bảng. ELF đã build chỉ nằm trong bộ nhớ cho phiên này. Nó là một sự thật về phiên này, không thuộc về tài liệu, nên nó không bao giờ được lưu, xuất hay chia sẻ.
Danh sách lệnh
Cùng mười bốn lệnh mà firmware/build.sh chạy, với hai khác biệt mà WASI buộc phải có (đều đã được tìm ra trong bản chứng minh):
-c crt0.Skhiến clang cần hai công việc, một tiền xử lý và một assemble, và clang tắt cc1 tích hợp ngay khi có nhiều hơn một, mà trên WASI là "unable to execute command: WASI does not support spawning subprocesses". Hai nửa được liệt kê riêng.- Việc liên kết đi qua
ld.lldtrực tiếp thay vì qua trình điều khiển clang, nên các cờ liên kết của ESP32-C3 mất tiền tố-Wl,.firmware/uno/build.shđã gọild.lldvì lý do tương tự.
Hệ thống tệp mà các công cụ thấy:
| đường dẫn | là gì |
|---|---|
/usr/include |
các header tài nguyên của clang, từ bundle bộ công cụ |
/firmware cho ESP32-C3, /firmware/<family> cho phần còn lại |
mã nguồn runtime, các header, crt0.S, link.ld của chúng ta |
/firmware/lib |
các trình điều khiển header-only dùng chung, cùng đường dẫn cho mọi họ |
/project |
các tệp của bo mạch, dưới tên riêng của chúng, để #include "pins.h" hoạt động |
/build |
các object, sketch đã bao, ELF |
Assembly
Các tệp .S và .s của chính dự án cũng được biên dịch ở đây, vì arduino-cli biên dịch một tệp .S nằm cạnh một sketch, và một bo mạch có thể chỉ gồm assembly mà thôi.
Bốn phần, tất cả trong web/src/compile/:
- Kế hoạch.
projectPlan(toolchain.ts) thêm một cặp bước cho mỗi.S: một bước tiền xử lý với đường dẫn include, đường dẫn quote và các define riêng của sketch (nên#include <avr/io.h>cho ra tên thanh ghi và__ASSEMBLER__được đặt), rồi một bước hợp dịch bản đã tiền xử lý. Là hai lượt chạy vì lý do màruntimeStepsđã nêu:-c foo.Skhiến clang muốn hai tác vụ, và clang tắt cc1 tích hợp ngay khi có nhiều hơn một, mà trên WASI là "unable to execute command: WASI does not support spawning subprocesses". Một tệp.sđược hợp dịch trực tiếp, không có bước tiền xử lý. Các dấu# <line> "<file>"của bộ tiền xử lý được giữ nguyên, nên một chẩn đoán và một dòng DWARF là dòng của chính thẻ đó chứ không phải dòng của bản đã tiền xử lý, điều này cho phép trình gỡ lỗi đặt breakpoint trên một dòng.S. Bước hợp dịch chỉ truyền các cờ mà chính trình hợp dịch đọc, cộng thêm-g -gdwarf-4. - Phần kiểm tra toán hạng.
asm-check.tsđọc mọi tệp AVR.Svà.scủa dự án trước khi bất kỳ công cụ nào chạy, và báo lỗi theo đúng định dạngfile:line:col: error:của clang nênparseDiagnosticsvà bảng biên dịch không cần biết thêm gì mới. Nó thực hiện những kiểm tra màavr-aslàm còn trình biên dịch AVR của LLVM âm thầm bỏ qua:ldi r16, 300(giữ nguyên thành 0x2C),sbi PORTB, 1(địa chỉ dữ liệu đặt vào chỗ của địa chỉ I/O),add r16, 5(đọc thànhadd r16, r5),out PORTB, r16thiếu__SFR_OFFSET 0(cảnh báo: lệnh trỏ đến một thanh ghi khác),invàoutvượt quá 63,sbiwvàadiwvượt quá 63, và bit vượt quá 7. Một toán hạng chỉ được phán xét khi có thể tính được: số, các.equ,.setvà#definecủa chính tệp, và các tên thanh ghi, tên bit trong tệp header của bo mạch đọc từ runtime bundle, thông qua_SFR_IO_ADDR(),lo8(),hi8()và các toán tử C. Còn lại được giao cho trình hợp dịch và trình liên kết, vốn xử lý đúng những thứ đó. Một lỗi sẽ dừng việc biên dịch trước khi công cụ nào khởi động (plan.checkFailed). - Việc liên kết, khi không có sketch.
isAssemblyProject(bundles.ts) là dự án có tệp chỉ toàn hợp dịch;assemblyLinkInputscho biết ngoài các object của chính nó thì nó liên kết thêm gì. Trên bo mạch AVR đó là objectcrt0.Scủa runtime và không có gì khác, đóng vai trò giống nhưgcrt1.ocủa avr-libc vớiavr-gcc main.S: bảng vector với mọi__vector_<n>là mộtretiweak,r1được xóa, stack đặt tại RAMEND,.datađược sao chép,.bssđược xóa, và một lời gọi tớimaincủa dự án. Dự án có tệp tự định nghĩa section.vectorshoặc nhãn__vectors(definesVectors) thì không nhận gì, và mọi bo mạch ARM cũng vậy, nơi tệp chính là bảng vector. Không có Arduino core trong cả hai trường hợp: khôngsetup(), không nhịpmillis(), khôngSerial. - Trình dịch ngược.
disasm.tslà của chính chúng tôi, vì bản LLVM trong trình duyệt có clang,ld.lldvàllvm-objcopymà không cóllvm-objdump. Nó đọc các đoạn thực thi được của ELF mà ứng dụng đã giữ sẵn, nên danh sách Disassembly trong tab Debug và nút Step instruction không cần thêm một lượt truyền tin. Bộ giải mã AVR bao phủ toàn bộ tập lệnh; bộ giải mã Thumb bao phủ mọi mã hóa 16 bit,BL, và các dạng Thumb-2 32 bit mà trình biên dịch hay một khóa học thường dùng, còn phần còn lại hiện thành.inst.w 0x…thay vì đoán sai. Văn bản đúng nhưllvm-objdump, vàdisasm.test.tsgiữ nó như vậy: mọi lệnh của các bản build thật (bốn dự án hợp dịch khởi đầu, và một sketch có phép tính dấu phẩy động,Serialvà chân) cho Uno, Mega, Pico và Black Pill phải đọc đúng nhưllvm-objdumpcủa máy đọc.
Những bo mạch nào hỗ trợ dự án hợp dịch không core được liệt kê trong src/asm/boards.ts: Uno, Nano, Pro Mini, Pico và STM32F411. Mọi bo mạch khác vẫn biên dịch được đều nhận tab .S cạnh một sketch, trừ các bo Xtensa (xem trên). asm.test.ts build và chạy tất cả trên trình mô phỏng.
Một công cụ bị bẫy
clang và lld đều đi vào đường abort trước một số lỗi nghiêm trọng (chủ yếu là thiếu #include): in chẩn đoán ra stderr rồi chạy vào unreachable thay vì gọi exit. Trong WASI điều này thành một WebAssembly.RuntimeError thật, không phải proc_exit, và nếu không sẽ thoát ra thành một rejection chưa bắt không kèm chẩn đoán: một sự cố, chứ không phải lỗi build.
Toolchain.run (src/compile/toolchain.ts) xử lý đúng trường hợp đó: một trap xảy ra sau khi công cụ đã ghi gì đó vào stderr sẽ quay về như một bước thất bại thông thường, result.trapped được đặt và result.code khác không, mọi thứ đã ghi trước trap vẫn nằm trong result.err. runSteps (src/compile/worker.ts) sau đó đối xử với nó như mọi mã thoát khác không: bất cứ gì parseDiagnostics tìm thấy là những gì bảng biên dịch hiển thị, nhấn được như mọi chẩn đoán khác, và chỉ rơi về "trình biên dịch đã bị sập (<tool> ở bước <step>)" khi trap không mang theo gì để nói. Mỗi lần chạy công cụ đều nhận một WebAssembly.Instance mới từ đúng một Module đã biên dịch (toolchainFor biên dịch module một lần; Toolchain.run khởi tạo nó ở mỗi lần gọi), nên trap trong lần chạy này không để lại gì cho lần sau. Không có instance nào để nhiễm bẩn và chẳng có gì ở đây tự khởi tạo lại module.
Các tab .ino được nối và bọc theo cách Arduino IDE làm (src/compile/prototypes.ts): #include "arduino.h", rồi tab chính và các tab .ino khác theo thứ tự bảng chữ cái, mỗi tab sau #line 1 "<tab>.ino", kèm prototype cho mọi hàm mà các tab định nghĩa, viết ngay trước hàm đầu tiên, mỗi prototype sau một #line trỏ về nơi định nghĩa, và một #line sau khối đó. Nhờ vậy một sketch gọi hàm được định nghĩa bên dưới loop() vẫn build được, và trình biên dịch vẫn báo lỗi tại sketch.ino:12:3 để bảng biên dịch đưa trình soạn code tới đó. Template, thành viên lớp, bất cứ thứ gì trong namespace, hàm do sketch tự khai báo và hàm có chữ ký nêu tên thứ gì đó được khai báo phía sau thì không có prototype; hàm nằm trong khối #if thì có prototype nằm trong bản sao của chính các điều kiện đó; đối số mặc định được chuyển vào prototype và xóa đi, từng cột một, khỏi phần định nghĩa. Tệp .c được biên dịch thành C11, .cpp/.cc/.ino thành C++17; còn lại được ghi vào /project để phục vụ include và không được biên dịch.
Tệp của người dùng được biên dịch với các cờ cảnh báo của runtime trừ -Werror (userWarnings trong bundles.ts): cảnh báo -Wall -Wextra được báo trong bảng biên dịch, và một object trong bộ nhớ đệm giữ nguyên cảnh báo của nó để lần Chạy sau hiển thị lại, nhưng cảnh báo không dừng bản build, giống như Arduino IDE. Bản thân runtime, cùng projectPlan(..., { strict: true }) (phần chứng minh Xtensa, các kiểm thử thư viện gốc và mô-đun giao tiếp), vẫn giữ -Werror, đây chính là thứ giữ cho code và ví dụ của Mokxi sạch cảnh báo.
Cái gì được cache, và ở đâu
| là gì | ở đâu | khóa | mất khi |
|---|---|---|---|
byte của clang.wasm |
Cache API, mokxi-toolchain-v1 |
/toolchain/<version>/clang.wasm |
họ bo mạch nào cũng không dùng phiên bản đó nữa, đĩa đầy, bộ nhớ bị xóa |
| các tệp object của runtime | Cache API, cùng kho | /toolchain/<version>/runtime/<family>-<bundle hash>.objects |
phiên bản thay đổi, firmware thay đổi, bộ nhớ bị xóa |
WebAssembly.Module đã biên dịch |
worker, trong bộ nhớ | phiên bản toolchain | trang đóng |
| các tệp object của runtime | worker, trong bộ nhớ | phiên bản toolchain + họ bo mạch | trang đóng |
| tệp object của từng mã nguồn dự án | worker, trong bộ nhớ | văn bản nguồn + chính xác lệnh chạy | trang đóng |
| ELF đã build | ứng dụng, trong bộ nhớ | id bo mạch + chữ ký tệp | trang đóng |
Các object runtime là chục file mỗi file vài kilobyte, được đóng gói vào một mục cache thay vì chục mục (MOKO, một độ dài header, một chỉ mục JSON gồm các cặp [path, length], rồi các byte nối đầu đuôi nhau), nên một lần trúng cache là một match và một arrayBuffer thay vì mười hai lần mỗi loại. Khóa mang một hash của gói runtime đúng như lúc được tải về, gồm mọi nguồn, header và cờ trong đó, nên sửa firmware/src/gpio.c rồi tạo lại sẽ ra khóa khác thay vì một object file cũ. Bất cứ gì không thể giải nén đều bị xóa và xây lại, vì một blob đọc không được còn tệ hơn cả không có blob.
Những gì không còn truy cập được sẽ bị dọn theo lối cũ đi qua: mọi mục của toolchain cũ hơn, và một runtime của họ bo mạch mà nguồn đã thay đổi. Một họ bo mạch mà trang này không nhắc gì đến thì được giữ nguyên: người dùng có runtime Uno trong cache mà hôm nay làm việc với ESP32-C3 thì vẫn giữ nó.
Mọi phần của cơ chế này đều suy giảm êm: không có Cache API, một cache bị lỗi, một put chạm hạn mức: mỗi trường hợp đều là "làm lại công việc", không bao giờ là "không có trình biên dịch".
Số đo thực tế
Trên Chromium 141 trong build container, chạy với npm run dev qua loopback (serve clang.wasm không nén, nên lần tải về là trường hợp bi quan; bản production serve từ R2 với Content-Encoding: br):
| từ cú nhấn đến khi chạy được | nó đã làm gì | |
|---|---|---|
| biên dịch lần đầu, lạnh | 6,1 đến 7,8 s | tải 74 MB, WebAssembly.compile, 12 object runtime, sketch, link, strip |
| lần truy cập thứ hai trở đi | 1,5 đến 1,8 s | không có request clang.wasm; runtime ra khỏi Cache API trong 3 đến 9 ms |
| sửa rồi Run lại, cùng phiên | 0.21 s | sketch.ino 51 ms, link 10 ms, strip 5 ms |
| Run mà không sửa gì | không biên dịch gì cả | |
| file ELF | 1,5 KB | nhấp nháy GPIO 8 đúng tốc độ sketch yêu cầu, trên engine thật ở 1,00x |
Bốn lần truy cập trong một profile trình duyệt chỉ tạo một request cho clang.wasm, và lần thứ hai cùng mọi lần sau bỏ qua runtime hoàn toàn:
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
Những gì còn lại của một lần quay lại là hai thứ, không thứ nào là runtime: khoảng 0,7 s để đọc lại 74 MB từ Cache API và compileStreaming nó, và khoảng 0,5 s cho lần chạy công cụ đầu tiên trong một module mới biên dịch, đó là engine đang khởi động; lần sửa thứ hai trong cùng phiên là con số 51 ms phía trên.
Bảng biên dịch hiển thị phần trăm tải về, từng bước với thời gian của nó, và một dòng cuối: Built esp1.elf, 1.5 KB, 0.21 s.
Những gì Worker phải serve
/toolchain/<version>/<file> phải đến từ bucket R2 mokxi-toolchain (các object <version>/<file>), với Cache-Control dài (đường dẫn có phiên bản, nên các object là bất biến) và Content-Encoding: br cho wasm. Response cần Content-Type: application/wasm và Content-Length: thanh tiến độ của bảng đọc độ dài, và WebAssembly.compileStreaming từ chối mọi thứ không phải application/wasm.
CMSIS và HAL của ST trên các bo mạch STM32
Bo mạch Nucleo-F411RE, Black Pill và Blue Pill cũng biên dịch được code viết cho các header chính thức của ST: code thao tác thanh ghi có include stm32f4xx.h (hoặc stm32f1xx.h, hoặc header cũ stm32f10x.h) và các dự án STM32CubeIDE dùng STM32Cube HAL. Các tệp của ST được đưa vào trong firmware/stm32cube/ (xem README ở đó để biết các commit và giấy phép nguồn) và được đóng gói bởi web/scripts/bundle-stm32cube.mjs thành web/public/firmware/stm32cube/f4.json và f1.json, cỡ 0.47 và 0.40 MB sau nén Brotli. Chúng không nằm trong các bundle runtime và không tải ở lần mở đầu tiên của trình soạn code: worker chỉ tải một trong hai khi dự án include một header của ST, hoặc một tệp main.h mà nó chưa có (wantsCube trong src/compile/stm32cube.ts), rồi giữ lại cho cả trang.
cubePlan quyết định phần còn lại, và projectPlan theo nó:
- gói được mount tại
/stm32cube, các thư mục include của nó vào path, với-DSTM32F411xEhoặc-DSTM32F103xB,-DUSE_HAL_DRIVERkhi dùng HAL,-DUSE_FULL_LL_DRIVERkhi dùng LL, và-DMOKXI_ST_CMSIS, thứ này khiến header bo mạch của runtime nhường chỗ cho header của ST trong một sketch; - các module HAL mà
stm32f?xx_hal_conf.hcủa dự án bật, các file LL nó include và file system được biên dịch với-wvà link như thành viên thư viện, nên lần biên dịch HAL đầu tiên biên dịch khoảng chục file của ST (9 đến 15 giây trên wasm clang-v2 trong các test) và lần sau tái dùng object của chúng; - một dự án có
main()riêng được link bare (bareMetalLinkInputs): code khởi động và bảng vector của runtime giữ nguyên, mọi object runtime khác là thành viên thư viện, vàmokxi_cube_bare.cđưaprintf()qua_write()hoặc__io_putchar()của dự án. Một sketch giữ Arduino core, vàmokxi_cube_sketch.cbiến tick của HAL thànhmillis(); - những gì một dự án dán vào thiếu thì được viết với mặc định của CubeIDE cho bo mạch đó (
main.h, cấu hình HAL, handler SysTick, một file MSP), file khởi động của ST cùngsyscalls.cvàsysmem.ccủa CubeIDE bị bỏ ra, và mỗi điều đó là một ghi chú trong log biên dịch (ProjectPlan.notes); - một dự án gọi đến ngoại vi mà chip mô phỏng không có (SPI, I2C, DMA, RTC và vài thứ khác) nhận một ghi chú nói vậy; bản build vẫn thành công.
Các chip mô phỏng không có giao diện flash, bộ điều khiển nguồn hay vùng bit-band, và HAL ghi cả ba trong HAL_Init() và trong mọi SystemClock_Config() của CubeIDE. Trình đóng gói thêm một include vào header thiết bị của ST (mokxi_cube_regs.h: FLASH và PWR trở thành RAM cùng bố cục) và một vào stm32f?xx_hal.h (mokxi_cube_hal.h: các lệnh ghi bit-band của macro RCC trở thành lệnh ghi thanh ghi thường); các file vendored giữ nguyên. src/compile/stm32cube.test.ts biên dịch và chạy mọi ví dụ trong firmware/stm32cube/examples/, và /learn/stm32-hal-register-code là trang dành cho người dùng.
Giới hạn
- C, C++ và assembly (
.Svà.s, xem ở trên). Không có MicroPython và không có ngôn ngữ nào khác: MicroPython của Pico vàmain.pycủa Raspberry Pi chạy một ảnh firmware thay vì đi qua đường này. - Dự án có cấu trúc phẳng: tên tệp không chứa thư mục, nên đường dẫn include chỉ sâu một mức.
- Một bo mạch có chuỗi
programtrong danh mục không nêu họ nào thì không thuộc họ nào cả, nênfamilyForkhông tìm thấy gì và bo mạch chạy ELF dựng sẵn của nó. Một bo mạch có họ chưareadycũng làm vậy, kèmnotecủa họ được hiển thị trong bảng. - Lần quay lại vẫn mất khoảng 0,7 giây để lấy lại 74 MB từ Cache API và biên dịch.
compileStreamingtừ mộtResponsetrong cache là điều cho phép engine dùng lại chính code cache của nó, nhưng không gì ở đây có thể đảm bảo điều đó chắc chắn. - Trong quá trình phát triển, toolchain được Vite phục vụ từ
web/public/toolchain/; còn khi chạy thực tế thì Worker phục vụ nó từ R2.worker/assets.tscố tình trả về 404 cho/toolchain/, nên middleware phát triển trongweb/vite.config.tsphải để nguyên tiền tố đó. Nó đang làm đúng vậy, và phá vỡ điều này chính là lý do trình biên dịch tải về trang 404.