More trampoline comments.

core/executor/src/wasmtime/trampoline.rs

@@ -124,7 +124,16 @@ unsafe fn stub_fn_inner(
 
 /// Create a trampoline for invoking a host function.
 ///
-/// This code is mostly copied from wasmtime's wasmtime-api/src/trampoline/func.rs.
+/// The trampoline is a dynamically generated entry point to a runtime host call. The function is
+/// generated by manually constructing Cranelift IR and using the Cranelift compiler. The
+/// trampoline embeds the function index (the `call_id` parameter) as a constant and delegates to
+/// a stub function in Rust, which takes the function index and a memory reference to the stack
+/// arguments and return value slots.
+///
+/// This code is taken entirely from wasmtime's wasmtime-api/src/trampoline/func.rs. It is
+/// deliberately not modified to improve readability in this code base in order to simplify diffs
+/// with the upstream code and updates. We do, however, insert additional comments beginning with
+/// "NOTE:" for clarity when helpful.
 pub fn make_trampoline(
 	isa: &dyn isa::TargetIsa,
 	code_memory: &mut CodeMemory,
@@ -152,6 +161,10 @@ pub fn make_trampoline(
 	// Add error/trap return.
 	stub_sig.returns.push(ir::AbiParam::new(ir::types::I32));
 
+	// NOTE: Each parameter and return value gets a 64-bit (8-byte) wide slot on the stack, as that
+	// is large enough to fit all Wasm primitive types. The `VMContext` pointer, which is a
+	// parameter the function signature, is excluded as it is passed directly to the stub function,
+	// rather than being looked up on the caller stack from the `values_vec` pointer.
 	let values_vec_len = 8 * cmp::max(signature.params.len() - 1, signature.returns.len()) as u32;
 
 	let mut context = Context::new();