docs/decompiler.md - external/github.com/WebAssembly/wabt - Git at Google

 # 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 `()`.
	# 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 `()`.