From 66c2827ac947932d07e21f982338d087eb8a2ad4 Mon Sep 17 00:00:00 2001 From: Dan Gohman Date: Wed, 3 Mar 2021 12:05:36 -0800 Subject: [PATCH] Document the `-Wl,--stack-first` option to clang. As discussed in WebAssembly/wasi-libc#233, document the `-Wl,--stack-first` option to help users diagnose stack overflow errors. --- docs/wasm-c.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/docs/wasm-c.md b/docs/wasm-c.md index 243ab4af04..65f87d53d8 100644 --- a/docs/wasm-c.md +++ b/docs/wasm-c.md @@ -12,4 +12,12 @@ that provide builds of Clang and sysroot libraries. WASI doesn't yet support `setjmp`/`longjmp` or C++ exceptions, as it is waiting for [unwinding support in WebAssembly]. +By default, the C/C++ toolchain orders linear memory to put the globals first, +the stack second, and start the heap after that. This reduces code size, +because references to globals can use small offsets. However, it also means +that stack overflow will often lead to corrupted globals. The +`-Wl,--stack-first` flag to clang instructs it to put the stack first, followed +by the globals and the heap, which may produce slightly larger code, but will +more reliably trap on stack overflow. + [unwinding support in WebAssembly]: https://github.com/WebAssembly/exception-handling/