Skip to content

Commit 4a5dc87

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

File tree

4 files changed

+39
-3
lines changed

4 files changed

+39
-3
lines changed

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

Lines changed: 17 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -94,10 +94,15 @@ pub struct ConfigSpace {
9494
// SAFETY: `ConfigSpace` contains only PODs.
9595
unsafe impl ByteValued for ConfigSpace {}
9696

97+
/// VirtIO network device.
98+
///
99+
/// It emulates a network device able to exchange L2 frames between the guest
100+
/// and a host-side tap device.
97101
#[derive(Debug)]
98102
pub struct Net {
99103
pub(crate) id: String,
100104

105+
/// The backend for this device: a tap.
101106
pub tap: Tap,
102107

103108
pub(crate) avail_features: u64,
@@ -124,10 +129,13 @@ pub struct Net {
124129
pub(crate) device_state: DeviceState,
125130
pub(crate) activate_evt: EventFd,
126131

132+
/// The MMDS stack corresponding to this interface.
133+
/// Only if MMDS transport has been associated with it.
127134
pub mmds_ns: Option<MmdsNetworkStack>,
128135
}
129136

130137
impl Net {
138+
/// Create a new virtio network device with the given TAP interface.
131139
pub fn new_with_tap(
132140
id: String,
133141
tap: Tap,
@@ -181,7 +189,7 @@ impl Net {
181189
})
182190
}
183191

184-
/// Create a new virtio network device with the given TAP interface.
192+
/// Create a new virtio network device given the interface name.
185193
pub fn new(
186194
id: String,
187195
tap_if_name: &str,
@@ -638,6 +646,10 @@ impl Net {
638646
tap.write_iovec(buf)
639647
}
640648

649+
/// Process a single RX queue event.
650+
///
651+
/// This is called by the event manager responding to the guest adding a new
652+
/// buffer in the RX queue.
641653
pub fn process_rx_queue_event(&mut self) {
642654
METRICS.net.rx_queue_event_count.inc();
643655

@@ -684,6 +696,10 @@ impl Net {
684696
}
685697
}
686698

699+
/// Process a single TX queue event.
700+
///
701+
/// This is called by the event manager responding to the guest adding a new
702+
/// buffer in the TX queue.
687703
pub fn process_tx_queue_event(&mut self) {
688704
METRICS.net.tx_queue_event_count.inc();
689705
if let Err(err) = self.queue_evts[TX_INDEX].read() {

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

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

4+
//! Implements a virtio network device.
5+
46
use std::io;
57

8+
/// Maximum size of the frame buffers handled by this device.
69
pub const MAX_BUFFER_SIZE: usize = 65562;
10+
/// Queue size for network device.
711
pub const NET_QUEUE_SIZE: u16 = 256;
12+
/// The number of queues of the network device.
813
pub const NET_NUM_QUEUES: usize = 2;
914
pub const NET_QUEUE_SIZES: [u16; NET_NUM_QUEUES] = [NET_QUEUE_SIZE; NET_NUM_QUEUES];
10-
// The index of the rx queue from Net device queues/queues_evts vector.
15+
/// The index of the rx queue from Net device queues/queues_evts vector.
1116
pub const RX_INDEX: usize = 0;
12-
// The index of the tx queue from Net device queues/queues_evts vector.
17+
/// The index of the tx queue from Net device queues/queues_evts vector.
1318
pub const TX_INDEX: usize = 1;
1419

1520
pub mod device;
@@ -32,6 +37,7 @@ pub enum NetQueue {
3237
Tx,
3338
}
3439

40+
/// Errors the network device can trigger.
3541
#[derive(Debug, thiserror::Error)]
3642
pub enum NetError {
3743
/// Open tap device failed

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

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,8 @@ use crate::devices::virtio::{DeviceState, TYPE_NET};
2424
use crate::rate_limiter::persist::RateLimiterState;
2525
use crate::rate_limiter::RateLimiter;
2626

27+
/// Information about the network config's that are saved
28+
/// at snapshot.
2729
#[derive(Debug, Default, Clone, Versionize)]
2830
// NOTICE: Any changes to this structure require a snapshot version bump.
2931
pub struct NetConfigSpaceState {
@@ -59,29 +61,40 @@ impl NetConfigSpaceState {
5961
}
6062
}
6163

64+
/// Information about the network device that are saved
65+
/// at snapshot.
6266
#[derive(Debug, Clone, Versionize)]
6367
// NOTICE: Any changes to this structure require a snapshot version bump.
6468
pub struct NetState {
6569
id: String,
6670
tap_if_name: String,
6771
rx_rate_limiter_state: RateLimiterState,
6872
tx_rate_limiter_state: RateLimiterState,
73+
/// The associated MMDS network stack.
6974
pub mmds_ns: Option<MmdsNetworkStackState>,
7075
config_space: NetConfigSpaceState,
7176
virtio_state: VirtioDeviceState,
7277
}
7378

79+
/// Auxiliary structure for creating a device when resuming from a snapshot.
7480
#[derive(Debug)]
7581
pub struct NetConstructorArgs {
82+
/// Pointer to guest memory.
7683
pub mem: GuestMemoryMmap,
84+
/// Pointer to the MMDS data store.
7785
pub mmds: Option<Arc<Mutex<Mmds>>>,
7886
}
7987

88+
/// Errors triggered when trying to construct a network device at resume time.
8089
#[derive(Debug, derive_more::From)]
8190
pub enum NetPersistError {
91+
/// Failed to create a network device.
8292
CreateNet(super::NetError),
93+
/// Failed to create a rate limiter.
8394
CreateRateLimiter(io::Error),
95+
/// Failed to re-create the virtio state (i.e queues etc).
8496
VirtioState(VirtioStateError),
97+
/// Indicator that no MMDS is associated with this device.
8598
NoMmdsDataStore,
8699
}
87100

src/vmm/src/devices/virtio/net/tap.rs

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -162,6 +162,7 @@ impl Tap {
162162
})
163163
}
164164

165+
/// Retrieve the interface's name as a str.
165166
pub fn if_name_as_str(&self) -> &str {
166167
let len = self
167168
.if_name

0 commit comments

Comments
 (0)