@@ -124,50 +124,50 @@ There are a few differences between Binaryen IR and the WebAssembly language:
124124 used in the containing node. Such a block is sometimes called an "implicit
125125 block".
126126 * Reference Types
127- * The wasm text and binary formats require that a function whose address is
128- taken by ` ref.func ` must be either in the table, or declared via an
129- ` (elem declare func $..) ` . Binaryen will emit that data when necessary, but
130- it does not represent it in IR. That is, IR can be worked on without needing
131- to think about declaring function references.
132- * Binaryen IR allows non-nullable locals in the form that the wasm spec does,
133- (which was historically nicknamed "1a"), in which a ` local.get ` must be
134- structurally dominated by a ` local.set ` in order to validate (that ensures
135- we do not read the default value of null). Despite being aligned with the
136- wasm spec, there are some minor details that you may notice:
137- * A nameless ` Block ` in Binaryen IR does not interfere with validation.
138- Nameless blocks are never emitted into the binary format (we just emit
139- their contents), so we ignore them for purposes of non-nullable locals. As
140- a result, if you read wasm text emitted by Binaryen then you may see what
141- seems to be code that should not validate per the spec (and may not
142- validate in wasm text parsers), but that difference will not exist in the
143- binary format (binaries emitted by Binaryen will always work everywhere,
144- aside for bugs of course).
145- * The Binaryen pass runner will automatically fix up validation after each
146- pass (finding things that do not validate and fixing them up, usually by
147- demoting a local to be nullable). As a result you do not need to worry
148- much about this when writing Binaryen passes. For more details see the
149- ` requiresNonNullableLocalFixups() ` hook in ` pass.h ` and the
150- ` LocalStructuralDominance ` class.
151- * Binaryen IR uses the most refined types possible for references,
152- specifically:
153- * The IR type of a ` ref.func ` is always a specific function type, and not
154- plain ` funcref ` . It is also non-nullable.
155- * Non-nullable types are also used for the type that ` try_table ` sends
156- on branches (if we branch, a null is never sent), that is, it sends
157- (ref exn) and not (ref null exn).
158- In both cases if GC is not enabled then we emit the less-refined type in the
159- binary. When reading a binary, the more refined types will be applied as we
160- build the IR.
161- * ` br_if ` output types are more refined in Binaryen IR: they have the type of
162- the value, when a value flows in. In the wasm spec the type is that of the
163- branch target, which may be less refined. Using the more refined type here
164- ensures that we optimize in the best way possible, using all the type
165- information, but it does mean that some roundtripping operations may look a
166- little different. In particular, when we emit a ` br_if ` whose type is more
167- refined in Binaryen IR then we emit a cast right after it, so that the
168- output has the right type in the wasm spec. That may cause a few bytes of
169- extra size in rare cases (we avoid this overhead in the common case where
170- the ` br_if ` value is unused).
127+ * The wasm text and binary formats require that a function whose address is
128+ taken by ` ref.func ` must be either in the table, or declared via an
129+ ` (elem declare func $..) ` . Binaryen will emit that data when necessary, but
130+ it does not represent it in IR. That is, IR can be worked on without needing
131+ to think about declaring function references.
132+ * Binaryen IR allows non-nullable locals in the form that the wasm spec does,
133+ (which was historically nicknamed "1a"), in which a ` local.get ` must be
134+ structurally dominated by a ` local.set ` in order to validate (that ensures
135+ we do not read the default value of null). Despite being aligned with the
136+ wasm spec, there are some minor details that you may notice:
137+ * A nameless ` Block ` in Binaryen IR does not interfere with validation.
138+ Nameless blocks are never emitted into the binary format (we just emit
139+ their contents), so we ignore them for purposes of non-nullable locals. As
140+ a result, if you read wasm text emitted by Binaryen then you may see what
141+ seems to be code that should not validate per the spec (and may not
142+ validate in wasm text parsers), but that difference will not exist in the
143+ binary format (binaries emitted by Binaryen will always work everywhere,
144+ aside for bugs of course).
145+ * The Binaryen pass runner will automatically fix up validation after each
146+ pass (finding things that do not validate and fixing them up, usually by
147+ demoting a local to be nullable). As a result you do not need to worry
148+ much about this when writing Binaryen passes. For more details see the
149+ ` requiresNonNullableLocalFixups() ` hook in ` pass.h ` and the
150+ ` LocalStructuralDominance ` class.
151+ * Binaryen IR uses the most refined types possible for references,
152+ specifically:
153+ * The IR type of a ` ref.func ` is always a specific function type, and not
154+ plain ` funcref ` . It is also non-nullable.
155+ * Non-nullable types are also used for the type that ` try_table ` sends
156+ on branches (if we branch, a null is never sent), that is, it sends
157+ (ref exn) and not (ref null exn).
158+ In both cases if GC is not enabled then we emit the less-refined type in the
159+ binary. When reading a binary, the more refined types will be applied as we
160+ build the IR.
161+ * ` br_if ` output types are more refined in Binaryen IR: they have the type of
162+ the value, when a value flows in. In the wasm spec the type is that of the
163+ branch target, which may be less refined. Using the more refined type here
164+ ensures that we optimize in the best way possible, using all the type
165+ information, but it does mean that some roundtripping operations may look a
166+ little different. In particular, when we emit a ` br_if ` whose type is more
167+ refined in Binaryen IR then we emit a cast right after it, so that the
168+ output has the right type in the wasm spec. That may cause a few bytes of
169+ extra size in rare cases (we avoid this overhead in the common case where
170+ the ` br_if ` value is unused).
171171 * Strings
172172 * Binaryen allows string views (` stringview_wtf16 ` etc.) to be cast using
173173 ` ref.cast ` . This simplifies the IR, as it allows ` ref.cast ` to always be
0 commit comments