@@ -101,16 +101,19 @@ The macros are optional. A guest can define the underlying symbols directly,
101101which is useful for advanced setup work or custom dispatch logic (for example
102102the WIT-based guests in ` src/tests/rust_guests/witguest ` ).
103103
104- The host expects two guest symbols:
104+ The runtime provides weak default definitions for two guest symbols. A guest
105+ can override either definition:
105106
106107* ` pub extern "C" fn hyperlight_main() ` runs once at guest startup. Use it to
107108 register functions or initialize global state.
108- * ` pub extern "Rust" fn guest_dispatch_function(function_call: FunctionCall) -> Result<Vec<u8>, HyperlightGuestError> `
109- is invoked when the host calls a function name that is not registered.
109+ * ` pub extern "Rust" fn guest_dispatch_function(function_call: FunctionCall) -> Result<Vec<u8>> `
110+ handles calls that do not match a registered guest function. Its default
111+ implementation returns ` GuestFunctionNotFound ` .
110112
111113` hyperlight-guest-bin ` exposes ` #[main] ` and ` #[dispatch] ` macros that generate
112114these symbols from a regular Rust function, so most "advanced" guests still use
113- the macros rather than writing the raw ` extern "C" ` items themselves.
115+ the macros rather than defining the symbols directly. A generated or direct
116+ definition overrides the runtime's weak default.
114117
115118If you mix the manual form with ` #[guest_function] ` , registrations from the
116119macro still happen automatically. Your ` hyperlight_main ` only needs to do
@@ -143,6 +146,19 @@ C API library.
143146The ` hyperlight_guest.h ` header contains the corresponding APIs to register
144147guest functions and call host functions from within the guest.
145148
149+ Registered guest functions are checked first. When no registered function
150+ matches, the runtime calls:
151+
152+ ``` c
153+ hl_ReturnValue *c_guest_dispatch_function (const hl_FunctionCall * function_call);
154+ ```
155+
156+ The C API provides a weak default implementation that returns `NULL`, which the
157+ runtime reports as `GuestFunctionNotFound`. Define this function only when the
158+ guest needs custom dynamic dispatch. The guest definition overrides the weak
159+ default and must return either `NULL` or a value created by an
160+ `hl_result_from_*` function.
161+
146162See [src/tests/c_guests/c_simpleguest/main.c](../src/tests/c_guests/c_simpleguest/main.c)
147163for a complete example.
148164
0 commit comments