diff --git a/arch/src/x86_64/mod.rs b/arch/src/x86_64/mod.rs index a412663e2..aff777f8b 100644 --- a/arch/src/x86_64/mod.rs +++ b/arch/src/x86_64/mod.rs @@ -905,6 +905,7 @@ pub fn configure_vcpu( } /// Returns a Vec of the valid memory addresses. +/// /// These should be used to configure the GuestMemory structure for the platform. /// For x86_64 all addresses are valid from the start of the kernel except a /// carve out at the end of 32bit address space. diff --git a/hypervisor/src/kvm/aarch64/mod.rs b/hypervisor/src/kvm/aarch64/mod.rs index 965f86920..f4ca12f25 100644 --- a/hypervisor/src/kvm/aarch64/mod.rs +++ b/hypervisor/src/kvm/aarch64/mod.rs @@ -82,6 +82,7 @@ macro_rules! arm64_core_reg_id { } /// Specifies whether a particular register is a system register or not. +/// /// The kernel splits the registers on aarch64 in core registers and system registers. /// So, below we get the system registers by checking that they are not core registers. /// diff --git a/pci/src/configuration.rs b/pci/src/configuration.rs index 589595bd8..030f62cf7 100644 --- a/pci/src/configuration.rs +++ b/pci/src/configuration.rs @@ -180,8 +180,10 @@ impl PciSubclass for PciNetworkControllerSubclass { } } -/// A PCI class programming interface. Each combination of `PciClassCode` and -/// `PciSubclass` can specify a set of register-level programming interfaces. +/// Trait to define a PCI class programming interface +/// +/// Each combination of `PciClassCode` and `PciSubclass` can specify a +/// set of register-level programming interfaces. /// This trait is implemented by each programming interface. /// It allows use of a trait object to generate configurations. pub trait PciProgrammingInterface { @@ -418,6 +420,7 @@ pub struct PciConfigurationState { } /// Contains the configuration space of a PCI node. +/// /// See the [specification](https://en.wikipedia.org/wiki/PCI_configuration_space). /// The configuration space is accessed with DWORD reads and writes from the guest. pub struct PciConfiguration { diff --git a/rate_limiter/src/group.rs b/rate_limiter/src/group.rs index af4ad4c4f..47d5bc4c8 100644 --- a/rate_limiter/src/group.rs +++ b/rate_limiter/src/group.rs @@ -43,10 +43,11 @@ pub enum Error { EventFdWrite(#[source] io::Error), } -/// The RateLimiterGroupHandle is a handle to a RateLimiterGroup that may be -/// used in exactly the same way as the RateLimiter type. When the RateLimiter -/// within a RateLimiterGroup is unblocked, each RateLimiterGroupHandle will -/// be notified. +/// Handle to a RateLimiterGroup +/// +/// The RateLimiterGroupHandle may be used in exactly the same way as +/// the RateLimiter type. When the RateLimiter within a RateLimiterGroup +/// is unblocked, each RateLimiterGroupHandle will be notified. pub struct RateLimiterGroupHandle { eventfd: Arc, inner: Arc, diff --git a/virtio-devices/src/device.rs b/virtio-devices/src/device.rs index b70092f89..3f0951373 100644 --- a/virtio-devices/src/device.rs +++ b/virtio-devices/src/device.rs @@ -177,6 +177,8 @@ pub trait VirtioDevice: Send { fn set_access_platform(&mut self, _access_platform: Arc) {} } +/// Trait to define address translation for devices managed by virtio-iommu +/// /// Trait providing address translation the same way a physical DMA remapping /// table would provide translation between an IOVA and a physical address. /// The goal of this trait is to be used by virtio devices to perform the diff --git a/virtio-devices/src/lib.rs b/virtio-devices/src/lib.rs index 04d4eb5eb..aaed464cd 100644 --- a/virtio-devices/src/lib.rs +++ b/virtio-devices/src/lib.rs @@ -155,6 +155,8 @@ impl TryInto for RateLimiterConfig { } } +/// Return the host virtual address corresponding to the given guest address range +/// /// Convert an absolute address into an address space (GuestMemory) /// to a host pointer and verify that the provided size define a valid /// range within a single memory region. diff --git a/virtio-devices/src/vsock/mod.rs b/virtio-devices/src/vsock/mod.rs index 2dbf96c99..21c44250e 100644 --- a/virtio-devices/src/vsock/mod.rs +++ b/virtio-devices/src/vsock/mod.rs @@ -115,6 +115,7 @@ pub enum VsockEpollHandlerError { } /// A passive, event-driven object, that needs to be notified whenever an epoll-able event occurs. +/// /// An event-polling control loop will use `get_polled_fd()` and `get_polled_evset()` to query /// the listener for the file descriptor and the set of events it's interested in. When such an /// event occurs, the control loop will route the event to the listener via `notify()`. @@ -130,8 +131,9 @@ pub trait VsockEpollListener { fn notify(&mut self, evset: epoll::Events); } -/// Any channel that handles vsock packet traffic: sending and receiving packets. Since we're -/// implementing the device model here, our responsibility is to always process the sending of +/// Trait to describe any channel that handles vsock packet traffic (sending and receiving packets) +/// +/// Since we're implementing the device model here, our responsibility is to always process the sending of /// packets (i.e. the TX queue). So, any locally generated data, addressed to the driver (e.g. /// a connection response or RST), will have to be queued, until we get to processing the RX queue. /// @@ -151,8 +153,9 @@ pub trait VsockChannel { fn has_pending_rx(&self) -> bool; } -/// The vsock backend, which is basically an epoll-event-driven vsock channel, that needs to be -/// sendable through a mpsc channel (the latter due to how `vmm::EpollContext` works). +/// The vsock backend, which is basically an epoll-event-driven vsock channel +/// +/// It that needs to be sendable through a mpsc channel (the latter due to how `vmm::EpollContext` works). /// Currently, the only implementation we have is `crate::virtio::unix::muxer::VsockMuxer`, which /// translates guest-side vsock connections to host-side Unix domain socket connections. pub trait VsockBackend: VsockChannel + VsockEpollListener + Send {} diff --git a/vm-device/src/dma_mapping/mod.rs b/vm-device/src/dma_mapping/mod.rs index 134d8bdea..69cd880ee 100644 --- a/vm-device/src/dma_mapping/mod.rs +++ b/vm-device/src/dma_mapping/mod.rs @@ -2,6 +2,8 @@ // // SPDX-License-Identifier: Apache-2.0 OR BSD-3-Clause +/// Trait to trigger DMA mapping updates for devices managed by virtio-iommu +/// /// Trait meant for triggering the DMA mapping update related to an external /// device not managed fully through virtio. It is dedicated to virtio-iommu /// in order to trigger the map update anytime the mapping is updated from the diff --git a/vm-migration/src/lib.rs b/vm-migration/src/lib.rs index 5454bdb7c..39b16aac7 100644 --- a/vm-migration/src/lib.rs +++ b/vm-migration/src/lib.rs @@ -63,6 +63,7 @@ pub trait Pausable { } /// A Snapshottable component snapshot section. +/// /// Migratable component can split their migration snapshot into /// separate sections. /// Splitting a component migration data into different sections @@ -94,6 +95,8 @@ impl SnapshotData { } } +/// Data structure to describe snapshot data +/// /// A Snapshottable component's snapshot is a tree of snapshots, where leafs /// contain the snapshot data. Nodes of this tree track all their children /// through the snapshots field, which is basically their sub-components. @@ -207,8 +210,9 @@ pub trait Transportable: Pausable + Snapshottable { } } -/// Trait to be implemented by any component (device, CPU, RAM, etc) that -/// can be migrated. +/// Trait to define shared behaviors of components that can be migrated +/// +/// Examples are device, CPU, RAM, etc. /// All migratable components are paused before being snapshotted, and then /// eventually resumed. Thus any Migratable component must be both Pausable /// and Snapshottable.