hyperlight-common 0.16.0

/*
Copyright 2026  The Hyperlight Authors.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
*/

//! Memory Access Traits for Virtqueue Operations
//!
//! This module defines the [`MemOps`] trait that abstracts memory access patterns
//! required by the virtqueue implementation. This allows the virtqueue code to
//! work with different memory backends e.g. Host vs Guest.

use alloc::sync::Arc;

use bytemuck::Pod;

/// Backend-provided memory access for virtqueue.
///
/// # Safety
///
/// Implementations must ensure that:
/// - Addresses accepted by these methods are translated according to the
///   backend's memory model.
/// - Invalid or inaccessible addresses are reported with `Self::Error` rather
///   than causing undefined behavior.
/// - Memory ordering guarantees are upheld as documented.
/// - Typed reads/writes and atomic operations honor alignment and initialized
///   memory requirements for the translated addresses.
///
/// [`RingProducer`]: super::RingProducer
/// [`RingConsumer`]: super::RingConsumer
pub unsafe trait MemOps {
    type Error;

    /// Read bytes from physical memory.
    ///
    /// Used for reading buffer contents pointed to by descriptors.
    ///
    /// # Arguments
    ///
    /// * `addr` - Guest physical address to read from
    /// * `dst` - Destination buffer to fill
    ///
    /// Implementations must return an error if `addr` cannot be read for
    /// at least `dst.len()` bytes.
    fn read(&self, addr: u64, dst: &mut [u8]) -> Result<(), Self::Error>;

    /// Write bytes to physical memory.
    ///
    /// # Arguments
    ///
    /// * `addr` - address to write to
    /// * `src` - Source data to write
    ///
    /// Implementations must return an error if `addr` cannot be written for
    /// at least `src.len()` bytes.
    fn write(&self, addr: u64, src: &[u8]) -> Result<(), Self::Error>;

    /// Load a u16 with acquire semantics.
    ///
    /// Implementations must return an error if `addr` does not translate to a
    /// valid, aligned `AtomicU16` in shared memory.
    fn load_acquire(&self, addr: u64) -> Result<u16, Self::Error>;

    /// Store a u16 with release semantics.
    ///
    /// Implementations must return an error if `addr` does not translate to a
    /// valid, aligned `AtomicU16` in shared memory.
    fn store_release(&self, addr: u64, val: u16) -> Result<(), Self::Error>;

    /// Get a direct read-only slice into shared memory.
    ///
    /// # Safety
    ///
    /// The caller must ensure:
    /// - `addr` is valid and points to at least `len` bytes.
    /// - The memory region is not concurrently modified for the lifetime of
    ///   the returned slice. Caller must uphold this via protocol-level
    ///   synchronisation, e.g. descriptor ownership transfer.
    ///
    /// See also [`BufferOwner`]: super::BufferOwner
    unsafe fn as_slice(&self, addr: u64, len: usize) -> Result<&[u8], Self::Error>;

    /// Get a direct mutable slice into shared memory.
    ///
    /// # Safety
    ///
    /// The caller must ensure:
    /// - `addr` is valid and points to at least `len` bytes.
    /// - No other references (shared or mutable) to this memory region exist
    ///   for the lifetime of the returned slice.
    /// - Protocol-level synchronisation (e.g. descriptor ownership) guarantees
    ///   exclusive access.
    #[allow(clippy::mut_from_ref)]
    unsafe fn as_mut_slice(&self, addr: u64, len: usize) -> Result<&mut [u8], Self::Error>;

    /// Read a Pod type at the given pointer.
    ///
    /// Implementations must return an error if `addr` is not valid, aligned,
    /// and initialized for `T`.
    fn read_val<T: Pod>(&self, addr: u64) -> Result<T, Self::Error> {
        let mut val = T::zeroed();
        let bytes = bytemuck::bytes_of_mut(&mut val);

        self.read(addr, bytes)?;
        Ok(val)
    }

    /// Write a Pod type at the given pointer.
    ///
    /// Implementations must return an error if `addr` is not valid and aligned
    /// for `T`.
    fn write_val<T: Pod>(&self, addr: u64, val: T) -> Result<(), Self::Error> {
        let bytes = bytemuck::bytes_of(&val);
        self.write(addr, bytes)?;
        Ok(())
    }
}

// SAFETY: Arc delegates all memory operations to the wrapped backend, preserving
// that backend's MemOps contract.
unsafe impl<T: MemOps> MemOps for Arc<T> {
    type Error = T::Error;

    fn read(&self, addr: u64, dst: &mut [u8]) -> Result<(), Self::Error> {
        (**self).read(addr, dst)
    }

    fn write(&self, addr: u64, src: &[u8]) -> Result<(), Self::Error> {
        (**self).write(addr, src)
    }

    fn load_acquire(&self, addr: u64) -> Result<u16, Self::Error> {
        (**self).load_acquire(addr)
    }

    fn store_release(&self, addr: u64, val: u16) -> Result<(), Self::Error> {
        (**self).store_release(addr, val)
    }

    unsafe fn as_slice(&self, addr: u64, len: usize) -> Result<&[u8], Self::Error> {
        unsafe { (**self).as_slice(addr, len) }
    }

    #[allow(clippy::mut_from_ref)]
    unsafe fn as_mut_slice(&self, addr: u64, len: usize) -> Result<&mut [u8], Self::Error> {
        unsafe { (**self).as_mut_slice(addr, len) }
    }
}