Document the summary of two pthread implementations (bytecodealliance#2104)

And add `wasi-threads` to the key feature list in README.md.

Author: yamt

README.md

@@ -29,6 +29,7 @@ WebAssembly Micro Runtime (WAMR) is a lightweight standalone WebAssembly (Wasm)
 - [The mechanism to export native APIs to Wasm applications](./doc/export_native_api.md), see [how to register native APIs](./doc/export_native_api.md)
 - [Multiple modules as dependencies](./doc/multi_module.md), ref to [document](./doc/multi_module.md) and [sample](samples/multi-module)
 - [Multi-thread, pthread APIs and thread management](./doc/pthread_library.md), ref to [document](./doc/pthread_library.md) and [sample](samples/multi-thread)
+- [wasi-threads](./doc/pthread_impls.md#wasi-threads-new), ref to [document](./doc/pthread_impls.md#wasi-threads-new) and [sample](samples/wasi-threads)
 - [Linux SGX (Intel Software Guard Extension) support](./doc/linux_sgx.md), ref to [document](./doc/linux_sgx.md)
 - [Source debugging support](./doc/source_debugging.md), ref to [document](./doc/source_debugging.md)
 - [XIP (Execution In Place) support](./doc/xip.md), ref to [document](./doc/xip.md)

doc/pthread_impls.md

@@ -0,0 +1,59 @@
+# Pthread implementations
+
+WAMR has two pthread implementations available as of writing this.
+
+These implementations are not ABI-compatible. You at least need to rebuild
+your wasm modules when migrating from one pthread implementation to another.
+
+For new users, we recommend to use (or at least experiment)
+the new wasi-threads based implementation.
+In future, we might remove the old implementation.
+
+## WAMR lib-pthread (old)
+
+  * The pthread API is directly implemented as host functions in WAMR.
+    (`WAMR_BUILD_LIB_PTHREAD`)
+
+  * Only minimum API is implemented as of writing this.
+    (eg. no pthread barriers)
+
+  * WAMR-specific ABI
+
+  * [Known limitations](pthread_library.md#known-limits)
+
+## wasi-threads (new)
+
+  * The pthread API is implemented in wasi-libc, based on
+    [wasi-threads](https://github.com/WebAssembly/wasi-threads)
+    and [WASM threads](https://github.com/WebAssembly/threads) proposals.
+
+  * It requires a recent-enough version of wasi-libc. The experimental support
+    is included in
+    [wasi-sdk 20.0](https://github.com/WebAssembly/wasi-sdk/releases/tag/wasi-sdk-20)
+    or later.
+    To build your application, cmake users can use the
+    [cmake toolchain file](https://github.com/WebAssembly/wasi-sdk/blob/main/wasi-sdk-pthread.cmake)
+    provided by wasi-sdk.
+
+  * wasi-threads is implemented as a host function in WAMR.
+    (`WAMR_BUILD_LIB_WASI_THREADS`)
+
+  * The ABI is specified in wasi-threads proposal.
+    You can run the same wasm modules on other runtimes which implement
+    the proposal. (wasmtime, toywasm, ...)
+
+  * Basically more feature-rich and complete than WAMR lib-pthread.
+
+    **EXCEPTION**: `pthread_exit` is not available as of writing this.
+    If `pthread_exit` is important for your use cases, please speak up in
+    the [GitHub issue](https://github.com/WebAssembly/wasi-threads/issues/7).
+
+    **EXCEPTION**: For threads created by `pthread_create`, the AUX stack
+    (aka C shadow stack) overflow detection mechanism is disabled as of
+    writing this.
+    If it's important for your use cases, please speak up in the
+    [GitHub issue](https://github.com/WebAssembly/wasi-threads/issues/12).
+
+# References
+
+* https://github.com/bytecodealliance/wasm-micro-runtime/issues/1790

doc/pthread_library.md

@@ -1,5 +1,8 @@
 # WAMR pthread library
 
+**Note**: This document describes the old pthread implementation.
+See [Pthread implementations](pthread_impls.md).
+
 WAMR provides a built-in library to support pthread APIs. You can call pthread APIs in your application source code.
 
 ## Build and run