pub struct Drive {Show 36 fields
pub node_name: Option<String>,
pub discard: Option<IgnoreUnmap>,
pub cache_direct: Option<OnOff>,
pub cache_no_flush: Option<OnOff>,
pub read_only: Option<OnOff>,
pub auto_read_only: Option<OnOff>,
pub force_share: Option<OnOff>,
pub detect_zeroes: Option<OnOffUnmap>,
pub file: Option<PathBuf>,
pub interface: Option<DriveInterface>,
pub bus: Option<usize>,
pub unit: Option<usize>,
pub index: Option<String>,
pub media: Option<DriveMedia>,
pub snapshot: Option<OnOff>,
pub cache: Option<DriveCacheType>,
pub id: Option<String>,
pub aio: Option<DriveAIOType>,
pub format: Option<String>,
pub rerror: Option<DriveErrorAction>,
pub werror: Option<DriveErrorAction>,
pub copy_on_ready: Option<OnOff>,
pub bps: Option<usize>,
pub bps_rd: Option<usize>,
pub bps_wr: Option<usize>,
pub bps_max: Option<usize>,
pub bps_rd_max: Option<usize>,
pub bps_wr_max: Option<usize>,
pub iops: Option<usize>,
pub iops_rd: Option<usize>,
pub iops_wr: Option<usize>,
pub iops_max: Option<usize>,
pub iops_rd_max: Option<usize>,
pub iops_wr_max: Option<usize>,
pub iops_size: Option<usize>,
pub group: Option<String>,
}Expand description
Define a new drive. This includes creating a block driver node (the
backend) as well as a guest device, and is mostly a shortcut for
defining the corresponding -blockdev and -device options.
-drive accepts all options that are accepted by -blockdev.
Fields§
§node_name: Option<String>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.
discard: Option<IgnoreUnmap>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.
cache_direct: Option<OnOff>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.
cache_no_flush: Option<OnOff>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.
read_only: Option<OnOff>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.
auto_read_only: Option<OnOff>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.
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.
detect_zeroes: Option<OnOffUnmap>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.
file: Option<PathBuf>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.
interface: Option<DriveInterface>This option defines on which type on interface the drive is connected. Available types are: ide, scsi, sd, mtd, floppy, pflash, virtio, none.
bus: Option<usize>These options define where is connected the drive by defining the bus number and the unit id.
unit: Option<usize>§index: Option<String>This option defines where the drive is connected by using an index in the list of available connectors of a given interface type.
media: Option<DriveMedia>This option defines the type of the media: disk or cdrom.
snapshot: Option<OnOff>snapshot is “on” or “off” and controls snapshot mode for the
given drive (see -snapshot).
cache: Option<DriveCacheType>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.
id: Option<String>§aio: Option<DriveAIOType>aio is “threads”, “native”, or “io_uring” and selects between pthread based disk I/O, native Linux AIO, or Linux io_uring API.
format: Option<String>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.
rerror: Option<DriveErrorAction>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.
werror: Option<DriveErrorAction>§copy_on_ready: Option<OnOff>copy-on-read is “on” or “off” and enables whether to copy read backing file sectors into the image file.
bps: Option<usize>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.
bps_rd: Option<usize>§bps_wr: Option<usize>§bps_max: Option<usize>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.
bps_rd_max: Option<usize>§bps_wr_max: Option<usize>§iops: Option<usize>Specify request rate limits in requests per second, either for all request types or for reads or writes only.
iops_rd: Option<usize>§iops_wr: Option<usize>§iops_max: Option<usize>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.
iops_rd_max: Option<usize>§iops_wr_max: Option<usize>§iops_size: Option<usize>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.
group: Option<String>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.