From 21492f71d5d3c9693ee8cd28792282fbccdd8bb9 Mon Sep 17 00:00:00 2001
From: Chris Fallin <chris@cfallin.org>
Date: Thu, 17 Aug 2023 10:39:03 -0700
Subject: [PATCH] wmemcheck: update docs. (#6856)

* wmemcheck: update docs.

This PR expands the documentation for the Wasm memchecker (`wmemcheck`)
feature significantly, and also links it from the top-level
documentation hierarchy.

* Add syntax/language annotations to quotation sections to keep mdbook happy.
---
 docs/SUMMARY.md   |  1 +
 docs/wmemcheck.md | 44 +++++++++++++++++++++++++++++++++++++++++++-
 2 files changed, 44 insertions(+), 1 deletion(-)

diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md
index 223b1ffc7101..1d247417773c 100644
--- a/docs/SUMMARY.md
+++ b/docs/SUMMARY.md
@@ -28,6 +28,7 @@
     - [Linking Modules](./examples-c-linking.md)
     - [Debugging](./examples-c-debugging.md)
     - [Using Multi-Value](./examples-c-multi-value.md)
+  - [Checking Guests' Memory Accesses](./wmemcheck.md)
 - [Using WebAssembly from your language](./lang.md)
   - [Rust](./lang-rust.md)
   - [C](./lang-c.md)
diff --git a/docs/wmemcheck.md b/docs/wmemcheck.md
index 40ba26e89425..76d731f2cce7 100644
--- a/docs/wmemcheck.md
+++ b/docs/wmemcheck.md
@@ -1,8 +1,50 @@
+# Wasm memcheck (wmemcheck)
 
-Wmemcheck provides debug output for invalid mallocs, reads, and writes.
+wmemcheck provides the ability to check for invalid mallocs, reads, and writes
+inside a Wasm module, as long as Wasmtime is able to make certain assumptions
+(`malloc` and `free` functions are visible and your program uses only the
+default allocator). This is analogous to the Valgrind tool's memory checker
+(memcheck) tool for native programs.
 
 How to use:
+
 1. When building Wasmtime, add the CLI flag "--features wmemcheck" to compile with wmemcheck configured.
     > cargo build --features wmemcheck
 2. When running your wasm module, add the CLI flag "--wmemcheck".
     > wasmtime run --wmemcheck test.wasm
+
+If your program executes an invalid operation (load or store to non-allocated
+address, double-free, or an internal error in malloc that allocates the same
+memory twice) you will see an error that looks like a Wasm trap. For example, given the program
+
+```c
+#include <stdlib.h>
+
+int main() {
+    char* p = malloc(1024);
+    *p = 0;
+    free(p);
+    *p = 0;
+}
+```
+
+compiled with WASI-SDK via
+
+```plain
+$ /opt/wasi-sdk/bin/clang -o test.wasm test.c
+```
+
+you can observe the memory checker working like so:
+
+```plain
+$ wasmtime run --wmemcheck ./test.wasm
+Error: failed to run main module `./test.wasm`
+
+Caused by:
+    0: failed to invoke command default
+    1: error while executing at wasm backtrace:
+           0:  0x103 - <unknown>!__original_main
+           1:   0x87 - <unknown>!_start
+           2: 0x2449 - <unknown>!_start.command_export
+    2: Invalid store at addr 0x10610 of size 1
+```