feat: add narrow shared memory accessor to UninitializedSandbox

[danbugs]

Summary

Adds a public shared_mem_mut() method to UninitializedSandbox that returns a mutable reference to the sandbox's ExclusiveSharedMemory.

This provides a narrow, type-safe accessor for downstream consumers (e.g., Nanvix) that need to write data into the sandbox's shared memory region before initialization, without exposing the internal SandboxMemoryManager or its mgr field.

Motivation

Downstream projects like Nanvix need to write configuration data (e.g., a credits counter) into the sandbox's shared memory at a known GPA offset before evolving it into an initialized sandbox. Previously this required making mgr and SandboxMemoryManager public, leaking implementation details. This PR provides a minimal accessor that exposes only what is needed.

Changes

• src/hyperlight_host/src/sandbox/uninitialized.rs: Add pub fn shared_mem_mut(&mut self) -> &mut ExclusiveSharedMemory

No visibility changes to SandboxMemoryManager or the mgr field. Additive-only API, no behavioral changes.

Test plan

• cargo clippy passes (linux + windows feature combinations)
• cargo test -p hyperlight-host --no-default-features -F "kvm,init-paging" --lib passes (83 tests)
• Existing CI should pass (additive-only, no behavioral changes)

[syntactically]

I wouldn't like this to be part of the public API. Can we go into a little more detail about how this is being used right now, and whether there are alternative ways to get the same result?

[jsturtevant]

This provides a narrow, type-safe accessor for downstream consumers (e.g., Nanvix) that need to write data into the sandbox's shared memory region before initialization

What region is it writing too?

I wouldn't like this to be part of the public API. Can we go into a little more detail about how this is being used right now, and whether there are alternative ways to get the same result?

If we constrained the usage to something like write_shared_mem(&mut self, src: &[u8], offset: usize) where we could do checks and things would the be helpful?

[ludfjig]

The main worry I have is public usage of this API which is probably somethign we don't want. I'd also want to know what it's useful more specifically, but I'd be open to add this under a new feature flag with maybe a scary name since that would discourage general use

[jsturtevant]

The main worry I have is public usage of this API which is probably somethign we don't want. I'd also want to know what it's useful more specifically, but I'd be open to add this under a new feature flag with maybe a scary name since that would discourage general use

hmm, it seems the requirement is some system need some extra metadata during boot sequence, I wonder for those systems not using paging (or maybe even with paging), if they could use the sratch region or a subset of it?

[dblnz]

I have the same concerns other people mentioned around here. Exposing an implementation detail binds us to keeping it that way.
Maybe we can find another way to do this that doesn't imply knowing the memory layout to be able to interact with the API.

[danbugs]

Addressed the concerns about exposing shared_mem_mut() as a public API. The latest push replaces it with:

pub fn guest_memory_ptr(&mut self, gpa: u64) -> Result<*mut u8>

This does bounds-checked GPA-to-host-pointer translation — the caller provides a guest physical address and gets back a host pointer into the mapped sandbox memory. The API no longer exposes SharedMemory internals or the memory manager.

Nanvix uses this for its credits-based flow control: the host and guest agree on a fixed GPA (CREDITS_GPA, last 8 bytes of the kernel pool) where a shared credit counter lives. The host increments/decrements the counter via volatile writes through this pointer, and the guest reads it directly from memory.

This is narrower than the previous shared_mem_mut() approach: it validates that the GPA falls within the sandbox's mapped region and returns an error otherwise. It doesn't expose the base pointer or total size, so callers can't accidentally access memory outside their intended range.