https://a-j.gitbook.io/wasm-experimentation/wasm-internals-1

 
W
W
WASM experimentation
Search...
 
Index
 
WASM Internals 1
 
Powered By GitBook
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!

 1. 1.
    Execution of the server program.

1
$ node server.js
2
Server listening on port: 3000
Copied!

 1. 1.
    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

[spaces]
square(2)

References

 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

 
Previous
Index
Last modified 11m ago
Copy link
Contents
 
Introduction
 
Most basic webassembly module
 
A webassembly module with a simple computation
 
Execution procedures
 
Node runtime
 
Inside the browser
 
References