-
Notifications
You must be signed in to change notification settings - Fork 14
Add 3i and grate documentation #493
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
base: main
Are you sure you want to change the base?
Conversation
End-to-End Test ReportTest PreviewTest Report Deterministic TestsSummary
Test Results by Category
Non Deterministic TestsSummary
Test Results by Category
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
rennergade
left a comment
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
some minor formatting feedback
|
This also seems to be failing the linter for reasons not specific to this PR. Devops is looking into it. |
End-to-End Test ReportTest PreviewTest Report Deterministic TestsSummary
Test Results by Category
Non Deterministic TestsSummary
Test Results by Category
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
JustinCappos
left a comment
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Added a few thoughts. I'm confused in a few places, but it seems like a writing problem with the docs rather than the implementation in most places.
Updated the Lind-Wasm documentation to clarify the concepts of cages, grates, and the 3i system. Enhanced explanations of memory safety, control flow integrity, and the roles of Wasmtime and RawPOSIX.
End-to-End Test ReportTest PreviewTest Report Deterministic TestsSummary
Test Results by Category
Non Deterministic TestsSummary
Test Results by Category
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
End-to-End Test ReportTest PreviewTest Report Deterministic TestsSummary
Test Results by Category
Non Deterministic TestsSummary
Test Results by Category
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
I will comment on some of the lower portions which I think are wrong.
End-to-End Test ReportTest PreviewTest Report Deterministic TestsSummary
Test Results by Category
Non Deterministic TestsSummary
Test Results by Category
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
docs/internal/3i.md
Outdated
|
|
||
| Each Wasm module in Wasmtime has its own `VMContext`, which encapsulates all runtime state required for that instance’s execution. When 3i performs a cross-module call (e.g., from _cage A_ to a _grate B_), the currently executing context belongs to _A_, but 3i needs to restore the latest runtime state of _B_ before re-entering its Wasm code. | ||
|
|
||
| Because Rust’s lifetime system prevents us from directly sharing or globally storing references to the caller’s runtime structures, we instead store and pass raw pointers to the target module’s `VMContext`. 3i uses a registered callback function pointer and retrived the corresponding runtime context (`VMContext`) from pointer to re-enter the target Wasm instance. This allows 3i to reconstruct the correct execution environment for _B_ at re-entry time, ensuring cross-instance transitions without violating Rust’s ownership and lifetime rules. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I find this confusing. I don't really understand. Is there a location where this information is stored that persists? Do we just do a table lookup for this?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I do still need some help here. Is this really a Rust problem? Isn't this that you need to restore the state and you don't get passed what you need lower in the call stack?
docs/internal/3i.md
Outdated
|
|
||
| Because Rust’s lifetime system prevents us from directly sharing or globally storing references to the caller’s runtime structures, we instead store and pass raw pointers to the target module’s `VMContext`. 3i uses a registered callback function pointer and retrived the corresponding runtime context (`VMContext`) from pointer to re-enter the target Wasm instance. This allows 3i to reconstruct the correct execution environment for _B_ at re-entry time, ensuring cross-instance transitions without violating Rust’s ownership and lifetime rules. | ||
|
|
||
| During module initialization, Wasmtime captures each instance’s low-level `VMContext`, representing its active execution state (memories, globals, tables, etc.). However, the registration of interposition handlers (`register_handler`) often occurs after initialization. To bridge this timing gap, Wasmtime maintains a runtime-local table: |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think that 3i will contain the information (in the optional info of the register_handler / make_syscall calls) to handle this. Do you need a table still?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Sorry, this only contains the jump address. If the tid / pid (cageid) are consistent, then I think you could look this up in the cases you need the context.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I'm realizing we also need an explanation of how the stack looks and where it lives, etc. I find this part very confusing. How do we return back up the call stack after a series of grates?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I need some clarity here too. Probably need to chat.
End-to-End Test ReportTest PreviewTest Report Deterministic TestsSummary
Test Results by Category
Non Deterministic TestsSummary
Test Results by Category
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
End-to-End Test ReportTest PreviewTest Report Deterministic TestsSummary
Test Results by Category
Non Deterministic TestsSummary
Test Results by Category
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
End-to-End Test ReportTest PreviewTest Report Deterministic TestsSummary
Test Results by Category
Non Deterministic TestsSummary
Test Results by Category
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
JustinCappos
left a comment
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I made the fixes I could. Needs more discussion. Happy to work more on this once I understand a few things.
docs/internal/3i.md
Outdated
|
|
||
| Each Wasm module in Wasmtime has its own `VMContext`, which encapsulates all runtime state required for that instance’s execution. When 3i performs a cross-module call (e.g., from _cage A_ to a _grate B_), the currently executing context belongs to _A_, but 3i needs to restore the latest runtime state of _B_ before re-entering its Wasm code. | ||
|
|
||
| Because Rust’s lifetime system prevents us from directly sharing or globally storing references to the caller’s runtime structures, we instead store and pass raw pointers to the target module’s `VMContext`. 3i uses a registered callback function pointer and retrived the corresponding runtime context (`VMContext`) from pointer to re-enter the target Wasm instance. This allows 3i to reconstruct the correct execution environment for _B_ at re-entry time, ensuring cross-instance transitions without violating Rust’s ownership and lifetime rules. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I do still need some help here. Is this really a Rust problem? Isn't this that you need to restore the state and you don't get passed what you need lower in the call stack?
docs/internal/3i.md
Outdated
|
|
||
| Because Rust’s lifetime system prevents us from directly sharing or globally storing references to the caller’s runtime structures, we instead store and pass raw pointers to the target module’s `VMContext`. 3i uses a registered callback function pointer and retrived the corresponding runtime context (`VMContext`) from pointer to re-enter the target Wasm instance. This allows 3i to reconstruct the correct execution environment for _B_ at re-entry time, ensuring cross-instance transitions without violating Rust’s ownership and lifetime rules. | ||
|
|
||
| During module initialization, Wasmtime captures each instance’s low-level `VMContext`, representing its active execution state (memories, globals, tables, etc.). However, the registration of interposition handlers (`register_handler`) often occurs after initialization. To bridge this timing gap, Wasmtime maintains a runtime-local table: |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I need some clarity here too. Probably need to chat.
docs/internal/3i.md
Outdated
| - Key: `(cageid, tid)` -- cage and its thread identifiers | ||
| - Value: `Box<GrateFnEntry>` -- stable heap-allocated entry containing callback and necessary context pointers | ||
|
|
||
| When the user’s Wasm code calls `register_handler`, the entry is extracted and passed to 3i, where it becomes the canonical reference for that `(cageid, tid)` pair. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Does the tid indicate which VMContext is used to run a request in the grate?
Co-authored-by: Justin Cappos <[email protected]>
Co-authored-by: Justin Cappos <[email protected]>
End-to-End Test ReportTest PreviewTest Report Deterministic TestsSummary
Test Results by Category
Non Deterministic TestsSummary
Test Results by Category
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
1 similar comment
End-to-End Test ReportTest PreviewTest Report Deterministic TestsSummary
Test Results by Category
Non Deterministic TestsSummary
Test Results by Category
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
End-to-End Test ReportTest PreviewTest Report Deterministic TestsSummary
Test Results by Category
Non Deterministic TestsSummary
Test Results by Category
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
End-to-End Test ReportTest PreviewTest Report Deterministic TestsSummary
Test Results by Category
Non Deterministic TestsSummary
Test Results by Category
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|
||
| Each Wasm module in Wasmtime has its own `VMContext`, which encapsulates all runtime state required for that instance’s execution. When 3i performs a cross-module call (e.g., from _cage A_ to a _grate B_), the currently executing context belongs to _A_, but 3i needs to load the latest runtime state of _B_ before re-entering _B_'s Wasm code. | ||
|
|
||
| Another design difference in lind-wasm is that each thread within a cage is represented by a separate Wasmtime instance. These per-thread instances share the same host memory by importing a common memory object, which enables in-process shared memory between threads. Each thread instance, however, maintains its own call stack. Because of this design, when storing runtime contexts we must uniquely identify them by both cage ID (`cageid`) and thread ID (`tid`). Most system calls can execute using the main-thread instance (`threadid = 0`), since they do not depend on per-thread stack state. However, calls such as `fork()`, which must capture or replicate the current thread’s execution stack, require referring to the precise thread-specific instance. To handle concurrent requests, lind-wasm maintains a small instance pool for the main-thread context: instead of a single threadid = 0 instance, we pre-allocate around ten clones that share the same memory but have separate stacks. This allows multiple inbound grate requests to execute in parallel without blocking on a single Wasm context. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
i think the thread per instance distinction needs to move closer to the beginning, also some confusion in module vs instance on my end
rennergade
left a comment
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
asked for a minor clarification but this makes sense to me
|
|
||
| **Context Staging:** | ||
|
|
||
| Wasmtime captures the instance’s `VMContext` and stores both the callback and context pointers in the `GRATE_FN_WASM_TABLE`. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
What does it mean to capture here? Is this just putting a pointer in or are you copying a data structure?
Do these pointers ever change or are they the same for a Context throughout its lifetime?
Co-authored-by: Justin Cappos <[email protected]>
End-to-End Test ReportTest PreviewTest Report Deterministic TestsSummary
Test Results by Category
Non Deterministic TestsSummary
Test Results by Category
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
End-to-End Test ReportTest PreviewTest Report Deterministic TestsSummary
Test Results by Category
Non Deterministic TestsSummary
Test Results by Category
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
This PR adds documentation for the 3i and Grate subsystems, resolves #190 and resolves #366
It describes their design principles, runtime-agnostic API structure, and execution flow, including how Wasmtime integrates with 3i through function pointer registration and context management.