Webassembly Tutorial

Introduction

Key concepts

• Module: it is the compiled binary code (in other words, the .wasm file).
• Memory: a JavaScript typed array that represents the memory for your program.
• Table: an array (separated from the memory) that contains the references to the function that you use.
• Instance: it is the union of a Module, a Memory and a Table plus some other values that needs to be stored.

WASM workflow

1. Compile C/C++ code with Emscripten, to obtain a WASM binary.
2. Bind your WASM binary to your page using a JavaScript "glue code".
3. Run your app and let the browser to instantiate your WASM module, the memory and the table of references. Once that is done, your WebApp is fully operative.

Browser environment

// "standard" C code to open a file
FILE *fp;
fp = fopen("/path/to/file/file.txt", "r");

Install Emscripten

# Update the package lists
sudo apt-get update

# Install *gcc* (and related dependencies)
sudo apt-get install build-essential

# Install cmake
sudo apt-get install cmake

• python 2.7
• node.js

# Install Python
sudo apt-get install python2.7

# Install node.js
sudo apt-get install nodejs

1. Download and unzip the Software Development Kit (SDK) package to the directory of your choice. Here is the the link.
2. Open a terminal inside the folder emsdk-portable you already unzipped.
3. Now run the emsdk commands to obtain the latest tools from Github and set them as active:
   

   # Fetch the latest registry of available tools.
   ./emsdk update
   
   # Download and install the latest SDK tools. This may take a while
   ./emsdk install latest
   
   # Make the "latest" SDK "active" for the current user. (writes ~/.emscripten file)
   ./emsdk activate latest
   
   # Activate PATH and other environment variables in the current terminal
   source ./emsdk_env.sh

   At this point, you should see something like that.

Your first WASM webapp

1. Create a folder wherever you want that contains a C file with this simple code:

#include <stdio.h>

int main(){
    printf("Hello world!\n");
    return 0;
}

2. With your previous terminal, move in to the new directory and compile the C code to WASM using Emscripten.
   

   emcc hello.c -o hello.html -s WASM=1

   Important:
   when you open a new terminal you won't be able to run the emcc command. You will indeed obtain this error:
   

   The program 'emcc' is currently not installed. You can install it by typing:
   sudo apt install emscripten.

   DON'T DO IT, the version that will be installed is outdated or broken and will give you tons of issues. Instead, just move back to the emsdk-portable directory and type:
   

   source ./emsdk_env.sh

   to activate the path and other environmental variables to this current terminal.
   Then move again to the repository with the file to compile and go on with the compilation.
   Explanation:
   emcc is the program you call to compile your C code (similar to call gcc or g++ when you compile your C/C++ files "normally").
   • -o hello.html tells the compiler to create the hello.html file so you can visualize the results of the WASM code.
   • -s WASM=1 tells the compiler to create a separated .wasm file. You can omit this and the everything will work the same, just your hello.js (see next point) will contain also the WASM binary.
   Note that since this is the first time you use the stdio.h library, Emscripten needs to compile it to WASM binary before it can actually compile your code. This may take some moments.


3. Now you should be able to see other three files in the same directory: hello.html, hello.js and hello.wasm.
   • hello.wasm is the file that contains the Webassembly code (the compiled code).
   • hello.js is the "glue code" needed to allow JavaScript to call and "communicate" with WASM compiled code. Emscripten generates this automatically and it is absolutely needed in order to run WASM modules. If you compile without the -s WASM=1 flag this file will contain also the content of hello.wasm (but makes no difference in reality).
   • hello.html is just a web page automatically generated that shows the result of your Webassembly code in a user friendly way. You don't actually need this file, but it is a cool way to quickly visualize what are you doing. You can tell Emscripten not to generate it by just using -o hello.js instead of -o hello.html (everything else remains as before).

1. open a terminal in the directory containing the file .html you want to run, and control your python version by typing:
   

   python -V

2. and then run:

   # if your version is 2.x
   python -m SimpleHTTPServer 8080
   
   # if your version is 3.x
   python -m http.server 8080
   

3. At this point go in the browser and open (type in the URL) localhost:8080. Note that the number 8080 is the same as the one you typed in the terminal previously (you can change it if you want, but be careful since not all the ports are for http).

<script src="hello.js"></script>
<p>Open the console to see the result!</p>

#include <iostream>

int main(){
    std::cout << "Hello world!" << std::endl;
    return 0;
}

# note that also emcc will work as well
em++ hello.cpp -o hello.html

# -O2 is already a pretty high level of optimization
emcc hello.c -o hello.js -O2 -s WASM=1

Functions

#include <stdio.h>

int fib(int n){
    if(n == 0 || n == 1)
        return 1;
    else
        return fib(n - 1) + fib(n - 2);
}

int main(){
    printf("Hello world!\n");
    int res = fib(5);
    printf("fib(5) = %d\n", res);
    return 0;
}

• ccall: calls a compiled C function with the specified variables and return the result.
• cwrap: "wraps" a compiled C function and returns a JavaScript function you can call normally. That is, by far, more useful and we will focus on this method.

var js_wrapped_fib = Module.cwrap("fib", "number", ["number"]);

var result = js_wrapped_fib(parameter);

• name of the function: name of the function in the C source code.
• return type: the return type of the function. This can be "number", "string" or "array", which correspond to the appropriate JavaScript types (use number for any C pointer), or for a void function it can be null (note: the JavaScript null value, not a string containing the word "null").
• list of parameter's types (optional): within square brackets. An array of the types of arguments for the function (if there are no arguments, this can be omitted). Types are as in return type, except that array is not supported as there is no way for us to know the length of the array.

• You can add EMSCRIPTEN_KEEPALIVE to your C functions in the code as shown below:

  #include <stdio.h>
  #include <emscripten.h> // note we added the emscripten header
  
  int EMSCRIPTEN_KEEPALIVE fib(int n){
      if(n == 0 || n == 1)
          return 1;
      else
          return fib(n - 1) + fib(n - 2);
  }
  
  int main(){
      printf("Hello world!\n");
      int res = fib(5);
      printf("fib(5) = %d\n", res);
      return 0;
  }

  In order to test it, compile the C code again, but this time tell the compiler to add cwrap as an extra exported runtime method by using this command:

  emcc hello.c -o hello.js -s WASM=1 -s EXTRA_EXPORTED_RUNTIME_METHODS='["cwrap"]'

  Then edit and run your custom .html file as below:

  <script src="hello.js"></script>
  <script>
  var js_wrapped_fib = Module.cwrap("fib", "number", ["number"]);
  
  function pressBtn(){
      console.log("The result of fib(5) is:", js_wrapped_fib(5));
  }
  </script>
  
  <button onclick="pressBtn()">Click me!</button>
  <p>Open the console to see the result!</p>

  Each time you press the "Click me!" button you should see "The result of fib(5) is: 8" appearing on your console.


• Alternatively, you can just tell the compiler that you need that functions by using this command (this way you don't need to add anything to your C code):

  emcc hello.c -o hello.js -s WASM=1 -s EXPORTED_FUNCTIONS='["_fib"]' -s EXTRA_EXPORTED_RUNTIME_METHODS='["cwrap"]'

  Note that underscore before the function name, you will always have to add it.
  Test this again (you don't need to modify your custom .html file, just refresh the page).
  You should also notice that the main is no more executed automatically, indeed, it is not even exported. You can add it to the list of exported functions:

  emcc hello.c -o hello.js -s WASM=1 -s EXPORTED_FUNCTIONS='["_fib", "_main"]' -s EXTRA_EXPORTED_RUNTIME_METHODS='["cwrap"]'

  Now your main will be again automatically executed at the beginning. You can also call it from JS whenever you want if you wrap it by adding (note that there are no input parameters):

  var js_wrapped_main = Module.cwrap("main", "number");

extern "C"{

int my_func(/* ... */){
    // do stuffs
}

}

Call JavaScript from C/C++

#include <stdio.h>
#include <emscripten.h>

int main(){
    printf("WASM is running!");
    emscripten_run_script("alert('I have been called from C!')");
    return 0;
}

emscripten_run_script("set_background_color(1)");

<script src="hello.js"></script>
<script>
function set_background_color(color_idx){
    var color = "red";
    if(color_idx == 1)  	color = "blue";
    else if(color_idx == 2) color = "green";
    
    document.body.style.backgroundColor = color; // set the new background color
}
</script>

#include <time.h>   // for time
#include <stdlib.h> // for rand
#include <stdio.h>
#include <emscripten.h>

int main(){
    printf("WASM is running!\n");
    
    srand(time(NULL));      	// initialize random seed
    int color_idx = rand() % 3; // could be 0, 1 or 2
    
    EM_ASM(
        // here you can write inline javascript code!
        console.log("(1) I have been printed from inline JavaScript!");
        console.log("I have no parameters and I do not return anything :(");
        // end of javascript code
    );
        
    // note the underscore and the curly brackets (to pass one or more parameters)
    EM_ASM_({
        console.log("(2) I have received a parameter! It is:", $0);
        console.log("Setting the background to that color index!");
        set_background_color($0);
    }, color_idx);
        
    // note that you have to specify the return type after EM_ASM_
    int result = EM_ASM_INT({
        console.log("(3) I received two parameters! They are:", $0, $1);
        console.log("Let's return their sum!");
        return sum($0, $1);
    
        function sum(a, b){
            return a + b;
        }
    }, 13, 10);
    
    printf("(4) The C code received %d as result!\n", result);
    
    return 0;
}

Libraries

• header tinyexpr.h (2 KB),
• source tinyexpr.c (20 KB).

#include <stdio.h>
#include "tinyexpr.h"

int main(){
    // te_interp just evaluates the expression in the string and returns a float
    printf("The result of (2+23)/5-1 is: %f\n", te_interp("(2+23)/5-1", 0));
    return 0;
}

emcc hello.c tinyexpr.c -o hello.html -s WASM=1

emcc lib/libzstd.bc -o zstd.js -O2 -s WASM=1 -s EXPORTED_FUNCTIONS="['_ZSTD_compress', '_ZSTD_compressBound', '_ZSTD_isError']" -s EXTRA_EXPORTED_RUNTIME_METHODS="['cwrap']" -s ALLOW_MEMORY_GROWTH=1 -s ABORTING_MALLOC=0

Memory

Module.HEAP8

• setValue(ptr, value, type)
• getValue(ptr, type)

// add one to the value in the input ptr and write this to the content of the output ptr
void addOne(int* input_ptr, int* output_ptr){
	*output_ptr = (*input_ptr) + 1;
}

emcc hello.c -o hello.js -s WASM=1 -s EXPORTED_FUNCTIONS='["_addOne"]' -s EXTRA_EXPORTED_RUNTIME_METHODS='["cwrap", "getValue", "setValue"]'

<script src="hello.js"></script>
<script>
var addOne = Module.cwrap("addOne", null, ["number", "number"]); // void function

function pressBtn(){
	// alloc 4 bytes of memory for the input and 4 for the output (32-bit integers)
	var input_ptr = Module._malloc(4);
	var output_ptr = Module._malloc(4);
    
	var value = 6;                                   // value to increment by one
	Module.setValue(input_ptr, value, "i32");        // set the value in WASM memory
	addOne(input_ptr, output_ptr);                   // call the WASM function
	var result = Module.getValue(output_ptr, "i32"); // extract the result from WASM memory
	console.log("The result read is", result, "at position", output_ptr);
    
	// dealloc memory to avoid memory leaks
	Module._free(input_ptr);
	Module._free(output_ptr);
}
</script>

<button onclick="pressBtn()">Click me!</button>
<p>Open the console to see the result!</p>

1. Alloc two new memory locations in the heap and get pointers to them (malloc).
2. Set the value of the input writing directly to that memory position (setValue).
3. Call the C function to perform our calculation.
4. Access the output value stored in the memory (getValue).
5. Free the memory in the heap (free).

// now the pointers represent two array of length equal to len
void addOne(int* input_ptr, int* output_ptr, int len){
	int i;
	for(i = 0; i < len; i++)
    	output_ptr[i] = input_ptr[i] + 1;
}

<script src="hello.js"></script>
<script>
var addOne = Module.cwrap("addOne", null, ["number", "number", "number"]);

function pressBtn(){
	var input_array = new Int32Array([10, 5, -3, 120, -70]); // array of 32-bit signed int to pass
	var len = input_array.length;					         // 5 elements
	var bytes_per_element = input_array.BYTES_PER_ELEMENT;   // 4 bytes each element
    
	// alloc memory, in this case 5*4 bytes
	var input_ptr = Module._malloc(len * bytes_per_element);
	var output_ptr = Module._malloc(len * bytes_per_element);
    
	Module.HEAP32.set(input_array, input_ptr / bytes_per_element); // write WASM memory calling the set method of the Int32Array, (see below for details)
	addOne(input_ptr, output_ptr, len);   	                       // call the WASM function
	var output_array = new Int32Array(Module.HEAP32.buffer, output_ptr, len); // extract data to another JS array
	console.log("The starting array was:", input_array);
	console.log("The result read is:	", output_array);
    
	// dealloc memory
	Module._free(input_ptr);
	Module._free(output_ptr);
}
</script>

<button onclick="pressBtn()">Click me!</button>
<p>Open the console to see the result!</p>

# On Firefox
RangeError: invalid or out-of-range index
# On Chrome
Uncaught RangeError: Source is too large

int countOccurrences(char* str, int len, char target){
	int i, count = 0;
	for(i = 0; i < len; i++){
    	if(str[i] == target){
        	count++;
    	}
	}
	return count;
}

<script src="hello.js"></script>
<script>
var countOccurrences = Module.cwrap("countOccurrences", "number", ["number", "number", "number"]); // note that also the target char is passed as number (char is an unsigned 8-bit integer)

function pressBtn(){
	var str    = "string to examine for this example";
	var target = "e";
	var len    = str.length;
    
	var converted_str    = new Uint8Array(toUTF8Array(str)); // array of bytes (8-bit unsigned int) representing the string
	var converted_target = toUTF8Array(target)[0];           // byte representing the target (8-bit unsigned int)
    
	// alloc memory
	var input_ptr = Module._malloc(len * 1);     // 1 byte per element (left just to see)
    
	Module.HEAPU8.set(converted_str, input_ptr); // write WASM memory calling the set method of the Uint8Array
	var occurrences = countOccurrences(input_ptr, len, converted_target); // call the WASM function
	console.log("Occurrences found: ", occurrences);
    
	// dealloc memory
	Module._free(input_ptr);
}

// source: https://stackoverflow.com/questions/18729405/how-to-convert-utf8-string-to-byte-array
function toUTF8Array(str) {
	var utf8 = [];
	for (var i=0; i < str.length; i++) {
    	var charcode = str.charCodeAt(i);
    	if (charcode < 0x80) utf8.push(charcode);
    	else if (charcode < 0x800) {
        	utf8.push(0xc0 | (charcode >> 6), 0x80 | (charcode & 0x3f));
    	}
    	else if (charcode < 0xd800 || charcode >= 0xe000) {
        	utf8.push(0xe0 | (charcode >> 12), 0x80 | ((charcode>>6) & 0x3f), 0x80 | (charcode & 0x3f));
    	}
    	else {
        	i++;
        	charcode = 0x10000 + (((charcode & 0x3ff)<<10) | (str.charCodeAt(i) & 0x3ff));
        	utf8.push(0xf0 | (charcode >>18), 0x80 | ((charcode>>12) & 0x3f), 0x80 | ((charcode>>6) & 0x3f), 0x80 | (charcode & 0x3f));
    	}
	}
	return utf8;
}
</script>

<button onclick="pressBtn()">Click me!</button>
<p>Open the console to see the result!</p>

Files

<!-- WASM SCRIPTS -->

1. In order to work with these files we have to read them. To do this we just use a JS Filereader.

   var reader = new FileReader();     // FileReader object
   reader.readAsArrayBuffer(file);    // perform reading

2. Once the Filereader fires the onload event, we get the file as an array of bytes that we will use as raw data to compress.

   // getting bytes as an Uint8Array
   var raw_data = new Uint8Array(reader.result, 0, reader.result.byteLength);

3. In the compress_byteArray function we just compress the raw data Uint8Array that represents the file, the code should be self-explanatory.
4. Once we compress and extract the data from the WASM memory, we pass them to a function that creates and downloads a file from these binary data: download_binary_file.

Conclusion

• What is Webassembly and how it works.
• How to compile C/C++ programs to Webassembly using Emscripten.
• How to use C/C++ functions and how to call JavaScript from the compiled code.
• How does memory works in Webassembly and how to pass data structures to C/C++ functions.

References

• Emscripten website (absolutely amazing for details about Emscripten):
  https://kripken.github.io/emscripten-site
• MDN Webassembly section (good and detailed explanation of WASM concepts):
  https://developer.mozilla.org/en-US/docs/WebAssembly

Comments