commit | 62d83d5fcad015ce52f0f3122eab9df1c629cafb | [log] [tgz] |
---|---|---|
author | Alon Zakai <azakai@google.com> | Thu Dec 16 17:39:17 2021 |
committer | GitHub <noreply@github.com> | Thu Dec 16 17:39:17 2021 |
tree | 894177e8addef43e42918afa486143925c644608 | |
parent | 4905e74fff164d57aa1c5aaf7cb0f5c60ec635bc [diff] |
Add binary format parse checking for ref.as input type (#4389) If that type is not valid then we cannot even create and finalize the node, which means we'd hit an assertion inside finalize(), before we reach the validator. Fixes #4383
Binaryen is a compiler and toolchain infrastructure library for WebAssembly, written in C++. It aims to make compiling to WebAssembly easy, fast, and effective:
Easy: Binaryen has a simple C API in a single header, and can also be used from JavaScript. It accepts input in WebAssembly-like form but also accepts a general control flow graph for compilers that prefer that.
Fast: Binaryen‘s internal IR uses compact data structures and is designed for completely parallel codegen and optimization, using all available CPU cores. Binaryen’s IR also compiles down to WebAssembly extremely easily and quickly because it is essentially a subset of WebAssembly.
Effective: Binaryen's optimizer has many passes (see an overview later down) that can improve code size and speed. These optimizations aim to make Binaryen powerful enough to be used as a compiler backend by itself. One specific area of focus is on WebAssembly-specific optimizations (that general-purpose compilers might not do), which you can think of as wasm minification, similar to minification for JavaScript, CSS, etc., all of which are language-specific.
Compilers using Binaryen include:
AssemblyScript
which compiles a variant of TypeScript to WebAssemblywasm2js
which compiles WebAssembly to JSAsterius
which compiles Haskell to WebAssemblyGrain
which compiles Grain to WebAssemblyBinaryen also provides a set of toolchain utilities that can
Consult the contributing instructions if you're interested in participating.
Binaryen's internal IR is designed to be
There are a few differences between Binaryen IR and the WebAssembly language:
catch
blocks in the exception handling feature) are represented as pop
subexpressions.--generate-stack-ir --print-stack-ir
, which prints Stack IR, this is guaranteed to be valid for wasm parsers.)ref.func
must be either in the table, or declared via an (elem declare func $..)
. Binaryen will emit that data when necessary, but it does not represent it in IR. That is, IR can be worked on without needing to think about declaring function references.As a result, you might notice that round-trip conversions (wasm => Binaryen IR => wasm) change code a little in some corner cases.
src/wasm-stack.h
). Stack IR allows a bunch of optimizations that are tailored for the stack machine form of WebAssembly‘s binary format (but Stack IR is less efficient for general optimizations than the main Binaryen IR). If you have a wasm file that has been particularly well-optimized, a simple round-trip conversion (just read and write, without optimization) may cause more noticeable differences, as Binaryen fits it into Binaryen IR’s more structured format. If you also optimize during the round-trip conversion then Stack IR opts will be run and the final wasm will be better optimized.Notes when working with Binaryen IR:
Binaryen intrinsic functions look like calls to imports, e.g.,
(import "binaryen-intrinsics" "foo" (func $foo))
Implementing them that way allows them to be read and written by other tools, and it avoids confusing errors on a binary format error that could happen in those tools if we had a custom binary format extension.
An intrinsic method may be optimized away by the optimizer. If it is not, it must be lowered before shipping the wasm, as otherwise it will look like a call to an import that does not exist (and VMs will show an error on not having a proper value for that import). That final lowering is not done automatically. A user of intrinsics must run the pass for that explicitly, because the tools do not know when the user intends to finish optimizing, as the user may have a pipeline of multiple optimization steps, or may be doing local experimentation, or fuzzing/reducing, etc. Only the user knows when the final optimization happens before the wasm is “final” and ready to be shipped. Note that, in general, some additional optimizations may be possible after the final lowering, and so a useful pattern is to optimize once normally with intrinsics, then lower them away, then optimize after that, e.g.:
wasm-opt input.wasm -o output.wasm -O --intrinsic-lowering -O
Each intrinsic defines its semantics, which includes what the optimizer is allowed to do with it and what the final lowering will turn it to. See intrinsics.h for the detailed definitions. A quick summary appears here:
call.without.effects
: Similar to a call_ref
in that it receives parameters, and a reference to a function to call, and calls that function with those parameters, except that the optimizer can assume the call has no side effects, and may be able to optimize it out (if it does not have a result that is used, generally).This repository contains code that builds the following tools in bin/
:
Usage instructions for each are below.
Binaryen contains a lot of optimization passes to make WebAssembly smaller and faster. You can run the Binaryen optimizer by using wasm-opt
, but also they can be run while using other tools, like wasm2js
and wasm-metadce
.
addDefaultFunctionOptimizationPasses
.wasm-opt --help
for how to set them and other details.See each optimization pass for details of what it does, but here is a quick overview of some of the relevant ones:
if
arms have some shared instructions at their end).block
to an outer one where possible, reducing their number.local.set
of a value that is already present in a local. (Overlaps with CoalesceLocals; this achieves the specific operation just mentioned without all the other work CoalesceLocals does, and therefore is useful in other places in the optimization pipeline.)br
or br_table
(like turning a block
with a br
in the middle into an if
when possible).local.get/set/tee
” optimization pass, doing things like replacing a set and a get with moving the set’s value to the get (and creating a tee) where possible. Also creates block/if/loop
return values instead of using a local to pass the value.if
arm that has no contents, a drop of a constant value with no side effects, a block
with a single child, etc.“LTO” in the above means an optimization is Link Time Optimization-like in that it works across multiple functions, but in a sense Binaryen is always “LTO” as it usually is run on the final linked wasm.
Advanced optimization techniques in the Binaryen optimizer include SSAification, Flat IR, and Stack/Poppy IR.
Binaryen also contains various passes that do other things than optimizations, like legalization for JavaScript, Asyncify, etc.
cmake . && make
A C++14 compiler is required. Note that you can also use ninja
as your generator: cmake -G Ninja . && ninja
.
Binaryen.js can be built using Emscripten, which can be installed via the SDK).
emcmake cmake . && emmake make binaryen_js
Using the Microsoft Visual Studio Installer, install the “Visual C++ tools for CMake” component.
Generate the projects:
mkdir build cd build "%VISUAL_STUDIO_ROOT%\Common7\IDE\CommonExtensions\Microsoft\CMake\CMake\bin\cmake.exe" ..
Substitute VISUAL_STUDIO_ROOT with the path to your Visual Studio installation. In case you are using the Visual Studio Build Tools, the path will be “C:\Program Files (x86)\Microsoft Visual Studio\2017\BuildTools”.
From the Developer Command Prompt, build the desired projects:
msbuild binaryen.vcxproj
CMake generates a project named “ALL_BUILD.vcxproj” for conveniently building all the projects.
Run
bin/wasm-opt [.wasm or .wat file] [options] [passes, see --help] [--help]
The wasm optimizer receives WebAssembly as input, and can run transformation passes on it, as well as print it (before and/or after the transformations). For example, try
bin/wasm-opt test/passes/lower-if-else.wat --print
That will pretty-print out one of the test cases in the test suite. To run a transformation pass on it, try
bin/wasm-opt test/passes/lower-if-else.wat --print --lower-if-else
The lower-if-else
pass lowers if-else into a block and a break. You can see the change the transformation causes by comparing the output of the two print commands.
It's easy to add your own transformation passes to the shell, just add .cpp
files into src/passes
, and rebuild the shell. For example code, take a look at the lower-if-else
pass.
Some more notes:
bin/wasm-opt --help
for the full list of options and passes.--debug
will emit some debugging info.Run
bin/wasm2js [input.wasm file]
This will print out JavaScript to the console.
For example, try
$ bin/wasm2js test/hello_world.wat
That output contains
function add(x, y) { x = x | 0; y = y | 0; return x + y | 0 | 0; }
as a translation of
(func $add (; 0 ;) (type $0) (param $x i32) (param $y i32) (result i32) (i32.add (local.get $x) (local.get $y) ) )
wasm2js‘s output is in ES6 module format - basically, it converts a wasm module into an ES6 module (to run on older browsers and Node.js versions you can use Babel etc. to convert it to ES5). Let’s look at a full example of calling that hello world wat; first, create the main JS file:
// main.mjs import { add } from "./hello_world.mjs"; console.log('the sum of 1 and 2 is:', add(1, 2));
The run this (note that you need a new enough Node.js with ES6 module support):
$ bin/wasm2js test/hello_world.wat -o hello_world.mjs $ node --experimental-modules main.mjs the sum of 1 and 2 is: 3
Things keep to in mind with wasm2js's output:
-O
or another optimization level. That will optimize along the entire pipeline (wasm and JS). It won't do everything a JS minifer would, though, like minify whitespace, so you should still run a normal JS minifer afterwards../check.py
(or python check.py
) will run wasm-shell
, wasm-opt
, etc. on the testcases in test/
, and verify their outputs.
The check.py
script supports some options:
./check.py [--interpreter=/path/to/interpreter] [TEST1] [TEST2]..
./check.py --list-suites
.emcc
or nodejs
in the path. They will not run if the tool cannot be found, and you'll see a warning.tests/spec
, in git submodules. Running ./check.py
should update those../third_party/setup.py [mozjs|v8|wabt|all]
(or python third_party/setup.py
) installs required dependencies like the SpiderMonkey JS shell, the V8 JS shell and WABT in third_party/
. Other scripts automatically pick these up when installed.
Run pip3 install -r requirements-dev.txt
to get the requirements for the lit
tests. Note that you need to have the location pip
installs to in your $PATH
(on linux, ~/.local/bin
).
./scripts/fuzz_opt.py [--binaryen-bin=build/bin]
(or python scripts/fuzz_opt.py
) will run various fuzzing modes on random inputs with random passes until it finds a possible bug. See the wiki page for all the details.
“Binaryen” is a combination of binary - since WebAssembly is a binary format for the web - and Emscripten - with which it can integrate in order to compile C and C++ all the way to WebAssembly, via asm.js. Binaryen began as Emscripten's WebAssembly processing library (wasm-emscripten
).
“Binaryen” is pronounced in the same manner as “Targaryen”: bi-NAIR-ee-in. Or something like that? Anyhow, however Targaryen is correctly pronounced, they should rhyme. Aside from pronunciation, the Targaryen house words, “Fire and Blood”, have also inspired Binaryen's: “Code and Bugs.”
Yes, it does. Here's a step-by-step tutorial on how to compile it under Windows 10 x64 with with CMake and Visual Studio 2015. However, Visual Studio 2017 may now be required. Help would be appreciated on Windows and OS X as most of the core devs are on Linux.