Address comments.

Author: stupendoussuperpowers

README.md

@@ -4,7 +4,10 @@ This reposistory contains a collection of example grate implementations that can
 
 Grates provide custom syscall wrappers for Lind cages. Each example grate here demonstrates how to override one or more syscalls with a custom implementation.
 
-For more details on Lind and grates, refer to the official [documentation.](https://lind-project.github.io/lind-wasm/)
+For more details, refer to the documentation here:
+
+- [Lind-Wasm documentation](https://lind-project.github.io/lind-wasm/)
+- [3i](https://github.com/Lind-Project/lind-wasm/blob/main/src/threei/README.md)
 
 ## Repository Structure
 
@@ -98,6 +101,8 @@ This also allows multiple grates to be interposed. For example:
 
 Grates are compiled similarly to standard Lind programs, with the additional requirement that the WASM module exports the `pass_fptr_to_wt` function.
 
+[`lind_compile`](https://github.com/Lind-Project/lind-wasm/blob/main/scripts/lind_compile) script compiles `.c` programs to `.wasm` binaries for lind.
+
 Example of a compile script: [`examples/geteuid-grate/compile_grate.sh`](./examples/geteuid-grate/compile_grate.sh)
 
 ## Running a Grate

examples/geteuid-grate/build.conf

@@ -0,0 +1 @@
+ENTRY=geteuid_grate.c

examples/geteuid-grate/compile_grate.sh

@@ -1,25 +1,58 @@
-#!/bin/bash
-if [ $# -lt 1 ]; then
-    echo "Usage: $0 <source.c>"
+#!/usr/bin/env bash
+set -euo pipefail
+
+if [[ $# -ne 1 ]]; then
+    echo "usage: $0 <example-dir>"
+    exit 1
+fi
+
+TARGET="$1"
+
+# Enter the example directory
+pushd "$TARGET" >/dev/null
+
+# Now everything is relative to the example dir
+echo "[cwd] $(pwd)"
+
+# Load per-example config
+if [[ ! -f build.conf ]]; then
+    echo "missing build.conf"
     exit 1
 fi
+source build.conf
+
+CLANG="${CLANG:-/home/lind/lind-wasm/clang+llvm-18.1.8-x86_64-linux-gnu-ubuntu-18.04/bin/clang}"
+SYSROOT="${SYSROOT:-/home/lind/lind-wasm/src/glibc/sysroot}"
+WASM_OPT="${WASM_OPT:-/home/lind/lind-wasm/tools/binaryen/bin/wasm-opt}"
+WASMTIME="${WASMTIME:-/home/lind/lind-wasm/src/wasmtime/target/release/wasmtime}"
 
-SRC="$1"
-BASE="${SRC%.c}"
+SRC_DIR="src"
+mkdir -p output
+OUT="output/${ENTRY%.c}"
 
-CLANG="/home/lind/lind-wasm/clang+llvm-18.1.8-x86_64-linux-gnu-ubuntu-18.04/bin/clang"
-SYSROOT="/home/lind/lind-wasm/src/glibc/sysroot"
-WASM_OPT="/home/lind/lind-wasm/tools/binaryen/bin/wasm-opt"
-WASMTIME="/home/lind/lind-wasm/src/wasmtime/target/release/wasmtime"
+MAX_MEMORY="${MAX_MEMORY:-268435456}"
+EXTRA_CFLAGS="${EXTRA_CFLAGS:-}"
+EXTRA_WASM_OPT="${EXTRA_WASM_OPT:-}"
+
+echo "[build] $OUT (max-mem=$MAX_MEMORY)"
 
 "$CLANG" -pthread \
-    --target=wasm32-unknown-wasi \
-    --sysroot "$SYSROOT" \
-    -Wl,--import-memory,--export-memory,--max-memory=67108864,\
+  --target=wasm32-unknown-wasi \
+  --sysroot "$SYSROOT" \
+  -Wl,--import-memory,--export-memory,--max-memory="$MAX_MEMORY",\
 --export=__stack_pointer,--export=__stack_low,--export=pass_fptr_to_wt \
-    "$SRC" \
-    -g -O0 -o "${BASE}.wasm"
+  $EXTRA_CFLAGS \
+  "$SRC_DIR"/*.c \
+  -g -O0 -o "$OUT.wasm"
+
+"$WASM_OPT" \
+  --asyncify \
+  --epoch-injection \
+  --debuginfo \
+  $EXTRA_WASM_OPT \
+  "$OUT.wasm" -o "$OUT.wasm"
 
-"$WASM_OPT" --asyncify --epoch-injection --debuginfo "${BASE}.wasm" -o "${BASE}.wasm"
+"$WASMTIME" compile "$OUT.wasm" -o "$OUT.cwasm"
 
-"$WASMTIME" compile "${BASE}.wasm" -o "${BASE}.cwasm"
+# Return to original directory
+popd >/dev/null

examples/geteuid-grate/src/geteuid_grate.c

@@ -1,4 +1,5 @@
 #include <errno.h>
+// lind_syscall.h provides functions needed for cage interactions: register_handler, copy_data_between_cage, and make_threei_call
 #include <lind_syscall.h>
 #include <stdio.h>
 #include <stdlib.h>
@@ -7,6 +8,19 @@
 #include <unistd.h>
 
 // Dispatcher function
+//
+// Entry point into a grate when a child cage invokes a registered
+// syscall. This function is used to invoke the appropriate handler,
+// and value returned is the passed down to the calling cage.
+//
+// Args:
+// 	fn_ptr_uint	Address of the registered syscall handler within the
+// 			grate's address space.
+// 	cageid		Identifier of the calling cage.
+// 	arg[1-6]	Syscall arguments. Numeric types are passed by value, pointers
+// 			are passed as addresses in the originating cage's address space.
+// 	arg[1-6]cage	Cage IDs corresponding to each argument, indicating which cage's address
+// 			space the argument belongs to.
 int pass_fptr_to_wt(uint64_t fn_ptr_uint, uint64_t cageid, uint64_t arg1,
                     uint64_t arg1cage, uint64_t arg2, uint64_t arg2cage,
                     uint64_t arg3, uint64_t arg3cage, uint64_t arg4,