Tham khảo

Biên dịch một sketch ngay trong trình duyệt

Một sketch trở thành firmware thế nào mà không cần máy chủ biên dịch nào cả.

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):

  1. clang-v2 không có backend Xtensa. Nó được build với LLVM_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.
  2. 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ết esp32 và esp8266 (upstream main thêm esp32s2 và esp32s3). Nhưng upstream ld.lld không có đích Xtensa nào cả: không có lld/ELF/Arch/Xtensa.cpp trên main hoặc trên release/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ỏng l32r căn lưới dưới -ffunction-sections (llvm/llvm-project#190204, vẫn mở). Xtensa vẫn ở trạng thái LLVM_ALL_EXPERIMENTAL_TARGETS upstream.
  3. Espressif's fork has all of it. esp-clang (espressif/llvm-project, mới nhất esp-22.1.4_20260825, LLVM 22.1.4, Apache-2.0 with LLVM exception) carries the Xtensa front end with -mcpu=esp32, esp8266, esp32s2 and esp32s3, and an lld/ELF/Arch/Xtensa.cpp that handles R_XTENSA_32, R_XTENSA_SLOT0_OP (L32R, CALL8, branches) and the DIFF/ASM_EXPAND relocations. Xtensa is experimental there too, so it has to go in LLVM_EXPERIMENTAL_TARGETS_TO_BUILD; build-wasm-clang.sh now splits that out of the target list by itself. The fork does not carry the WASI portability commit, so proofs/compile/patches/llvm-wasi-portability.patch (the same commit clang-v2 is built with, from YoWASP) is applied on top. It applies cleanly to esp-22.1.4_20260825 (one hunk at an offset of one line). That commit's WASI close() returns a stale errno and fails clean writes ("IO failure on output stream: No such file or directory"), so build-wasm-clang.sh always applies proofs/compile/patches/llvm-wasi-close-errno.patch after it, on either tree. The clang-v2 served today predates that fix; ERRNO_RESET_HEADER and runtimeFiles in web/src/compile/toolchain.ts work around it until it is rebuilt (docs/clang-v2-rebuild.md has 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, rainbow and usbserial included) and nine for the ESP8266 (20 steps), about 1 s each natively;
  • ld.lld giải quyết mọi relocation (trong các object ESP32: 3,407 R_XTENSA_32 và 430 R_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-as là bắt buộc. Với Xtensa, driver Espressif mặc định giao một .s file 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-as trì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ả hai crt0.S file 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 .S và .s file riêng của một dự án không được hỗ trợ trên các bo mạch Xtensa: chỉ .c, .cpp và .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.yaml của nó không có mục này. BareMetal::findMultilibs chỉ đọc một multilib.yaml nế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 --native truyền nó.
  • -mlongcalls và -mtext-section-literals của GCC bị bỏ đi. Clang báo -mlongcalls là đối số không dùng tới, thành lỗi dưới -Werror. Không có -mtext-section-literals thì clang phát sinh các .literal.<function> section, mà cả ba link.ld file đã đặt ở đầu .text, well inside L32R'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

  1. Build bởi .github/workflows/clang-v3.yml, lần chạy 36358476287 (lần thử 3, main tại 4578344f): espressif/llvm-project tại esp-22.1.4_20260825 với RISCV;AVR;ARM;Xtensa, cả hai bản vá WASI, rồi plan.ts --wasm cho 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. Artifact clang-v3, sha256 của zip là ef27b7aa…3eafd; clang.wasm nặng 80,735,841 bytes, sha256 7546c54c07c392e231ea450f8e3aaa6680346ffeb08e13d97d970b26d88666e5.
  2. Xuất bản ngày 2026-09-28: artifact được giải nén vào web/public/toolchain/clang-v3/, rồi deploy/fetch-toolchain.sh --publish clang-v3. https://mokxi.com/toolchain/clang-v3/ phục vụ clang.wasm, bundle.json và include.tgz với đúng kiểu, đúng độ dài và cùng sha256 với artifact. bundle.json chưa được cắt bớt (16 MB, mọi resource header của clang); chỉ các mục /usr/include củ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 đó.
  3. Kiểm tra trong Chromium (headless, với npm run dev và các file đã xuất bản trong web/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ới proof/esp8266/blink.elf của workflow.
  4. 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. CCOUNT chạy lùi, bộ đếm chu kỳ 64-bit của runtime đọc đó là tràn 2^32 chu kỳ, và mọi delay() 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_to trong crates/parts/src/parts/esp8266.rs và hai file anh em), và blink_keeps_its_half_period_when_a_pin_moves_as_the_core_parks giữ vững điều đó (chạy với MOKXI_ESP8266_ELF_DIR trỏ vào các ELF clang).
  5. Dấu phẩy động dùng soft float. -mcpu=esp32 và -mcpu=esp32s3 bật FPU đơn độ chính xác, mà mô hình không có, nên lúc đầu phép nhân float, phép so sánh hoặc isnan(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ào mokxi_float.c như 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 file mokxi_float.c.

Các bước tiếp theo

  1. 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ạy crash.test.ts và 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.
  2. Kiểm tra các thư viện có sẵn trên các họ Xtensa. firmware/lib nằm trên đường dẫn include của chúng như trên mọi bo mạch, nhưng stock-libraries.test.ts không liệt kê chúng, nên Servo.h, Wire.h và các thư viện còn lại chưa được kiểm thử ở đó.
  3. Cắt bớt bundle.json chỉ 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:

  1. 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.
  2. 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ại reuse.
  • 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):

  1. -c crt0.S khiế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.
  2. Việc liên kết đi qua ld.lld trự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ọi ld.lld vì 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/:

  1. 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.S khiế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.
  2. Phần kiểm tra toán hạng. asm-check.ts đọc mọi tệp AVR .S và .s củ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ạng file:line:col: error: của clang nên parseDiagnostics và 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-as là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ành add r16, r5), out PORTB, r16 thiếu __SFR_OFFSET 0 (cảnh báo: lệnh trỏ đến một thanh ghi khác), in và out vượt quá 63, sbiw và adiw vượ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, .set và #define củ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).
  3. 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; assemblyLinkInputs cho 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à object crt0.S của runtime và không có gì khác, đóng vai trò giống như gcrt1.o của avr-libc với avr-gcc main.S: bảng vector với mọi __vector_<n> là một reti weak, 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ới main của dự án. Dự án có tệp tự định nghĩa section .vectors hoặ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ông setup(), không nhịp millis(), không Serial.
  4. Trình dịch ngược. disasm.ts là của chính chúng tôi, vì bản LLVM trong trình duyệt có clang, ld.lld và llvm-objcopy mà 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.ts giữ 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, Serial và chân) cho Uno, Mega, Pico và Black Pill phải đọc đúng như llvm-objdump củ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 -DSTM32F411xE hoặc -DSTM32F103xB, -DUSE_HAL_DRIVER khi dùng HAL, -DUSE_FULL_LL_DRIVER khi 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.h của dự án bật, các file LL nó include và file system được biên dịch với -w và 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 đưa printf() qua _write() hoặc __io_putchar() của dự án. Một sketch giữ Arduino core, và mokxi_cube_sketch.c biến tick của HAL thành millis();
  • 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ùng syscalls.c và sysmem.c củ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 (.S và .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.py củ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 program trong danh mục không nêu họ nào thì không thuộc họ nào cả, nên familyFor khô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ưa ready cũng làm vậy, kèm note củ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. compileStreaming từ một Response trong 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.ts cố tình trả về 404 cho /toolchain/, nên middleware phát triển trong web/vite.config.ts phả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.

Câu hỏi

Quá trình biên dịch diễn ra ở đâu?

Ngay trên máy của bạn, trong tab trình duyệt. Không có máy chủ biên dịch, không có hàng chờ và không có phút biên dịch.

Toolchain lớn bao nhiêu?

Khoảng bảy mươi megabyte. Nó được truyền xuống một lần và trình duyệt lưu cache, nên sau lần biên dịch đầu tiên mọi thứ đều chạy cục bộ.