fix clippy warnings

A more recent clippy version requires the public
unsafe functions to have a #Safety section in their
documentation.
Fixes: rust-vmm#101.

Signed-off-by: Laura Loghin <lauralg@amazon.com>

src/ioctls/system.rs

@@ -41,7 +41,7 @@ impl Kvm {
     pub fn new() -> Result<Self> {
         // Open `/dev/kvm` using `O_CLOEXEC` flag.
         let fd = Self::open_with_cloexec(true)?;
-        // Safe because we verify that ret is valid and we own the fd.
+        // Safe because we verify that the fd is valid in `open_with_cloexec` and we own the fd.
         Ok(unsafe { Self::new_with_fd_number(fd) })
     }
 
@@ -54,6 +54,24 @@ impl Kvm {
     ///
     /// * `fd` - File descriptor for `/dev/kvm`.
     ///
+    /// # Safety
+    ///
+    /// This function is unsafe as the primitives currently returned have the contract that
+    /// they are the sole owner of the file descriptor they are wrapping. Usage of this function
+    /// could accidentally allow violating this contract which can cause memory unsafety in code
+    /// that relies on it being true.
+    ///
+    /// The caller of this method must make sure the fd is valid and nothing else uses it.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// # use kvm_ioctls::Kvm;
+    /// let kvm_fd = Kvm::open_with_cloexec(true).unwrap();
+    /// // Safe because we verify that the fd is valid in `open_with_cloexec` and we own the fd.
+    /// let kvm = unsafe { Kvm::new_with_fd_number(kvm_fd) };
+    /// ```
+    ///
     pub unsafe fn new_with_fd_number(fd: RawFd) -> Self {
         Kvm {
             kvm: File::from_raw_fd(fd),
@@ -430,10 +448,32 @@ impl Kvm {
 
     /// Creates a VmFd object from a VM RawFd.
     ///
+    /// # Arguments
+    ///
+    /// * `fd` - the RawFd used for creating the VmFd object.
+    ///
+    /// # Safety
+    ///
     /// This function is unsafe as the primitives currently returned have the contract that
     /// they are the sole owner of the file descriptor they are wrapping. Usage of this function
     /// could accidentally allow violating this contract which can cause memory unsafety in code
     /// that relies on it being true.
+    ///
+    /// The caller of this method must make sure the fd is valid and nothing else uses it.
+    ///
+    /// # Example
+    ///
+    /// ```rust
+    /// # extern crate kvm_ioctls;
+    /// # use std::os::unix::io::AsRawFd;
+    /// # use kvm_ioctls::Kvm;
+    /// let kvm = Kvm::new().unwrap();
+    /// let vm = kvm.create_vm().unwrap();
+    /// let rawfd = unsafe { libc::dup(vm.as_raw_fd()) };
+    /// assert!(rawfd >= 0);
+    /// let vm = unsafe { kvm.create_vmfd_from_rawfd(rawfd).unwrap() };
+    /// ```
+    ///
     pub unsafe fn create_vmfd_from_rawfd(&self, fd: RawFd) -> Result<VmFd> {
         let run_mmap_size = self.get_vcpu_mmap_size()?;
         Ok(new_vmfd(File::from_raw_fd(fd), run_mmap_size))

src/ioctls/vm.rs

@@ -1040,17 +1040,25 @@ impl VmFd {
 
     /// Creates a VcpuFd object from a vcpu RawFd.
     ///
+    /// # Arguments
+    ///
+    /// * `fd` - the RawFd used for creating the VcpuFd object.
+    ///
+    /// # Safety
+    ///
     /// This function is unsafe as the primitives currently returned have the contract that
     /// they are the sole owner of the file descriptor they are wrapping. Usage of this function
     /// could accidentally allow violating this contract which can cause memory unsafety in code
     /// that relies on it being true.
     ///
+    /// The caller of this method must make sure the fd is valid and nothing else uses it.
+    ///
     /// # Example
     ///
     /// ```rust
     /// # extern crate kvm_ioctls;
     /// # use std::os::unix::io::AsRawFd;
-    /// # use kvm_ioctls::{Kvm, VmFd, VcpuFd};
+    /// # use kvm_ioctls::Kvm;
     /// let kvm = Kvm::new().unwrap();
     /// let vm = kvm.create_vm().unwrap();
     /// // Create one vCPU with the ID=0.

src/lib.rs

@@ -61,9 +61,9 @@
 //!     use kvm_bindings::KVM_MEM_LOG_DIRTY_PAGES;
 //!     use kvm_bindings::kvm_userspace_memory_region;
 //!
-//!	let mem_size = 0x4000;
-//!	let guest_addr = 0x1000;
-//!	let asm_code: &[u8];
+//!     let mem_size = 0x4000;
+//!     let guest_addr = 0x1000;
+//!     let asm_code: &[u8];
 //!
 //!     // Setting up architectural dependent values.
 //!     #[cfg(any(target_arch = "x86", target_arch = "x86_64"))]