Reorganize docs and add clamping/stacking paragraphs#711
Draft
rennergade wants to merge 13 commits intomainfrom
Draft
Reorganize docs and add clamping/stacking paragraphs#711rennergade wants to merge 13 commits intomainfrom
rennergade wants to merge 13 commits intomainfrom
Conversation
Contributor
End-to-End Test ReportTest PreviewTest Report Deterministic TestsSummary
Test Results by Category
Fail TestsSummary
Test Results by Category
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Yaxuan-w
requested changes
Feb 9, 2026
Member
Yaxuan-w
left a comment
Yaxuan-w
left a comment
There was a problem hiding this comment.
Thanks for reorganization and adding stacking/clamping for grates! It looks good. Left some suggestions to make it more fluent.
docs/internal/grates.md
Outdated
| @@ -0,0 +1,73 @@ | |||
| # Grates | |||
|
|
|||
| A grate is a cage whose primary role is to intercept and handle system calls issued by other cages. Lind makes no distinction between cages and grates; any cage may register system call handlers and thereby act as a grate. | |||
Member
There was a problem hiding this comment.
any cage may register system call handlers and thereby act as a grate
Does this mean the cage executing register_handler or the one implementing syscall handler functions?
If it's the first one, then it's not true on our current model. Probably worth being more precise here.
Contributor
Author
There was a problem hiding this comment.
I'm not 100% sure what you're saying here. Can you elaborate?
Contributor
There was a problem hiding this comment.
I'm guessing a grate needs to export pass_fptr_to_wt
Member
There was a problem hiding this comment.
The way to distinguish grate and cage is by their functionality: whether the current cage handles some operations for syscalls. We write registering handlers logics in grates, but the operation is actually happens in the cage's process. The grate typically doesn't register handlers for a cage, but the cage will register handlers for itself.
any cage may register system call handlers and thereby act as a grate.
It's quite confused to mention in this way..
Contributor
End-to-End Test ReportTest PreviewTest Report Deterministic TestsSummary
Test Results by Category
Fail TestsSummary
Test Results by Category
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
rennergade
requested review from
JustinCappos,
stupendoussuperpowers and
vidyalakshmir
Co-authored-by: Justin Cappos <justincappos@gmail.com>
Contributor
End-to-End Test ReportTest PreviewTest Report Deterministic TestsSummary
Test Results by Category
Fail TestsSummary
Test Results by Category
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Contributor
End-to-End Test ReportTest PreviewTest Report Deterministic TestsSummary
Test Results by Category
Fail TestsSummary
Test Results by Category
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
docs/internal/grates.md
Outdated
| @@ -0,0 +1,73 @@ | |||
| # Grates | |||
|
|
|||
| A grate is a cage whose primary role is to intercept and handle system calls issued by other cages. Lind makes no distinction between cages and grates; any cage may register system call handlers and thereby act as a grate. | |||
Contributor
There was a problem hiding this comment.
I'm guessing a grate needs to export pass_fptr_to_wt
Contributor
Author
|
@Yaxuan-w @JustinCappos @stupendoussuperpowers thank you all for your comments, very helpful. I made some updates that I believe answer your questions. Let me know if there's anything else I could improve. |
|
|
||
| --- | ||
|
|
||
| ### Execution Flow |
Member
There was a problem hiding this comment.
Maybe needs some high level context.
Member
There was a problem hiding this comment.
I've put up some context here, but I'm wondering whether splitting this section out to another execution flow md makes more sense?
Something that combines (1) the rawposix execution flow for lind-wasm, (2) grate call execution flow, (3) overall arch figures, etc
Yaxuan-w
reviewed
Feb 24, 2026
docs/internal/grates.md
Outdated
|
|
||
| However, the ancestor grate may register additional internal syscall numbers. For example, a namespace grate may allow the normal `write` syscall number to continue routing toward RawPOSIX or a grate stacked below it, while registering a new internal syscall number such as `write_imfs` for an in-memory filesystem grate. | ||
|
|
||
| When `write` is invoked by a child cage, the ancestor grate examines the arguments and decides how to route the call. It may issue a new 3i call using the original `write` number to continue normal routing, or issue a call using the internal `write_imfs` number to direct the operation to the in-memory filesystem grate. |
Member
There was a problem hiding this comment.
We should register a handler for write syscall with dest_cageid=imfs_grateid to achieve this...?
docs/internal/grates.md
Outdated
|
|
||
| Clamping is used when an ancestor grate needs structural control over how a descendant handles system calls. | ||
|
|
||
| Often this is used to divide a namespace, but it is more general than that. Clamping allows an ancestor to ensure that certain checks, routing decisions, or transformations occur before a descendant’s handler executes. |
Member
There was a problem hiding this comment.
Seems like we let users to handle behaviors related to ancestors /descendants relationships entirely in grate implementation. If so, mentioning how to achieve this in 1-2 sentences would be clearer to understand.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
4 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Changes
Added a clear description of grate stacking, including the possible outcomes of interception (handle-and-pass, handle-only, no interception, and blocking).
Added documentation for grate clamping, explaining how ancestor grates interpose at handler registration time to enforce routing structure on descendants.
Separated concerns between 3i (mechanism) and grates (policy/services) by moving grate-specific behavior out of the 3i overview.