rust/pv: More documentation

Improve the API documentation of the pv crate.

Acked-by: Marc Hartmayer <mhartmay@linux.ibm.com>
Signed-off-by: Steffen Eiden <seiden@linux.ibm.com>

rust/pv_core/src/lib.rs

@@ -1,17 +1,9 @@
 // SPDX-License-Identifier: MIT
 //
-// Copyright IBM Corp. 2023
+// Copyright IBM Corp. 2023, 2024
 #![deny(missing_docs)]
 #![allow(unused)]
-//! pv_core - basic library for pv-tools
-//!
-//! This library is intened to be used by tools and libraries that
-//! are used for creating and managing IBM Secure Execution guests.
-//! `pv_core` provides abstraction layers for secure memory management,
-//! and accessing the uvdevice.
-//!
-//! It does not provide any cryptographic operations through OpenSSL.
-//! For this use `pv` which reexports all symbos from this crate.
+#![doc = include_str!("../README.md")]
 mod error;
 mod macros;
 mod utils;
@@ -30,6 +22,9 @@ pub mod misc {
 }
 
 /// Definitions and functions for interacting with the Ultravisor
+///
+/// For detailed Information on how to send Ultravisor Commands see [`crate::uv::UvDevice`] and
+/// [`crate::uv::UvCmd`]
 pub mod uv {
     pub use crate::uvdevice::secret::{AddCmd, ListCmd, LockCmd};
     pub use crate::uvdevice::secret_list::{ListableSecretType, SecretEntry, SecretId, SecretList};

rust/pv_core/src/uvdevice.rs

@@ -99,7 +99,8 @@ pub trait UvCmd {
     }
     /// Converts UV return codes into human readable error messages
     ///
-    /// no need to handle `0x0000, 0x0001, 0x0002, 0x0005, 0x0030, 0x0031, 0x0032, 0x0100`
+    /// # Note for implementations
+    /// No need to handle `0x0000, 0x0001, 0x0002, 0x0005, 0x0030, 0x0031, 0x0032, 0x0100`
     fn rc_fmt(&self, rc: u16, rrc: u16) -> Option<&'static str>;
 
     /// Returns data used by this command if available.
@@ -158,7 +159,31 @@ pub enum UvcSuccess {
     RC_MORE_DATA = UvDevice::RC_MORE_DATA,
 }
 
-/// The UvDevice is a (virtual) device on s390 machines to send Ultravisor commands from userspace.
+/// The UvDevice is a (virtual) device on s390 machines to send Ultravisor commands(UVCs) from userspace.
+///
+/// On s390 machines with Ultravisor enabled (Secure Execution guest & hosts) the device at
+/// `/dev/uv` will accept ioctls.
+///
+/// # Example
+///
+/// Use a implementation of [`UvCmd`] to send a specific Ultravisor cammand to the uvevice to
+/// forward to Firmware.
+///
+/// ```rust,no_run
+/// # use pv_core::uv::UvDevice;
+/// # use pv_core::uv::AddCmd;
+/// # use std::fs::File;
+/// # fn main() -> pv_core::Result<()> {
+/// let mut file = File::open("request")?;
+/// let uv = UvDevice::open()?;
+/// let mut cmd = AddCmd::new(&mut file)?;
+/// uv.send_cmd(&mut cmd)?;
+/// # Ok(())
+/// # }
+/// // do something with the result
+///
+///
+/// ```
 pub struct UvDevice(File);
 
 impl UvDevice {