Struct machina_virtio_device::DeviceBuilder

pub struct DeviceBuilder<N> { /* private fields */ }

Helper to process device messages and build a Device

The DeviceBuilder provides a stateful interface and can assist with process the startup messages for queue configuration that virtio devices need to undertake.

If a device needs full control of how messages are handled it can use the raw [add_queue] and [build] methods to build a Device, otherwise it is expected that config_builder_from_stream will typically be sufficient and automates the message loop.

Implementations

impl DeviceBuilder<()>

pub fn new(trap: Option<GuestBellTrap>, vmo: Option<Vmo>) -> DeviceBuilder<()>

Construct a new DeviceBuilder

This provides complete flexibility on processing the StartInfo, but typically it is expected that from_start_info is the more useful way to get a partially initialized DeviceBuilder.

If a GuestBellTrap exists it can optionally be provided here. If not provided then the final Device will not have the trap, although users can always process the stream of trap notifications themselves.

impl<N> DeviceBuilder<N>

pub fn map_notify<N2>( self, map: impl FnOnce(N) -> Result<N2, DeviceError> ) -> Result<DeviceBuilder<N2>, DeviceError>

Check if a trap has been configured.

Since it is an error to [set_trap] if one already exists Change the notify to a different type.

Passes the current notification object to the provided function, and stores any success result as the new notify.

When building the final Device the internal notify will be given to each [Queue] that is constructed. Initially the notify type N will always be NotifyEvent and is created from the [zx::Event] provided in the [StartInfo`].

The normal reason to want to change the notify type is to interpose a [BufferedNotify] (virtio_device::util::BufferedNotify).

builder.map_notify(
    |e| Result::<_, zx::Status>::Ok(virtio_device::util::BufferedNotify::new(e))
)

pub fn add_queue(self, config: QueueConfig) -> Result<Self, DeviceError>

Add the specified QueueConfig to the list of queues.

This just records the QueueConfig and aside from ensuring config.queue is not a duplicate, no further validation is done. The [Queue] itself will get build in the [build] step after all queues have been specified.

pub fn configured_queues(&self) -> impl Iterator<Item = u16> + '_

Query the queues configured so far.

Returns an iterator of the queue numbers that have been configured so far in the builder.

pub fn take_vmo(&mut self) -> Option<Vmo>

Allow virtio devices to take the guest zx::Vmo. If the zx::Vmo is not taken it will be dropped as part of the DeviceBuilder::build call

Returns an option to guest vmo

impl<N: Clone> DeviceBuilder<N>

pub fn build<'a, M: DriverMem>( self, negotiated_features: u32, mem: &'a M ) -> Result<Device<'a, N>, DeviceError>

Build a Device from the current builder state.

This builds all of the queues the were configured and constructs the final Device. The negotiated features and a [DriverMem] need to given here for queue building.

Trait Implementations

impl<N: Debug> Debug for DeviceBuilder<N>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.