WebAssembly 模块解析

1. 前言

2. 基础概念

2.1 模块（Modules）

2.2 类型（Types）

2.3 变量（Variables）

2.4 函数（Functions）

2.5 指令（Instructions）

2.6 陷阱（Traps）

2.7 表（Tables）

2.8 线性内存（Linear memory）

3 模块结构

3.1 部分（Sections）

• 自定义部分（custom section）：自定义部分的 id 为 0。它们旨在用于调试信息或第三方扩展，并且被 WebAssembly 语义忽略。它们的内容包括进一步标识自定义部分的名称，后面是用于自定义使用的未解释的字节序列。如果解释器实现了自定义部分的数据，则该数据中的错误或部分的位置不能使模块失效。

• 类型部分（type section）：类型部分由 id 以及一个函数类型向量组成。它表示了模块中的所有自定义函数类型。

• 函数部分（function section）：函数段的 id 为 3。它由类型索引的向量组成，这些类型索引表示模块的 funcs 组件中函数的类型。函数的局部变量和函数体在代码部分中。

• 表部分（table section），内存部分（memory section），全局部分（global section），导入部分（import section），导出部分（export section）：这几部分顾名思义，由每部分名称对应的元素的向量组成。

• 起始部分（start section）：起始部分的 id 为 8，它能表示一个可选的开始函数。

• 元素部分（element section）：元素部分的 id 为 9，它由多个元素段（element segments）组成。元素段的二进制格式有 8 种，开头用一个 u32 整数来区分。u32 的第 0 位表示被动（passive）或声明性（declarative）段，第 1 位表示主动（active）段存在显式表索引（explicit table index），并以其他方式区分被动和声明性段，第 2 位表示使用元素类型和元素表达式，而不是元素类型和元素索引。在 WebAssembly 的未来版本中可能会添加更多的元素类型。

• 代码部分（code section）：代码部分的 id 为 10，它包括了一个代码向量。向量里的每个元素是一段代码，每段代码包括代码长度，函数的局部变量和函数体表达式。与其他部分一样，解码不需要代码大小，但可用于在浏览二进制文件时跳过函数。如果大小与相应函数代码的长度不匹配，则模块格式错误。

• 数据部分（data section）：数据部分的 id 为 11，它由数据向量组成。表示数据的二进制格式有 3 种，用开头的 u32 整数区分。位 0 表示被动段，位 1 表示主动段的显式内存索引的存在。在当前版本的 WebAssembly 中，在单个模块中最多可以定义或导入一个内存，因此所有有效的活动数据段都有一个 0 的内存值。

• 数据计数部分（data count section）：数据计数部分的 id 为 12。它由一个可选的 u32 数字组成，表示数据部分中数据段（data segment）的数量。如果此计数与数据段向量的长度不匹配，则模块格式错误。

3.2 模块（Modules）

4. 文本格式

4.1 S-expression

4.2 词法定义

4.2.1 词法格式（Lexical Format）

(module)
;; this is a linecomment
(;
this is a blockcomment
;)

4.2.2 值（Values）

(func $add ...)
...
(export "add" (func $add)) ;; "add"是一个名称，$add 是一个 id，'a', 'd', '$'都是 idchar

4.2.3 类型（Types）

• 数字类型包括 32 和 64 位的整型 i32 i64 和浮点型 f32 f64。

• 向量类型则是 128 位长度的向量 v128，可以解释为整型或者浮点型数据。

• 引用类型包括函数引用 funcref 或者外部引用 externref。所有的引用类型都是不透明的，用户无法观测到大小或者是位模式（bit pattern），引用类型的值可以存在表里。

• 值类型则是数字，向量，引用类型的统称。它没有自己的特定的类型标识符，仅仅用于词法定义上

• 函数类型能够表示完整的函数文本。函数词法定义中，用到了值类型作为占位标识符，下面给出形式化定义：

(func $add (param $lhs i32) (param $rhs i32) (result i32) ;; t 最终被替换为 i32
  get_local $lhs
  get_local $rhs
  i32.add
)

• 限定和内存类型的词法都表示为数字，WebAssembly 中声明一块内存，则可以完全的用限定类型表示，示例中的 1 和 0 1 都是限定类型的文本表示：

(memory 1) ;; 1 page initialized
(memory 0 1) ;; maxinum 1 page

• 表类型也需要用到限定类型，因为需要初始化表的大小，具体可以写成这样：

(table 2 anyfunc) ;; 2 is a limit type

• 最后就是全局类型。我们可以把全局类型近似于值类型，唯一的区别就是存在一个可选的 mut 字段表示是否是可变的，比如我们声明一个存在不可变 32 位整数参数的全局类型，初始化为 100：

(global $g1 (mut i32) (i32.const 100)) ;; mutable

4.2.4 指令（Instructions）

4.2.5 模块（Modules）

(module
(type ... )
(import ... )
(func ... )
(table ... )
(mem ... )
(global ... )
(export ... )
(start ... )
(elem ... )
(data ...

函数域（Functions）

(func $add (param $lhs i32) (param $rhs i32) (result i32) ...)

类型域（Types）

(module
  (type $ft1 (func (param i32 i32) (result i32)))
  (func $add (type $ft1) ... )
)

导入导出域（Imports and Exports）

(module
  (import "console" "log" (func $log (param i32)))
  (func (export "logIt") ... )
)

内存域（Memories)

(module
  (memory $m0 1 1) ;; limits: {min: 1, max: 1}
  (memory $m1 (data "Hello, " "World!\n")) ;; limits: {min: 1}, inline data
  (memory $m2 (import "env" "m2") 1 1) ;; inline import
  (memory $m3 (export "env" "m3") 1 1) ;; inline export
)

数据段（Data Segments)

(module
  (memory 4 16)
  (data (offset (i32.const 100)) "Hello, ")
  (data (offset (i32.const 108)) "World!\n")
)

(module
  (memory 4 16)
  (data $d0 "Hello, " "World!\n") ;; passive mode
  (func $f0 memory.init $d0) ;; calling `memory.init` instruction in func $f0
)

全局域（Globals）

(module
  (global $g1 (import "env" "gbl") i32) ;; import
  (global $g2 (mut i32) (i32.const 100)) ;; mutable
  (global $g3 f32 (f32.const 3.14)) ;; immutable
  (global $g4 (export "gbl") ...) ;; export
)

表域（Tables）

(module
  (func $log ...)
  (func (export "writeHi") call $log))
)

(module
(func $f1 (result i32) i32.const 42)
  (func $f2 (result i32) i32.const 13)
  (table funcref (elem (offset i32.const 0) $f1 $f2))
  (type $return_i32 (func (result i32)))
  (func (export "callByIndex") (param $i i32) (result i32)
    local.get $i
    call_indirect (type $return_i32))
)

元素段（Element Segments）

起始函数（Start Function）

(module
  (func $start ... )
  (start $start)
)

4.3 手写一个简单的 WebAssembly 模块

1. 声明一个模块

(module)

1. 插入两个函数类型，其中一个接受一个 i32 类型的参数，另外一个没有参数，且两个都没有返回值

(module
  (type (;0;) (func (param i32)))
  (type (;1;) (func))
)

1. 声明本模块需要导入一个函数，类型是索引为 0 的函数类型，函数自身的索引为 0

(module
  (type (;0;) (func (param i32)))
  (type (;1;) (func))
  (import "imports" "imported_func" (func (;0;) (type 0)))
)

1. 增加一个内部定义的函数，使用索引为 1 的函数类型，这个函数自身的索引也为 1。这个函数将一个 i32 类型、值为 88 的常量压入栈，并调用索引为 0 的函数

(module
  (type (;0;) (func (param i32)))
  (type (;1;) (func))
  (import "imports" "imported_func" (func (;0;) (type 0)))
  (func (;1;) (type 1)
    i32.const 88
    call 0)
)

1. 最后，将第 4 步定义、索引为 1 的函数，用命名 exported_func 导出到外部

(module
(type (;0;) (func (param i32)))
(type (;1;) (func))
(import "imports" "imported_func" (func (;0;) (type 0)))
(func (;1;) (type 1)
  i32.const 88
  call 0)
(export "exported_func" (func 1))
)

1. 将上述文件保存为 simple.wat，并使用 wat2wasm 转换为 WebAssembly 二进制文件

# install wat2wasm by `npm install -g wat2wasm`
wat2wasm simple.wat -o simple.wasm

1. 在 JavaScript 中调用它

2. 读取模块的二进制表示，并存储到一个 ArrayBuffer 中；

3. 根据模块所需的导入内容构建导入对象 import_obj;

4. 调用 WebAssembly.instantiate 实例化并调用导出的函数；

5. 得到了来自 WebAssembly 的问候！

// test.js
// execute：node test.js
const fs = require('fs');
const wasm_buffer = fs.readFileSync("simple.wasm");
const js_func = (i) => console.log("From WebAssembly: " + i);
const import_obj = {imports: {imported_func: js_func}};

WebAssembly.instantiate(wasm_buffer, import_obj)
.then((result) => result.instance.exports.exported_func());

5. 总结

6. 参考文献