Stabilize memory-releated `std::arch::wasm32` intrinsics

[alexcrichton]

This is a tracking issue where I'm going to propose that we stabilize two functions in the standard library:

• std::arch::wasm32::memory_size
• std::arch::wasm32::memory_grow

These intrinsics are currently existing as memory::size and memory::grow, but I'm going to propose here that we don't do that and flatten them in the wasm32 module. As a reference, their signatures are:

fn memory_size(memory_index: u32) -> usize;
fn memory_grow(memory_index: u32, delta_pages: usize) -> isize;

Semantics

These two intrinsics represent instructions stabilized in the WebAssembly specification.

The memory.size instruction will return the current size, in WebAssembly pages, of the specified memory index. Currently only index 0 is allowed, the index is required to be a constant value, and the return value is an usize value. Note that usize is used instead of the spec's i32 for two reasons: this is more forward compatible with a possible wasm64 architecture and the return value is always an unsigned number.

The memory.grow instruction will grow the memory index specified by the given number of pages. The old size of memory, in pages, is returned. If the grow operation fails, then -1 is returned. LIke memory_size, the memory index is currently required to be 0 and must be a constant value. The delta may be a runtime value, however.

The binary encoding of these two instructions each have a reserved zero byte which is intended to be used to specify a different nonzero memory index in the future. As a recap, each WebAssembly module may have multiple "memory" instances, each assigned a unique index starting from zero. In the WebAssembly MVP, however, only at most one memory can be assigned with each wasm module, always located at index 0. (the memory may be omitted as well)

While the memory argument is currently required to be zero, it's expected that future versions of WebAssembly will no longer have this requirement and any u32 value can be specified. It's also worth noting that the zero byte in the encoding of memory.size and memory.grow may not only be exclusively used for new indices. Current proposals to WebAssembly have repurposed required zero bytes as flags fields in addition to specified more than nonzero indices. While I'm not aware of any proposal to do so, it may be possible that a future feature to WebAssembly will have more than just a memory index argument to these instructions.

Stabilization in Rust

Stabilization of these intrinsics would be a significant step for Rust on multiple axes:

• Primarily these would be the first non-x86 intrinsics stabilized. This means it's the first architecture to have a stable std::arch module which isn't x86/x86_64.
• Unlike x86 intrinsics, there is no prior art for how these intrinsics should be stabilized. Unlike x86/x86_64 the "vendor" (the WebAssembly specification) isn't giving us a document of functions with signatures.

Stabilization here will be paving a path forward for future stabilization of WebAssembly intrinsics, so it's good to consider conventions! It's unclear if the WebAssembly specification will, if ever, provide a document like Intel does for intrinsics with function names and function signatures for other languages to provide.

We've had some discussion on the naming of wasm intrinsics. We'd like to ensure that we match Clang (like we do for x86/x86_64), but Clang doesn't currently (AFAIK) have a naming convention beyond the __builtin_* internal defines it has today.

What I'm proposing here is basically a convention of:

• We provide intrinsics for instructions not natively expressable in Rust. For example we don't give an i32.add intrinsic function as it's just a + b.
• Intrinsic signatures match the effective signature of the instruction, to the best it can. Above the memory.grow and memory.size intrinsics are fairly simple.
• Intrinsic names match the name of the wasm intstructions, with non-rust-identifier characters mapped to an underscore.

The thinking behind these set of conventions it that it should be very easy to figure out what each intrinsic does, just like it is for Intel. The Rust documentation would always link to the WebAssembly specification for stabilized intrinsics.

Additionally we won't have any sort of automatic verification of WebAssembly intrinsics just yet like we do for x86 intrinsics in the stdsimd repository. There's so few WebAssembly intrinsics it's thought that we can simply manually verify each intrinsic.

TODO items before stabilization is finalized

• FCP (this issue)
• Rename the intrinsics (if that's decided on)
• Fix the "This is supported on MIPS only" message in documentation
• Update documentation to link to WebAssembly specification
• maybe flag functions as safe
• Update documentation on behavior with nonzero indexes
• Document the page size on these intrinsics.

[alexcrichton]

Note that for alternatives of naming I'm not listing them exhaustively here as there's some discussion already at rust-lang/stdarch#562, but if others feel that we should name them differently, it'd be good to discuss here/there!

[alexcrichton]

@rfcbot fcp merge

cc @rust-lang/wg-wasm
cc @tlively

There's a good long description in the post above about the stabilization here, and now I'd like to request a sign-off

[rfcbot]

Team member @alexcrichton has proposed to merge this. The next step is review by the rest of the tagged teams:

• @Kimundi
• @SimonSapin
• @alexcrichton
• @dtolnay
• @sfackler
• @withoutboats

Concerns:

• u32 resolved by Stabilize memory-releated std::arch::wasm32 intrinsics #56292 (comment)

Once a majority of reviewers approve (and none object), this will enter its final comment period. If you spot a major issue that hasn't been raised at any point in this process, please speak up!

See this document for info about what commands tagged team members can give me.

[alexcrichton]

Oh sorry it's probably also worth mentioning the rationale for stabilization here. That's twofold:

• First, this enables allocators like wee_alloc to be built on stable Rust now that they'd have access to the actual wasm instructions to allocate memory.
• Second, this starts the process on stabilizing a convention for how to encode WebAssembly intrinsics in Rust, paving the way for future instructions like atomics and SIMD

[fitzgen]

First: I would love to get wee_alloc on stable and anything else using these wasm instructions! +1 from me.

However, I find it very strange from a language design perspective that there is this exception to the way that functions and their arguments behave where certain functions' arguments must be "const" but that is not expressible in the type system at all. It didn't feel weird for intrinsics, since those are not normal functions, but here it does. Alex tells me that the extant arch::x86 functions already behave like this, so I suppose it isn't worth re-litigating...

[alexcrichton]

Ah yes @fitzgen, an excellent point! FWIW I think it was briefly considered for arch::x86{,_64} to use traits for this, but it was quickly ruled out for that use case specifically because:

• There are thousands of intrinsics which would require practically thousands of traits
• We couldn't automatically generate "the most appropriate trait" for each intrinsic with good naming and such, as it wasn't programmatically specified anywhere
• There's so much history with the existing intrinsics in C/C++ we wanted to draw from that instead of trying to pave a new set of conventions.

You might realize, though, that none of these arguments apply to WebAssembly! We're talking about a handful of possible intrinsics as well as no prior art/history/specification. We're blazing a new trail here!

The std::arch module I think is definitely open to having a per-platform conventions rather than attempting to have a cross-platform convention for all the various intrinsics here and there. In that sense I do think it's a possible legitimate alternative to have something like:

fn memory_size<T: Memory>() -> i32;
fn memory_grow<T: Memory>(delta: i32) -> i32;

trait Memory: Sealed { /* all unstable */ }
struct Memory0;

impl Memory for Memory0 { /* ... */ }

memory_size::<Memory0>(); 
// etc...

I would probably personally still be in favor of an x86/x86_64-like approach where we require, for now, arguments to be constants. It makes the functions a little weird, but is in theory something we can fix in the future and is hopefully a largely forward-compatible story. With these being such low-level intrinsics I'm also tempted to not try to add too much abstraction as it could run the risk of not being too beneficial in practice (as these are so rarely used) and also providing hindrances to usage or stabilization accidentally.

[alexcrichton]

Oh one other point I can bring up as well, is that both of these intrinsics are unsafe. Neither, however, actually need to be unsafe. Unlike x86/x86_64 we don't have to worry about "what happens if a cpu executes an unknown instruction" because that's actually impossible for WebAssembly. As a result these functions can likely be safe as they don't expose any amount of inherent unsafety.

[Centril]

cc @rust-lang/lang I think this proposal seems fine, but as it affects intrinsics / the abstract machine, I think we'll want to look at this. :)

[eddyb]

IMO we should bring in either @rust-lang/lang and/or @rust-lang/compiler into the decision (not sure what adding T- tags will do, but we probably don't need to change the FCP?).

For myself, this change is fine, including (only for intrinsics), "required-const arguments".

cc @sunfishcode

[joshtriplett]

I'd like to see the low-level intrinsics match the instructions as closely as possible. We can then have higher level wrappers similar to the type system approach proposed above.

Could we please name the "memory" argument something else, though? Something that makes it less ambiguous?

[Centril]

@eddyb

not sure what adding T- tags will do

Nothing due to rfcbot bugs. :(

For myself, this change is fine, including (only for intrinsics), "required-const arguments".

Wait; I missed this... What exactly does #[rustc_args_required_const(n)] do? make the nth argument const X: T such that it must be evaluable at compile time? Seems this is used in a bunch of stable intrinsics for x86 right now.