From 50bd6e37219fd6dabee4f661ed3530c0331c7b06 Mon Sep 17 00:00:00 2001
From: johannst <johannes.stoelp@gmail.com>
Date: Wed, 2 Jun 2021 00:11:49 +0200
Subject: added doc

---
 src/vm.rs | 26 +++++++++++++++++++++++++-
 1 file changed, 25 insertions(+), 1 deletion(-)

(limited to 'src/vm.rs')

diff --git a/src/vm.rs b/src/vm.rs
index 6f8a355..95caf3c 100644
--- a/src/vm.rs
+++ b/src/vm.rs
@@ -1,3 +1,5 @@
+//! VM system ioctls.
+
 use std::fs;
 use std::io;
 use std::os::unix::io::FromRawFd;
@@ -5,6 +7,13 @@ use std::os::unix::io::FromRawFd;
 use crate::vcpu::Vcpu;
 use crate::{ioctl, kvm_sys, KvmRun, PhysAddr, UserMem};
 
+/// Wrapper for VM ioctls.
+///
+/// Representation of the file descriptor obtained by the [`KVM_CREATE_VM`][kvm-create-vm] ioctl.
+/// This wrapper provides access to the `VM ioctls` as described in [KVM API][kvm].
+///
+/// [kvm]: https://www.kernel.org/doc/html/latest/virt/kvm/api.html#general-description
+/// [kvm-create-vm]: https://www.kernel.org/doc/html/latest/virt/kvm/api.html#kvm-create-vm
 pub struct Vm {
     vm: fs::File,
     vcpu_mmap_size: usize,
@@ -15,12 +24,23 @@ impl Vm {
         Vm { vm, vcpu_mmap_size }
     }
 
+    /// Map memory from userspace into the VM as `guest physical` memory starting at address
+    /// `phys_addr`.
+    /// The underlying operation is the [`KVM_SET_USER_MEMORY_REGION`][kmv-set-user-memory-region]
+    /// ioctl.
+    ///
+    /// # Safety
+    ///
+    /// The `mem: &UserMem` argument passed to this function must at least live as long the `Vcpu`
+    /// instance.
+    ///
+    /// [kvm-set-user-memory-region]: https://www.kernel.org/doc/html/latest/virt/kvm/api.html#kvm-set-user-memory-region
     pub unsafe fn set_user_memory_region(
         &self,
         phys_addr: PhysAddr,
         mem: &UserMem,
     ) -> io::Result<()> {
-        // Create guest physical memory mapping for `slot : 0` at guest `phys addr : 0`.
+        // Create guest physical memory mapping for `slot : 0` at guest `phys_addr`.
         let mut kvm_mem = kvm_sys::kvm_userspace_memory_region::default();
         kvm_mem.userspace_addr = mem.ptr as u64;
         kvm_mem.memory_size = mem.len as u64;
@@ -34,6 +54,10 @@ impl Vm {
         .map(|_| ())
     }
 
+    /// Create a new virtual cpu with the [`KVM_CREATE_VCPU`][kvm-create-vcpu] ioctl.
+    /// Returns a wrapper [`vcpu::Vcpu`][crate::vcpu::Vcpu] representing the VCPU.
+    ///
+    /// [kvm-create-vcpu]: https://www.kernel.org/doc/html/latest/virt/kvm/api.html#kvm-create-vcpu
     pub fn create_vpcu(&self, id: u64) -> io::Result<Vcpu> {
         let vcpu = ioctl(&self.vm, kvm_sys::KVM_CREATE_VCPU, id)
             .map(|fd| unsafe { fs::File::from_raw_fd(fd) })?;
-- 
cgit v1.2.3