feat: pass file mapping info via PEB with label support#1322
Open
simongdavies wants to merge 1 commit intohyperlight-dev:mainfrom
Open
feat: pass file mapping info via PEB with label support#1322simongdavies wants to merge 1 commit intohyperlight-dev:mainfrom
simongdavies wants to merge 1 commit intohyperlight-dev:mainfrom
Conversation
Add FileMappingInfo struct (guest_addr, size, label) and file_mappings field to HyperlightPEB so file mapping metadata is communicated to the guest through the PEB. Space for MAX_FILE_MAPPINGS (32) entries is statically reserved after the PEB struct to avoid dynamic layout changes. - Add label parameter to map_file_cow (optional, defaults to filename) - Add shared memory overlap validation (full mapped range) - Add inter-mapping overlap detection - Add write_file_mapping_entry on SandboxMemoryManager - Add MAX_FILE_MAPPINGS limit enforcement at registration time - Update PEB region sizing in get_memory_regions and layout tests Signed-off-by: Simon Davies <simongdavies@users.noreply.github.com>
simongdavies
requested review from
danbugs,
dblnz,
devigned and
ludfjig
as code owners
simongdavies
added
the
kind/enhancement
simongdavies
requested review from
jprendes,
marosset and
syntactically
as code owners
Contributor
There was a problem hiding this comment.
Pull request overview
This PR extends the Hyperlight host↔guest ABI by adding file-mapping metadata (guest address, size, label) to the PEB, enabling guests to discover host-mapped files and their identities. It reserves space for a fixed-size FileMappingInfo array immediately after the PEB to keep the layout stable.
Changes:
- Add
FileMappingInfo+MAX_FILE_MAPPINGSand extendHyperlightPEBwith afile_mappingsdescriptor. - Add optional
labelsupport tomap_file_cow, validate mapping overlaps, and enforce the max mapping count. - Update memory layout sizing to reserve space for the PEB + mappings array, and write mapping entries into the PEB at map time / evolve time.
Reviewed changes
Copilot reviewed 8 out of 8 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
| src/hyperlight_host/src/sandbox/uninitialized_evolve.rs | Writes file mapping metadata into the PEB during evolve for deferred mappings. |
| src/hyperlight_host/src/sandbox/uninitialized.rs | Adds label parameter + limit/overlap validation for deferred file mappings. |
| src/hyperlight_host/src/sandbox/initialized_multi_use.rs | Adds label parameter, validates overlaps, writes mapping metadata into the PEB, updates tests for new signature. |
| src/hyperlight_host/src/sandbox/file_mapping.rs | Stores a fixed-size C-string label in prepared mappings and validates/truncates labels. |
| src/hyperlight_host/src/mem/mgr.rs | Adds write_file_mapping_entry to write FileMappingInfo entries into the PEB’s reserved array. |
| src/hyperlight_host/src/mem/layout.rs | Reserves space after the PEB for MAX_FILE_MAPPINGS entries and wires up PEB offsets/pointers. |
| src/hyperlight_host/examples/crashdump/main.rs | Updates map_file_cow calls for the new label parameter. |
| src/hyperlight_common/src/mem.rs | Adds shared ABI types/constants and extends HyperlightPEB with file_mappings. |
You can also share your feedback on Copilot code review. Take the survey.
| let new_end = mapping_end; | ||
| for existing in &self.pending_file_mappings { | ||
| let ex_start = existing.guest_base; | ||
| let ex_end = ex_start + existing.size as u64; |
Comment on lines
+393
to
+398
| // Write the entry into the next available slot. | ||
| let entry_offset = self.layout.get_file_mappings_array_offset() | ||
| + current_count * std::mem::size_of::<FileMappingInfo>(); | ||
| self.shared_mem.write::<u64>(entry_offset, guest_addr)?; | ||
| self.shared_mem.write::<u64>(entry_offset + 8, size)?; | ||
| self.shared_mem.copy_from_slice(label, entry_offset + 16)?; |
Comment on lines
+632
to
+637
| // Record the mapping metadata in the PEB so the guest can | ||
| // discover it. Must happen before mark_consumed() so that if | ||
| // this fails, Drop still cleans up the host resources. | ||
| self.mem_mgr | ||
| .write_file_mapping_entry(prepared.guest_base, size, &prepared.label)?; | ||
|
|
jsturtevant
reviewed
Mar 19, 2026
| // this fails, Drop still cleans up the host resources. | ||
| self.mem_mgr | ||
| .write_file_mapping_entry(prepared.guest_base, size, &prepared.label)?; | ||
|
|
Contributor
There was a problem hiding this comment.
If write_file_mapping_entry fails here, prepared hasn't been consumed yet so its Drop frees the host-side file resources — but the VM already holds a mapping from map_region above, leaving it with a dangling backing. The evolve path in uninitialized_evolve.rs avoids this by calling mark_consumed() immediately after map_region, then write_file_mapping_entry. Consider matching that order here.
danbugs
added a commit
to nanvix/hyperlight
that referenced
this pull request
Mar 19, 2026
Cherry-pick of hyperlight-dev#1322. Add FileMappingInfo struct (guest_addr, size, label) and file_mappings field to HyperlightPEB so file mapping metadata is communicated to the guest through the PEB. Space for MAX_FILE_MAPPINGS (32) entries is statically reserved after the PEB struct to avoid dynamic layout changes. - Add label parameter to map_file_cow (optional, defaults to filename) - Add shared memory overlap validation (full mapped range) - Add inter-mapping overlap detection - Add write_file_mapping_entry on SandboxMemoryManager - Add MAX_FILE_MAPPINGS limit enforcement at registration time - Update PEB region sizing in get_memory_regions and layout tests
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
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.
Add FileMappingInfo struct (guest_addr, size, label) and file_mappings field to HyperlightPEB so file mapping metadata is communicated to the guest through the PEB. Space for MAX_FILE_MAPPINGS (32) entries is statically reserved after the PEB struct to avoid dynamic layout changes.