DriveBuilder

qemu_command_builder::drive

Struct DriveBuilder 

Source 
pub struct DriveBuilder<S: State = Empty> { /* private fields */ }
Expand description

Use builder syntax to set the inputs and finish with build().

Implementations§

Source§

impl<S: State> DriveBuilder<S>

Source

pub fn build(self) -> Drive
where S: IsComplete,

Finish building and return the requested object

Source

pub fn node_name(self, value: String) -> DriveBuilder<SetNodeName<S>>
where S::NodeName: IsUnset,

Optional (Some / Option setters).

This defines the name of the block driver node by which it will be referenced later. The name must be unique, i.e. it must not match the name of a different block driver node, or (if you use -drive as well) the ID of a drive.

If no node name is specified, it is automatically generated. The generated node name is not intended to be predictable and changes between QEMU invocations. For the top level, an explicit node name must be specified.

Source

pub fn maybe_node_name( self, value: Option<String>, ) -> DriveBuilder<SetNodeName<S>>
where S::NodeName: IsUnset,

Optional (Some / Option setters).

This defines the name of the block driver node by which it will be referenced later. The name must be unique, i.e. it must not match the name of a different block driver node, or (if you use -drive as well) the ID of a drive.

If no node name is specified, it is automatically generated. The generated node name is not intended to be predictable and changes between QEMU invocations. For the top level, an explicit node name must be specified.

Source

pub fn discard(self, value: IgnoreUnmap) -> DriveBuilder<SetDiscard<S>>
where S::Discard: IsUnset,

Optional (Some / Option setters).

discard is one of “ignore” (or “off”) or “unmap” (or “on”) and controls whether discard (also known as trim or unmap) requests are ignored or passed to the filesystem. Some machine types may not support discard requests.

Source

pub fn maybe_discard( self, value: Option<IgnoreUnmap>, ) -> DriveBuilder<SetDiscard<S>>
where S::Discard: IsUnset,

Optional (Some / Option setters).

discard is one of “ignore” (or “off”) or “unmap” (or “on”) and controls whether discard (also known as trim or unmap) requests are ignored or passed to the filesystem. Some machine types may not support discard requests.

Source

pub fn cache_direct(self, value: OnOff) -> DriveBuilder<SetCacheDirect<S>>
where S::CacheDirect: IsUnset,

Optional (Some / Option setters).

The host page cache can be avoided with cache.direct=on. This will attempt to do disk IO directly to the guest’s memory. QEMU may still perform an internal copy of the data.

Source

pub fn maybe_cache_direct( self, value: Option<OnOff>, ) -> DriveBuilder<SetCacheDirect<S>>
where S::CacheDirect: IsUnset,

Optional (Some / Option setters).

The host page cache can be avoided with cache.direct=on. This will attempt to do disk IO directly to the guest’s memory. QEMU may still perform an internal copy of the data.

Source

pub fn cache_no_flush(self, value: OnOff) -> DriveBuilder<SetCacheNoFlush<S>>
where S::CacheNoFlush: IsUnset,

Optional (Some / Option setters).

In case you don’t care about data integrity over host failures, you can use cache.no-flush=on. This option tells QEMU that it never needs to write any data to the disk but can instead keep things in cache. If anything goes wrong, like your host losing power, the disk storage getting disconnected accidentally, etc. your image will most probably be rendered unusable.

Source

pub fn maybe_cache_no_flush( self, value: Option<OnOff>, ) -> DriveBuilder<SetCacheNoFlush<S>>
where S::CacheNoFlush: IsUnset,

Optional (Some / Option setters).

In case you don’t care about data integrity over host failures, you can use cache.no-flush=on. This option tells QEMU that it never needs to write any data to the disk but can instead keep things in cache. If anything goes wrong, like your host losing power, the disk storage getting disconnected accidentally, etc. your image will most probably be rendered unusable.

Source

pub fn read_only(self, value: OnOff) -> DriveBuilder<SetReadOnly<S>>
where S::ReadOnly: IsUnset,

Optional (Some / Option setters).

Open the node read-only. Guest write attempts will fail.

Note that some block drivers support only read-only access, either generally or in certain configurations. In this case, the default value read-only=off does not work and the option must be specified explicitly.

Source

pub fn maybe_read_only( self, value: Option<OnOff>, ) -> DriveBuilder<SetReadOnly<S>>
where S::ReadOnly: IsUnset,

Optional (Some / Option setters).

Open the node read-only. Guest write attempts will fail.

Note that some block drivers support only read-only access, either generally or in certain configurations. In this case, the default value read-only=off does not work and the option must be specified explicitly.

Source

pub fn auto_read_only(self, value: OnOff) -> DriveBuilder<SetAutoReadOnly<S>>
where S::AutoReadOnly: IsUnset,

Optional (Some / Option setters).

If auto-read-only=on is set, QEMU may fall back to read-only usage even when read-only=off is requested, or even switch between modes as needed, e.g. depending on whether the image file is writable or whether a writing user is attached to the node.

Source

pub fn maybe_auto_read_only( self, value: Option<OnOff>, ) -> DriveBuilder<SetAutoReadOnly<S>>
where S::AutoReadOnly: IsUnset,

Optional (Some / Option setters).

If auto-read-only=on is set, QEMU may fall back to read-only usage even when read-only=off is requested, or even switch between modes as needed, e.g. depending on whether the image file is writable or whether a writing user is attached to the node.

Source

pub fn force_share(self, value: OnOff) -> DriveBuilder<SetForceShare<S>>
where S::ForceShare: IsUnset,

Optional (Some / Option setters).

Override the image locking system of QEMU by forcing the node to utilize weaker shared access for permissions where it would normally request exclusive access. When there is the potential for multiple instances to have the same file open (whether this invocation of QEMU is the first or the second instance), both instances must permit shared access for the second instance to succeed at opening the file.

Enabling force-share=on requires read-only=on.

Source

pub fn maybe_force_share( self, value: Option<OnOff>, ) -> DriveBuilder<SetForceShare<S>>
where S::ForceShare: IsUnset,

Optional (Some / Option setters).

Override the image locking system of QEMU by forcing the node to utilize weaker shared access for permissions where it would normally request exclusive access. When there is the potential for multiple instances to have the same file open (whether this invocation of QEMU is the first or the second instance), both instances must permit shared access for the second instance to succeed at opening the file.

Enabling force-share=on requires read-only=on.

Source

pub fn detect_zeroes( self, value: OnOffUnmap, ) -> DriveBuilder<SetDetectZeroes<S>>
where S::DetectZeroes: IsUnset,

Optional (Some / Option setters).

detect-zeroes is “off”, “on” or “unmap” and enables the automatic conversion of plain zero writes by the OS to driver specific optimized zero write commands. You may even choose “unmap” if discard is set to “unmap” to allow a zero write to be converted to an unmap operation.

Source

pub fn maybe_detect_zeroes( self, value: Option<OnOffUnmap>, ) -> DriveBuilder<SetDetectZeroes<S>>
where S::DetectZeroes: IsUnset,

Optional (Some / Option setters).

detect-zeroes is “off”, “on” or “unmap” and enables the automatic conversion of plain zero writes by the OS to driver specific optimized zero write commands. You may even choose “unmap” if discard is set to “unmap” to allow a zero write to be converted to an unmap operation.

Source

pub fn file(self, value: PathBuf) -> DriveBuilder<SetFile<S>>
where S::File: IsUnset,

Optional (Some / Option setters).

This option defines which disk image (see the :ref:disk images chapter in the System Emulation Users Guide) to use with this drive. If the filename contains comma, you must double it (for instance, “file=my,,file” to use file “my,file”).

Special files such as iSCSI devices can be specified using protocol specific URLs. See the section for “Device URL Syntax” for more information.

Source

pub fn maybe_file(self, value: Option<PathBuf>) -> DriveBuilder<SetFile<S>>
where S::File: IsUnset,

Optional (Some / Option setters).

This option defines which disk image (see the :ref:disk images chapter in the System Emulation Users Guide) to use with this drive. If the filename contains comma, you must double it (for instance, “file=my,,file” to use file “my,file”).

Special files such as iSCSI devices can be specified using protocol specific URLs. See the section for “Device URL Syntax” for more information.

Source

pub fn interface(self, value: DriveInterface) -> DriveBuilder<SetInterface<S>>
where S::Interface: IsUnset,

Optional (Some / Option setters).

This option defines on which type on interface the drive is connected. Available types are: ide, scsi, sd, mtd, floppy, pflash, virtio, none.

Source

pub fn maybe_interface( self, value: Option<DriveInterface>, ) -> DriveBuilder<SetInterface<S>>
where S::Interface: IsUnset,

Optional (Some / Option setters).

This option defines on which type on interface the drive is connected. Available types are: ide, scsi, sd, mtd, floppy, pflash, virtio, none.

Source

pub fn bus(self, value: usize) -> DriveBuilder<SetBus<S>>
where S::Bus: IsUnset,

Optional (Some / Option setters).

These options define where is connected the drive by defining the bus number and the unit id.

Source

pub fn maybe_bus(self, value: Option<usize>) -> DriveBuilder<SetBus<S>>
where S::Bus: IsUnset,

Optional (Some / Option setters).

These options define where is connected the drive by defining the bus number and the unit id.

Source

pub fn unit(self, value: usize) -> DriveBuilder<SetUnit<S>>
where S::Unit: IsUnset,

Optional (Some / Option setters).

Source

pub fn maybe_unit(self, value: Option<usize>) -> DriveBuilder<SetUnit<S>>
where S::Unit: IsUnset,

Optional (Some / Option setters).

Source

pub fn index(self, value: String) -> DriveBuilder<SetIndex<S>>
where S::Index: IsUnset,

Optional (Some / Option setters).

This option defines where the drive is connected by using an index in the list of available connectors of a given interface type.

Source

pub fn maybe_index(self, value: Option<String>) -> DriveBuilder<SetIndex<S>>
where S::Index: IsUnset,

Optional (Some / Option setters).

This option defines where the drive is connected by using an index in the list of available connectors of a given interface type.

Source

pub fn media(self, value: DriveMedia) -> DriveBuilder<SetMedia<S>>
where S::Media: IsUnset,

Optional (Some / Option setters).

This option defines the type of the media: disk or cdrom.

Source

pub fn maybe_media(self, value: Option<DriveMedia>) -> DriveBuilder<SetMedia<S>>
where S::Media: IsUnset,

Optional (Some / Option setters).

This option defines the type of the media: disk or cdrom.

Source

pub fn snapshot(self, value: OnOff) -> DriveBuilder<SetSnapshot<S>>
where S::Snapshot: IsUnset,

Optional (Some / Option setters).

snapshot is “on” or “off” and controls snapshot mode for the given drive (see -snapshot).

Source

pub fn maybe_snapshot( self, value: Option<OnOff>, ) -> DriveBuilder<SetSnapshot<S>>
where S::Snapshot: IsUnset,

Optional (Some / Option setters).

snapshot is “on” or “off” and controls snapshot mode for the given drive (see -snapshot).

Source

pub fn cache(self, value: DriveCacheType) -> DriveBuilder<SetCache<S>>
where S::Cache: IsUnset,

Optional (Some / Option setters).

cache is “none”, “writeback”, “unsafe”, “directsync” or “writethrough” and controls how the host cache is used to access block data. This is a shortcut that sets the cache.direct and cache.no-flush options (as in -blockdev), and additionally cache.writeback, which provides a default for the write-cache option of block guest devices (as in -device). The modes correspond to the following settings:

============= =============== ============ ============== \ cache.writeback cache.direct cache.no-flush ============= =============== ============ ============== writeback on off off none on on off writethrough off off off directsync off on off unsafe on off on ============= =============== ============ ==============

The default mode is cache=writeback.

Source

pub fn maybe_cache( self, value: Option<DriveCacheType>, ) -> DriveBuilder<SetCache<S>>
where S::Cache: IsUnset,

Optional (Some / Option setters).

cache is “none”, “writeback”, “unsafe”, “directsync” or “writethrough” and controls how the host cache is used to access block data. This is a shortcut that sets the cache.direct and cache.no-flush options (as in -blockdev), and additionally cache.writeback, which provides a default for the write-cache option of block guest devices (as in -device). The modes correspond to the following settings:

============= =============== ============ ============== \ cache.writeback cache.direct cache.no-flush ============= =============== ============ ============== writeback on off off none on on off writethrough off off off directsync off on off unsafe on off on ============= =============== ============ ==============

The default mode is cache=writeback.

Source

pub fn id(self, value: String) -> DriveBuilder<SetId<S>>
where S::Id: IsUnset,

Optional (Some / Option setters).

Source

pub fn maybe_id(self, value: Option<String>) -> DriveBuilder<SetId<S>>
where S::Id: IsUnset,

Optional (Some / Option setters).

Source

pub fn aio(self, value: DriveAIOType) -> DriveBuilder<SetAio<S>>
where S::Aio: IsUnset,

Optional (Some / Option setters).

aio is “threads”, “native”, or “io_uring” and selects between pthread based disk I/O, native Linux AIO, or Linux io_uring API.

Source

pub fn maybe_aio(self, value: Option<DriveAIOType>) -> DriveBuilder<SetAio<S>>
where S::Aio: IsUnset,

Optional (Some / Option setters).

aio is “threads”, “native”, or “io_uring” and selects between pthread based disk I/O, native Linux AIO, or Linux io_uring API.

Source

pub fn format(self, value: String) -> DriveBuilder<SetFormat<S>>
where S::Format: IsUnset,

Optional (Some / Option setters).

Specify which disk format will be used rather than detecting the format. Can be used to specify format=raw to avoid interpreting an untrusted format header.

Source

pub fn maybe_format(self, value: Option<String>) -> DriveBuilder<SetFormat<S>>
where S::Format: IsUnset,

Optional (Some / Option setters).

Specify which disk format will be used rather than detecting the format. Can be used to specify format=raw to avoid interpreting an untrusted format header.

Source

pub fn rerror(self, value: DriveErrorAction) -> DriveBuilder<SetRerror<S>>
where S::Rerror: IsUnset,

Optional (Some / Option setters).

Specify which action to take on write and read errors. Valid actions are: “ignore” (ignore the error and try to continue), “stop” (pause QEMU), “report” (report the error to the guest), “enospc” (pause QEMU only if the host disk is full; report the error to the guest otherwise). The default setting is werror=enospc and rerror=report.

Source

pub fn maybe_rerror( self, value: Option<DriveErrorAction>, ) -> DriveBuilder<SetRerror<S>>
where S::Rerror: IsUnset,

Optional (Some / Option setters).

Specify which action to take on write and read errors. Valid actions are: “ignore” (ignore the error and try to continue), “stop” (pause QEMU), “report” (report the error to the guest), “enospc” (pause QEMU only if the host disk is full; report the error to the guest otherwise). The default setting is werror=enospc and rerror=report.

Source

pub fn werror(self, value: DriveErrorAction) -> DriveBuilder<SetWerror<S>>
where S::Werror: IsUnset,

Optional (Some / Option setters).

Source

pub fn maybe_werror( self, value: Option<DriveErrorAction>, ) -> DriveBuilder<SetWerror<S>>
where S::Werror: IsUnset,

Optional (Some / Option setters).

Source

pub fn copy_on_ready(self, value: OnOff) -> DriveBuilder<SetCopyOnReady<S>>
where S::CopyOnReady: IsUnset,

Optional (Some / Option setters).

copy-on-read is “on” or “off” and enables whether to copy read backing file sectors into the image file.

Source

pub fn maybe_copy_on_ready( self, value: Option<OnOff>, ) -> DriveBuilder<SetCopyOnReady<S>>
where S::CopyOnReady: IsUnset,

Optional (Some / Option setters).

copy-on-read is “on” or “off” and enables whether to copy read backing file sectors into the image file.

Source

pub fn bps(self, value: usize) -> DriveBuilder<SetBps<S>>
where S::Bps: IsUnset,

Optional (Some / Option setters).

Specify bandwidth throttling limits in bytes per second, either for all request types or for reads or writes only. Small values can lead to timeouts or hangs inside the guest. A safe minimum for disks is 2 MB/s.

Source

pub fn maybe_bps(self, value: Option<usize>) -> DriveBuilder<SetBps<S>>
where S::Bps: IsUnset,

Optional (Some / Option setters).

Specify bandwidth throttling limits in bytes per second, either for all request types or for reads or writes only. Small values can lead to timeouts or hangs inside the guest. A safe minimum for disks is 2 MB/s.

Source

pub fn bps_rd(self, value: usize) -> DriveBuilder<SetBpsRd<S>>
where S::BpsRd: IsUnset,

Optional (Some / Option setters).

Source

pub fn maybe_bps_rd(self, value: Option<usize>) -> DriveBuilder<SetBpsRd<S>>
where S::BpsRd: IsUnset,

Optional (Some / Option setters).

Source

pub fn bps_wr(self, value: usize) -> DriveBuilder<SetBpsWr<S>>
where S::BpsWr: IsUnset,

Optional (Some / Option setters).

Source

pub fn maybe_bps_wr(self, value: Option<usize>) -> DriveBuilder<SetBpsWr<S>>
where S::BpsWr: IsUnset,

Optional (Some / Option setters).

Source

pub fn bps_max(self, value: usize) -> DriveBuilder<SetBpsMax<S>>
where S::BpsMax: IsUnset,

Optional (Some / Option setters).

Specify bursts in bytes per second, either for all request types or for reads or writes only. Bursts allow the guest I/O to spike above the limit temporarily.

Source

pub fn maybe_bps_max(self, value: Option<usize>) -> DriveBuilder<SetBpsMax<S>>
where S::BpsMax: IsUnset,

Optional (Some / Option setters).

Specify bursts in bytes per second, either for all request types or for reads or writes only. Bursts allow the guest I/O to spike above the limit temporarily.

Source

pub fn bps_rd_max(self, value: usize) -> DriveBuilder<SetBpsRdMax<S>>
where S::BpsRdMax: IsUnset,

Optional (Some / Option setters).

Source

pub fn maybe_bps_rd_max( self, value: Option<usize>, ) -> DriveBuilder<SetBpsRdMax<S>>
where S::BpsRdMax: IsUnset,

Optional (Some / Option setters).

Source

pub fn bps_wr_max(self, value: usize) -> DriveBuilder<SetBpsWrMax<S>>
where S::BpsWrMax: IsUnset,

Optional (Some / Option setters).

Source

pub fn maybe_bps_wr_max( self, value: Option<usize>, ) -> DriveBuilder<SetBpsWrMax<S>>
where S::BpsWrMax: IsUnset,

Optional (Some / Option setters).

Source

pub fn iops(self, value: usize) -> DriveBuilder<SetIops<S>>
where S::Iops: IsUnset,

Optional (Some / Option setters).

Specify request rate limits in requests per second, either for all request types or for reads or writes only.

Source

pub fn maybe_iops(self, value: Option<usize>) -> DriveBuilder<SetIops<S>>
where S::Iops: IsUnset,

Optional (Some / Option setters).

Specify request rate limits in requests per second, either for all request types or for reads or writes only.

Source

pub fn iops_rd(self, value: usize) -> DriveBuilder<SetIopsRd<S>>
where S::IopsRd: IsUnset,

Optional (Some / Option setters).

Source

pub fn maybe_iops_rd(self, value: Option<usize>) -> DriveBuilder<SetIopsRd<S>>
where S::IopsRd: IsUnset,

Optional (Some / Option setters).

Source

pub fn iops_wr(self, value: usize) -> DriveBuilder<SetIopsWr<S>>
where S::IopsWr: IsUnset,

Optional (Some / Option setters).

Source

pub fn maybe_iops_wr(self, value: Option<usize>) -> DriveBuilder<SetIopsWr<S>>
where S::IopsWr: IsUnset,

Optional (Some / Option setters).

Source

pub fn iops_max(self, value: usize) -> DriveBuilder<SetIopsMax<S>>
where S::IopsMax: IsUnset,

Optional (Some / Option setters).

Specify bursts in requests per second, either for all request types or for reads or writes only. Bursts allow the guest I/O to spike above the limit temporarily.

Source

pub fn maybe_iops_max(self, value: Option<usize>) -> DriveBuilder<SetIopsMax<S>>
where S::IopsMax: IsUnset,

Optional (Some / Option setters).

Specify bursts in requests per second, either for all request types or for reads or writes only. Bursts allow the guest I/O to spike above the limit temporarily.

Source

pub fn iops_rd_max(self, value: usize) -> DriveBuilder<SetIopsRdMax<S>>
where S::IopsRdMax: IsUnset,

Optional (Some / Option setters).

Source

pub fn maybe_iops_rd_max( self, value: Option<usize>, ) -> DriveBuilder<SetIopsRdMax<S>>
where S::IopsRdMax: IsUnset,

Optional (Some / Option setters).

Source

pub fn iops_wr_max(self, value: usize) -> DriveBuilder<SetIopsWrMax<S>>
where S::IopsWrMax: IsUnset,

Optional (Some / Option setters).

Source

pub fn maybe_iops_wr_max( self, value: Option<usize>, ) -> DriveBuilder<SetIopsWrMax<S>>
where S::IopsWrMax: IsUnset,

Optional (Some / Option setters).

Source

pub fn iops_size(self, value: usize) -> DriveBuilder<SetIopsSize<S>>
where S::IopsSize: IsUnset,

Optional (Some / Option setters).

Let every is bytes of a request count as a new request for iops throttling purposes. Use this option to prevent guests from circumventing iops limits by sending fewer but larger requests.

Source

pub fn maybe_iops_size( self, value: Option<usize>, ) -> DriveBuilder<SetIopsSize<S>>
where S::IopsSize: IsUnset,

Optional (Some / Option setters).

Let every is bytes of a request count as a new request for iops throttling purposes. Use this option to prevent guests from circumventing iops limits by sending fewer but larger requests.

Source

pub fn group(self, value: String) -> DriveBuilder<SetGroup<S>>
where S::Group: IsUnset,

Optional (Some / Option setters).

Join a throttling quota group with given name g. All drives that are members of the same group are accounted for together. Use this option to prevent guests from circumventing throttling limits by using many small disks instead of a single larger disk.

Source

pub fn maybe_group(self, value: Option<String>) -> DriveBuilder<SetGroup<S>>
where S::Group: IsUnset,

Optional (Some / Option setters).

Join a throttling quota group with given name g. All drives that are members of the same group are accounted for together. Use this option to prevent guests from circumventing throttling limits by using many small disks instead of a single larger disk.

Auto Trait Implementations§

§

impl<S> Freeze for DriveBuilder<S>

§

impl<S> RefUnwindSafe for DriveBuilder<S>

§

impl<S> Send for DriveBuilder<S>

§

impl<S> Sync for DriveBuilder<S>

§

impl<S> Unpin for DriveBuilder<S>

§

impl<S> UnwindSafe for DriveBuilder<S>

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = Infallible

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.