Struct MmapMappingManager 

pub struct MmapMappingManager<M: VirtioMediaHostMemoryMapper> { /* private fields */ }

Range manager for MMAP buffers, using a host memory mapper.

Devices that allocate MMAP buffers can register a buffer using Self::register_buffer and unregister them with Self::unregister_buffer. Registered buffers can then be mapped into the guest address space by calling Self::create_mapping on their offset. This will return the address of their guest mapping, which can then be accessed or used to unmap them with Self::remove_mapping.

Implementations

impl<M: VirtioMediaHostMemoryMapper> MmapMappingManager<M>

pub fn register_buffer( &mut self, offset: Option<u32>, size: u32, ) -> Result<u32, RegisterBufferError>

Registers a new buffer at offset. If offset if None, then an offset is allocated and returned.

This method fails if the range is full, or if offset is Some and the requested offset if already used by some other buffer. If offset is Some and the function succeed, then the returned value is guaranteed to be the passed offset.

Note that the ranges automatically allocated are of fixed size: only the offset of a buffer is relevant when mapping it, not its size. Real V4L2 drivers also use this trick of allocating ranges such that buffers appear to overlap. This is useful as the address space is technically 32-bit, and we might need to use buffers which added size would not fit.

TODO: we should recycle offsets, and further type MmapMappingManager so that only one allocation type can be used per instance (fixed or dynamic).

pub fn unregister_buffer(&mut self, offset: u32) -> bool

Unregisters the buffer previously registered at offset. Returns true if a buffer was indeed registered as starting at offset, false otherwise.

pub fn create_mapping( &mut self, offset: u32, fd: BorrowedFd<'_>, rw: bool, ) -> Result<(u64, u64), CreateMappingError>

Create a new mapping for the buffer registered at offset. rw indicates whether the mapping is read-only or read-write. Returns the guest address at which the buffer is mapped, and the size of the mapping, which should be equal to the size of the buffer.

This method can be called several times and will reuse the prior mapping if it exists. The mapping will also persist until an identical number of calls to Self::remove_mapping are performed.

Note however that requiring the same active mapping with different rw permissions will result in a EPERM error.

pub fn remove_mapping( &mut self, guest_addr: u64, ) -> Result<bool, RemoveMappingError>

Returns true if the buffer still has other mappings, false if this was the last mapping.

pub fn is_mapped(&self, offset: u64) -> bool

Returns true if the buffer registered at offset is already mapped.

pub fn into_mapper(self) -> M

Consume the mapping manager and return the mapper it has been constructed from.

Trait Implementations

impl<M: VirtioMediaHostMemoryMapper> From<M> for MmapMappingManager<M>

fn from(mapper: M) -> Self

Converts to this type from the input type.