Skip to content

Commit cbf3723

Browse files
dianpopaShadowCurse
authored andcommitted
devices: doc for the virtio block
Doc for the virtio block Signed-off-by: Diana Popa <dpopa@amazon.com>
1 parent 958a6a9 commit cbf3723

File tree

3 files changed

+36
-6
lines changed

3 files changed

+36
-6
lines changed

src/vmm/src/devices/virtio/block/device.rs

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -48,6 +48,7 @@ pub enum CacheType {
4848
Writeback,
4949
}
5050

51+
/// The engine file type, either Sync or Async (through io_uring).
5152
#[derive(Debug, PartialEq, Eq, Deserialize, Serialize)]
5253
pub enum FileEngineType {
5354
/// Use an Async engine, based on io_uring.
@@ -63,6 +64,7 @@ impl Default for FileEngineType {
6364
}
6465

6566
impl FileEngineType {
67+
/// Whether the Async engine is supported on the current host kernel.
6668
pub fn is_supported(&self) -> Result<bool, utils::kernel_version::Error> {
6769
match self {
6870
Self::Async if KernelVersion::get()? < min_kernel_version_for_io_uring() => Ok(false),
@@ -281,6 +283,10 @@ impl Block {
281283
})
282284
}
283285

286+
/// Process a single event in the VirtIO queue.
287+
///
288+
/// This function is called by the event manager when the guest notifies us
289+
/// about new buffers in the queue.
284290
pub(crate) fn process_queue_event(&mut self) {
285291
METRICS.block.queue_event_count.inc();
286292
if let Err(err) = self.queue_evts[0].read() {
@@ -327,6 +333,7 @@ impl Block {
327333
}
328334
}
329335

336+
/// Device specific function for peaking inside a queue and processing descriptors.
330337
pub fn process_queue(&mut self, queue_index: usize) {
331338
// This is safe since we checked in the event handler that the device is activated.
332339
let mem = self.device_state.mem().unwrap();
@@ -502,6 +509,7 @@ impl Block {
502509
&self.rate_limiter
503510
}
504511

512+
/// Retrieve the file engine type.
505513
pub fn file_engine_type(&self) -> FileEngineType {
506514
match self.disk.file_engine() {
507515
FileEngine::Sync(_) => FileEngineType::Sync,
@@ -515,6 +523,7 @@ impl Block {
515523
}
516524
}
517525

526+
/// Prepare device for being snapshotted.
518527
pub fn prepare_save(&mut self) {
519528
if !self.is_activated() {
520529
return;

src/vmm/src/devices/virtio/block/mod.rs

Lines changed: 12 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,8 @@
11
// Copyright 2018 Amazon.com, Inc. or its affiliates. All Rights Reserved.
22
// SPDX-License-Identifier: Apache-2.0
33

4+
//! Implements a virtio block device.
5+
46
pub mod device;
57
mod event_handler;
68
mod io;
@@ -14,16 +16,23 @@ pub use self::device::{Block, CacheType};
1416
pub use self::event_handler::*;
1517
pub use self::request::*;
1618

19+
/// Size of config space for block device.
1720
pub const BLOCK_CONFIG_SPACE_SIZE: usize = 8;
21+
/// Sector shift for block device.
1822
pub const SECTOR_SHIFT: u8 = 9;
23+
/// Size of block sector.
1924
pub const SECTOR_SIZE: u64 = (0x01_u64) << SECTOR_SHIFT;
25+
/// Queue size for block device.
2026
pub const BLOCK_QUEUE_SIZE: u16 = 256;
27+
/// The number of queues of block device.
2128
pub const BLOCK_NUM_QUEUES: usize = 1;
2229
pub const BLOCK_QUEUE_SIZES: [u16; BLOCK_NUM_QUEUES] = [BLOCK_QUEUE_SIZE];
2330
// The virtio queue can hold up to 256 descriptors, but 1 request spreads across 2-3 descriptors.
2431
// So we can use 128 IO_URING entries without ever triggering a FullSq Error.
32+
/// Maximum number of io uring entries we allow in the queue.
2533
pub const IO_URING_NUM_ENTRIES: u16 = 128;
2634

35+
/// Errors the block device can trigger.
2736
#[derive(Debug)]
2837
pub enum BlockError {
2938
/// Guest gave us too few descriptors in a descriptor chain.
@@ -46,11 +55,11 @@ pub enum BlockError {
4655
FileEngine(io::BlockIoError),
4756
// Error manipulating the backing file.
4857
BackingFile(std::io::Error, String),
49-
// Error opening eventfd.
58+
/// Error opening eventfd.
5059
EventFd(std::io::Error),
51-
// Error creating an irqfd.
60+
/// Error creating an irqfd.
5261
IrqTrigger(std::io::Error),
53-
// Error coming from the rate limiter.
62+
/// Error coming from the rate limiter.
5463
RateLimiter(std::io::Error),
5564
// Persistence error.
5665
Persist(crate::devices::virtio::persist::PersistError),

src/vmm/src/devices/virtio/block/persist.rs

Lines changed: 15 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -20,10 +20,16 @@ use crate::devices::virtio::{DeviceState, TYPE_BLOCK};
2020
use crate::rate_limiter::persist::RateLimiterState;
2121
use crate::rate_limiter::RateLimiter;
2222

23-
#[derive(Clone, Copy, Debug, PartialEq, Eq, Versionize)]
23+
/// Holds info about block's cache type. Gets saved in snapshot.
2424
// NOTICE: Any changes to this structure require a snapshot version bump.
25+
#[derive(Clone, Copy, Debug, PartialEq, Eq, Versionize)]
2526
pub enum CacheTypeState {
27+
/// Flushing mechanic will be advertised to the guest driver, but
28+
/// the operation will be a noop.
2629
Unsafe,
30+
/// Flushing mechanic will be advertised to the guest driver and
31+
/// flush requests coming from the guest will be performed using
32+
/// `fsync`.
2733
Writeback,
2834
}
2935

@@ -45,13 +51,16 @@ impl From<CacheTypeState> for CacheType {
4551
}
4652
}
4753

48-
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Versionize)]
54+
/// Holds info about block's file engine type. Gets saved in snapshot.
4955
// NOTICE: Any changes to this structure require a snapshot version bump.
56+
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Versionize)]
5057
pub enum FileEngineTypeState {
58+
/// Sync File Engine.
5159
// If the snap version does not contain the `FileEngineType`, it must have been snapshotted
5260
// on a VM using the Sync backend.
5361
#[default]
5462
Sync,
63+
/// Async File Engine.
5564
Async,
5665
}
5766

@@ -73,8 +82,9 @@ impl From<FileEngineTypeState> for FileEngineType {
7382
}
7483
}
7584

76-
#[derive(Debug, Clone, Versionize)]
85+
/// Holds info about the block device. Gets saved in snapshot.
7786
// NOTICE: Any changes to this structure require a snapshot version bump.
87+
#[derive(Debug, Clone, Versionize)]
7888
pub struct BlockState {
7989
id: String,
8090
partuuid: Option<String>,
@@ -112,8 +122,10 @@ impl BlockState {
112122
}
113123
}
114124

125+
/// Auxiliary structure for creating a device when resuming from a snapshot.
115126
#[derive(Debug)]
116127
pub struct BlockConstructorArgs {
128+
/// Pointer to guest memory.
117129
pub mem: GuestMemoryMmap,
118130
}
119131

0 commit comments

Comments
 (0)