Web Assembly

May 26, 2024

WebAssembly（简称 Wasm）是一种面向堆栈虚拟机的二进制指令格式（这就比使用寄存器的汇编简单很多，但也可看作是一门低级的类汇编语言）。
Wasm 被设计为编程语言的便携式编译目标，使其能够在网络上部署客户端和服务器端应用程序。

本篇不涉及 WASI：WebAssembly 系统接口（WASI）是一组针对编译为 W3C WebAssembly（Wasm）标准的软件的标准 API 规范。WASI 旨在为应用程序提供一个安全的标准接口，这些应用程序可以从任何语言编译为 Wasm，并能够在任何环境中运行——从浏览器到云端再到嵌入式设备。

API 概览

参考性地观察 Typescript 类型声明：

浏览器

Deno

名称	描述
Global	表示一个全局变量实例，可以从 JavaScript 访问，并且可以在一个或多个 WebAssembly.Module 实例之间导入/导出。这允许动态链接多个模块。
Module	包含了已经被浏览器编译的无状态 WebAssembly 代码。该代码能够高效地与 Worker 共享，并多次实例化。
Instance	一个有状态的、可执行的模块（Module）的实例。实例对象包含了所有能够从 JavaScript 调用 WebAssembly 代码的导出的 WebAssembly 函数。
compile()	将 WebAssembly 二进制代码编译为 WebAssembly.Module 对象。
compileStreaming()	直接从流式底层源编译 WebAssembly.Module。
instantiate()	允许你编译和实例化 WebAssembly 代码。
instantiateStreaming()	编译和实例化 WebAssembly 代码的主要 API，它返回 Module 及其第一个实例。
Memory	一个存储了可被实例（Instance）访问的内存原始字节的可变长 ArrayBuffer。
Table	一个用于存储可被实例（Instance）访问的不透明值（例如函数引用）的可变长类型化数组。

理解 WebAssembly 文本格式和二进制格式

概述

Wasm 二进制格式是对 Wasm 模块的抽象语法树的紧凑线性编码，格式通过属性文法定义。模块的二进制编码被组织成多个段。大多数段对应于模块记录的一个组成部分，唯一的例外是函数定义被分成了两个段：函数段和代码段。函数段包含函数的类型声明，而代码段包含函数的主体。

Wasm 文本格式（WAT，WebAssembly Text format）是一种人类可读的表示形式。本质上来说，它类似于汇编指令。语法上类似于 Lisp，将抽象语法树表示为 S- 表达式，格式同样由属性文法定义。

下面以一个非常简单的 Wasm 模块举例，模块包含 add 函数，并可在 C 语言中表示如下：

int32_t add(int32_t lhs, int32_t rhs) {
    return lhs + rhs;
}

wasm

(module
  (func $add (param $lhs i32) (param $rhs i32) (result i32)
    local.get $lhs
    local.get $rhs
    i32.add
  )
  (export "add" (func $add))
)

00 61 73 6D  "\0asm"
01 00 00 00  版本 1


注：下面是多个段，每个段的第一个字节是段号
附：段长可以置0，表示解码者需要推测段长，但此时段尾需要添加 FIXUP

01        段号为1，类型（type）段
07        长度为7字节
01        类型数量为1
60        当前为函数类型
02        参数数量为2
7F 7F     参数类型为 (i32, i32)
01        返回值数量为 1
7F        返回类型为 (i32)

03        段号为3，函数（function）段
02        长度为2字节
01        包含1个函数
00        索引为1

07        段号为7，导出（export）段
07        长度为7字节
01        导出数量为1
03        导出的符号名称长度为3字节
61 64 64  "add"
00        导出类型为函数
00        导出的索引为0

0A        段号为10，代码（code）段
09        段长为9字节
01        包含1个函数体
07        函数体长度为7字节
00        包含0个本地（local）变量
20 00     local.get 0
20 01     local.get 1
6A        i32.add
0B        end

显然可以看出，WAT 格式虽然比汇编语言要“高级”一些，但也很接近编译后的二进制表示。因此下面只以 WAT 格式来说明。

wabt 工具包提供命令行程序，可实现 WAT 与 WASM 格式的双向转换。（wabt demos）

当然也可以在 npm 中找到一些库来验证：

import { compile } from "watr";

const u8a = compile(`(module
  (func $add (param $lhs i32) (param $rhs i32) (result i32)
    local.get $lhs
    local.get $rhs
    i32.add
  )
  (export "add" (func $add))
)`);
// OR:
const u8a = Buffer.from("0061736d0100000001070160027f7f017f030201000707010361646400000a09010700200020016a0b", "hex");

const module = new WebAssembly.Module(u8a);
const instance = new WebAssembly.Instance(module);
const { add } = instance.exports;

add(128, 256); // 384

模块

本篇主要关注 Wasm 的 MVP（Minimum Viable Product）版本，更新的特性很可能被省略。
有关各执行环境的支持程度，参考此处。

Wasm 含且仅含一个模块。在文本格式中，一个模块被表示为一个大的 S- 表达式，其 EBNF 语法参见此处。

在最开始的示例中，使用了别名来引用变量。我们可能会见到使用索引来引用变量的代码，因此加以说明：

wasm

(func (param i32) (param f32) (local f64)
  local.get 0    ;; 将0号局部变量（i32类型的参数）入栈
  local.get 1    ;; 将1号局部变量（f32类型的参数）入栈
  local.get 2    ;; 将2号局部变量（类型为f64）入栈
  drop drop drop ;; 无返回值，因此丢弃栈中的所有值
)

;; 使用索引来获取局部变量很不友好，更清晰的做法是使用别名
;; 在类型声明的前面添加一个使用美元符号（$）作为前缀的名字

(func (param $p1 i32) (param $p2 f32) (local $loc i32)
  local.get $p1
  local.get $p2
  local.get $loc
  drop drop drop
)

Wasm 的目标之一是安全，因此函数调用会检查类型。

wasm

(func $add (param $lhs i32) (param $rhs i32)
  (result i32) ;; 返回值，执行后栈顶会多出一个i32类型的值
  (i32.add (local.get $lhs) (local.get $rhs))
)

;; 下面是错误示例

(func (export "test")
  (call $add (f32.const 3.14) (i64.const 15926)) ;; CompileError，参数类型不匹配
  i32.const 8080 ;; CompileError，因为没有声明返回值，执行后栈应为空
)

下面是一个更复杂的示例，阶乘函数（循环实现）：

wasm

(func $factorial (param $n i32) (result i32)
  (local $result i32) ;; 定义局部变量 $result
  (local $counter i32) ;; 定义局部变量 $counter

  local.get $n
  local.set $counter ;; 等价于 (local.set $counter (local.get $n)) 即 $counter = $n
  i32.const 1
  local.set $result ;; 等价于 (local.set $result (i32.const 1)) 即 $result = 1

  block
    loop
      local.get $counter
      i32.const 1
      i32.le_s ;; 等价于 (i32.le_s (local.get $counter) (i32.const 1))
      br_if 1  ;; 如果 $counter <= 1，则跳出循环

      local.get $result
      local.get $counter
      i32.mul           ;; 等价于 (i32.mul (local.get $result) (local.get $counter))
      local.set $result ;; $result *= $counter

      local.get $counter
      i32.const 1
      i32.sub            ;; 等价于 (i32.sub (local.get $counter) (i32.const 1))
      local.set $counter ;; $counter -= 1

      br 0 ;; 跳回循环的开始
    end
  end

  local.get $result ;; 返回 $result
)

递归实现则更简洁（非尾递归）：

wasm

(func $factorial (param $n i32) (result i32)
  (local $result i32)

  ;; 递归基准情况：如果 $n <= 1，返回 1
  local.get $n
  i32.const 1
  i32.le_s
  if (result i32)
    i32.const 1
  ;; 递归情况：$n * factorial($n - 1)
  else
    local.get $n
    local.get $n
    i32.const 1
    i32.sub
    call $factorial
    i32.mul
  end
)

通过 WebAssembly API 与 Javascript 交互

导入导出

导出函数（到外部）

wasm

;; 声明后导出
(export "exportName" (func $funcName))

;; 声明即导出
(func (export "exportName") (param $n i32) (result i32)
  (local.set $n)
)

导入函数（从外部）

wasm

(module
  (import "console" "log" (func $log (param i32)))
  (func (export "log666")
    i32.const 666
    call $log
  )
)

通过 JavaScript 提供函数，以及获取 Wasm 函数，可以通过以下方法：

const importObject = {
    console: {
        log: (arg) => {
            console.log(arg);
        },
    },
};

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

const { log666 } = instance.exports;

log666();

模块之间还可以导入和导出全局变量

wasm

(module
  ;; 定义全局变量
  (global $myGlobal (mut i32) (i32.const 42))

  ;; 导出全局变量
  (export "myGlobal" (global $myGlobal))

  ;; 导入全局变量
  (global $g (import "js" "global") (mut i32))

  ;; 获取全局变量
  (func (export "getGlobal") (result i32)
    (global.get $g)
  )

  ;; 修改全局变量
  (func (export "incGlobal")
    (global.set $g (i32.add (global.get $g) (i32.const 1)))
  )
)

可以在多个 Wasm 以及 JavaScript 之间导入和导出，下面只演示了从 JavaScript 导入

const global = new WebAssembly.Global({ value: "i32", mutable: true }, 0);
const importObject = { js: { global } };
global.value = 32; // 可修改

内存

显然，仅通过栈，我们只能传递多个 i32,i64,f32,f64 这样的值。如果要传递数组（比如字符串，本质上来说就是指针），则是行不通的，我们需要内存（WebAssembly.Memory）。

内存也可在多个 Wasm 以及 JavaScript 之间创建、导入和导出（但 MVP 版本的 Wasm 模块只支持一个内存）。

wasm

(import "js" "mem"
  (memory 1) ;; 表示导入的内存必须至少有 1 页 (64KB)
)

(import "console" "log" (
  func $log (param i32 i32)) ;; 打印字符串：两个参数表示字符串，起始地址和长度
)

(data
  (i32.const 0) "Hello, world!" ;; 因为是静态字符串，因此直接在数据段声明
)

(func (export "helloWorld")
  i32.const 0  ;; 起始地址为 0
  i32.const 13 ;; 长度为 13
  call $log

  ;; 写入内存当然需要其它指令，如：
  ;; (i32.store (i32.const 0) (i32.const 123))
)

const mem = new WebAssembly.Memory({
    initial: 1,
    // 可增长 .grow() 但初始页数为 1
});

const importObject = {
    console: {
        log: (offset, length) => {
            const bytes = new Uint8Array(mem.buffer, offset, length);
            const string = new TextDecoder("utf8").decode(bytes);
            console.log(string);
        },
    },
    js: { mem },
};

下面的示例覆盖了上例没有演示的部分：

wasm

;; 从 Wasm 创建多个内存
(memory $mem0 1)
(memory $mem1 1)
;; 默认写入0号内存
(data (i32.const 0) "Hello from mem0")
;; 写入指定内存
(data (memory $mem1) (i32.const 1) "Hello from mem1")
;; 从 Wasm 导出内存
(export "memory1" (memory $mem1))
;; 创建初始页面大小为1、最大为2的共享内存
(memory $sharedMem 1 2 shared)

内存支持如下指令（MDN Reference）：

Grow: 增加内存实例的大小
Size: 获取内存实例的大小
Load: 从内存中加载一个数字
Store: 将一个数字存储到内存中
Copy: 将数据从内存的一个区域复制到另一个区域
Fill: 将一个区域的所有值设置为特定的字节

当然也都有完全等效的 JavaScript API

class Memory {
    constructor(descriptor: {
        initial: number;
        maximum?: number;
        /**
         * shared 指定底层的 buffer 是 ArrayBuffer 还是 SharedArrayBuffer
         */
        shared?: boolean;
    });

    readonly buffer: ArrayBuffer | SharedArrayBuffer;

    /**
     * 增长多少页（每页 64KB）
     */
    grow(delta: number): number;
}

对于规范中新的共享内存，很显然涉及到多线程（当然是指运行环境的多线程，毕竟 Wasm 只是提供模块而已）。
我们都以浏览器环境为例，那么 JavaScript 对多线程的支持是通过 Web Workers API 实现的。
规范也新增内存原子性访问指令，此处就不展开了。

表格

为保证内存安全，Wasm 不允许随意解释内存（例如，不允许将一块内存解释为函数指针），因为内存可随时被动态修改。

作为替代，可以使用表格（WebAssembly.Table），表格也由环境提供。目前，表格只能存储 anyfunc，即任意类型的函数引用。表格还可以在多个实例中共享，实现动态链接。

wasm

(module
  (table 2 funcref)
  (elem (i32.const 0) $f1 $f2)
  (func $f1 (result i32) i32.const 123)
  (func $f2 (result i32) i32.const 456)

  (type $return_i32 (func (result i32))) ;; 类型段，调用函数需要提供类型
  (func (export "callAnyfunc0and1")
    (call_indirect (type $return_i32) (i32.const 0)) ;; 通过索引调用函数
    (call_indirect (type $return_i32) (i32.const 1))
  )
)

;; 注：上面因为只有一个表格，故 call_indirect 无需指定表格
;; 也可创建命名表格并指定之
(table $tableName 1 funcref)
(func $callTableNameFn0
  i32.const 0
  call_indirect $tableName (type $return_i32)
)

注：由于 JavaScript 是弱类型的，所以在 JavaScript 调用 Wasm 表格的函数是很随意的。
但 Wasm 通过 call_indirect 调用函数则需要提供类型，并且会检查类型。
不匹配的类型将导致 WebAssembly.RuntimeError

也可以在 JavaScript 中修改表格：

const table = new WebAssembly.Table({ initial: 2, element: "anyfunc" });
const f0 = table.get(0);
const f1 = table.get(1);
table.set(0, () => {});
table.set(1, () => {});

异常

Wasm 和 JavaScript 都可以抛出和捕获异常。对于 JavaScript，使用的是 WebAssembly 命名空间下的异常。

Wasm 异常的本质是一个标签：

wasm

(tag $my_exception (param i32))

(func $throw_exception
  $my_exception (i32.const 42)
)

(func $try_catch
  (try
    (do
      ;; 可能抛出异常的代码
    )
    (catch $my_exception
      ;; 异常处理代码
      ;; 或使用 catch_all 捕获所有异常
    )
  )
)

(func $handle_exception (result i32)
  (local $exception_param i32)
  (try (result i32)
    (do
      (call $throw_exception)
      (i32.const 0) ;; 返回 0
    )
    (catch $my_exception
      (local.set $exception_param)
      (local.get $exception_param) ;; 返回异常标签携带的参数
    )
  )
)

从 JavaScript 导入异常

wasm

(module
  (import "extmod" "exttag" (tag $tagname (param i32)))

  (func $throwException (param $errorValueArg i32)
    local.get $errorValueArg
    throw $tagname
  )

  (func (export "run")
    i32.const 42
    call $throwException
  )
)

const exttag = new WebAssembly.Tag({ parameters: ["i32"] });

const importObject = { extmod: { exttag } };

WebAssembly.instantiateStreaming(fetch("example.wasm"), importObject)
    .then(({ instance }) => {
        console.log(instance.exports.run());
    })
    .catch((e) => {
        const err = e as WebAssembly.Exception;
        console.error(err);

        if (err.is(exttag)) {
            console.log(`getArg 0 : ${err.getArg(exttag, 0)}`);
        }
    });

Useful links

←Back to home

This work is licensed under CC BY-NC-SA 4.0