Fill in CanonicalABI.md

[lukewagner]

This PR rebases interface-types/#140 onto the Component Model, building on all the great work @alexcrichton already did and filling in some of the developments since then.

Compared to interface-types/#140, this PR makes the following updates:

• The Python/Rust pseudo-code in interface-types/Adding a use directive to *.wit #140 has been replaced with real runnable Python (depending on the Structural Pattern Matching feature introduced in Python 3.10) and includes a small test suite. I didn't actually know Python before writing this, so apologies if it's not super idiomatic; patches welcome (but perhaps after merging, to avoid mixing semantic changes with Pythonic changes).
• Support was adding for the 3 string encodings.
• The per-element free calls were replaced with a single (optional) call to a single post-return function. This both reduces the number of function calls and allows core wasm more flexibility in allocation strategy.
• The exact rules for the merging of payload types during variant flattening were tweaked a bit to have fewer cases.
• Flags may be packed into a u8 or u16 in memory when there are less than 8 or 16 flags, resp.
• The "size" measure was split into slightly different "element size" and "byte size" measures, the former used by lists and the latter used otherwise.
• Support was added for putting all params and/or results in linear memory when flattening would produce too many params/results. The stopgap solution for lack of multi-value return gets to reuse this general support.
• Since they aren't in the general explainer yet (and need to be tweaked before doing so), handle/buffer support is not included.

Lastly, this PR makes the following tweaks to the overall proposal (AST/binary/text) that came up as part of fleshing out the canonical ABI:

• Variants (and specializations of variants) now explicitly require >=1 cases (and a comment explaining why in the "Type Definitions" section of Explainer.md)
• unit was made a specialization of record (as it should've been in the first place). This is mostly a spec-internal change; the binary/text format isn't affected.
• As a text-format change, the string canonopt was renamed string-encoding to be a bit more clear.
• The into canonopt, which took an index to an instance, was replaced with separate canonopts for individual export of the into instance. This made sense given the post-return change (which doesn't belong as an export of the instance that exports memory).

[alexcrichton]

Thanks for writing this all up! I really like the idea of adding a Python test suite which we can run and ideally add tests for in the future as well to ensure that this is internally consistent.

Most of the changes from the original draft all make sense to me, although I left a few comments below about some that I didn't fully understand.

[alexcrichton]

As-is I don't think that assert is the right thing for alignment here. Above this mentions that assert should never fire, but the raw return of a function is currently passed to load (similar to the raw return of realloc is passed to store) meaning that this could fail at runtime.

Historically I vaguely remember concluding with you at one point that we should pass alignment around but not require it. If that's the case I think a few load/store algorithms need tweaking to respect misaligned pointers. Otherwise though I think this should change to trap_if and/or the initial calls to load and store should have trap_if alignment checks and this would continue to be an assert

[lukewagner]

Ah, right! Yes, you're right, there should be a dynamic trap here.

[lukewagner]

Fixed. I ended up putting the traps on what I think are the minimal cut points: where we accept a pointer from wasm (viz. lifting/lowering lists and too-many-flat), instead of load/store.

[alexcrichton]

To clarify though why do we want to require alignment in the canonical ABI but not in core wasm itself? Personally I see alignment being passed so the language, if it requires it, can take advantage of it but it's not required to take advantage of it. We can already make all accesses on a host or similar work with unaligned addresses so this otherwise runs a small risk of making conversion of arguments/returns slower since it's another thing to check.

[lukewagner]

Ah ok, so you're saying to just drop the alignment assertion altogether?

[lukewagner]

Yeah, it's a good idea to ask why since you're right that, in general, wasm doesn't enforce alignment. I think perhaps the difference here is that core wasm load and store and the bulk-mem ops are engine-internal, so that the engine can paper over any alignment restrictions in the host (with, e.g., traps and byte-loads). Also, we did actually want and consider traps, but the problem is that it would just be cost-prohibitive on many implementations. With the Canonical ABI, we're hoping to pass out raw pointers to the host which may have ambient alignment assumptions (not just in the CPU, but also perhaps the compiler), so if I pass out a (list (tuple u32 u32)), ideally I'd be able to pass it out with a pointer-to-struct { uint32_t, uint32_t }, but if it's unaligned, that may not be legal.

[alexcrichton]

I've found that when thinking about the raw-pointer-into-wasm-linear-memory issue another major issue to consider beyond alignment is endianness, for example the C struct you mentioned would only work well on little-endian hosts. Additionally C has such weird alignment of all its integers types across various platforms I found that at least in Wasmtime it's common to have wrappers around the pointers into wasm linear memory. In that sense I've never felt the need that anything would have been nicer/easier if the wasm pointers were aligned.

The consequence of this, though, is that for example in Rust if you get a list<u64> from wasm then what you actually get in Rust is something akin to &[Le<u64>] where Le is force-alignment-to-one and has an accessor that does the endian switch as appropriate. This would, though, be a hindrance to calling any native Rust API that requires something lke &[u64].

[lukewagner]

Yeah, I know that there are a variety situations where the canonical ABI won't line up, but if it mostly lines up for many popular systems for simple types like list<u64>, alignment still seems like a net win?

[alexcrichton]

At least from a library author perspective I don't find it useful if the representation only lines up on some hosts but not others. For example I wouldn't want wasmtime to have an entirely different API on little-endian vs big-endian platforms since that's just pushing all of the portability issues to end-users rather than handling them in Wasmtime itself. The endianness issue is the sticking point for me, personally, where that means we'll never hand out "absolutely raw" views into linear memory, they'll always have a wrapper of one form or another around them.

[lukewagner]

Separate from the question of whether it's worth it for Wasmtime in particular to be endian-agnostic, I think there are in general going to be implementations that are happy to specialize to little-endian and benefit from this simplification. Thus, there will be implementations (including perhaps Wasmtime at some future point, perhaps as a binding-generation option) that do want to take advantage of being able to pass out raw typed pointers to linear memory. This is also a conservative starting point, since one can always relax the trapping behavior in the future.

[lukewagner]

Thanks for all the great feedback! It looks like things have quieted down; if it's still quiet by the end of the week, I'll merge (then move on to fixing #11).

[sunfishcode]

It would be good to add a test for float NaN canonicalization.

[lukewagner]

Done. Rather than generalize the existing test function to handle nan not being equal itself, I made a separate special testing function.

[lukewagner]

Ok, merging. As always, we can continue to iterate on this in new issues and PRs.