docs: add documentation and example of using stack maps for GC

[maxnatamo]

• Adds a documentation entry for how stack maps might be used to implement a garbage collector.
• Adds an example project which shows off how a simple garbage collector might actually be implemented. Currently only supports x64 and aarch64 (only tested on aarch64 macOS). The code might be slightly overdone, but it was also copied from a side-project.

This was originally discussed on Zulip.

[abrown]

cc: @fitzgen, you probably have more context here?

[maxnatamo]

There seems to be an issue with getting the correct return addresses when walking the stack on x64 Linux.

From what I gather, it's because Rust and/or LLVM doesn't use frame pointers the same way on some targets. It can be fixed by forcing frame pointers using -Cforce-frame-pointers, but I hope there is a better solution.

[cfallin]

There seems to be an issue with getting the correct return addresses when walking the stack on x64 Linux.

From what I gather, it's because Rust and/or LLVM doesn't use frame pointers the same way on some targets. It can be fixed by forcing frame pointers using -Cforce-frame-pointers, but I hope there is a better solution.

I gather you're building your own runtime, but to offer parallel wisdom from Wasmtime, we know that we can only trust any invariants about the code that we ourselves generate with Cranelift; so we record entry and exit FPs for an "activation" of Wasm (call into Wasm from host, call from Wasm back out to host) and only walk the FP chain in that range. In general, when interacting with code produced by other compilers you need to follow their ABI (which in general on Linux means no frame pointers required, and using DWARF to interpret stack frames and unwind them).

[maxnatamo]

Is there an "easy" solution which won't pollute the example with stack walking code? Could something like the unwinder crate in Wasmtime function here? I'll admit, this is outside of what I know about stack frames, unwinding, etc.

[cfallin]

No, Wasmtime's unwinder has nothing to do with native stack frames; it is specific to Wasmtime's metadata format.

You'll probably want to do similar to Wasmtime (and Cranelift's clif-util test runner) and emit a trampoline that uses get_frame_pointer at both ends of your Cranelift frames (entry and exit), then delimit your walk by those -- this very reason is why we added that intrinsic.

[maxnatamo]

I've tried implementing something similar to what Wasmtime does, but I'm a little in over my head with this. The new implementation walks frame entries which are pushed and popped from trampolines, but the stack pointer is way off. There might be a simple solution to this, but I might've stared at this code for too long.

[fitzgen]

Hi @maxnatamo, I don't have time to help debug this example program. In general, I'd suggest simplifying as much as possible, doing nothing else but saving the FP/SP that bookend each activation, make sure that works in isolation, and then slowly add more from there, checking that things look right along the way.

In the meantime, adding the doc comment expansions here that we talked about on Zulip might be the expeditious option.

[maxnatamo]

I can split the documentation entry and example into two separate PRs, if that helps. Then if I can't get the example working, the documentation can still be merged in.