wasm-decompile

Decompiles binary wasm modules into a text format that is significantly more compact and familiar (for users of C-style languages).

Example:

bin/wasm-decompile test.wasm -o test.dcmp

Goals.

This tool is aimed at users that want to be able to "read" large volumes of Wasm code such as language, runtime and tool developers, or any programmers that may not have the source code of the generated wasm available, or are trying to understand what the generated code does.

The syntax has been designed to be as light-weight and as readable as possible, while still allowing one to see the underlying Wasm constructs clearly.

Non-goals.

Be a programming language.

Though compiling this output code back into a wasm module is possible, such functionality is currently not provided. The format is very low-level, much like Wasm itself, so even though it looks more high level than the .wat format, it wouldn't be any more suitable for general purpose programming.

Language guide.

This section shows some aspects of the language in terms of how they map to Wasm and/or how they might differ from a typical C-like language. It does not try to define the actual semantics of Wasm, the reader is expected to already be mostly familiar with that.

Naming.

wasm-decompile, much like wasm2wat, derives names from the name section (preferrably), or linker symbols (if available), or import/export (if not available in the other 2). For things that have no names, names are generated starting from a, b, c and so forth.

In addition, prefixes are used for things that are not arguments/locals: f_ for functions, g_ for globals, etc.

Existing names may be generated "demangled" C++ function signatures, which in the case of functions using STL types may end up several hundred characters long. Besides removing characters not typically part of an identifier, the decompiler also strips common keywords/types from these in an effort to reduce their size.

Linker symbols are typically only available in wasm .o files, though if useful for naming can be retained in fully linked wasm modules using the --emit-reloc flag to wasm.ld. This gives you names for most functions even when --strip-debug was used.

Top level declarations.

Top level items may be preceded with import or export.

Memory is declared like memory m(initial: 1, max: 0);

Globals: global my_glob:int;

Data: data d_a(offset: 0) = "Hello, World!";

Functions (see below for instructions that may appear between {}): function f(a:int, b:int):int { return a + b; }

Statements and expressions.

An expression is generated for any sequence of Wasm instructions that leave exactly 1 value on the stack.

For instructions that leave no value values on the stack, a statement is generated, which is an expression that sits on its own line in the context of a control-flow block, or the function itself. A statement may also be generated for expressions that return a value through control flow, such as a branch instruction.

Instructions that leave multiple values on the stack, or otherwise do stack operations that break the "expression order", instead force the values to be written to temporary variables (named t1, t2 etc) which the subsequent instructions can then operate upon (this does not happen with MVP-only code).

Declaration of arguments and locals.

Arguments are defined in the function signature, as shown above.

Locals are defined upon first use: var my_local:int = 1;

Types.

The decompiler uses int and long for 32-bit and 64-bit integers, and float and double for 32-bit and 64-bit floating point numbers.

Besides these, there are the types byte and ubyte (8-bit), short and ushort (16-bit), and uint, which are used exclusively with certain load/store operations.

Loads and stores.

These tend to be the hardest to "read" in Wasm code, as they've lost all context of the data structures and types the language that Wasm was compiled from was operating upon.

wasm-decompile has a few features to try and make these more readable.

The basic form looks like an array indexing operation, so o[2]:int says: read element 2 from o when seen as an array of ints. This thus accesses 4 bytes at byte-offset 8.

o is just declared as an int, since there is no such thing as a pointer type in Wasm. But wasm-decompile tries to derive them. For example, if the code is doing o[0]:int = o[1]:int + o[2]:int, then wasm-decompile assumes o points to a struct with 3 ints, and may instead compile this to:

var o:{ a:int, b:int, c:int };
o.a = o.b + o.c

The {} type is a nameless struct declaration (named ones tbd) that hints the reader at what kind of memory layout o is accessing. This seems more informative than just uncorrelated indices all over the code.

Sadly, optimized output from a compiler like LLVM often reworks memory accesses in such crazy ways that this "struct detection" fails, for example it falls back to indexing operations when there are holes or overlaps in the memory layout, or types are mixed, etc. This happens even more so when locals such as o are being re-used for unrelated things in memory.

For accesses that are not contiguous, but at least of the same type, the decompiler will change the pointer type from o:int to e.g. o:float_ptr (and similarly, it will omit the type from the actual access, o[2] instead of o[2]:int).

Additionally, wasm-decompile tried to clean up typical indexing operations. For example, when accessing any array of 32-bit elements, generated Wasm code often looks like (base + (index << 2))[0]:int, since Wasm has no built-in way to scale the index by the type of thing being loaded. wasm-decompile then transforms this into just base[index]:int, since the scaling of anything between the [] by the type size is already implied.

Control flow.

Wasm's if-then maps fairly directly to a C-like if (c) { 1; } else { 2; }. Unlike most languages, these if-thens can also be expressions, as shown in this example (wasm-decompile does not currently use the ?: ternary).

Wasm's loop becomes a loop L { ...; continue L; } structure. The inclusion of a label means nested loops can continue any of them.

Wasm's blocks are little more than a label for forward jumps, and cause excessive amounts of nesting in other text formats such as .wat, so here they are reduced to what they naturally are: a label. This label uses {} for denoting a block only when used as an expression, so typically does not indent, and thus doesn't cause endless nesting:

if (c) goto L;
...
label L:

Operator precedence.

wasm-decompile uses the following operator precedence to reduce the amount of () needed in expressions, from high (needs no ()) to low (always needs () when nested):

(), a, 1, a()
[]
if () {} else {}
*, /, %
+, -
<<, >>
==, !=, <, >, >=, <=
&, |
min, max
=

Only + and * are associative, i.e. can have multiple of them in sequence without additional ().

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!