Struct rutabaga_gfx::Rutabaga

pub struct Rutabaga {
    resources: BTreeMap<u32, RutabagaResource>,
    contexts: BTreeMap<u32, Box<dyn RutabagaContext>>,
    components: BTreeMap<RutabagaComponentType, Box<dyn RutabagaComponent>>,
    default_component: RutabagaComponentType,
    capset_info: Vec<RutabagaCapsetInfo>,
    fence_handler: RutabagaFenceHandler,
}

The global libary handle used to query capability sets, create resources and contexts.

Currently, Rutabaga only supports one default component. Many components running at the same time is a stretch goal of Rutabaga GFX.

Not thread-safe, but can be made so easily. Making non-Rutabaga, C/C++ components thread-safe is more difficult.

Fields

resources: BTreeMap<u32, RutabagaResource>

contexts: BTreeMap<u32, Box<dyn RutabagaContext>>

components: BTreeMap<RutabagaComponentType, Box<dyn RutabagaComponent>>

default_component: RutabagaComponentType

capset_info: Vec<RutabagaCapsetInfo>

fence_handler: RutabagaFenceHandler

Implementations

impl Rutabaga

pub fn snapshot( &self, w: &mut impl Write, directory: &str ) -> RutabagaResult<()>

Take a snapshot of Rutabaga’s current state. The snapshot is serialized into an opaque byte stream and written to w.

pub fn restore( &mut self, r: &mut impl Read, directory: &str ) -> RutabagaResult<()>

Restore Rutabaga to a previously snapshot’d state.

Snapshotting on one host machine and then restoring on another (“host migration”) might work for very similar machines but isn’t explicitly supported yet.

Rutabaga will recreate resources internally, but it’s the VMM’s responsibility to re-attach backing iovecs and re-map the memory after re-creation. Specifically:

• Mode2D
  • The VMM must call Rutabaga::attach_backing calls for all resources that had backing memory at the time of the snapshot.
• ModeVirglRenderer
  • Not supported.
• ModeGfxstream
  • WiP support.

NOTES: This is required because the pointers to backing memory aren’t stable, help from the VMM is necessary. In an alternative approach, the VMM could supply Rutabaga with callbacks to translate to/from stable guest physical addresses, but it is unclear how well that approach would scale to support 3D modes, which have others problems that require VMM help, like resource handles.

fn capset_id_to_component_type( &self, capset_id: u32 ) -> RutabagaResult<RutabagaComponentType>

fn capset_index_to_component_info( &self, index: u32 ) -> RutabagaResult<RutabagaCapsetInfo>

pub fn get_capset_info(&self, index: u32) -> RutabagaResult<(u32, u32, u32)>

Gets the version and size for the capabilty set index.

pub fn get_capset( &self, capset_id: u32, version: u32 ) -> RutabagaResult<Vec<u8>>

Gets the capability set for the capset_id and version. Each capability set is associated with a context type, which is associated with a rutabaga component.

pub fn get_num_capsets(&self) -> u32

Gets the number of capsets

pub fn force_ctx_0(&self)

Forces context zero for the default rutabaga component.

pub fn create_fence(&mut self, fence: RutabagaFence) -> RutabagaResult<()>

Creates a fence with the given fence. If the flags include RUTABAGA_FLAG_INFO_RING_IDX, then the fence is created on a specific timeline on the specific context.

pub fn event_poll(&self)

Polls the default rutabaga component.

pub fn poll_descriptor(&self) -> Option<SafeDescriptor>

Returns a pollable descriptor for the default rutabaga component. In practice, it is only not None if the default component is virglrenderer.

pub fn resource_create_3d( &mut self, resource_id: u32, resource_create_3d: ResourceCreate3D ) -> RutabagaResult<()>

Creates a resource with the resource_create_3d metadata.

pub fn attach_backing( &mut self, resource_id: u32, vecs: Vec<RutabagaIovec> ) -> RutabagaResult<()>

Attaches vecs to the resource.

pub fn detach_backing(&mut self, resource_id: u32) -> RutabagaResult<()>

Detaches any previously attached iovecs from the resource.

pub fn unref_resource(&mut self, resource_id: u32) -> RutabagaResult<()>

Releases guest kernel reference on the resource.

pub fn transfer_write( &mut self, ctx_id: u32, resource_id: u32, transfer: Transfer3D ) -> RutabagaResult<()>

For HOST3D_GUEST resources, copies from the attached iovecs to the host resource. For HOST3D resources, this may flush caches, though this feature is unused by guest userspace.

pub fn transfer_read( &mut self, ctx_id: u32, resource_id: u32, transfer: Transfer3D, buf: Option<IoSliceMut<'_>> ) -> RutabagaResult<()>

1. If specified, copies to buf from the host resource.
2. Otherwise, for HOST3D_GUEST resources, copies to the attached iovecs from the host resource. For HOST3D resources, this may invalidate caches, though this feature is unused by guest userspace.

pub fn resource_flush(&mut self, resource_id: u32) -> RutabagaResult<()>

pub fn resource_create_blob( &mut self, ctx_id: u32, resource_id: u32, resource_create_blob: ResourceCreateBlob, iovecs: Option<Vec<RutabagaIovec>>, handle: Option<RutabagaHandle> ) -> RutabagaResult<()>

Creates a blob resource with the ctx_id and resource_create_blob metadata. Associates iovecs with the resource, if there are any. Associates externally created handle with the resource, if there is any.

pub fn map(&mut self, resource_id: u32) -> RutabagaResult<RutabagaMapping>

Returns a memory mapping of the blob resource.

pub fn unmap(&mut self, resource_id: u32) -> RutabagaResult<()>

Unmaps the blob resource from the default component

pub fn map_info(&self, resource_id: u32) -> RutabagaResult<u32>

Returns the map_info of the blob resource. The valid values for map_info are defined in the virtio-gpu spec.

pub fn vulkan_info(&self, resource_id: u32) -> RutabagaResult<VulkanInfo>

Returns the vulkan_info of the blob resource, which consists of the physical device index and memory index associated with the resource.

pub fn query(&self, resource_id: u32) -> RutabagaResult<Resource3DInfo>

Returns the 3D info associated with the resource, if any.

pub fn export_blob( &mut self, resource_id: u32 ) -> RutabagaResult<RutabagaHandle>

Exports a blob resource. See virtio-gpu spec for blob flag use flags.

pub fn export_fence(&self, fence_id: u64) -> RutabagaResult<RutabagaHandle>

Exports the given fence for import into other processes.

pub fn create_context( &mut self, ctx_id: u32, context_init: u32, context_name: Option<&str> ) -> RutabagaResult<()>

Creates a context with the given ctx_id and context_init variable. context_init is used to determine which rutabaga component creates the context.

pub fn destroy_context(&mut self, ctx_id: u32) -> RutabagaResult<()>

Destroys the context given by ctx_id.

pub fn context_attach_resource( &mut self, ctx_id: u32, resource_id: u32 ) -> RutabagaResult<()>

Attaches the resource given by resource_id to the context given by ctx_id.

pub fn context_detach_resource( &mut self, ctx_id: u32, resource_id: u32 ) -> RutabagaResult<()>

Detaches the resource given by resource_id from the context given by ctx_id.

pub fn submit_command( &mut self, ctx_id: u32, commands: &mut [u8], fence_ids: &[u64] ) -> RutabagaResult<()>

submits commands to the context given by ctx_id.