WASM Internals 1

Introduction

GitHub - antferdom/wasm_playground: Deep dive into the WASM internal structure and behaviour.
GitHub
Github with the wasm source code
This first part introduces the most basic WASM module in textual format (.wat) and several insights in the generated bytecode file (.wasm). Then a more elaborated wasm program with a simple computation is shown. This computation will be the square of a given natural number. And to conclude, two different options are explored for being capable of executing the compiled wasm programs. One of these is execution over the Node runtime and the other inside the browser via Javascript interoperability.

Most basic webassembly module

File: empty_module.wat
1
;; The most basic module possible to be created in webassembly textual format.
2
(module)
3
4
;; This code needs to be compile to bytecode. Not currently understandable by any runtime.
5
;; Text (.wat) -> Bytecode (.wasm). This is provided by wabt toolkit.
6
;; wabt includes compilers to convert between WebAssembly’s text representation and wasm (wat2wasm),
7
;; and vice versa, plus more besides.
8
;; Location (github): https://github.com/webassembly/wabt
9
;; Location (homebrew): https://formulae.brew.sh/formula/wabt#default
Copied!
Compile the textual representation of a webassembly program to bytecode via wat2wasm compiler.
e.g:
Compiler flags:
  • -o output_filename : Specifies the target generated file.
1
$ wat2wasm empty_module.wat -o empty_module.wasm
Copied!
Inspect the contents of the wasm file to see what it looks like. UNIX command -> xxd
e.g: empty_module.wasm
1
$ xxd empty_module.wasm
2
00000000: 0061 736d 0100 0000 00000000: 0061 736d 0100 0000 .asm....
Copied!
For fine grained bytecode representation of the generated output file, specify the flag for verbose compilation. Opcodes underneath. will be shown.
Compiler flags:
  • -v
e.g: empty_module.wasm
1
$ wat2wasm empty_module.wat -v -o empty_module.wasm
2
0000000: 0061 736d ; WASM_BINARY_MAGIC
3
0000004: 0100 0000 ; WASM_BINARY_VERSION
Copied!
NOTE: The previously opcodes shown as examples are universally present in every wasm file as main headers.

A webassembly module with a simple computation

Name: math.wat Description: Take a number a compute its square. Then call it from the browser and exectue it.
1
(module
2
;; The string after the $ symbol specifies the name of the function.
3
;; Given a number compute its square.
4
;; Input
5
;; param i32
6
;;
7
;; Output
8
;; result i32
9
(func $square (param i32) (result i32)
10
local.get 0 ;; pull the input value and push it to the stack
11
local.get 0 ;; square function needs the same number twice
12
i32.mul ;; mul operation expects two numbers from the stack
13
;; Evaluation of arithmetic expressions using a stack
14
;;
15
;; (2 * 2)
16
;; would be written as
17
;;
18
;; 2 2 *
19
;; and evaluated like this
20
;;
21
;; Contents of the stack Program being evaluated
22
;;
23
;; [ ] | 2 2 *
24
;; [2] | 2 *
25
;; [2, 2] | *
26
;; [4] |
27
;;
28
;; The return value will be the final content of the stack after the execution.
29
)
30
;; export the previous function so javascript can run it.
31
(export "square" (func $square))
32
)
Copied!
Detailed bytecode opcodes (math.wasm):
1
0000000: 0061 736d ; WASM_BINARY_MAGIC
2
0000004: 0100 0000 ; WASM_BINARY_VERSION
3
; section "Type" (1)
4
0000008: 01 ; section code
5
0000009: 00 ; section size (guess)
6
000000a: 01 ; num types
7
; func type 0
8
000000b: 60 ; func
9
000000c: 01 ; num params
10
000000d: 7f ; i32
11
000000e: 01 ; num results
12
000000f: 7f ; i32
13
0000009: 06 ; FIXUP section size
14
; section "Function" (3)
15
0000010: 03 ; section code
16
0000011: 00 ; section size (guess)
17
0000012: 01 ; num functions
18
0000013: 00 ; function 0 signature index
19
0000011: 02 ; FIXUP section size
20
; section "Export" (7)
21
0000014: 07 ; section code
22
0000015: 00 ; section size (guess)
23
0000016: 01 ; num exports
24
0000017: 06 ; string length
25
0000018: 7371 7561 7265 square ; export name
26
000001e: 00 ; export kind
27
000001f: 00 ; export func index
28
0000015: 0a ; FIXUP section size
29
; section "Code" (10)
30
0000020: 0a ; section code
31
0000021: 00 ; section size (guess)
32
0000022: 01 ; num functions
33
; function body 0
34
0000023: 00 ; func body size (guess)
35
0000024: 00 ; local decl count
36
0000025: 20 ; local.get
37
0000026: 00 ; local index
38
0000027: 20 ; local.get
39
0000028: 00 ; local index
40
0000029: 6c ; i32.mul
41
000002a: 0b ; end
42
0000023: 07 ; FIXUP func body size
43
0000021: 09 ; FIXUP section size
44
[email protected] playground %
Copied!

Execution procedures

Node runtime

  1. 1.
    npm init
  2. 2.
    Package.json
1
...
2
"type": "module"
3
...
Copied!
  1. 1.
    Execute the file index.js e.g: square(10)
1
$ node index.js
2
100
Copied!

Inside the browser

  1. 1.
    Create an Express.js server.
  2. 2.
    Create and instatiate the appropiated server process in a file named server.js.
  3. 3.
    Create a public folder and move math.wasm to its location.
1
$ mv math.wasm ./public
Copied!
4. Execution of the server program.
1
$ node server.js
2
Server listening on port: 3000
Copied!
5. Create a standar HTML document and call the appropiate WASM module there.
5.1 Inside the browser go to: localhost:3000/test.html
5.2 Open the developer tools.
5.3 The output will be in the console
square(2)

References

Chris Hay
YouTube
Youtube channel
  1. 1.
    Chris Hay Youtube channel. Special thanks to him and his great work which led me to this field.
  2. 2.
    Programming WebAssembly with Rust, by Kevin Hoffman (book)
  3. 3.
    Understanding WebAssembly text format, MDN Web Docs
  4. 4.
    Converting WebAssembly text format to wasm, MDN Web Docs