Skip to content

Commit 106301d

Browse files
committed
Remove outdated docs about broken ABI
1 parent 38b6058 commit 106301d

File tree

1 file changed

+0
-117
lines changed

1 file changed

+0
-117
lines changed

src/doc/rustc/src/platform-support/wasm32-unknown-unknown.md

-117
Original file line numberDiff line numberDiff line change
@@ -207,120 +207,3 @@ conditionally compile code instead. This is notably different to the way native
207207
platforms such as x86\_64 work, and this is due to the fact that WebAssembly
208208
binaries must only contain code the engine understands. Native binaries work so
209209
long as the CPU doesn't execute unknown code dynamically at runtime.
210-
211-
## Broken `extern "C"` ABI
212-
213-
This target has what is considered a broken `extern "C"` ABI implementation at
214-
this time. Notably the same signature in Rust and C will compile to different
215-
WebAssembly functions and be incompatible. This is considered a bug and it will
216-
be fixed in a future version of Rust.
217-
218-
For example this Rust code:
219-
220-
```rust,ignore (does-not-link)
221-
#[repr(C)]
222-
struct MyPair {
223-
a: u32,
224-
b: u32,
225-
}
226-
227-
extern "C" {
228-
fn take_my_pair(pair: MyPair) -> u32;
229-
}
230-
231-
#[no_mangle]
232-
pub unsafe extern "C" fn call_c() -> u32 {
233-
take_my_pair(MyPair { a: 1, b: 2 })
234-
}
235-
```
236-
237-
compiles to a WebAssembly module that looks like:
238-
239-
```wasm
240-
(module
241-
(import "env" "take_my_pair" (func $take_my_pair (param i32 i32) (result i32)))
242-
(func $call_c
243-
i32.const 1
244-
i32.const 2
245-
call $take_my_pair
246-
)
247-
)
248-
```
249-
250-
The function when defined in C, however, looks like
251-
252-
```c
253-
struct my_pair {
254-
unsigned a;
255-
unsigned b;
256-
};
257-
258-
unsigned take_my_pair(struct my_pair pair) {
259-
return pair.a + pair.b;
260-
}
261-
```
262-
263-
```wasm
264-
(module
265-
(import "env" "__linear_memory" (memory 0))
266-
(func $take_my_pair (param i32) (result i32)
267-
local.get 0
268-
i32.load offset=4
269-
local.get 0
270-
i32.load
271-
i32.add
272-
)
273-
)
274-
```
275-
276-
Notice how Rust thinks `take_my_pair` takes two `i32` parameters but C thinks it
277-
only takes one.
278-
279-
The correct definition of the `extern "C"` ABI for WebAssembly is located in the
280-
[WebAssembly/tool-conventions](https://github.com/WebAssembly/tool-conventions/blob/main/BasicCABI.md)
281-
repository. The `wasm32-unknown-unknown` target (and only this target, not other
282-
WebAssembly targets Rust support) does not correctly follow this document.
283-
284-
Example issues in the Rust repository about this bug are:
285-
286-
* [#115666](https://github.com/rust-lang/rust/issues/115666)
287-
* [#129486](https://github.com/rust-lang/rust/issues/129486)
288-
289-
This current state of the `wasm32-unknown-unknown` backend is due to an
290-
unfortunate accident which got relied on. The `wasm-bindgen` project prior to
291-
0.2.89 was incompatible with the "correct" definition of `extern "C"` and it was
292-
seen as not worth the tradeoff of breaking `wasm-bindgen` historically to fix
293-
this issue in the compiler.
294-
295-
Thanks to the heroic efforts of many involved in this, however, `wasm-bindgen`
296-
0.2.89 and later are compatible with the correct definition of `extern "C"` and
297-
the nightly compiler currently supports a `-Zwasm-c-abi` implemented in
298-
[#117919](https://github.com/rust-lang/rust/pull/117919). This nightly-only flag
299-
can be used to indicate whether the spec-defined version of `extern "C"` should
300-
be used instead of the "legacy" version of
301-
whatever-the-Rust-target-originally-implemented. For example using the above
302-
code you can see (lightly edited for clarity):
303-
304-
```shell
305-
$ rustc +nightly -Zwasm-c-abi=spec foo.rs --target wasm32-unknown-unknown --crate-type lib --emit obj -O
306-
$ wasm-tools print foo.o
307-
(module
308-
(import "env" "take_my_pair" (func $take_my_pair (param i32) (result i32)))
309-
(func $call_c (result i32)
310-
;; ...
311-
)
312-
;; ...
313-
)
314-
```
315-
316-
which shows that the C and Rust definitions of the same function now agree like
317-
they should.
318-
319-
The `-Zwasm-c-abi` compiler flag is tracked in
320-
[#122532](https://github.com/rust-lang/rust/issues/122532) and a lint was
321-
implemented in [#117918](https://github.com/rust-lang/rust/issues/117918) to
322-
help warn users about the transition if they're using `wasm-bindgen` 0.2.88 or
323-
prior. The current plan is to, in the future, switch `-Zwasm-c-api=spec` to
324-
being the default. Some time after that the `-Zwasm-c-abi` flag and the
325-
"legacy" implementation will all be removed. During this process users on a
326-
sufficiently updated version of `wasm-bindgen` should not experience breakage.

0 commit comments

Comments
 (0)