Skip to content

Commit 1373dc3

Browse files
Add troubleshooting section (#19)
* Rename section name Setup -> Installation * Mention reactor exec model in library use * Add troubleshooting section * Update src/getting-started/troubleshooting.md Co-authored-by: Max Desiatov <max@desiatov.com> Co-authored-by: Max Desiatov <max@desiatov.com>
1 parent a391124 commit 1373dc3

File tree

3 files changed

+56
-4
lines changed

3 files changed

+56
-4
lines changed

src/SUMMARY.md

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
- [Introduction](README.md)
44
- [Getting Started](getting-started/index.md)
5-
- [Setup](getting-started/setup.md)
5+
- [Installation](getting-started/setup.md)
66
- [Hello, World](getting-started/hello-world.md)
77
- [Using Swift Package Manager](getting-started/swift-package.md)
88
- [Porting code from other platforms](getting-started/porting.md)
@@ -11,6 +11,7 @@
1111
- [Concurrency](getting-started/concurrency.md)
1212
- [Testing your app](getting-started/testing.md)
1313
- [Debugging](getting-started/debugging.md)
14+
- [Troubleshooting](getting-started/troubleshooting.md)
1415
- [Examples](examples/index.md)
1516
- [Importing function](examples/importing-function.md)
1617
- [Exporting function](examples/exporting-function.md)

src/examples/exporting-function.md

Lines changed: 17 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -11,11 +11,21 @@ func add(_ lhs: Int, _ rhs: Int) -> Int {
1111

1212
You need to compile the Swift code with linker option `--export`.
1313

14+
To call the exported function as a library multiple times, you need to:
15+
16+
1. Compile it as a [*WASI reactor* execution model](https://github.com/WebAssembly/WASI/blob/bac366c8aeb69cacfea6c4c04a503191bf1cede1/legacy/application-abi.md).
17+
The default execution model is *command*, so you need to pass `-mexec-model=reactor` to linker.
18+
2. Call `_initialize` function before interacting with the instance.
19+
20+
If your code has any top-level code, you need to export `main` function as well, and call it after `_initialize` function.
21+
1422
```bash
1523
$ swiftc \
1624
-target wasm32-unknown-wasi \
1725
lib.swift -o lib.wasm \
18-
-Xlinker --export=add
26+
-Xlinker --export=add \
27+
-Xswiftc -Xclang-linker -Xswiftc -mexec-model=reactor \
28+
-Xlinker --export=main # Optional
1929
```
2030

2131
Then, you can use the exported function from host environment.
@@ -43,9 +53,13 @@ const main = async () => {
4353
const wasmBinary = await readFile("lib.wasm");
4454

4555
// Instantiate the WebAssembly file
46-
let { instance } = await WebAssembly.instantiate(wasmBinary, {
56+
const { instance } = await WebAssembly.instantiate(wasmBinary, {
4757
wasi_snapshot_preview1: wasi.wasiImport,
4858
});
59+
// Initialize the instance by following WASI reactor ABI
60+
instance.exports._initialize();
61+
// (Optional) Run the top-level code
62+
instance.exports.main();
4963
// Get the exported function
5064
const addFn = instance.exports.add;
5165
console.log("2 + 3 = " + addFn(2, 3))
@@ -55,4 +69,4 @@ const main = async () => {
5569
main()
5670
```
5771

58-
If you use SwiftPM package, you can omit linker flag using clang's `__atribute__`. Please see [swiftwasm/JavaScriptKit#91](https://github.com/swiftwasm/JavaScriptKit/pull/91/files) for more detail info
72+
If you use SwiftPM package, you can omit linker flag using clang's `__atribute__`. Please see [swiftwasm/JavaScriptKit#91](https://github.com/swiftwasm/JavaScriptKit/pull/91/files) for more detail info
Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
# Troubleshooting
2+
3+
These are some common issues you may run into while using SwiftWasm.
4+
5+
If you are having trouble that is not listed here, try searching for it in the [SwiftWasm issue tracker](https://github.com/swiftwasm/swift/issues).
6+
If you are still having trouble, please file an issue or contact us at [the community Discord server](https://discord.gg/ashJW8T8yp).
7+
8+
9+
## `RuntimeError: memory access out of bounds`
10+
11+
If you encounter this error, there are 3 possible causes:
12+
13+
### 1. You are trying to access invalid memory in your code
14+
15+
In this case, you need to make sure which memory operations are invalid in your code by `UnsafePointer` or C code.
16+
17+
### 2. You missed program initialization defined in [WASI Application ABI](https://github.com/WebAssembly/WASI/blob/bac366c8aeb69cacfea6c4c04a503191bf1cede1/legacy/application-abi.md).
18+
19+
If your application is used as a library, you need to follow [*WASI reactor ABI*](https://github.com/WebAssembly/WASI/blob/bac366c8aeb69cacfea6c4c04a503191bf1cede1/legacy/application-abi.md).
20+
21+
Please make sure that you followed it by reviewing the [Exporting function guide](../examples/exporting-function.md)
22+
23+
### 3. Stack overflow is occurring.
24+
25+
If you are using `--stack-first` linker option (carton uses it by default), you can face `RuntimeError: memory access out of bounds` error due to stack overflow.
26+
27+
You have two options to solve this issue:
28+
1. Avoid recursive calls if possible.
29+
2. Extend the stack size by linker option `-z stack-size=<size>`. [The default stack size is 64KB](https://github.com/llvm/llvm-project/blob/fabe915705472e2c06ed1aa9a90620462594e82f/llvm/include/llvm/BinaryFormat/Wasm.h#L32)
30+
```
31+
swift build --triple wasm32-unknown-wasi -Xlinker -z -Xlinker stack-size=131072
32+
```
33+
34+
2. Identify which function consumes a lof of stack space by some tools like [wasm-stack-consumer](https://github.com/kateinoigakukun/wasm-stack-consumer)
35+
36+
37+
See also: [LLVM Bugzilla – wasm32: Allow placing the stack before global data](https://bugs.llvm.org/show_bug.cgi?id=37181)

0 commit comments

Comments
 (0)