Add an Intrinsics mechanism, and a call.without.effects intrinsic (#4126)

An "intrinsic" is modeled as a call to an import. We could also add new
IR things for them, but that would take more work and lead to less
clear errors in other tools if they try to read a binary using such a
nonstandard extension.

A first intrinsic is added here, call.without.effects This is basically the same
as call_ref except that the optimizer is free to assume the call has no
side effects. Consequently, if the result is not used then it can be optimized
out (as even if it is not used then side effects could have kept it around).
Likewise, the lack of side effects allows more reordering and other
things.

A lowering pass for intrinsics is provided. Rather than automatically
lower them to normal wasm at the end of optimizations, the user must
call that pass explicitly. A typical workflow might be

-O --intrinsic-lowering -O

That optimizes with the intrinsic present - perhaps removing calls
thanks to it - then lowers it into normal wasm - it turns into a call_ref -
and then optimizes further, which would turns the call_ref into a
direct call, potentially inline, etc.

1 files changed, 40 insertions, 0 deletions

diff --git a/README.md b/README.md
index 1ad54a183..a35518c27 100644
--- a/README.md
+++ b/README.md
@@ -141,6 +141,46 @@ Notes when working with Binaryen IR:
    incorrectly.
  * For similar reasons, nodes should not appear in more than one functions.
 
+### Intrinsics
+
+Binaryen intrinsic functions look like calls to imports, e.g.,
+
+```wat
+(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](https://github.com/WebAssembly/binaryen/blob/main/src/ir/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).
+
 ## Tools
 
 This repository contains code that builds the following tools in `bin/`: