Skip to content

Commit 24adb76

Browse files
dianpopaShadowCurse
authored andcommitted
doc: final changes for having doc on devices
Final changes for having doc on devices Signed-off-by: Diana Popa <dpopa@amazon.com>
1 parent ac71d45 commit 24adb76

File tree

8 files changed

+38
-2
lines changed

8 files changed

+38
-2
lines changed

src/vmm/src/device_manager/mmio.rs

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -313,7 +313,7 @@ impl MMIODeviceManager {
313313
irq_number
314314
}
315315

316-
/// Gets the the specified device.
316+
/// Gets the specified device.
317317
pub fn get_device(
318318
&self,
319319
device_type: DeviceType,

src/vmm/src/devices/bus.rs

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@ use std::cmp::{Ord, Ordering, PartialEq, PartialOrd};
1111
use std::collections::btree_map::BTreeMap;
1212
use std::sync::{Arc, Mutex};
1313

14+
/// Errors triggered during bus operations.
1415
#[derive(Debug, thiserror::Error)]
1516
pub enum BusError {
1617
/// The insertion failed because the new device overlapped with an old device.

src/vmm/src/devices/mod.rs

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,9 @@
44
// Portions Copyright 2017 The Chromium OS Authors. All rights reserved.
55
// Use of this source code is governed by a BSD-style license that can be
66
// found in the THIRD-PARTY file.
7+
8+
//! Emulates virtual and hardware devices.
9+
710
use std::io;
811

912
pub mod bus;

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

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -42,9 +42,12 @@ impl DeviceState {
4242
}
4343
}
4444

45+
/// The 2 types of interrupt sources in MMIO transport.
4546
#[derive(Debug)]
4647
pub enum IrqType {
48+
/// Interrupt triggered by change in config.
4749
Config,
50+
/// Interrupt triggered by used vring buffers.
4851
Vring,
4952
}
5053

@@ -97,6 +100,7 @@ pub trait VirtioDevice: AsAny + Send {
97100
/// - self.avail_features() & self.acked_features() = self.get_acked_features()
98101
fn set_acked_features(&mut self, acked_features: u64);
99102

103+
/// Check if virtio device has negotiated given feature.
100104
fn has_feature(&self, feature: u64) -> bool {
101105
(self.acked_features() & 1 << feature) != 0
102106
}

src/vmm/src/devices/virtio/mmio.rs

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -74,11 +74,12 @@ impl MmioTransport {
7474
}
7575
}
7676

77+
/// Gets the encapsulated locked VirtioDevice.
7778
pub fn locked_device(&self) -> MutexGuard<dyn VirtioDevice + 'static> {
7879
self.device.lock().expect("Poisoned lock")
7980
}
8081

81-
// Gets the encapsulated VirtioDevice.
82+
/// Gets the encapsulated VirtioDevice.
8283
pub fn device(&self) -> Arc<Mutex<dyn VirtioDevice>> {
8384
self.device.clone()
8485
}

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

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@
66
// found in the THIRD-PARTY file.
77

88
//! Implements virtio devices, queues, and transport mechanisms.
9+
910
use std::any::Any;
1011
use std::io::Error as IOError;
1112

@@ -50,27 +51,37 @@ mod device_status {
5051

5152
/// Types taken from linux/virtio_ids.h.
5253
/// Type 0 is not used by virtio. Use it as wildcard for non-virtio devices
54+
/// Virtio net device ID.
5355
pub const TYPE_NET: u32 = 1;
56+
/// Virtio block device ID.
5457
pub const TYPE_BLOCK: u32 = 2;
58+
/// Virtio rng device ID.
5559
pub const TYPE_RNG: u32 = 4;
60+
/// Virtio balloon device ID.
5661
pub const TYPE_BALLOON: u32 = 5;
5762

5863
/// Offset from the base MMIO address of a virtio device used by the guest to notify the device of
5964
/// queue events.
6065
pub const NOTIFY_REG_OFFSET: u32 = 0x50;
6166

67+
/// Errors triggered when activating a VirtioDevice.
6268
#[derive(Debug)]
6369
pub enum ActivateError {
70+
/// Epoll error.
6471
EpollCtl(IOError),
72+
/// General error at activation.
6573
BadActivate,
6674
}
6775

6876
/// Trait that helps in upcasting an object to Any
6977
pub trait AsAny {
78+
/// Return the immutable any encapsulated object.
7079
fn as_any(&self) -> &dyn Any;
7180

81+
/// Return the mutable encapsulated any object.
7282
fn as_mut_any(&mut self) -> &mut dyn Any;
7383
}
84+
7485
impl<T: Any> AsAny for T {
7586
fn as_any(&self) -> &dyn Any {
7687
self

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

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,11 +18,14 @@ use super::device::*;
1818
use super::queue::*;
1919
use crate::devices::virtio::MmioTransport;
2020

21+
/// Errors thrown during restoring virtio state.
2122
#[derive(Debug)]
2223
pub enum PersistError {
24+
/// Snapshot state contains invalid queue info.
2325
InvalidInput,
2426
}
2527

28+
/// Queue information saved in snapshot.
2629
#[derive(Clone, Debug, PartialEq, Eq, Versionize)]
2730
// NOTICE: Any changes to this structure require a snapshot version bump.
2831
pub struct QueueState {
@@ -91,15 +94,22 @@ impl Persist<'_> for Queue {
9194
#[derive(Clone, Debug, Default, PartialEq, Eq, Versionize)]
9295
// NOTICE: Any changes to this structure require a snapshot version bump.
9396
pub struct VirtioDeviceState {
97+
/// Device type.
9498
pub device_type: u32,
99+
/// Available virtio features.
95100
pub avail_features: u64,
101+
/// Negotiated virtio features.
96102
pub acked_features: u64,
103+
/// List of queues.
97104
pub queues: Vec<QueueState>,
105+
/// The MMIO interrupt status.
98106
pub interrupt_status: usize,
107+
/// Flag for activated status.
99108
pub activated: bool,
100109
}
101110

102111
impl VirtioDeviceState {
112+
/// Construct the virtio state of a device.
103113
pub fn from_device(device: &dyn VirtioDevice) -> Self {
104114
VirtioDeviceState {
105115
device_type: device.device_type(),
@@ -162,6 +172,7 @@ impl VirtioDeviceState {
162172
}
163173
}
164174

175+
/// Transport information saved in snapshot.
165176
#[derive(Clone, Debug, PartialEq, Eq, Versionize)]
166177
// NOTICE: Any changes to this structure require a snapshot version bump.
167178
pub struct MmioTransportState {
@@ -174,9 +185,12 @@ pub struct MmioTransportState {
174185
config_generation: u32,
175186
}
176187

188+
/// Auxiliary structure for initializing the transport when resuming from a snapshot.
177189
#[derive(Debug)]
178190
pub struct MmioTransportConstructorArgs {
191+
/// Pointer to guest memory.
179192
pub mem: GuestMemoryMmap,
193+
/// Device associated with the current MMIO state.
180194
pub device: Arc<Mutex<dyn VirtioDevice>>,
181195
}
182196

src/vmm/src/devices/virtio/queue.rs

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -223,6 +223,7 @@ impl Queue {
223223
}
224224
}
225225

226+
/// Maximum size of the queue.
226227
pub fn get_max_size(&self) -> u16 {
227228
self.max_size
228229
}
@@ -233,6 +234,7 @@ impl Queue {
233234
min(self.size, self.max_size)
234235
}
235236

237+
/// Validates that the queue's representation is correct.
236238
pub fn is_valid(&self, mem: &GuestMemoryMmap) -> bool {
237239
let queue_size = u64::from(self.actual_size());
238240
let desc_table = self.desc_table;

0 commit comments

Comments
 (0)