Skip to content

Commit 647e601

Browse files
committed
Update docs
Signed-off-by: Ludvig Liljenberg <4257730+ludfjig@users.noreply.github.com>
1 parent 4f7c9dd commit 647e601

1 file changed

Lines changed: 20 additions & 4 deletions

File tree

‎docs/how-to-build-a-hyperlight-guest-binary.md‎

Lines changed: 20 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -101,16 +101,19 @@ The macros are optional. A guest can define the underlying symbols directly,
101101
which is useful for advanced setup work or custom dispatch logic (for example
102102
the 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
112114
these 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

115118
If you mix the manual form with `#[guest_function]`, registrations from the
116119
macro still happen automatically. Your `hyperlight_main` only needs to do
@@ -143,6 +146,19 @@ C API library.
143146
The `hyperlight_guest.h` header contains the corresponding APIs to register
144147
guest 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+
146162
See [src/tests/c_guests/c_simpleguest/main.c](../src/tests/c_guests/c_simpleguest/main.c)
147163
for a complete example.
148164

0 commit comments

Comments
 (0)