DEV Community: Yangholmes

EMSCRIPTEN 多线程编程笔记

Yangholmes — Fri, 19 Sep 2025 08:23:17 +0000

操作系统的多线程

进程是操作系统分配资源的最小单位，每创建一个新的进程，会把父进程的资源复制一份到子进程。而线程是一种轻量级的进程，不独立拥有系统资源，操作系统内核是按照线程作为调度单位来调度资源。每一个进程是由一个或者多个线程组成的。

进程中 Text、Data、BSS 和 Heap 部分线程之间共享，Stack 不共享，每个线程拥有自己独立的栈。

Linux 系统中普遍使用 pthread 库开发多线程程序，pthread 符合 POSIX 标准，提供管理和操作线程的方法，包含在 pthread.h 头文件中。同一个进程中，除了栈，所有线程共享同一份内存，同时因为线程的执行是并行的，所以不可避免地发生资源竞争的问题，即同一时间有多个线程试图获取或者修改同一个内存资源。当开发者小心翼翼地处理内存使用时，并行地读写内存可以带来效率提升，一旦不注意可能带来严重的问题。假设用 2 个线程执行如下代码，counter 的结果可能远小于 2000 ：

for (int i = 0; i < 1000; i++) counter++;

pthread 提供了锁来解决这个问题，最常见的锁是互斥锁和读写锁。

互斥锁：同一时间只能有唯一一个线程访问，使用 pthread_mutex_t
读写锁：同一时间只能有唯一一个线程写入，允许多个线程读取，使用 pthread_rwlock_t

这里不打算展开 Linux 多线程编程，超出了本篇讨论的重点。

EMSCRIPTEN 的多线程

浏览器是一个多线程应用，我们在《web 应用榨干 CPU 性能的正确姿势》一文中介绍过这些线程，这里引用一张图：

这些线程由浏览器管理，开发者并不能干预，可以把这些线程看作是“不可编程”的多线程；浏览器像开发者提供了“可编程”的多线程，那就是 Worker 。《web 应用榨干 CPU 性能的正确姿势》介绍了在 JavaScript 中如何使用 Worker 实现多线程编程，并介绍了线程之间 Transferable objects 数据传输方式。 Transferable objects 有点类似互斥锁，数据从一个线程传输至另一个线程的时候，不进行数据拷贝，而是传递数据所在的内存所有权，数据传输完成之后，只有接收线程可以访问这块数据，其他线程都无法访问；和互斥锁不同的是， Transferable objects 没有“解锁”方法，如果需要将数据“还给”发送线程，就按照 Transferable objects 的方式重新发送数据。Transferable objects 数据适用于 ArrayBuffer 一类数据，没有“共享”的属性。如果想要在不同的线程之间“共享”内存，就像使用真正的内存那样，就需要使用 SharedArrayBuffer 。

Worker 和 SharedArrayBuffer 正是 emscripten 多线程的实现基础，尽可能地实现 POSIX 标准的 pthread 功能。Worker 实现了独立栈和共享 Text， SharedArrayBuffer 实现了共享堆，和文件系统类似，也是通过替换系统函数，移花接木。

SharedArrayBuffer

SharedArrayBuffer 对象表示一块二进制内存缓冲区，和 ArrayBuffer 类似，但 SharedArrayBuffer 可以被共享同时不能被 transfer 。new SharedArrayBuffer(length) 效果和 calloc(nmemb, size) 非常类似，运行之后都可以获得值全为 0 的内存，只不过 SharedArrayBuffer 长度为 length * 8 bit ， calloc 长度为 nmemb * size bit 。也就是说，SharedArrayBuffer 申请的内存是没有类型的，使用的时候需要根据实际情况构造成相应的 TypedArray 类型。

const sab = new SharedArrayBuffer(1024);
const ta = new Uint8Array(sab);
ta[0] = 100;
console.log(ta[0]); // 100
console.log(ta[1]); // 0
worker.postMessage(sab);

SharedArrayBuffer 可以在主线程和多个 Worker 线程中创建、传输和修改，当多个线程同时使用同一块内存时，这块内存的修改传播到不同上下文需要花费一些时间，也就是说，修改生效不是立即的，和操作系统上多线程内存操作一样。使用上 1 节的例子，当 2 个线程执行如下代码后，counter 的结果可能远小于 2000 ：

// 在某一个线程创建共享内存
cosnt _counter = new ShareArrayBuffer(1);
const counter = new Uint8Array(_counter);

// 在 2 个线程中执行累加
for (int i = 0; i < 1000; i++) counter[0]++;

JavaScript 并不采用“锁”来控制内存读写，而是提供 Atomics 对象来保证数据读写准确。Atomics 的细节请参考文档，这里不赘述。如果想要让 counter 的最终结果是 2000 ，只需要简单修改一下加法命令：

for (let i = 0; i < 1000; i++) {
  Atomics.add(counter, 0, 1); // 原子加操作
}

Atomics 可以用来实现锁功能， emscripten 就是这么做的。简单地讲，使用 Atomics.wait 实现等待， Atomics.compareExchange 实现加锁，Atomics.store 实现解锁，Atomics.notify 实现通知线程。

cross-origin isolated

使用 SharedArrayBuffer 必须满足两个条件：

安全上下文，即 https://、 wss:// 和 localhost
cross-origin isolated ，即跨源隔离

安全上下文想必大家都知道是什么含义，这里简单解析一下 cross-origin isolated（跨源隔离）。跨源隔离是一种网页的状态，此时只能在同源 document 共享上下文和使用 CORS 加载的资源（<iframe> 的话是 COEP ）。同时，浏览器将把这个源的页面独立一个进程来管理，意味着这个源的页面拥有独立的操作系统资源，崩溃报错不会轻易影响到其他页面。SharedArrayBuffer 必须在 cross-origin isolated 状态下使用，否则会找不到这个构造函数。除了 SharedArrayBuffer 外，cross-origin isolated 还具有其余两个特性：

Performance.now() 精度提高，提高到 5ms 甚至更高
Performance.measureUserAgentSpecificMemory() 可用

如何开启 cross-origin isolated ？在页面的响应头中添加 COEP 和 COOP ：

Cross-Origin-Embedder-Policy: require-corp
Cross-Origin-Opener-Policy: same-origin

cross-origin isolated 会带来一些不便：

非同源嵌入式资源无法直接加载，如 <img>、 <script>、 <video> 等，解决方法：
1. 在服务端设置正确的 Access-Control-Allow-Origin 响应头，并在标签中添加 crossorigin属性，如 <img src="***" crossorigin>
2. 使用 CORP ，服务端为资源设置 Cross-Origin-Resource-Policy 响应头
3. 代理转发，把跨域资源处理称为同源资源
<iframe> 必须显性标明跨域嵌入，否则无法加载
非同源 popup window.opener 为 null
无法改写 document.domain

是否开启多线程需要结合页面使用的资源情况来决定。

如果不确定一个页面是否符合 cross-origin isolated ，可以读取 window.crossOriginIsolated 嗅探，在 worker 中为 self.crossOriginIsolated 。无法提前预判运行环境是否跨源隔离，通常需要分别准备一套单线程方案和一套多线程方案，通过嗅探决定使用哪一种。

if (window.crossOriginIsolated) {
  const myWorker = new Worker("worker-pthread.js");
  const buffer = new SharedArrayBuffer(16);
  myWorker.postMessage(buffer);
} else {
  const myWorker = new Worker("worker-single.js");
  const buffer = new ArrayBuffer(16);
  myWorker.postMessage(buffer, [buffer]);
}

主线程阻塞

WebAssembly 在主线程唤起执行通常会导致主线程阻塞，进而引发 UI 卡死。一般的做法是把 WebAssembly 放到一个独立的线程去执行，这个在前面的文档中多次提及。在 emscripten 中，由于线程由编译器管理，根据当前硬件状况自动合理分配，如果此时手动再增加一个线程，可能会导致线程分配不合理。解决这个问题有两个方案：

手动指定可用线程数。 -sPTHREAD_POOL_SIZE=<expression> 参数用来指定可用线程数，接受一个数字或一个 JavaScript 表示式。一般地我们会选择不传这个参数或者传入 navigator.hardwareConcurrency 。当开发者想要手动维护启动线程时，可以为启动线程保留一个线程数，设置为 -sPTHREAD_POOL_SIZE="navigator.hardwareConcurrency-1"
使用 -sPROXY_TO_PTHREAD 参数。添加这个参数后，c 程序中的 main() 函数会被替换成一个新的线程，在这个线程中运行原本的 main() 函数。相当于是方法 1 的自动化版本。有时候我们开发的 WebAssembly 模块并没有 main() 函数，此时可以参考使用方法 1

这里建议使用 -sPTHREAD_POOL_SIZE=<expression> 参数，无论是否手动分配启动线程。原因是当指定了 -sPTHREAD_POOL_SIZE=<expression> 后，程序将提前创建好 workers ，当代码执行到 pthread_create 可以直接使用 worker 而不是从实例化开始，可以提高效率，并获得跟原生 c 更接近的运行效果。

-sPROXY_TO_PTHREAD 和 --proxy-to-worker 很像，都是将 main() 函数代理到 worker 中，带不一样的地方在于，--proxy-to-worker 只是纯粹代理 main() ，并不支持 pthread 和 SharedArrayBuffer 。

Using SIMD in WebAssembly (Part 1)

Yangholmes — Wed, 10 Sep 2025 03:48:47 +0000

Overview of SIMD in WebAssembly

SIMD in WebAssembly has the same meaning as in CPUs: Single Instruction Multiple Data. SIMD instructions achieve parallel data processing by performing the same operation on multiple data elements simultaneously, enabling vectorized computation. Compute-intensive applications like audio/video processing, codecs, and image processing leverage SIMD for performance gains. SIMD implementation depends on CPU hardware, and different architectures support varying SIMD capabilities. WebAssembly's SIMD instruction set is relatively conservative, currently limited to fixed-length 128-bit (16-byte) instructions.

Most mainstream virtual machines now support SIMD:

Chrome ≥ 91 (May 2021)
Firefox ≥ 89 (June 2021)
Safari ≥ 16.4 (March 2023)
Node.js ≥ 16.4 (June 2021)

Before using SIMD, check client support in your user base, then implement progressive enhancement in your project. This means:

Create two versions of the same wasm module: one with SIMD instructions and one without
Detect host support for SIMD using libraries like wasm-feature-detect
Load the appropriate module based on detection results

wasm-feature-detect tests support for wasm features (including SIMD, 64-bit memory, multithreading) and is tree-shakable for web compatibility.

// loadWasmModule.js
import { simd } from 'wasm-feature-detect';

export default function(url, simdUrl) {

  return simd().then(isSupported => {
    return isSupported ? () => import(simdUrl) : () => import(url);
  });
}

SIMD Instruction Set

SIMD instructions resemble scalar operations but process vectors. Key categories include arithmetic, load/store, logical operations, and lane manipulation. Summary of common instructions:

Instruction Format	Description	Example
Load/Store
`v128.load offset=<n> align=<m>`	Load 128-bit vector from memory	`(v128.load offset=0 align=16 (i32.const 0))`
`v128.load8_splat`	Load 8-bit integer and splat to 16 lanes	`(v128.load8_splat (i32.const 42))`
`v128.store offset=<n> align=<m>`	Store 128-bit vector to memory	`(v128.store offset=16 align=16 (i32.const 32) (local.get $vec))`
Constants
`v128.const <type> <values>`	Create constant vector	`(v128.const i32x4 0 1 2 3)`
Integer Arithmetic
`i8x16.add(a, b)`	8-bit integer addition (16 lanes)	`(i8x16.add (local.get $a) (local.get $b))`
`i16x8.sub(a, b)`	16-bit integer subtraction (8 lanes)	`(i16x8.sub (local.get $a) (local.get $b))`
`i8x16.add_saturate_s(a, b)`	8-bit signed saturating addition	`(i8x16.add_saturate_s (local.get $a) (local.get $b))`
Integer Comparison
`i8x16.eq(a, b)`	8-bit integer equality (returns mask)	`(i8x16.eq (local.get $a) (local.get $b))`
`i32x4.lt_s(a, b)`	32-bit signed integer less-than	`(i32x4.lt_s (local.get $a) (local.get $b))`
Floating Point
`f32x4.add(a, b)`	32-bit float addition (4 lanes)	`(f32x4.add (local.get $a) (local.get $b))`
`f64x2.sqrt(a)`	64-bit float square root (2 lanes)	`(f64x2.sqrt (local.get $a))`
Bitwise
`v128.and(a, b)`	Bitwise AND	`(v128.and (local.get $a) (local.get $b))`
`v128.bitselect(a, b, mask)`	Bitwise selection by mask	`(v128.bitselect (local.get $a) (local.get $b) (local.get $mask))`
Shifts
`i32x4.shl(a, imm)`	32-bit integer left shift (immediate)	`(i32x4.shl (local.get $a) (i32.const 2))`
Lane Operations
`i8x16.extract_lane_s(idx, a)`	Extract signed 8-bit lane	`(i8x16.extract_lane_s 3 (local.get $a))`
`i8x16.shuffle(mask, a, b)`	Shuffle lanes from two vectors	`(i8x16.shuffle 0 1 2 3 12 13 14 15... (local.get $a) (local.get $b))`
Type Conversion
`i32x4.trunc_sat_f32x4_s(a)`	f32 to i32 (saturated truncation)	`(i32x4.trunc_sat_f32x4_s (local.get $a))`
Other
`v128.any_true(a)`	Check if any lane is non-zero	`(v128.any_true (local.get $a))`
`f32x4.ceil(a)`	32-bit float ceiling	`(f32x4.ceil (local.get $a))`

Instruction set summarized with DeepSeek assistance. Please report any inaccuracies.

Using SIMD Instructions

Example: Image color inversion

Non-SIMD implementation processes one pixel (4 bytes) per iteration:

(module
  (import "env" "log" (func $log (param i32)))

  (import "env" "memory" (memory 100))

  ;; invert RGB in place, skip Alpha
  (func $invert (param $start i32) (param $length i32)
    (local $end i32)   
    (local $i i32)    

    ;; Calculate end address = start + length * 4
    local.get $start
    (i32.mul (local.get $length) (i32.const 4))
    i32.add
    local.set $end

    local.get $start
    local.set $i

    (block $exit
      ;; Process R, G, B channels individually
      (loop $loop

        local.get $i
        local.get $end
        i32.ge_u
        br_if $exit


        ;; R
        local.get $i
        i32.const 255
        local.get $i
        i32.load8_u     
        i32.sub          
        i32.store8      

        ;; G
        local.get $i
        i32.const 1
        i32.add
        i32.const 255
        local.get $i
        i32.const 1
        i32.add
        i32.load8_u     
        i32.sub          
        i32.store8       

        ;; B
        local.get $i
        i32.const 2
        i32.add
        i32.const 255
        local.get $i
        i32.const 2
        i32.add
        i32.load8_u     
        i32.sub          
        i32.store8       

        ;; i = i + 4
        local.get $i
        i32.const 4
        i32.add
        local.set $i

        br $loop
      )
    )
  )

  (export "invert" (func $invert))
)

SIMD version processes 4 pixels (16 bytes) per iteration:

(module
  (import "env" "log" (func $log (param i32)))
  (import "env" "memory" (memory 100))

  (func $invert (param $start i32) (param $length i32)
    (local $end i32)        
    (local $i i32)          
    (local $chunk v128)     
    (local $mask v128)     
    (local $full255 v128)  

    ;; end = start + length * 4
    local.get $start
    local.get $length
    i32.const 4
    i32.mul

    i32.add
    i32.const 3
    i32.add
    local.set $end

    ;; i = start
    local.get $start
    local.set $i

    ;; Full 255 vector
    v128.const i8x16 255 255 255 255 255 255 255 255
                     255 255 255 255 255 255 255 255
    local.set $full255

    ;; Alpha channel mask (preserve positions 3,7,11,15)
    v128.const i8x16 0 0 0 255 0 0 0 255
                     0 0 0 255 0 0 0 255
    local.set $mask

    (block $exit
      (loop $loop
        ;; if (i >= end) break
        local.get $i
        local.get $end
        i32.ge_u
        br_if $exit

        ;; load 16 bytes (4 pixels)
        local.get $i
        v128.load
        local.set $chunk

        ;; tmp = 255 - chunk
        local.get $full255
        local.get $chunk
        i8x16.sub
        local.set $chunk

        ;; Preserve alpha channels
        local.get $i
        v128.load
        local.get $chunk
        local.get $mask
        v128.bitselect
        local.set $chunk

        ;; store back
        local.get $i
        local.get $chunk
        v128.store

        ;; i += 16
        local.get $i
        i32.const 16
        i32.add
        local.set $i

        br $loop
      )
    )
  )

  (export "invert" (func $invert))
)

Note: The SIMD version processes 16 bytes per iteration (line 18-20). Since image data might not be multiples of 16 bytes, we add 3 to the end address for alignment. This could potentially overwrite memory if other data exists, but is acceptable in this isolated example.

Performance Comparison:

Left: Original image (928×927 pixels)
Middle: Non-SIMD result (processing time: ~2.9ms)
Right: SIMD result (processing time: 0.5ms)

The SIMD implementation shows ~6x speedup. Larger images yield greater benefits, but even smaller images like the classic Lenna test image show significant improvements:

Part 2 will explore using SIMD in WebAssembly via C/C++ programs.

在 WebAssembly 中使用 SIMD（二）

Yangholmes — Tue, 09 Sep 2025 10:23:19 +0000

本篇讨论 C 程序 SIMD 的实现。

使用 emscripten 编译

emscripten 支持 SIMD 指令编译，使用之前需要引入头文件 #include <wasm_simd128.h> ，和 wat 一样，支持 128 位 SIMD 指令集，例如定义一个 32 位浮点数矢量：

v128_t v1 = wasm_f32x4_make(1.2f, 3.4f, 5.6f, 7.8f);

如果想要对一个已经成熟的 C 项目启用 SIMD 指令，是否需要深入源代码，在每个 C 代码的文件中增加 #include <wasm_simd128.h> 并改写成 v128_t 的样子呢？其实并不用， emscripten 支持自动嗅探并将“串行”代码转换成“并行”代码，只需要在编译的时候增加 -msimd128 参数（这得益于 LLVM 的自动矢量化优化）。

使用 -msimd128 参数需要搭配 -O2 或者 -O3 参数。

上一篇使用 wat 实现了一个图片反色的函数，这里使用 C 语言实现一下：

// invert-c.c
#include <stdint.h>
#include <emscripten/emscripten.h>

extern void my_log(long int value);

// 图片反色函数
void invert_colors(uint8_t *img_data, long int pixel_count)
{
  long total_bytes = pixel_count * 4;

  // 遍历所有像素数据
  for (long int i = 0; i < total_bytes; i += 4)
  {
    // 跳过 Alpha 通道（索引3），只处理 RGB 通道
    img_data[i + 0] = 255 - img_data[i + 0]; // R 通道反色
    img_data[i + 1] = 255 - img_data[i + 1]; // G 通道反色
    img_data[i + 2] = 255 - img_data[i + 2]; // B 通道反色
  }
}

不启用 SIMD 编译，编译命令为：

emcc invert-c.c -o invert-c.wasm \
-O3 -g3 \
-sERROR_ON_UNDEFINED_SYMBOLS=0 \
-sEXPORTED_FUNCTIONS='["_invert_colors"]' \
-sIMPORTED_MEMORY=1 \
-sINITIAL_MEMORY=6553600 \
-sALLOW_MEMORY_GROWTH=1 \
-sSTANDALONE_WASM --no-entry

启用 SIMD 编译，编译命令为：

emcc invert-c.c -o invert-c-simd.wasm \
-msimd128 -O3 -g3 \
-sERROR_ON_UNDEFINED_SYMBOLS=0 \
-sEXPORTED_FUNCTIONS='["_invert_colors"]' \
-sIMPORTED_MEMORY=1 \
-sINITIAL_MEMORY=6553600 \
-sALLOW_MEMORY_GROWTH=1 \
-sSTANDALONE_WASM --no-entry

使用相同的素材进行测试：

从左到右分别是原图、 wat 非 SIMD 、 wat SIMD 、 C 非 SIMD 、 C SIMD 处理后图片和耗时。可以看出，不启用 SIMD ，算法相同的情况下，通过 emscripten 编译的代码效率和 wat 相同，而启用 SIMD emscripten 编译的代码效率不如 wat 。为什么会有这种差别？使用 wabt wasm2wat 命令看看 emscripten 编译出来的算法策略是什么样的（摘抄部分关键代码）：

...
i8x16.shuffle 0 4 8 12 16 20 24 28 0 0 0 0 0 0 0 0    ;; 使用重排取出 R 通道
...
i8x16.shuffle 0 0 0 0 0 0 0 0 0 4 8 12 16 20 24 28    ;; 处理 G B 通道
i8x16.shuffle 0 1 2 3 4 5 6 7 24 25 26 27 28 29 30 31
v128.not                                              ;; 反相
local.tee 2
;; 写回内存
v128.store8_lane offset=61 15
local.get 1
local.get 2
v128.store8_lane offset=57 14
local.get 1
local.get 2
v128.store8_lane offset=53 13
...

;; G 和 B 通道同理

...

;; 如果像素总数不是 16 的倍数，剩余部分使用非 SIMD 代码处理
i32.load8_u      ;; 取出第一个通道
i32.const -1
i32.xor          ;; 取反
i32.store8       ;; 写回内存
...              
;; 其余两个通道同理
...

可以看出两点不同

像素数量不满足 16 倍数的处理，笔者的处理方式是补全到等于或超过 16 的倍数，确保可以命中所有内存，不需要再运行非 SIMD 代码，性能会更好一些
emscripten 采用重排的方式将每个像素的 RGBA 通道分别取出然后取反实现反色，最后写入的时候按照字节依次写入，笔者的实现方式是全部通道取反最后再将 Alpha 通道还原，原地读写，效率会更高一些

无论是手写的 SIMD 还是 emscripten 自动转换的 SIMD ，都要比非 SIMD 代码效率高。

shuffle 指令

i8x16.shuffle 是图形处理中非常常用的指令，可以用来一次性提取某个通道 128 位数据，方便后续运算。假设原始像素数据是这样排布的：

R0 G0 B0 A0 | R1 G1 B1 A1 | R2 G2 B2 A2 | R3 G3 B3 A3

接下来使用 i8x16.shuffle 提取 R 通道：

i8x16.shuffle 0 4 8 12 0 0 0 0 0 0 0 0

得到

[R0 R1 R2 R3 ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ??]

G 和 B 通道同理

;; G
i8x16.shuffle 1 5 9 13 0 0 0 0 0 0 0 0 

;; B
i8x16.shuffle 2 6 10 14 0 0 0 0 0 0 0 0

得到

[G0 G1 G2 G3 ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ??]
[B0 B1 B2 B3 ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ??]

?? 部分无所谓是什么数据，可以填 0 ，不影响计算。

最后就是 255 - x 的计算，uint 类型中，被全 1 数减相当于按位取反，这里直接使用 v128.not 指令，会比减法指令更高效一些。

使用 emscripten SIMD 指令

最后，笔者尝试使用 emscripten SIMD 指令重新编写代码。算法的思路和 wat 版本的一致，也是通过长度补齐的方式避免像素总数不是 16 的倍数：

// invert-c-simd.c
#include <stdint.h>
#include <emscripten/emscripten.h>
#include <wasm_simd128.h>

extern void my_log(long int value);

void invert_colors(uint8_t *img_data, long int pixel_count)
{
  // 每个像素包含 RGBA 4个字节
  long int total_bytes = pixel_count * 4;

  // 创建常量向量：255
  const v128_t const_255 = wasm_i8x16_splat((uint8_t)(255));

  // 创建掩码向量：每个像素的前3个字节为255（RGB），最后一个字节为0（Alpha）
  const v128_t mask = wasm_v128_load((const uint8_t[]){
      0xFF, 0xFF, 0xFF, 0x00,
      0xFF, 0xFF, 0xFF, 0x00,
      0xFF, 0xFF, 0xFF, 0x00,
      0xFF, 0xFF, 0xFF, 0x00});

  // 处理完整的16字节块（4个像素）
  long int simd_chunks = (total_bytes + 15) / 16;
  for (long int i = 0; i < simd_chunks; i++)
  {
    // 读取内存
    v128_t pixels = wasm_v128_load(img_data + i * 16);

    // 反色计算：255 - value
    v128_t inverted = wasm_i8x16_sub(const_255, pixels);

    // 使用位选择保留Alpha通道不变
    v128_t result = wasm_v128_bitselect(inverted, pixels, mask);

    // 写回内存
    wasm_v128_store(img_data + i * 16, result);
  }
}

查看结果：

左图依旧是原图，中间是 wat SIMD ，右图是 C SIMD 。可以看到，在相同的方案下，无论用什么语言来写，性能表现是一致的。

但是两种语言依旧有不同。上一篇有提到，字符补全方案有一个缺点，可能会污染其他数据，如果模块中需要实现不止一个功能的时候，需要非常小心；使用 emscripten 可以通过一些手段规避这个风险，在静态检查的时候会发现这个问题，为代码预留内存空间。

使用什么手段才能规避内存污染的风险呢？下期再讲。

在 WebAssembly 中使用 SIMD（一）

Yangholmes — Mon, 08 Sep 2025 08:21:26 +0000

WebAssembly 的 SIMD 概况

WebAssembly 的 SIMD 和 CPU 的 SIMD 是一个意思，都是指 Single Instruction Multiple Data (单指令多数据) 。SIMD 指令通过同时对多个数据执行相同的操作来实现并行数据处理，进而获得矢量运算能力，计算密集型应用，例如音视频处理、编解码器、图像处理，都采用 SIMD 提升性能。SIMD 的实现依赖于 CPU ，不同的硬件条件支持的 SIMD 能力不同，所以 SIMD 指令集很大，并且在不同架构之间有所不同，当然 WebAssembly SIMD 指令集也包含其中。另一方面， WebAssembly 作为一个通用型平台，其支持的 SIMD 指令集相对比较保守，目前仅限于固定长度 16 字节（128 位）的指令集。

目前主流的大部分虚拟机都支持 SIMD ：

Chrome ≥ 91 (2021年5月)
Firefox ≥ 89 (2021年6月)
Safari ≥ 16.4 (2023年3月)
Node.js ≥ 16.4 (2021年6月)

使用之前先看看大部分用户使用的客户端是否支持，然后考虑在项目中增加测试代码渐进增强。渐进增强的含义是，相同功能的 wasm 模块分别用非 SIMD 和 SIMD 指令编写，嗅探宿主对 SIMD 的支持情况，如果不支持则使用非 SIMD 模块，如果支持则使用 SIMD 模块。嗅探可以使用 wasm-feature-detect 库。这个库专门用于测试宿主对 wasm 特性支持程度，除了 SIMD 以外，这个库还可以检查诸如 64 位内存、多线程等新特性和实验特性，并且支持摇树（Tree-shakable），对 web 应用友好。

// loadWasmModule.js
import { simd } from 'wasm-feature-detect';

export default function(url, simdUrl) {
  return simd().then(isSupported => {
    return isSupported ? () => import(simdUrl) : () => import(url);
  });
}

SIMD 指令集

SIMD 指令和单字节指令类似，也是算术运算、读取写入、逻辑运算这几类。使用时需要严格按照栈式指令操作，SIMD 指令汇总：

指令格式	功能描述	示例
读取和存储
`v128.load offset=<n> align=<m>`	从内存加载 128 位向量	`(v128.load offset=0 align=16 (i32.const 0))`
`v128.load8_splat`	加载 8 位整数并复制 16 次填充向量	`(v128.load8_splat (i32.const 42))`
`v128.load16_splat`	加载 16 位整数并复制 8 次填充向量	`(v128.load16_splat (i32.const 1024))`
`v128.load32_splat`	加载 32 位整数并复制 4 次填充向量	`(v128.load32_splat (i32.const 0x12345678))`
`v128.load64_splat`	加载 64 位整数并复制 2 次填充向量	`(v128.load64_splat (i32.const 0))`
`v128.store offset=<n> align=<m>`	存储 128 位向量到内存	`(v128.store offset=16 align=16 (i32.const 32) (local.get $vec))`
创建常量
`v128.const <type> <values>`	创建常量向量	`(v128.const i32x4 0 1 2 3)`
`v128.const <type> <values>`	创建浮点常量向量	`(v128.const f32x4 1.0 2.0 3.0 4.0)`
整数算术运算
`i8x16.add(a, b)`	8 位整数加法（16 通道）	`(i8x16.add (local.get $a) (local.get $b))`
`i16x8.sub(a, b)`	16 位整数减法（8 通道）	`(i16x8.sub (local.get $a) (local.get $b))`
`i32x4.mul(a, b)`	32 位整数乘法（4 通道）	`(i32x4.mul (local.get $a) (local.get $b))`
`i64x2.add(a, b)`	64 位整数加法（2 通道）	`(i64x2.add (local.get $a) (local.get $b))`
`i8x16.add_saturate_s(a, b)`	8 位有符号饱和加法	`(i8x16.add_saturate_s (local.get $a) (local.get $b))`
`i16x8.sub_saturate_u(a, b)`	16 位无符号饱和减法	`(i16x8.sub_saturate_u (local.get $a) (local.get $b))`
整数比较运算
`i8x16.eq(a, b)`	8 位整数相等比较（返回掩码）	`(i8x16.eq (local.get $a) (local.get $b))`
`i32x4.lt_s(a, b)`	32 位有符号整数小于比较	`(i32x4.lt_s (local.get $a) (local.get $b))`
`i16x8.gt_u(a, b)`	16 位无符号整数大于比较	`(i16x8.gt_u (local.get $a) (local.get $b))`
浮点运算
`f32x4.add(a, b)`	32 位浮点加法（4 通道）	`(f32x4.add (local.get $a) (local.get $b))`
`f64x2.mul(a, b)`	64 位浮点乘法（2 通道）	`(f64x2.mul (local.get $a) (local.get $b))`
`f32x4.min(a, b)`	32 位浮点最小值（4 通道）	`(f32x4.min (local.get $a) (local.get $b))`
`f64x2.sqrt(a)`	64 位浮点平方根（2 通道）	`(f64x2.sqrt (local.get $a))`
位运算
`v128.and(a, b)`	按位与	`(v128.and (local.get $a) (local.get $b))`
`v128.or(a, b)`	按位或	`(v128.or (local.get $a) (local.get $b))`
`v128.xor(a, b)`	按位异或	`(v128.xor (local.get $a) (local.get $b))`
`v128.bitselect(a, b, mask)`	根据掩码选择位	`(v128.bitselect (local.get $a) (local.get $b) (local.get $mask))`
位移
`i32x4.shl(a, imm)`	32 位整数左移（立即数）	`(i32x4.shl (local.get $a) (i32.const 2))`
`i64x2.shr_u(a, imm)`	64 位无符号整数右移（立即数）	`(i64x2.shr_u (local.get $a) (i32.const 3))`
`i16x8.shl(a, imm)`	16 位整数左移（立即数）	`(i16x8.shl (local.get $a) (i32.const 4))`
通道操作
`i8x16.extract_lane_s(idx, a)`	提取 8 位有符号整数通道	`(i8x16.extract_lane_s 3 (local.get $a))`
`f64x2.replace_lane(idx, a, value)`	替换 64 位浮点通道	`(f64x2.replace_lane 1 (local.get $a) (f64.const 3.14))`
`i8x16.swizzle(a, s)`	根据索引向量重排通道	`(i8x16.swizzle (local.get $a) (local.get $indices))`
`i8x16.shuffle(mask, a, b)`	根据掩码混洗两个向量的通道	`(i8x16.shuffle 0 1 2 3 12 13 14 15 8 9 10 11 4 5 6 7 (local.get $a) (local.get $b))`
类型转换
`i32x4.trunc_sat_f32x4_s(a)`	32 位浮点转 32 位有符号整数（饱和截断）	`(i32x4.trunc_sat_f32x4_s (local.get $a))`
`f64x2.convert_i32x4_s(a)`	32 位有符号整数转 64 位浮点	`(f64x2.convert_i32x4_s (local.get $a))`
`i16x8.extend_low_i8x16_s(a)`	将低 8 个 8 位有符号整数扩展为 16 位	`(i16x8.extend_low_i8x16_s (local.get $a))`
其他
`v128.any_true(a)`	检查向量中是否有任意通道非零	`(v128.any_true (local.get $a))`
`i8x16.all_true(a)`	检查所有 8 位通道是否全为非零	`(i8x16.all_true (local.get $a))`
`f32x4.ceil(a)`	32 位浮点向上取整	`(f32x4.ceil (local.get $a))`
`f64x2.floor(a)`	64 位浮点向下取整	`(f64x2.floor (local.get $a))`

指令集使用 deepseek 协助汇总，没有严格校对，如有错误请指出。

使用 SIMD 指令

举个例子，如果想要对一张图片进行反色处理，如果不使用 SIMD 指令集， wat 实现如下：

(module
  (import "env" "log" (func $log (param i32)))
  ;; 导入内存
  (import "env" "memory" (memory 100))

  ;; 反色函数：原地转换 RGB 通道，跳过Alpha通道
  (func $invert (param $start i32) (param $length i32)
    (local $end i32)   ;; 结束地址
    (local $i i32)     ;; 当前字节索引

    ;; 计算结束地址 = start + length * 4
    local.get $start
    (i32.mul (local.get $length) (i32.const 4))
    i32.add
    local.set $end

    ;; 初始化循环变量 i = start
    local.get $start
    local.set $i

    (block $exit
      ;; 主循环（每次处理4个字节：R,G,B,A）
      (loop $loop

        ;; 检查是否到达结束地址
        local.get $i
        local.get $end
        i32.ge_u
        br_if $exit


        ;; 处理R通道（偏移0）
        local.get $i
        i32.const 255
        local.get $i
        i32.load8_u      ;; 加载原始R值
        i32.sub          ;; 计算255 - R
        i32.store8       ;; 存储反色后的R值

        ;; 处理G通道（偏移1）
        local.get $i
        i32.const 1
        i32.add
        i32.const 255
        local.get $i
        i32.const 1
        i32.add
        i32.load8_u      ;; 加载原始G值
        i32.sub          ;; 计算255 - G
        i32.store8       ;; 存储反色后的G值

        ;; 处理B通道（偏移2）
        local.get $i
        i32.const 2
        i32.add
        i32.const 255
        local.get $i
        i32.const 2
        i32.add
        i32.load8_u      ;; 加载原始B值
        i32.sub          ;; 计算255 - B
        i32.store8       ;; 存储反色后的B值

        ;; 跳过Alpha通道（偏移3），无需修改
        ;; 移动到下一个像素（i += 4）
        local.get $i
        i32.const 4
        i32.add
        local.set $i

        br $loop
      )
    )
  )

  ;; 导出函数
  (export "invert" (func $invert))
)

使用 SIMD 指令，每一步对 1 个像素点 1 个通道的操作会增强为对 4 个像素点4个通道的操作：

(module
  (import "env" "log" (func $log (param i32)))
  (import "env" "memory" (memory 100))

  (func $invert (param $start i32) (param $length i32)
    (local $end i32)        ;; 结束地址
    (local $i i32)          ;; 当前地址
    (local $chunk v128)     ;; 当前处理的16字节
    (local $mask v128)      ;; alpha 通道掩码
    (local $full255 v128)   ;; 全 255 掩码

    ;; end = start + length * 4
    local.get $start
    local.get $length
    i32.const 4
    i32.mul
    ;; 数据长度可能不是 4 的倍数，这里 +3 确保数据对齐
    i32.add
    i32.const 3
    i32.add
    local.set $end

    ;; i = start
    local.get $start
    local.set $i

    ;; 常量向量：全 255
    v128.const i8x16 255 255 255 255 255 255 255 255
                     255 255 255 255 255 255 255 255
    local.set $full255

    ;; 掩码：只保留 alpha 通道（第 3,7,11,15 个字节）
    v128.const i8x16 0 0 0 255 0 0 0 255
                     0 0 0 255 0 0 0 255
    local.set $mask

    (block $exit
      (loop $loop
        ;; if (i >= end) break
        local.get $i
        local.get $end
        i32.ge_u
        br_if $exit

        ;; load 16 bytes (4 pixels)
        local.get $i
        v128.load
        local.set $chunk

        ;; tmp = 255 - chunk
        local.get $full255
        local.get $chunk
        i8x16.sub
        local.set $chunk

        ;; 用 bitselect 保留 alpha 通道：
        local.get $i
        v128.load
        local.get $chunk
        local.get $mask
        v128.bitselect
        local.set $chunk

        ;; store back
        local.get $i
        local.get $chunk
        v128.store

        ;; i += 16
        local.get $i
        i32.const 16
        i32.add
        local.set $i

        br $loop
      )
    )
  )

  (export "invert" (func $invert))
)

注意看第 18 到第 20 行，WebAssembly SIMD 指令一次处理 16 字节数据，对应 rgba 4 个通道的图片 4 个像素，每张图片的像素点数量有可能不是 4 的倍数，所以这里加上一个大于 3 的数字即可确保所有数据都可以被处理。但是也要注意，WebAssembly 没有内存守护，这么处理会污染内存，导致其他数据错误，此例功能单一且没有其他数据，这样操作性能最好。

最后看性能对比：

上图最左边是素材原图，中间是没有使用 SIMD 指令的处理结果和用时，右边是使用 SIMD 指令的处理结果和用时。素材原图的尺寸为 928*927 ，除了中间的圆形图案以外，其余都是透明像素。可以看到，使用 SIMD 指令的方案性能要比不使用的快 6 倍左右。实际上，素材越大，效果越明显，不过笔者发现在处理更小的图片的场景中，也有显著的提升，比如经典的 lenna 图：

预告

下一篇将讨论，C 程序如何在 WebAssembly 中使用 SIMD 。

Using wabt

Yangholmes — Sat, 06 Sep 2025 09:22:15 +0000

wabt is a WebAssembly binary toolkit that provides compilation, analysis, debugging, and validation tools for wasm-related code. This article briefly introduces the usage of common commands.

Compiling wat Code

Implementing the Fibonacci sequence in wat:

;; fib.wat
(module
  (import "env" "log" (func $log (param i32)))

  ;; Allocate one page of memory
  (memory (export "memory") 1)

  ;; Global variable: heap pointer (points to next available memory address)
  (global $heap_ptr (mut i32) (i32.const 0))

  ;; Allocate memory block
  ;; params: size (i32) - bytes to allocate
  ;; return: starting address (i32)
  (func $allocate (param $size i32) (result i32)
    (local $start i32)
    (local.set $start (global.get $heap_ptr))
    (global.set $heap_ptr
      (i32.add
        (global.get $heap_ptr)
        (local.get $size)
      )
    )
    (local.get $start)
  )

  ;; Fibonacci sequence
  ;; params: n (i32) - array length
  ;; return: array starting address (i32)
  (func (export "fib") (param $n i32) (result i32)
    (local $i i32)
    (local $arr_ptr i32)
    (local $prev i32)
    (local $curr i32)
    (local $next i32)

    ;; Allocate memory: n * sizeof(i32) = n * 4
    (local.set $arr_ptr
      (call $allocate
        (i32.mul
          (local.get $n)
          (i32.const 4)
        )
      )
    )

    ;; Handle edge cases
    (if (i32.le_s (local.get $n) (i32.const 0))
      (then (return (local.get $arr_ptr)))  ;; Return empty array address
    )

    ;; Initialize first two elements
    (i32.store (local.get $arr_ptr) (i32.const 0))
    (if (i32.gt_s (local.get $n) (i32.const 1))
      (then
        (i32.store
          (i32.add (local.get $arr_ptr) (i32.const 4))
          (i32.const 1)
        )
      )
    )

    ;; Iteratively calculate subsequent elements
    (local.set $prev (i32.const 0))
    (local.set $curr (i32.const 1))
    (local.set $i (i32.const 2))
    (loop $loop
      ;; Calculate next Fibonacci number
      (local.set $next (i32.add (local.get $prev) (local.get $curr)))
      (local.set $prev (local.get $curr))
      (local.set $curr (local.get $next))

      ;; Store in memory
      (i32.store
        (i32.add
          (local.get $arr_ptr)
          (i32.mul (local.get $i) (i32.const 4))
        )
        (local.get $next)
      )

      ;; Loop control
      (local.set $i (i32.add (local.get $i) (i32.const 1)))
      (br_if $loop (i32.lt_s (local.get $i) (local.get $n)))
    )

    ;; Return array starting address
    (local.get $arr_ptr)  
  )
)

Compile the code using wabt:

wat2wasm ./fib.wat -o ./fib.wasm

Resulting wasm files:

├── fib.wasm
├── fib.wat
└── main.ts

main.ts provides the host environment for calling wasm code:

import fibUrl from './fib.wasm?url';

WebAssembly.instantiateStreaming(fetch(fibUrl), {
  env: {
    log: (value: string | number) => console.log(value)
  }
}).then(res => {
  // Destructure exports to get fib function and memory
  const { fib, memory } = res.instance.exports as unknown as {
    fib: (n: number) => number;
    memory: WebAssembly.Memory
  };
  // Fibonacci sequence length
  const n = 10;
  // Compute, storing result in memory, get result pointer
  const addr = fib(n);
  // Read result
  const buffer = new Uint32Array(memory.buffer, addr, n);
  const result = Array.from(buffer);
  console.log(result);
})

Using Vite as the build tool, which supports importing any resource type as a URL. Here we convert wasm to a resource URL and load it using WebAssembly.instantiateStreaming and fetch. Note that Vite also supports automatic wasm initialization using the ?init suffix (see Vite documentation for details).

We use the fib function to compute a Fibonacci sequence of length 10, with output:

Results match expectations.

Comparing wat code and wasm file sizes:

After compilation, the wasm file is an order of magnitude smaller than the source. This efficiency comes from both wasm's compact format and LEB128 compression.

Analyzing wasm

The wasm-objdump command is similar to the OS objdump, used for analyzing wasm file information. Practical use case: A developer receives a wasm module and wants to quickly identify exported functions, their parameter counts/types, and return value types/lengths. Using the previous fib.wasm as an example:

wasm-objdump ./fib.wasm -j Export -x

Output:

fib.wasm:       file format wasm 0x1

Section Details:

Export[2]:
 - memory[0] -> "memory"
 - func[2] <fib> -> "fib"

This shows fib.wasm has two exports: a memory and a fib function (type 2). Next, examine function signatures:

wasm-objdump ./fib.wasm -j Function -x

Output:

fib.wasm:       file format wasm 0x1

Section Details:

Function[2]:
 - func[1] sig=1
 - func[2] sig=1 <fib>

Function 2 uses type index 1 declared in the Type section. Export the Type section:

wasm-objdump ./fib.wasm -j Type -x

Type information:

fib.wasm:       file format wasm 0x1

Section Details:

Type[2]:
 - type[0] (i32) -> nil
 - type[1] (i32) -> i32

We've now obtained complete information about fib.wasm's exports:

Exported memory
Exported function fib with one i32 parameter and one i32 return value

wasm-objdump -x can be used alone to output all section information. For large files, it's better to output sections individually for easier analysis.

Formatting Code

The wat-desugar command formats existing wat code to conform to certain specifications. For example, the original fib.wat source didn't strictly follow the "push operands -> execute instruction" pattern, often writing operands after instructions. While valid, this doesn't follow stack machine conventions. wat-desugar helps standardize this code. Here's the formatted $allocate function:

(func $allocate (param $size i32) (result i32)
    (local $start i32)
    global.get $heap_ptr
    local.set $start
    global.get $heap_ptr
    local.get $size
    i32.add
    global.set $heap_ptr
    local.get $start
)

Compared to the original source, the formatted code is more compact and better follows stack-based calling conventions, though less readable. The most noticeable difference is the i32.add operation: the original placed operands after the instruction, while the standardized version pushes operands to the stack before calling the add instruction.

The name "desugar" contrasts with "Syntactic Sugar". Syntax like (i32.add (local.get 0) (local.get 1)) is syntactic sugar - operands aren't pushed to the stack before the instruction call (more like a register machine). Compilers accept this non-stack-machine syntax because it's more intuitive. "Desugar" is like the Cantonese phrase "走糖" (less sugar), removing the syntactic sugar to reveal the most fundamental code that strictly follows the push-operands-then-execute pattern.

Disassembly

wabt provides three disassembly commands:

wasm2wat: Disassembles wasm to wat code
wasm2c: Disassembles wasm to C source and header files
wasm-decompile: Disassembles wasm to readable C-style pseudocode

In practice, wasm-decompile combined with wasm2wat is most useful. Use wasm-decompile to analyze functionality implementation. If minor module modifications are needed, use wasm2wat to get a wat file, make changes, then recompile to wasm.

wabt 使用小记

Yangholmes — Thu, 04 Sep 2025 05:04:12 +0000

wabt 是 WebAssembly 二进制格式工具集，提供 wasm 相关的代码编译、分析、调试和验证等功能。这篇简单介绍一下常用命令的用法。

编译 wat 代码

用 wat 实现斐波那契数列：

;; fib.wat
(module
  (import "env" "log" (func $log (param i32)))

  ;; 申请一页内存
  (memory (export "memory") 1)

  ;; 全局变量：堆指针（指向下一个可用内存地址）
  (global $heap_ptr (mut i32) (i32.const 0))

  ;; 分配内存块
  ;; params：size (i32) - 需要分配的字节数
  ;; return：起始地址 (i32)
  (func $allocate (param $size i32) (result i32)
    (local $start i32)
    (local.set $start (global.get $heap_ptr))
    (global.set $heap_ptr
      (i32.add
        (global.get $heap_ptr)
        (local.get $size)
      )
    )
    (local.get $start)
  )

  ;; 斐波那契数列
  ;; params：n (i32) - 数组长度
  ;; return：数组起始地址 (i32)
  (func (export "fib") (param $n i32) (result i32)
    (local $i i32)
    (local $arr_ptr i32)
    (local $prev i32)
    (local $curr i32)
    (local $next i32)

    ;; 分配内存：n * sizeof(i32) = n * 4
    (local.set $arr_ptr
      (call $allocate
        (i32.mul
          (local.get $n)
          (i32.const 4)
        )
      )
    )

    ;; 边界情况处理
    (if (i32.le_s (local.get $n) (i32.const 0))
      (then (return (local.get $arr_ptr)))  ;; 返回空数组地址
    )

    ;; 初始化前两个元素
    (i32.store (local.get $arr_ptr) (i32.const 0))
    (if (i32.gt_s (local.get $n) (i32.const 1))
      (then
        (i32.store
          (i32.add (local.get $arr_ptr) (i32.const 4))
          (i32.const 1)
        )
      )
    )

    ;; 迭代计算后续元素
    (local.set $prev (i32.const 0))
    (local.set $curr (i32.const 1))
    (local.set $i (i32.const 2))
    (loop $loop
      ;; 计算下一个斐波那契数
      (local.set $next (i32.add (local.get $prev) (local.get $curr)))
      (local.set $prev (local.get $curr))
      (local.set $curr (local.get $next))

      ;; 存储到内存
      (i32.store
        (i32.add
          (local.get $arr_ptr)
          (i32.mul (local.get $i) (i32.const 4))
        )
        (local.get $next)
      )

      ;; 循环控制
      (local.set $i (i32.add (local.get $i) (i32.const 1)))
      (br_if $loop (i32.lt_s (local.get $i) (local.get $n)))
    )

    ;; 返回数组起始地址
    (local.get $arr_ptr)  
  )
)

使用 wabt 编译代码：

wat2wasm ./fib.wat -o ./fib.wasm

得到 wasm 文件：

├── fib.wasm
├── fib.wat
└── main.ts

main.ts 提供了宿主调用 wasm 代码：

import fibUrl from './fib.wasm?url';

WebAssembly.instantiateStreaming(fetch(fibUrl), {
  env: {
    log: (value: string | number) => console.log(value)
  }
}).then(res => {
  // 解构导出对象，获得 fib 函数 和 内存
  const { fib, memory } = res.instance.exports as unknown as {
    fib: (n: number) => number;
    memory: WebAssembly.Memory
  };
  // 斐波那契数列长度
  const n = 10;
  // 计算，结果保存在内存中，获得保存结果的指针
  const addr = fib(n);
  // 读取结果
  const buffer = new Uint32Array(memory.buffer, addr, n);
  const result = Array.from(buffer);
  console.log(result);
})

使用 vite 作为构建工具，vite 支持将任何类型资源作为 url 导入，这里将 wasm 转化成资源地址，使用 WebAssembly.instantiateStreaming 和 fetch 加载。实际上 vite 也支持使用 ?init 后缀加载并自动初始化 wasm 文件，详细可以查阅 vite 文档。

这里尝试使用 fib 函数去计算长度为 10 的斐波那契数列，输出结果为：

符合预期。

看一下 wat 代码和 wasm 文件的大小对比：

可以看出，经过编译后，wasm 文件比源码小了一个数量级。如此高效除了 wasm 格式紧凑以外， LEB128 压缩也贡献不少。

分析 wasm

wasm-objdump 命令跟操作系统 objdump 类似，用来分析 wasm 文件信息。有什么用？这里举一个例子：开发者拿到一个 wasm 模块，想要快速知道导出函数都有哪些，每个函数的入参数量和类型，返回值长度和类型，就可以使用 wasm-objdump 工具分析。以上一节 fib.wasm 文件为例：

 wasm-objdump ./fib.wasm -j Export -x

输出信息

fib.wasm:       file format wasm 0x1

Section Details:

Export[2]:
 - memory[0] -> "memory"
 - func[2] <fib> -> "fib"

说明 fib.wasm 有两个导出项，一个是内存，另一个是 fib 函数，函数类型是 2 ，接下来再导出函数签名

wasm-objdump ./fib.wasm -j Function -x

得到：

fib.wasm:       file format wasm 0x1

Section Details:

Function[2]:
 - func[1] sig=1
 - func[2] sig=1 <fib>

函数 2 的类型在 Type 段声明，且使用索引为 1 的类型，导出 Type 段：

wasm-objdump ./fib.wasm -j Type -x

Type 信息为：

fib.wasm:       file format wasm 0x1

Section Details:

Type[2]:
 - type[0] (i32) -> nil
 - type[1] (i32) -> i32

最终获取到了 fib.wasm 导出内容的全部信息：

导出内存
导出函数 fib ，fib 有一个 i32 类型的入参，有一个 i32 类型的返回值

wasm-objdump -x 参数可以单独直接使用，会输出 wasm 文件所有块信息，信息量小的文件可以直接全部输出，信息量大的文件建议分块输出，方便分析。

整理代码

wat-desugar 命令可以用来整理现有的 wat 代码，以符合某些规范。比如上文的 fib.wat 源码没有严格按照 操作数压栈 -> 执行指令 的流程编写，经常将操作数写在指令后面，尽管是合法的写法，但不符合栈式虚拟机的范式。使用 wat-desugar 可以帮助我们规范这份代码。这里展示 $allocate 函数整理后的代码：

(func $allocate (param $size i32) (result i32)
    (local $start i32)
    global.get $heap_ptr
    local.set $start
    global.get $heap_ptr
    local.get $size
    i32.add
    global.set $heap_ptr
    local.get $start
)

结合上文源码可以看出来整理后的代码紧凑，更加符合栈式调用的范式，但是更不易读了。最明显的区别就是加法运算 i32.add ，源码将操作数放在了指令的后面，而规范写法应该是先压栈再调用加法指令。

“desugar” 这个名称和 “Syntactic Sugar （语法糖）” 这个词语是相对的，形如 (i32.add (local.get 0) (local.get 1)) 这样的写法是一种语法糖，指令调用之前操作数并没有先压栈（有点像寄存器虚拟机），编译器接受这种不符合栈式虚拟机的语法，但这种写法仿佛更容易让人理解。“desugar” 类似广东人说的“走糖”，将语法糖代码的糖分去掉，使用语法最原汁原味的代码，老老实实先压栈再计算。

反汇编

wabt 工具有 3 个反汇编命令：

wasm2wat 将 wasm 反汇编成 wat 代码
wasm2c 将 wasm 反汇编成 C 源码和头文件
wasm-decompile 将 wasm 反汇编成容易阅读的 C 风格伪代码

笔者在开发过程中 wasm-decompile 配合 wasm2wat 使用比较多。 wasm-decompile 用来分析功能的实现，如果需要对模块小修小改，使用 wasm2wat 获得 wat 文件，修改后再用编译命令将 wat 编译成新的 wasm 即可。

WebAssembly 基础（二）

Yangholmes — Tue, 02 Sep 2025 08:16:57 +0000

wasm 二进制格式结构

和其他二进制格式一样，wasm 二进制格式也是以 魔术数+版本号 开头（ Magic Number + Version ），其他模块按照不同的类别聚合放在不同的段（ Segment ）中，严格按照顺序排列，分配 ID 。wasm 一共有 12 个段，魔术数和版本号没有分配 ID ，位于开头，其他段均有 ID ，范围是 1~11 ，ID 0 特殊，不需要按照顺序出现。二进制文件格式对人类阅读不友好，这里详细展开讨论，只介绍每个段的功能。

0. 自定义段 Custom Section

自定义段是可以用来存放任何数据，比如提供给编译器等工具使用，记录函数名等调试信息。这个段在模块中可有可无，wasm 不执行自定义段也不会出错。另外，虽然自定义段的 ID 是 0 ，但不必要出现在开头或者结尾，可以出现在任何一个非自定义段的前面或者后面，且可以存在多个自定义段。常见的内容有 sourceMap 链接、DWARF 调试信息。

1. 类型段 Type Section

列出模块中所有函数原型（或者说函数签名、函数类型），即函数的参数和返回值。类似 C 的头文件。

2. 导入段 Import Section

列出模块所有导入项，包括函数、内存、表、全局变量。

3. 函数段 Function Section

列出内部函数对应的签名索引。

4. 表段 Table Section

定义模块使用的表，如函数引用。 wasm v1.0 规定只有一张表，v2.0 表数量可以有多个。

5. 内存段 Memory Section

列出模块使用的线性内存，包括内存的初始页数、最大页数、内存数量。wasm v1.0 规定一个模块只能有一块内存，v2.0 内存数量可以有多个。

6. 全局段 Global Section

定义全局变量及其初始值。

7. 导出段 Export Section

声明模块对外暴露的对象。

8. 起始段 Start Section

指定起始函数，类似于 C 的 main 函数，在模块初始化时自动执行。

9. 元素段 Element Section

表的初始化数据。

10. 代码段

所有函数的二进制指令。函数段（ID 3）和代码段（ID 10）必须一一对应。

11. 数据段

初始化线性内存。

其中，类型段（1）、函数段（3）、代码段（10）是必需的，其他段可以省略，自定义段不参与代码执行。3 和 10 对应，4 和 9对应，5 和 11 对应。

因为 wasm 具有严格的段顺序，支持流式加载，所以 wasm 可以一边加载，一边解析，一边验证，一边编译，初始化效率非常高。

wasm 二进制格式采用小端方式（Little-Endian）编码，wasm 的魔术数为 \0asm ，占 4 个字节，版本号也占 4 个字节，\0asm 十六进制编码为 0x6D736100 ，版本为 1 十六进制编码为 0x00000001 。在 wasm 文件中编码为

00 61 73 6D 01 00 00 00

wasm 采用 LEB128 编码整数值，采用 IEEE 754 编码浮点数值。 LEB128 是一种变长码压缩，可以减少整型数的存储空间，压缩代码；IEEE 754 是常用的浮点数储存方法，这两个编码方式这里不展开。

wat 语法

wat 是 wasm 文本格式（ WebAssembly Text ），基于 S-Expression 的一种嵌套括号结构，是 wasm 等效的文本形式，失去了 wasm 严格的段顺序，取而代之的是更容易阅读的表达式顺序。wat 和 wasm 之间可以使用 wabt 工具转换。这里介绍一下 wat 核心语法结构。

S 表示 symbolic ，符号的。

1. 模块定义 Module

一个 wasm/wat 文件定义一个模块，以 (module ...) 代码包裹：

(module
  ;; 内部包含：函数、内存、表、全局变量等定义
)

wat 使用 ;; 注释

2. 函数 Functions

2.1 函数签名

(func $name (param $a i32) (param $b f64) (result f64) ...)

$name：函数名（可选，调试用）
param：参数类型（如 i32, f64）
result：返回值类型

wasm v1.0 规定函数只能有一个返回值，wasm v2.0 函数可以返回多个值，例如

(func $duplicate (param $x i32) (result i32 i32)
  local.get $x   ;; 第一个返回值
  local.get $x   ;; 第二个返回值
)

在 JavaScript 中 WebAssembly.Instance 只支持一个返回值，当有多个返回值时，会自动封装成数组。

console.log(instance.exports.duplicate(5));     // [5, 5]

2.2 局部变量

(func (param i32)
  (local.get 0)           ;; 获取第 0 个参数
  (local $var i32)        ;; 声明局部变量
  (local $a f64 $b i64)   ;; 声明多个同类型变量
)

2.3 函数体指令

指令按栈模型顺序执行

(func $add (param $a i32) (param $b i32) (result i32)
  local.get $a    ;; 将 $a 压栈
  local.get $b    ;; 将 $b 压栈
  i32.add         ;; 弹出栈顶两个值，相加后压回结果
)

3. 类型 Types

类型可以是 inline 的，也可以显式定义复用：

(type $AddSig (func (param i32 i32) (result i32)))
(func $add (type $AddSig) 
  local.get 0
  local.get 1
  i32.add
)

4. 内存 Memory

4.1 内存定义

wasm 只有四种数据类型 i32 i64 f32 f64 ，当需要处理其他的数据类型时，需要使用内存。内存可以在 JavaScript 中定义，也可以在 wasm 内部定义：

;; 内部定义
(memory <min> <max>?)

内存可以具名，方便导出：

(module
  ;; 定义内存：初始 5 页 (5 * 64KiB)，最大 10 页
  (memory $mem 5 10)

  ;; 导出内存，方便外部访问
  (export "memory" (memory $mem))
)

内存可以从宿主导入：

;; 导入外部定义
;; 从 JavaScript 导入一个内存对象，模块名 "js"，内存名 "mem"
(import "js" "mem" (memory 5 10))

JavaScript 定义：

const memory = new WebAssembly.Memory({
  initial: 5,  // 5 页
  maximum: 10  // 最大 10 页
});

const response = await WebAssembly.instantiateStreaming(..., {
  js: { mem: memory }
});

宿主导入的内存初始页数和最大页数要覆盖 wat 导入定义的初始页数和最大页数，也就是说，wat 导入声明初始页数 ≤ 宿主初始页数，宿主最大页数 ≥ wat 导入声明最大页数。否则模块初始化时，在验证阶段会报错。

4.2 读内存

;; 内存读取
[类型].load[位数][_符号]

符号后缀有两种， _u 表示无符号， _s 表示有符号。

常用的指令有：

i32.load i32.load8_s i32.load8_u i32.load16_s i32.load16_u
i64.load i64.load8_s i64.load8_u i64.load16_s i64.load16_u i64.load32_s i64.load32_u
f32.load
f64.load

加载指令看起来比较复杂，比如 i32.load8_s ，这条指令各部分的含义是：

i32：结果类型是 32 位整数
load：表示从内存中加载数据
8：表示加载的数据宽度是 8 位 (1 字节)
_s：表示是有符号扩展（sign-extend）

从内存中读取 8 位 (0..255) -> 这 8 位数字是有符号整型 (-128..127) -> 扩展成 32 位整数 (i32) -> 返回

例如：

(func (param $ptr i32) (result i32)
  local.get $ptr ;; 内存地址偏移量
  i32.load8_s    ;; 返回 -128..127 的无符号字节
)

读内存指令除了指定地址参数外，还可以指定对齐方式和地址偏移量，默认这两个参数可以省略。如果需要指定对齐方式和偏移，指令变成：

[类型].load[位数][_符号] align=N offset=M

这里 N 表示 2 的次幂，align=3 表示按 2³ = 8 字节对齐。

如果不指定对齐参数，那么将会使用自然对齐，即访问内存的数据长度。如 i32.load8_u 自然对齐为 8 位，一个字节，align=0 。

在很多 CPU 架构上，内存访问对齐可以提升性能（按数据类型的自然边界访问更快），指令带上对齐信息，能帮助编译器做优化。一般地，对齐参数和读取的位数量保持一致可以获得更好的性能，如 i32.load 自然对齐是 4 字节，即 align=2 ，i64.load 自然对齐是 8 字节，align=3 。如果指定了一个不合适的对齐方式参数，代码不会跑飞，编译器在编译的时候会去拼凑数据，使得字节数是对齐的，性能会变差。

内存地址偏移量是一个无符号 32 位整型数，使用这个参数相当于扩展了 wasm 的寻址范围。在不使用偏移量时内存的寻址范围是 2^32-1 大约为 4GB ；使用偏移量之后，寻址范围扩展到 2^32-1 + 2^32-1 = 2^33 - 2 大约是 8GB 。有些情况下最大内存不超过 4GB （取决于宿主），如果尝试越界访问，会触发越界异常 trap 。

4.3 写内存

;; 内存写入
[类型].store[位数]

常用的指令有：

i32.store8 i32.store16 i32.store（默认 32 位）
i64.store8 i64.store16 i64.store32 i64.store （默认 64 位）
f32.store
f64.store

例如：

;; 把字节 72 ('H') 写入位置 0
i32.const 0     ;; address
i32.const 72    ;; value
i32.store8      ;; 在 address 写一个字节

利用更宽的指令可以一次性写入更多数据，要注意 wasm 采用小端存储：

;; 写入字符 'h' 'e' 'l' 'l'
i32.const 0           ;; 内存地址
i32.const 0x6c6c6568  ;; memory bytes -> 68 65 6c 6c => 'h','e','l','l'
i32.store

写内存指令也可以提供对齐参数和偏移量，含义和读内存一致，这里就不赘述了。

4.4 字符串直接写入

wasm 只支持 4 中数值数据类型，如何将字符串直接写入内存？字符串写入需要使用 data 指令，以 UTF-8 字节写入内存：

;; 字符串写入默认内存
(data (i32.const <offset>) "bytes" ...)

;; 字符串写入具名内存
(data (memory $mem) (i32.const <offset>) "xxx\00")  ;; \00 表示终止符

举个例子，往内存中写入 “Hello World”：

(data (i32.const 0) "hello world\00")

4.5 其他内存控制指令

memory.size 返回当前内存页数（i32，单位 page）
memory.grow 内存增长，参数为需要增长的页数，执行成功返回增长前的页数（失败返回 -1）
memory.copy 参数为 dest src len ，把源地址+长度的数据复制到目标地址+长度内存中，支持重叠
memory.fill 参数为 dest value len ，把 len 个字节填充为 value

5. 表 Tables

表有两种类型，一种是函数引用 funcref ，另一种是宿主对象引用（外部引用） externref 。基本的语法为

(table $tbl <min> <max>? <reftype>)

min 定义了表的最小尺寸，max 定义表最大扩展尺寸。表的尺寸限定函数/引用的数量。表是 wasm 和宿主之间隐藏代码位置，间接调用/访问的方法。假如 wasm 要向 JavaScript 提供自增和自减两个函数，但不希望宿主直接获取函数的索引：

;; xxx.wat
(module
  ;; 定义一个函数类型：参数类型 i32，返回类型 i32
  (type $t (func (param i32) (result i32)))

  ;; 定义两个函数
  (func $inc (type $t) (param $x i32) (result i32)
    local.get $x
    i32.const 1
    i32.add
  )

  (func $dec (type $t) (param $x i32) (result i32)
    local.get $x
    i32.const 1
    i32.sub
  )

  ;; 定义一个表，初始大小 2，最大 5，用来存放函数引用
  (table $tbl 2 5 funcref)

  ;; 初始化表内容：索引 0 存 $inc，索引 1 存 $dec
  (elem (i32.const 0) $inc $dec)

  ;; 使用 call_indirect 调用表中的函数
  ;; 参数：表索引、函数参数
  (func (export "call_from_table") (param $idx i32) (param $x i32) (result i32)
    local.get $x      ;; push 参数
    local.get $idx    ;; push 函数索引
    call_indirect (type $t) (table $tbl)
  )
)

const { instance } = await WebAssembly.instantiateStreaming(fetch("xxx.wasm"));

console.log(instance.exports.call_from_table(0, 10)); // 11 (自增)
console.log(instance.exports.call_from_table(1, 10)); // 9  (自减)

其他指令：

table.get <tableidx> 从表里取出一个引用
table.set <tableidx> 向表中写入一个引用
table.size <tableidx> 取表当前大小
table.grow <tableidx> 扩展表容量
table.fill <tableidx> 批量填充某个引用
table.copy <dst> <src> 从一张表拷贝到另一张表

6. 全局变量 Globals

全局变量可以定位为常量或变量：

(global $counter (mut i32) (i32.const 0)) ;; 可变全局变量
(global $PI f64 (f64.const 3.14159))      ;; 常量

7. 导入和导出 Imports & Exports

7.1 导入

;; 导入函数
(import "env" "log" (func $log (param i32)))
;; 导入内存
(import "js" "mem" (memory 1))

7.2 导出

;; 导出函数
(export "add" (func $add))
;; 导出内存
(export "shared_mem" (memory $mem))

8. 控制流

wasm 的控制流指令有四类：块/循环、条件、跳转、控制。

8.1 块/循环

block 和 loop 。block 创建具名的代码块，可以声明返回值，块结束时会把栈顶值作为块的返回值，配合 br* 可以实现跳转。

(block $label (result <type>?) ... )

loop 是创建循环结构的入口，同样可以声明返回值，循环结束时会把栈顶值作为块的返回值，需要配合 br* 跳转到循环开头。如果循环块中没有 br* ，loop 并不会自动循环。

(loop $label (result <type>?) ... )

例如：

;; 等效于 for (let i = 0; i < 5; i++) {}
(local $i i32)
(loop $start
  (local.set $i (i32.add (local.get $i) 1))
  (br_if $start (i32.lt_s (local.get $i) (i32.const 5)))  ;; 循环5次
)

8.2 条件

if 用栈顶 i32 数值作为条件选择执行 then 或者 else，可以声明返回值，then 和 else 必须产生这个类型的返回。

(if (result <type>?)
  (then ...)
  (else ...)
  (end)
)

例如编写一个输出参数绝对值加一的函数：

(func (param $x i32) (result i32)
  local.get $x
  i32.const 0
  i32.lt_s        ;; x < 0 ?
  if (result i32)
    ;; then: x 是负数 -> return -x + 1
    local.get $x
    i32.const -1
    i32.mul       ;; 取反 x = x * -1
    i32.const 1
    i32.add
  else
    ;; else: x >= 0 -> x + 1
    local.get $x
    i32.const 1
    i32.add
  end
)

8.3 跳转

跳转指令有 3 个：无条件跳转 br ，条件跳转 br_if ，多路分支跳转 br_table 。

;; 无条件跳转
br <label>         
;; 消耗栈顶(i32)，若非零则跳转  
br_if <label>    
;; 栈顶(i32)作为索引，如果栈顶是 `[0, n]` 则跳转到对应的 `label` ，否则跳转到 `default`   
br_table <label_0> <label_1> ... <label_n> <default_label>

<label> 可以是块的名称，也可以使 i32 数字，使用数字时，表示跳出的层级，0 表示跳出当前层级，1 表示跳出父层级，以此类推。建议使用块名称。所谓跳转，并非跳转到定义块的首行，而是跳转到定义块的结尾。

举几个例子：

;; br
(block $outer
  (block $inner
    (br $outer)  ;; 直接跳出到 $outer
  )
  (unreachable)   ;; 此处往后，块内指令不会执行
)

;; br_if
(func (param $p i32) (result i32)
  (block $outer (result i32)
    (block $inner
      local.get $p
      i32.const 0
      i32.eq
      ;; 如果输入 p === 0 则跳到 $outer，带上 999 作为 $outer 的返回值
      i32.const 999
      br_if $outer
    )
    ;; 没有跳转则到这里，$outer 返回 123
    i32.const 123
  )
)

;; br_table
(func (param $i i32) (result i32)
  (block $end (result i32)
    (block $default
      (block $case2
        (block $case1
          (block $case0
            local.get $i
            ;; 参数顺序： <labels...> <default>
            ;; idx === 0 -> branch to $case0
            br_table $case0 $case1 $case2 $default
          ) ;; end $case0
          ;; 当分支到 $case0 时会执行下面这句
          i32.const 10
          br $end
        ) ;; end $case1
        ;; 当分支到 $case1 时会执行下面这句
        i32.const 20
        br $end
      ) ;; end $case2
      ;; 当分支到 $case2 时会执行下面这句
      i32.const 30
      br $end
    ) ;; end $default
    ;; 当 br_table 命中 default（index 超范围）时，会跳到 $default 的结束处，
    ;; 然后继续执行这里的代码 —— 返回默认值 99
    i32.const 99
  ) ;; end $end
)

如果块定义了返回值，记得在跳转之前先把返回值压栈。要注意返回值和判断值的压栈顺序是，先压返回值，再压判断条件，不压返回值或压栈顺序不对，类型检查会失败。

8.4 函数控制

函数控制指令有两类，一类是调用函数 call 和 call_indirect ，另一类是终止函数 return 。

call 是直接调用， call_indirect 是使用表索引间接调用。

call $funcname
call_indirect (type $t) (table $tbl?)

直接调用很简单，这里不举例了， call_indirect 比较复杂，在表这一章节中有示例，可以倒回去阅读代码，这里解释参数：

type $t 表示当前调用的函数签名
table $tbl? 当前调用的表索引，可以不指定，默认使用表0

调用函数在表中的索引和函数参数从栈获取，栈顶是索引，然后是参数。所以压栈的顺序是先压参数后压索引。

return 是直接跳出函数，并返回值。返回值从栈顶取，所以在执行之前先压栈。

8.5 其他

还有一些不太好分类的流控制指令：

unreachable 立即触发 trap ，即运行时异常。用于标记不应触及的路径或产生错误
nop 空操作，不做任何事，对行为无影响，占用一个机器指令执行周期

9. 数据段初始化内存

详见字符串直接写入。

10. 表初始化

详见表。

Getting Started with the Emscripten File System

Yangholmes — Wed, 27 Aug 2025 04:33:35 +0000

Let's step beyond the scope of GDAL and explore the features of emscripten.

File System

In computing, a File System is a method for managing and accessing data in the form of files. Data is stored on a variety of hardware devices, each with its own way of accessing data. The file system abstracts the complexities of data management and access into a unified interface, allowing users to manage and access stored data without understanding the underlying physical device parameters. Different operating systems have developed various file systems over time—for example, Linux supports ext, ext2, etc.; Windows supports NTFS, FAT32, etc.; and macOS supports HFS+, APFS, etc. These are not entirely compatible with each other.

To enable software to run across different UNIX-like operating systems, the IEEE developed the POSIX standard. Linux largely adheres to the POSIX specification, including its file system conventions. Linux implements abstraction through the VFS (Virtual File System) layer, a software layer in the kernel that provides a common interface for all types of file systems. Applications and system calls interact only with the VFS, which routes operations to specific file system drivers (e.g., ext4, NTFS).

Why discuss Linux and POSIX? Two main reasons:

Most algorithm libraries are compiled in operating systems that support POSIX-compliant file systems.

Emscripten’s file system design is inspired by Linux’s POSIX compatibility.

How Applications Access the File System

Operating systems provide library functions for file access to applications. In C/C++, this library is libc/libc++. These library functions further encapsulate the details of file system operations, turning file operations into operations on file handles. This approach offers several advantages:

Reduces kernel system calls.
Facilitates compatibility across different operating systems.
Simplifies operations.

To read a file in a C program, the process is: Open File → Read Data → Close File.

include <stdio.h>
include <stdlib.h>
int main(void) {

const char *path = "input.txt";

FILE *fp = fopen(path, "r");          // Open text file (read-only)

if (!fp) {
  perror("fopen failed");
  return 1;
}

char buffer[1024];                    // Buffer to store each line
while (fgets(buffer, sizeof(buffer), fp)) {
  // Data is now in buffer; use as needed
  // e.g., process the string, parse content, etc.
}

if (ferror(fp)) {                     // Check for read errors
  perror("read error");
  fclose(fp);
  return 1;
}

  fclose(fp);                          // Close the file
  return 0;
}

libc (C Standard Library) includes 30 header files to date. <stdio.h> contains core input/output functions, <stdlib.h> includes functions for number conversion, memory allocation, process control, etc. Other commonly used headers include <math.h> for math functions and <assert.h> for assertions.

How WebAssembly Reads and Writes Files

In JavaScript, files are typically stored as File objects, which inherit from Blob and are essentially large chunks of binary data. If designing an algorithm from scratch, one might write files into memory and pass an ArrayBuffer as a pointer when calling functions. However, mature libraries often rely on file system operations—using file paths to locate files and file handles to pass them—making it difficult to switch to pointer-based approaches.

To address this, Emscripten provides a set of interfaces compatible with standard file operations. Inspired by POSIX, these interfaces closely resemble Linux’s file operations. For applications, the file system is transparent; they only know how to read and write files via libc interfaces, unaware of the underlying data storage mechanisms. During compilation, Emscripten performs a "bait-and-switch," replacing libc interfaces with syscalls and substituting the operating system’s VFS calls with Emscripten VFS calls, enabling WebAssembly file operations.

Emscripten File System

With the file operation interfaces in place, how is the data stored? Emscripten offers a flexible virtual file system architecture:

MEMFS

The Memory File System is Emscripten’s default file system, automatically mounted at the root directory /. Data is stored in memory and is lost when the page is refreshed.

NODEFS / NODERAWFS

These file systems can only be used in a Node.js environment.

NODEFS proxies the host’s file system into Emscripten’s virtual file system using Node.js’s synchronous file APIs, indirect read/write access to the local disk.

NODERAWFS bypasses Emscripten’s proxying and directly uses Node.js’s file module. The key difference is that NODEFS requires calling FS.mount() to mount the virtual file system and access files via virtual paths, while NODERAWFS uses absolute physical paths directly without mounting.

NODERAWFS is faster than NODEFS, but NODEFS uses file caching to reduce system calls. Use NODERAWFS for reading/writing large files from disk, and NODEFS for handling small, fragmented files.

IDBFS

IDBFS can only be used in browsers, including Web Workers.

IDBFS stores data in an IndexedDB instance. IndexedDB provides an asynchronous interface, while POSIX standards are synchronous—the two are incompatible. When using IDBFS, Emscripten first stores data in MEMFS and tracks file changes. The user must call FS.syncfs() to flush changes to IndexedDB. If the user forgets to call FS.syncfs() before closing or refreshing the page, changes in MEMFS will be lost. This can be mitigated by listening to pagehide or beforeunload events to force a sync.

When mounting IDBFS, the autoPersist: true parameter can be set to automatically save changes after each file modification. However, frequent file changes may impact performance.

WORKERFS

WORKERFS can only be used within Workers.

This file system provides read-only access to File and Blob objects inside a Worker without copying the entire file data into memory, making it suitable for handling large files.

PROXYFS

PROXYFS enables file sharing between multiple WebAssembly modules.

// Module 2 can use the path "/fs1" to access and modify Module 1's filesystem
module2.FS.mkdir("/fs1");
module2.FS.mount(module2.PROXYFS, {
  root: "/",
  fs: module1.FS
}, "/fs1");

Virtual File System Analysis

The core data structure of Emscripten’s file system is FSNode, which mimics the inode structure in Linux file systems. The basic structure is:

class {
  node_ops = {}; // Node operations (e.g., lookup, create)
  stream_ops = {}; // Stream operations (e.g., read, write, seek)
  mounted = null; // Mount information of the node

  constructor(parent, name, mode, rdev) {
    if (!parent) {
      parent = this; // Root node sets parent to itself
    }

    this.parent = parent; // Parent node (directory node)
    this.name = name;     // Node name (file or directory name)
    this.mode = mode;     // File type and permissions
    this.rdev = rdev;     // Major/minor device numbers (0 for non-device files)

    this.id = FS.nextInode++; // Globally unique node ID
    this.contents = null;     // File content (ArrayBuffer) or list of directory entries
    this.size = 0;            // File size in bytes

    this.mount = parent.mount; // File system mounted at this node

    this.atime = this.mtime = this.ctime = Date.now(); // Access, modification, and status change times
  }
}

During file system initialization, FS.mount(MEMFS, {}, '/') is called to mount the memory file system at the root directory. Other file systems can be mounted as needed within MEMFS, e.g.,


FS.mount(WORKERFS, {
  files: files // Array of File objects or FileList
}, '/worker'); // Mount WORKERFS at /worker

Other file operations, such as mkdir, rmdir, chmod, and link, are implemented in the FS object and can be called directly. The file system is hierarchical; unless it is a mount point, child nodes inherit the file system type from their parent:

mkdir() -> mknod() -> lookupPath() -> new FSNode()

Application calls to open, read, write, and close are ultimately directed to FS.open, FS.read, FS.write, and FS.close.

The mode field records the file type and permissions using the POSIX standard, represented as a 32-bit integer. The first 8 bits indicate the file type, and the remaining 24 bits represent permissions.

Hardware Devices

Everything is a file. Like other Unix-like operating systems, Emscripten’s virtual file system can register hardware devices. For example, to simulate a serial communication device in the browser:

// Generate a device number
const dev = FS.makedev(1, 8);

// Register device operations
FS.registerDevice(dev, {
    read(stream, buffer, offset, length) {
        // TODO ...
    },
    write(stream, buffer, offset, length) {
        // TODO ...
    },
    ioctl() {
        // TODO Simulate getting baud rate
    }

});

// Create a device node
FS.mkdir('/dev/ttyUSB0');
FS.mkdev('/dev/ttyUSB0', dev);

Now, the serial port /dev/ttyUSB0 can be read from and written to in C.

Future Development

Currently, Emscripten’s virtual file system is implemented in JavaScript, which has a significant drawback: it does not support multithreading. Emscripten is developing a new file system, WASMFS, though it is not yet complete. In the future, WASMFS will support multithreading and is expected to deliver significant performance improvements.

EMSCRIPTEN File System 入门

Yangholmes — Tue, 26 Aug 2025 06:07:13 +0000

这篇我们跳出 GDAL 的范围，讨论一下 emscripten 的特性。

文件系统

在计算机中，文件系统 File System 一种以文件方式管理和访问数据的方式。数据存储在形形色色不同的硬件设备中，每种不同的设备访问数据的方式都不一样，文件系统将这些晦涩难懂的数据管理和访问抽象成统一的接口，用户就可以在不了解物理设备参数的情况下，通过一个个简单的文件管理和访问存储在上面的数据。不同的操作系统各自在不同时期发展出不同的文件系统，比如 Linux 支持 ext 、ext2 等，Windows 支持 NTFS 、FAT32 等，Mac OS 支持 HFS+ 、APFS 等，它们之间并不完全兼容。

为了能在不同的类 UNIX 操作系统之间运行软件， IEEE 制订了 POSIX 标准，Linux 基本上遵循了 POSIX 规范，包括文件系统。Linux 通过 VFS（Virtual File System）层实现了抽象，VFS 是内核中的一个软件层，它为所有不同类型的文件系统提供了一个通用的接口。应用程序和系统调用只与 VFS 交互，由 VFS 将操作路由到具体的文件系统驱动（如 ext4, ntfs）。

为什么要介绍 Linux 和 POSIX ？原因有 2 ：

绝大多数算法库都在兼容 POSIX 的文件系统的操作系统中编译

emscripten 的文件系统受到了 Linux 兼容 POSIX 的启发

应用程序对文件系统的访问

操作系统为应用程序提供文件访问的库函数，在 C/C++ 中，这个库是 libc/libc++ 。库函数进一步封装了文件系统的操作细节，操作文件变成了操作文件句柄，这样做的好处有：

减少系统内核调用
方便兼容不同的操作系统
简化操作

假设要在 C 程序中读取一个文件，流程是 打开文件 -> 读取数据 -> 关闭文件 ：

#include <stdio.h>
#include <stdlib.h>

int main(void) {
    const char *path = "input.txt";
    FILE *fp = fopen(path, "r");          // 打开文本文件（只读）
    if (!fp) {
        perror("fopen failed");
        return 1;
    }

    char buffer[1024];                    // 用于存储每一行数据
    while (fgets(buffer, sizeof(buffer), fp)) {
        // 此处数据已经存放在 buffer 中，可在需要时使用
        // 例如：处理字符串、解析内容等
    }

    if (ferror(fp)) {                     // 检查读取过程中是否出错
        perror("read error");
        fclose(fp);
        return 1;
    }

    fclose(fp);                           // 关闭文件
    return 0;
}

libc 是 C standard library ，即 C 标准库。截至目前，它包含了 30 个头文件，其中 <stdio.h> 包含核心的输入输出函数，<stdlib.h> 包含数值转换、内存分配、过程控制等函数。常用的还有数学计算函数 <math.h> ，断言 <assert.h> 等。

wasm 如何读写文件

在 JavaScript 中，一般使用 File 对象存储文件，File 继承自 Blob ，本质上大块的二进制数据。如果我们自己设计算法，一般会将文件写入 Memory 中，在调用函数的时候把 ArrayBuffer 作为指针传递。成熟的库文件读写基于文件系统开发，使用文件路径寻找文件，使用文件句柄传递文件，很难改成指针。

为此 emscripten 开发了一套接口用于兼容标准文件读写。由于是受 POSIX 启发，所以这套接口和 Linux 的读写接口非常相似。对于应用程序来说，文件系统是透明的，它只知道通过 libc 接口就可以读写文件，不知道数据在硬件设备上具体的存储机制，emscripten 在编译时使出一技偷梁换柱，把 libc 接口替换成 syscalls ，把原本操作系统的 VFS 调用替换成 emscripten VFS 调用，实现 wasm 文件读写。

emscripten 文件系统

文件读写接口有了，文件给如何存储呢？ emscripten 提供了一套灵活的虚拟文件系统架构：

MEMFS

内存文件系统是 emscripten 默认的文件系统，初始化时自动挂载在根目录 / ，数据保存在内存中，页面刷新会丢失数据。

NODEFS / NODERAWFS

这两种文件系统只能在 Node.js 环境中使用

NODEFS 文件系统将宿主的文件系统代理到 emscripten 虚拟文件系统中，使用 Node.js 同步文件 api ，可以间接读写本地磁盘的数据。

NODERAWFS 文件系统不需要通过 emscripten 代理，直接调用 Node.js 文件模块。最显著的区别是，NODEFS 需要执行 FS.mount() 挂载虚拟文件系统，通过虚拟路径读写文件；NODERAWFS 不需要挂载，直接使用绝对物理路径读写。

NODERAWFS 比 NODEFS 快，NODEFS 有文件缓存可以减少系统调用。当需要从磁盘读写大文件时，选 NODERAWFS ；当处理零碎小文件时，选 NODEFS 。

IDBFS

IDBFS 只能在浏览器中使用，包括 WebWorker

IDBFS 将数据存储在 IndexedDB 实例中。IndexedDB 提供异步接口，POSIX 标准是同步接口，两者无法兼容。使用 IDBFS 时，emscripten 先将数据存储在 MEMFS 中，并记录文件是否有修改，最后需要用户调用 FS.syncfs() 函数一次性把变更写入 IndexedDB 中。如果用户忘记执行 FS.syncfs() 便关闭页面或刷新页面，MEMFS 记录的文件将会丢失，可以通过监听 pagehide 或 beforeunload 事件强制刷盘。

在挂载 IDBFS 的时候可以设置 autoPersist: true 参数，这样每次有文件发生变化的时候都会保存。如果改动文件比较频繁，可能会造成性能浪费。

WORKERFS

WORKERFS 仅能在 Worker 中使用

该文件系统提供对 Worker 内部的 File 和 Blob 对象的只读访问，而无需将整个文件数据复制到内存中，可用于处理大文件。

PROXYFS

PROXYFS 用于多个 wasm 模块之间文件共享。

// Module 2 can use the path "/fs1" to access and modify Module 1's filesystem
module2.FS.mkdir("/fs1");
module2.FS.mount(module2.PROXYFS, {
    root: "/",
    fs: module1.FS
}, "/fs1");

虚拟文件系统解析

emscripten 文件系统的核心数据是 FSNode ，模拟了 Linux 文件系统中的 inode 数据结构。基本数据结构为：

class {
  node_ops = {};   // 节点操作（如 lookup , create 等）
  stream_ops = {}; // 流操作（如 read , write , seek 等）
  mounted = null;  // 节点的挂载信息

  constructor(parent, name, mode, rde) {
    if (!parent) {
      parent = this;  // root node sets parent to itself
    }

    this.parent = parent; // 父节点（目录节点）
    this.name = name;     // 节点名称（文件名或目录名）
    this.mode = mode;     // 文件类型和权限
    this.rdev = rdev;     // 设备文件的主/次设备号（非设备文件为 0）

    this.id = FS.nextInode++; // 全局唯一的 node 编号
    this.contents = null;     // 文件内容（ ArrayBuffer ）或目录项列表
    this.size = 0;            // 文件大小（字节数）

    this.mount = parent.mount; // 指向挂载到此节点的文件系统

    this.atime = this.mtime = this.ctime = Date.now(); // atime（访问时间）、 mtime（修改时间）和 ctime（状态改变时间）
  }
}

初始化文件系统时，执行 FS.mount(MEMFS, {}, '/') ，将内存文件系统挂载到根目录下，其他文件系统可以按需挂载到内存文件系统中，如

FS.mount(WORKERFS, {
  files: files // Array of File objects or FileList
}, '/worker'); // 挂载 WORKERFS 到 /worker 目录

其他文件操作，如 mkdir rmdir chmod link 等函数均在 FS 对象中实现，直接调用即可。文件系统具有继承性，除非是挂载点，子节点的文件系统类型继承自父节点:

mkdir() -> mknod() -> lookupPath() -> new FSNode()

应用程序调用 open read write close 最终会被指向 FS.open FS.read FS.write FS.close 。

mode 记录文件类型和权限，使用 POSIX 规范，使用 32 位证书表示，前 8 位表示文件类型，后 24 位表示权限。

硬件设备

万物皆文件，和其他类 Unix 操作系统一样，emscripten 虚拟文件系统可以注册硬件设备。举一个简单的例子，假设我们想在浏览器中模拟串行通信设备：

// 生成设备号
const dev = FS.makedev(1, 8);

// 注册设备操作
FS.registerDevice(dev, {
  read(stream, buffer, offset, length) {
    // TODO ...
  },
  write(stream, buffer, offset, length) {
    // TODO ...
  },
  ioctl() {
    // TODO 模拟获取波特率
  }
});

// 创建设备节点
FS.mkdir('/dev/ttyUSB0');
FS.mkdev('/dev/ttyUSB0', dev);

接下来便可以在 C 中对 /dev/ttyUSB0 串行口进行读写了。

发展

目前 emscripten 虚拟文件系统均基于 JavaScript 开发，有一个显著的缺点就是无法支持多线程。emscripten 正在开发新的文件系统 WASMFS ，目前还未完成，未来 WASMFS 会支持多线程，性能会有比较大的提高。

WebAssembly 基础（一）

Yangholmes — Thu, 21 Aug 2025 03:06:01 +0000

高级计算机语言的两种运行方式

预先编译 Ahead-of-Time Compilation ，简称 AOT
即时编译 Just-in-Time Compilation ，简称 JIT

像 C/C++ 这类属于预先编译的计算机语言，而 JavaScript 这种属于即时编译语言。

现代编译器结构

编译器的最终目的是将高级计算机语言编译成机器语言，由于用户使用的 CPU 五花八门，相同的高级语言代码编译出来的可执行文件都有可能是不同的。为了提高效率，编译器会按照编译流程模块化设计。一般由 前端(Front End) 、中端(Middle End) 和 后端(Back End) 组成，每个节点都会产生中间表示(IR)传递给下一级。前端和中端的处理与硬件无关，最终在后端生成符合硬件参数的汇编代码。这种设计的好处在于，同一个编译器在不同的平台只需要开发不同的后端即可：

举个例子，C 的编译过程：

WebAssembly 的编译流转过程

WASM 是编译器的目标代码，但从浏览器的角度来看，WASM 更像是中端产出的 IR 。最终要被 AOT/JIT 编译器编译成平台相关的机器码。

格式

二进制格式，文件后缀是 .wasm
文本格式，文件后缀是 .wat
内存格式

二进制格式是 wasm 模块的主要格式，文本格式是为了方便开发者调试和理解 wasm 。但其实 wat 的阅读性也很差，如同读汇编。

wasm 模块必须安全可靠，所以在进入实例化之前，浏览器会先解码 wasm 为内存格式(in-memory) ，使用内存格式进行验证。

wasm 结构

流式(Streamable)加载 + 严格的段顺序，保证 wasm 可以一遍(One-Pass)完成代码的加载、解析、验证和编译。

How to Use GDAL in Web Applications (Part 3)

Yangholmes — Wed, 20 Aug 2025 07:10:57 +0000

This article focuses on optimization.

The Necessity of Optimization

The previous article introduced a complete compilation script that successfully builds the WebAssembly version of GDAL.

However, the compilation results are not suitable for production environments because:

Excessive file sizes: Core wasm file (27MB), glue code (272KB), data file (11MB)
Redundant glue code: Contains Node.js and bash environment code, impossible to tree-shake
Debug info in production: Debug information is unnecessary in production environments

File size is the most critical issue—total artifacts exceed 38MB, which is unacceptable for any web application.

Additionally, the Makefile contains misconfigurations. Since emsdk silently ignores unsupported compilation options during build, these errors don't halt compilation. This article will also interpret the original author's intent and fix incorrect compilation parameters.

Disclaimer

Through compilation optimization, GDAL 3.x WebAssembly artifacts can be reduced but likely not enough. These techniques work well for GDAL 2.x and OpenCV 4.x. Deeper reasons relate to GDAL's source code and build mechanisms—beyond this series' scope.

TODO: Add OpenCV optimization comparison

Optimization Approaches

For web applications, smaller resources are better. Classical frontend workflows use modern build tools and modular design to shrink JavaScript via lazy loading and tree-shaking. Non-JS resources are transformed by "loaders" into JS modules for optimization. However, these methods don't work for WebAssembly:

Loader limitations: Wasm files can be compressed but can't be used client-side without extra code.
No tree-shaking: Wasm is binary code; dead code elimination can't be done like with JS ASTs.

Could a *.wasm loader exist? Tools like vite support loading Wasm via ?init, but this doesn't suit glue code integration.

Thus, we optimize during the wasm compilation phase.

Code Separation

WASM

Options:

0: Output combined wasm.js (wasm embedded in JS)
1: Separate wasm and JS output
2: Output both formats

wasm.js serves legacy browsers. -sWASM=2 outputs both, but if target browsers support wasm, wasm.js is unnecessary. wasm.js encodes wasm as base64, increasing file size.

Demand-Driven Compilation

"Compile only what you use"

1. Library Functions

Projects typically use only a small subset of a library. Dead code elimination is controlled by:

EXPORTED_FUNCTIONS # List of exported functions

EXPORT_ALL # Export all functions

Note: Exported functions require a _ prefix. For example:

-sEXPORTED_FUNCTIONS="['_add']"

2. Emscripten Runtime Functions

EXPORTED_RUNTIME_METHODS

Default is empty. Export only necessary methods. For virtual filesystems:

-sEXPORTED_RUNTIME_METHODS="['FS']"

The original gdal3.js exports nearly all GDAL functions, a key reason for large artifacts.

Debug Information

emcc parameters resemble gcc's. Disable debug info in production using:

-gsource-map
-source-map-base
-O<level>
-g<level>

1. `-gsource-map` and `-source-map-base`

Control sourcemap generation. If enabled, debuggers load .map files from <base-url>/<wasm-file-name>.map, with <base-url> set by -source-map-base (default: same as wasm path).

2. `-O<level>`

Optimization levels:

-O0: No optimization, full debug info
-O1: Basic optimizations, remove runtime asserts
-O2: Dead code elimination (beyond -O1)
-O3: Aggressive size reduction (beyond -O2)
-Og: Similar to -O1, more debug info
-Os: Similar to -O3, smaller output
-Oz: Smaller than -Os

Default -O0 retains full debug info.

Higher optimization levels increase compilation time.

3. `-g<level>`

Debug levels:

-g0: No debug info
-g1: Preserve whitespace in JS
-g2: Preserve function names
-g3: Full debug info (DWARF + LLVM metadata)

Omitting the number (e.g., -g) defaults to -g3.

Environment Configuration

By default, emscripten generates environment-detection code for multiple targets. For fixed environments, this is redundant. Use:

ENVIRONMENT

Valid values:

node: Node.js
web: Web browsers
webview: Same as web (embedded webviews)
worker: Web Worker
shell: Command line

For web apps, compile only -sENVIRONMENT=worker. Also configure:

EXPORT_ES6

Set to 1 to output ES Module-compliant glue code. Default output includes environment-sniffing CJS/IIFE, unusable with import. Compare:

// -sEXPORT_ES6=1

;return moduleRtn}export default CModule;


// -sEXPORT_ES6=0

;return moduleRtn}})();if(typeof exports==="object"&&typeof module==="object"){module.exports=CModule;module.exports.default=CModule}else if(typeof define==="function"&&define["amd"])define([],()=>CModule);

Filesystem

Libraries like GDAL rely on OS filesystems. Emscripten emulates this in JS. Disable if unused:

FILESYSTEM

Automatic if code references stdio.h/fprintf. For pure computation, disable manually.

Access via Module.FS.

Other Options

1. Polyfill

POLYFILL

Default true. Disable if polyfills are handled elsewhere.

2. Use JS Math Library

JS_MATH

Set true to use browser's Math, avoiding libc compilation. May reduce precision. Recommended for precision-insensitive tasks.

3. Minimal Runtime

MINIMAL_RUNTIME

Minimal output (no POSIX, no Module, no built-in XHR). May break functionality—not recommended.

Practical Optimization

Fixing gdal3.js Build Script Errors

1. Invalid Debug Level

Line 4 incorrectly uses -g4 (unsupported).

Fix for type=debug:

GDAL_EMCC_FLAGS += -O0 -g3

2. Sourcemap Misconfiguration

Same line: --source-map-base without -gsource-map. Fix:

GDAL_EMCC_FLAGS += -gsource-map=1 --source-map-base $(BASE_URL)

Optimizing gdal3.js Build Script

1. Disable Debug in Production

Line 6:

GDAL_EMCC_FLAGS += -Oz -g0

2. Specify Environment

GDAL_EMCC_FLAGS += -s ENVIRONMENT=worker -s EXPORT_ES6=1

3. Reduce Exported Functions

For the use case in Part 2 (only GDALOpen, GDALInfo, GDALClose):

GDAL_EMCC_FLAGS += -s EXPORTED_FUNCTIONS="[\
'_malloc',\
'_free',\
'_CSLCount',\
'_GDALOpen',\
'_GDALClose',\
'_GDALInfo'\
]"

Minimal runtime methods:

GDAL_EMCC_FLAGS += -s EXPORTED_RUNTIME_METHODS="[\
'ccall',\
'cwrap',\
'FS'\
]"

Results

Wasm file: Reduced by 6,177,075 bytes (22.44%)
JS file: Reduced by 18,299 bytes (10.21%)

Conclusion

Future articles will cover:

Emscripten's virtual filesystem
Purpose and optimization of *.data files

如何在 web 应用中使用 GDAL （三）

Yangholmes — Mon, 18 Aug 2025 11:32:34 +0000

这篇研究优化。

优化的必要性

上上篇介绍了一个完整的编译脚本，运行这个脚本可以顺利编译出 GDAL WebAssembly 版本的产物。

但是这个编译结果并不适合在生产环境中使用，原因有：

文件太大，核心 wasm 文件 27MB ，胶水代码 272KB ，data 文件 11 MB
胶水代码大量冗余，包含 Node 环境、bash 环境的代码，且无法进行 tree shaking
生产环境无需输出调试信息

其中文件过大是最致命的，构建产物全部加起来超过 38MB ，任何 web 应用都无法接受这么一个硕大文件依赖的模块。

另外，这个 Makefile 包含许多错误配置，由于 emsdk 在编译时会抛弃不支持的编译配置，这些错误并没有中断编译。本篇还将尝试解读 gdal3.js 作者的意图，修正错误的编译参数。

先叠甲

通过编译过程优化，GDAL 3.x 版本的 WebAssembly 编译产物可以缩小，但很难做到足够小。本篇介绍的操作对于编译 GDAL 2.x 和 OpenCV 4.x 非常有效。个中原因，需要了解 GDAL 的源码和编译机制才能分晓，已超出本系列范围，先按下不表。

TODO: 添加 OpenCV 的优化对比

如何优化

对于 web 应用来说，资源越小越好。经典的 web 开发流程中，开发者使用现代化的前端构建工具和模块化设计，通过注入懒加载、Tree-Shaking 等方法把原本可能比较大的 JavaScript 文件缩小成比较小的文件，并且可以做到按需要加载；JavaScript 以外的文件，使用各种“加载器”转换成 JavaScript 代码的样子，也可以实现构建和优化。但这些手段在 WebAssembly 面前都不起作用了：

加载器的原理是将非 *.js 文件转换成 JavaScript 模块，例如将 *.png 文件转换为 base64 字符串或 url 字符串并导出为模块；转换的过程中可以缩小文件，依赖于这种文件的压缩算法，压缩后的文件必须保证在不增加代码的前提下能够在客户端中使用； *.wasm 文件可以压缩，但是目前还无法做到客户端中不增加代码就能使用
JavaScript Tree-Shaking 是基于字符串代码抽象语法树去除死代码，*.wasm 是已经编译好的可执行文件，是二进制代码不是字符串，无法像 JavaScript 一样瘦身

能不能做一个 *.wasm 文件的 loader 呢？有的，其实是有的，比如说 vite 就可以使用 ?init 直接加载 WebAssembly 模块并初始化，省去写拉取初始化等代码的过程，但是这个写法并不适合结合胶水代码。

既然如此，我们应该着眼于 wasm 编译阶段的优化。

代码分离

WASM

有三个选项

0 - 生成 wasm.js ，wasm 代码和 js 代码合二为一
1 - wasm 代码和 js 代码分开输出
2 - 同时生成 wasm.js 和 wasm + js

wasm.js 通常用于旧版本浏览器，-sWASM=2 会同时输出 wasm.js 和 wasm + js ，浏览器加载独立的 wasm 失败后会自动加载 wasm.js 文件。wasm.js 将 wasm 编译成 base64 字符串保存在 js 文件中，通常会比 wasm + js 大一些。如果明确用户的浏览器版本支持 wasm ，没有必要使用 wasm.js 。

按需编译

“用多少编多少”

1. 库函数

通常在项目中，我们只会用到算法库中占整个库很小比例的若干几个功能，没有必要编译无用的功能；编译 C/C++ 项目时，编译器通常会自动消除死代码，可以通过以下两个参数控制：

EXPORTED_FUNCTIONS  # 导出函数列表

EXPORT_ALL  # 导出所有函数

注意，导出函数前面需要添加一个下划线 _ ，例如需要导出 add 函数，可以这样编写

-sEXPORTED_FUNCTIONS="['_add']""

2. emscripten 运行时函数

EXPORTED_RUNTIME_METHODS

emscripten 运行时函数，默认值是空数组。我们应该按照实际需要添加导出函数，比如需要使用虚拟文件系统时，添加 FS 到数组中

-sEXPORTED_RUNTIME_METHODS="['FS']"

在 gdal3.js 项目中，导出函数列表将几乎所有支持的 GDAL 功能都列进去了，这是编译产物巨大化的关键原因。

调试信息

emcc 编译参数和 gcc 的大致相同，可以选择关闭生产环境中的调试信息来优化产物。和调试信息相关的配置有

-gsource-map
-source-map-base
-O<level>
-g<level>

1. `-gsource-map` 和 `-source-map-base`

-gsource-map 控制是否输出 sourcemap ，如果设置了输出 sourcemap ，调试器将会在 <base-url> + <wasm-file-name> + .map 位置加载 .map 文件，<base-url> 由参数 -source-map-base 设置，默认为空，也就是和 wasm 文件同一个路径。

2. `-O<level>`

设置优化等级。

-O0 - 完全不优化，保留所有调试信息
-O1 - 基础优化，消除运行时断言
-O2 - -O1 基础上进一步优化，消除死代码
-O3 - -O2 基础上再优化，减小输出文件
-Og - 和 -O1 差不多，比 -O1 保留更多调试信息
-Os - 和 -O3 差不多，比 -O3 输出文件更小
-Oz - 和 -Os 差不多，比 -Os 输出文件更小

默认值是 -O0 ，保留所有调试信息。

注意，优化级别越高，编译的时间就会越长。

3. `-g<level>`

调试等级，一共有四个等级

-g0 - 不输出任何调试信息
-g1 - 链接时，保留 JavaScript 中的空格
-g2 - 链接时，保留编译代码中的函数名称
-g3 - 编译为目标文件时，保留调试信息，包括 JS 空格、函数名称和 LLVM 调试信息（DWARF）（如果有的话）

如果设置为 -g 不带有任何数字，相当于 -g3 。

运行环境设置

默认情况下，emscripten 认为胶水代码会在不同的环境中执行，自动生成各种环境的嗅探代码和初始化代码。实际上，对于一个确定的应用而言，运行环境是固定的，没有必要产出环境嗅探。运行环境的参数是

ENVIRONMENT

emscripten 支持的值有：

node - Node.js
web - 网页
webview - 也是网页，特指插入 native 应用的网页，等同于 web
worker - worker 环境
shell - 命令行中

如果是 web 应用，只需要编译 -sENVIRONMENT=worker 环境即可；同理，在 Node.js 环境中只需要编译 -sENVIRONMENT=node 。

还有一个与运行环境相关的配置项是

EXPORT_ES6

将这个配置设置为 1 ，便可以把胶水代码输出为符合 esmodule 规范的模块。默认情况下，胶水代码输出包含环境嗅探的 CommonJS 模块和 IIFE ，在现代前端项目中无法使用 import 导入。对比一下两种输出的区别：

// -sEXPORT_ES6=1

// ... 最后一行
;return moduleRtn}export default CModule;

// -sEXPORT_ES6=0

// ... 最后一行
;return moduleRtn}})();if(typeof exports==="object"&&typeof module==="object"){module.exports=CModule;module.exports.default=CModule}else if(typeof define==="function"&&define["amd"])define([],()=>CModule);

文件系统

某些算法库，如 GDAL ，需要依赖操作系统的文件系统读写文件和输出输出，emscripten 实现了一套基于 JavaScript 的内存文件系统。如果项目中没有使用文件系统，可以不使用，配置文件系统的参数是

FILESYSTEM

编译文件系统，如果代码引用了 stdio.h 和 fprintf ，会自动开启，如果代码是纯计算，可以手动关闭。

emscripten 的文件系统随 Module 导出，可以通过 Module.FS 访问

其他

1. polyfill

POLYFILL

是否添加 polyfill 支持旧版浏览器，默认值是 true 。一般需要支持旧版浏览器的项目，都会在统一的地方添加 polyfill ，无需 emscripten 再添加，建议关闭 polyfill 。

2. 使用 BOM 的 Math 库

JS_MATH

可以配置这个参数为 true 使用 JavaScript Math 库，这样就可以避免编译 libc 。如果使用 JavaScript Math 库，计算的结果可能和 libc math 库精度不一致。建议在对精度不是很敏感的项目中可以开启。

3. 最小化输出

MINIMAL_RUNTIME

最小化输出，不带 POSIX 功能，不带 Module ，也不带 emscripten 内置的 XHR 等模块。尽管可以获得非常小的产物，但是可能代码无法运行，不建议使用。

实战

gdal3.js 编译脚本纠错

1. 调试等级错误

FLAGS 文件第 4 行定义调试等级，emcc 支持参数 0~3 ，并不支持 -g4。

这里明显可以看出来，当 type 参数为 debug 时，编译输出完整的调试信息。所以这里应该使用

GDAL_EMCC_FLAGS += -O0 -g3`

2. sourcemap 设置错误

还是在同一行，配置了 --source-map-base ，但并未开启 -gsource-map 。这里同样是当 type 参数为 debug 时，需要编译完整的 sourcemap 方便跟踪调试， --source-map-base 建议从参数中读取，所以这里应该使用

GDAL_EMCC_FLAGS += -gsource-map=1 --source-map-base $(BASE_URL)

gdal3.js 编译脚本优化

1. 关闭所有调试信息

FLAGS 文件第 6 行增加关闭调试的配置

GDAL_EMCC_FLAGS += -Oz -g0

2. 指定运行环境

GDAL_EMCC_FLAGS += -s ENVIRONMENT=worker -s EXPORT_ES6=1

3. 减少导出函数

例如上一篇，我们在代码中值用到了 GDALOpen 、 GDALInfo 和 GDALClose ，那么我们就只导出这三个函数：

GDAL_EMCC_FLAGS += -s EXPORTED_FUNCTIONS="[\
  '_malloc',\
  '_free',\
  '_CSLCount',\
  '_GDALOpen',\
  '_GDALClose',\
  '_GDALInfo'\
]"

emscripten 提供的运行时函数也不需要太多，只导出用得上的：

GDAL_EMCC_FLAGS += -s EXPORTED_RUNTIME_METHODS="[\
  'ccall',\
  'cwrap',\
  'FS'\
]"

结果

wasm 文件减小了 6177075Bytes ，瘦身了 22.44% ； js 文件减小了 18299Bytes ，瘦身 10.21% 。

结语

后面的篇章我们将会讨论：

emscripten 的虚拟文件系统
*.data 是什么，有什么用，如何优化 *.data

DEV Community: Yangholmes

EMSCRIPTEN 多线程编程笔记

操作系统的多线程

EMSCRIPTEN 的多线程

SharedArrayBuffer

cross-origin isolated

主线程阻塞

Using SIMD in WebAssembly (Part 1)

Overview of SIMD in WebAssembly

SIMD Instruction Set

Using SIMD Instructions

Next

在 WebAssembly 中使用 SIMD（二）

使用 emscripten 编译

shuffle 指令

使用 emscripten SIMD 指令

在 WebAssembly 中使用 SIMD（一）

WebAssembly 的 SIMD 概况

SIMD 指令集

使用 SIMD 指令

预告

Using wabt

Compiling wat Code

Analyzing wasm

Formatting Code

Disassembly

wabt 使用小记

编译 wat 代码

分析 wasm

整理代码

反汇编

WebAssembly 基础（二）

wasm 二进制格式结构

0. 自定义段 Custom Section

1. 类型段 Type Section

2. 导入段 ​​Import Section

3. 函数段 Function Section

4. 表段 Table Section

5. 内存段 Memory Section

6. 全局段 Global Section

7. 导出段 ​​Export Section

8. 起始段 ​​Start Section

9. 元素段 Element Section

10. 代码段

11. 数据段

wat 语法

1. 模块定义 Module

2. 函数 Functions

2.1 函数签名

2.2 局部变量

2.3 函数体指令

3. 类型 Types

4. 内存 Memory

4.1 内存定义

4.2 读内存

4.3 写内存

4.4 字符串直接写入

4.5 其他内存控制指令

5. 表 Tables

6. 全局变量 Globals

7. 导入和导出 Imports & Exports

7.1 导入

7.2 导出

8. 控制流

8.1 块/循环

8.2 条件

8.3 跳转

8.4 函数控制

8.5 其他

9. 数据段初始化内存

10. 表初始化

Getting Started with the Emscripten File System

File System

How Applications Access the File System

How WebAssembly Reads and Writes Files

Emscripten File System

MEMFS

NODEFS / NODERAWFS

IDBFS

WORKERFS

2. 导入段 Import Section

7. 导出段 Export Section

8. 起始段 Start Section

1. `-gsource-map` and `-source-map-base`

2. `-O<level>`

3. `-g<level>`

1. `-gsource-map` 和 `-source-map-base`

2. `-O<level>`

3. `-g<level>`