Update README.md and geteuid_grate.c comments.

Author: stupendoussuperpowers

README.md

@@ -6,7 +6,7 @@ Grates provide custom syscall wrappers for Lind cages. Each example grate here d
 
 For more details on Lind and grates, refer to the official [documentation.](https://lind-project.github.io/lind-wasm/)
 
-## Repository Structure 
+## Repository Structure
 
 Each directory under `examples/` contains a standalone grate implementation.
 
@@ -15,19 +15,19 @@ For a grate written in `C`, the typical structure for an individual grate is:
 ```
 examples/<name>-grate
 ├── src/                // .c and .h source files.
-├── tests/              // Tests for this grate, run as child cages.
+├── tests/              // Tests for this grate.
 ├── build.conf          // Configuration file to describe additional build flags, `--max-memory` for wasm, and entry point for the grate.
-├── compile_grate.sh    // Compilation script that places the final *.wasm files in the `output/` folder.
-└── README.md 
+├── compile_grate.sh    // Compile script to generate *.wasm and *.cwasm binaries
+└── README.md
 ```
 
 ## Writing a Grate
 
-By default, syscalls called by a grate are redirected to `rawposix`. With grates, specific specific syscalls from a child cage can be redirected to custom handlers defined in the grate. 
+By default, syscalls invoked by a cage are forwarded to `rawposix`. A grate allows selected syscalls from a child cage to be intercepted and handled by custom functions.
 
-Following the example in `examples/geteuid-grate`:
+Using the example in `examples/geteuid-grate` to illustrate this process:
 
-**Registering Syscalls:**
+**Registering Syscall Handlers:**
 
 First, define a custom implementation of the syscall.
 
@@ -40,25 +40,27 @@ int geteuid_grate(uint64_t cageid) {
 Next, register this function as the handler for `geteuid` using the `register_handler` function
 
 ```c
+// Fork a child process
 pid_t pid = fork();
 if (pid == 0) {
     int cageid = getpid();
 
+    // Register our custom handler
     uint64_t fn_ptr_addr = (uint64_t)(uintptr_t_) &geteuid_grate;
     register_handler(cageid, 107, 1, grateid, fn_ptr_addr);
 
-    // Typically, the cage executable is provided as argv[1]
+    // Run the cage (provided as argv[1])
     execv(argv[1], &argv[1]);
 }
 ```
 
 **Dispatch Handling:**
 
-Each grate must define a dispatcher function named `pass_fptr_to_wt` which serves as the entry point for all interecepted syscalls in that grate. 
+Each grate must define a dispatcher function named `pass_fptr_to_wt` which serves as the entry point for all intercepted syscalls in that grate.
 
-The dispatcher is invoked using:
-- Function pointer registered for this syscall, 
-- Calling cage id, 
+The dispatcher is invoked with:
+- Function pointer registered for this syscall,
+- Calling cage id,
 - Syscall arguments (and their associated cage IDs)
 
 ```c
@@ -72,27 +74,37 @@ int pass_fptr_to_wt(uint64_t fn_ptr_uint, uint64_t cageid, uint64_t arg1,
     return -1;
   }
 
-  // Extract the function based on the function pointer that was passed. 
-  // This is the same address that was passed to the register_handler function. 
+  // Extract the function based on the function pointer that was passed.
+  // This is the same address that was passed to the register_handler function.
   int (*fn)(uint64_t) = (int (*)(uint64_t))(uintptr_t)fn_ptr_uint;
 
   // In this case, we only pass down the cageid as the argument for the geteuid syscall.
   return fn(cageid);
 }
 ```
 
+**Process Coordination:**
+
+Each grate must invoke `execv(argv[1], &argv[1])` exactly once, after registering its syscall handlers.
+
+This design avoids centralized process coordination. Once `execv` is called, further process creation or handler registrations are the responsibility of the executed cage.
+
+This also allows multiple grates to be interposed. For example:
+
+```lind_run geteuid_grate.wasm getuid_grate.wasm example.wasm```
+
+
 ## Compiling a Grate
 
-Grates are compiled similarly to regular Lind programs, with the additional requirement that the `pass_fptr_to_wt` function must be an export of the WASM module.
+Grates are compiled similarly to standard Lind programs, with the additional requirement that the WASM module exports the `pass_fptr_to_wt` function.
 
 Example of a compile script: [`examples/geteuid-grate/compile_grate.sh`](./examples/geteuid-grate/compile_grate.sh)
 
 ## Running a Grate
 
-Grates are run like regular lind programs, using the `lind_run` script. 
-
-By convention, a grate expects the child cage's command-line arguments to begin at `argv[1]`. The grate must execute the child cage using `execv(argv[1], &argv[1]`, thereby forwarding all remaining arguments to the cage unchanged.
+Grates are executed like standard Lind programs, that expect cage binaries to be present at `argv[1]`.
 
 Example usage:
 
-`lind_run geteuid_grate.wasm geteuid.wasm`
+```lind_run geteuid_grate.wasm example.wasm```
+

examples/geteuid-grate/build.conf

@@ -0,0 +1,90 @@
+#include <errno.h>
+#include <lind_syscall.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <sys/types.h>
+#include <sys/wait.h>
+#include <unistd.h>
+
+// Dispatcher function
+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,
+                    uint64_t arg4cage, uint64_t arg5, uint64_t arg5cage,
+                    uint64_t arg6, uint64_t arg6cage) {
+  if (fn_ptr_uint == 0) {
+    fprintf(stderr, "[Grate|geteuid] Invalid function ptr\n");
+    return -1;
+  }
+
+  printf("[Grate|geteuid] Handling function ptr: %llu from cage: %llu\n",
+         fn_ptr_uint, cageid);
+
+  int (*fn)(uint64_t) = (int (*)(uint64_t))(uintptr_t)fn_ptr_uint;
+
+  return fn(cageid);
+}
+
+// Function ptr and signatures of this grate
+int geteuid_grate(uint64_t);
+
+int geteuid_grate(uint64_t cageid) {
+  printf("[Grate|geteuid] In geteuid_grate %d handler for cage: %llu\n",
+         getpid(), cageid);
+  return 10;
+}
+
+// Main function will always be same in all grates
+int main(int argc, char *argv[]) {
+  // Should be at least two inputs (at least one grate file and one cage file)
+  if (argc < 2) {
+    fprintf(stderr, "Usage: %s <cage_file>\n", argv[0]);
+    exit(EXIT_FAILURE);
+  }
+
+  int grateid = getpid();
+
+  // Because we assume that all cages are unaware of the existence of grate,
+  // cages will not handle the logic of `exec`ing grate.
+  // Instead, a grate instance is responsible for mananging this.
+  //
+  // It forks and execs exactly once: To execute the child binary provided
+  // as argv[1], passing argv[1..] as that program's command-line arguments.
+  // Any further process management is handled by this executed program, not
+  // by the original grate.
+
+  pid_t pid = fork();
+  if (pid < 0) {
+    perror("fork failed");
+    exit(EXIT_FAILURE);
+  } else if (pid == 0) {
+    int cageid = getpid();
+    // Set the geteuid (syscallnum=107) of this cage to call this grate
+    // function geteuid_grate (func index=0)
+    // Syntax of register_handler:
+    //   register_handler(
+    //     int64_t targetcage, - Cage ID to be intercepted
+    //     uint64_t targetcallnum, - Syscall number to be intercepted
+    //     uint64_t handlefunc_flag, - 0 for deregister non-0 for register
+    //     uint64_t this_grate_id, - Grate ID to redirect call to
+    //     uint64_t optional_arg - Handler function pointer if registering
+    //   )
+    uint64_t fn_ptr_addr = (uint64_t)(uintptr_t)&geteuid_grate;
+    printf("[Grate|geteuid] Registering geteuid handler for cage %d in "
+           "grate %d with fn ptr addr: %llu\n",
+           cageid, grateid, fn_ptr_addr);
+    int ret = register_handler(cageid, 107, 1, grateid, fn_ptr_addr);
+
+    if (execv(argv[1], &argv[1]) == -1) {
+      perror("execv failed");
+      exit(EXIT_FAILURE);
+    }
+  }
+
+  int status;
+  while (wait(&status) > 0) {
+    printf("[Grate|geteuid] terminated, status: %d\n", status);
+  }
+
+  return 0;
+}