rust/pv: Fix some comments

The library is used by multiple PV related tools, not only for managing
the guest secret store.
Reviewed-by: Steffen Eiden <seiden@linux.ibm.com>
Signed-off-by: Marc Hartmayer <mhartmay@linux.ibm.com>
Signed-off-by: Steffen Eiden <seiden@linux.ibm.com>

rust/pv/src/lib.rs

@@ -11,7 +11,7 @@
     unused_qualifications
 )]
 #![doc = include_str!("../README.md")]
-//! # Manage guest secret store
+//! # Library for Protected Virtualization (PV) related tools
 //!
 //! This crate provides functionalities for creating add-secret requests. Also provides support for
 //! sending those requests, list all stored secrets, and lock the secret store.

rust/pv/src/uvsecret/user_data.rs

@@ -141,7 +141,7 @@ impl UserData {
         Ok(Self::Signed(SignedUserData { sign_key, data }))
     }
 
-    /// Signs data in buf, writes signature to buf+user_data_offset+sign_offset if applicable.
+    /// Signs data in buf, writes signature to `buf+user_data_offset+sign_offset` if applicable.
     ///
     /// Uses [`MessageDigest::sha512`] as digest. Does not modify the abritary user data buffer.
     ///

rust/pv/src/verify.rs

@@ -23,7 +23,7 @@ use crate::Result;
 mod helper;
 mod test;
 
-/// A HkdVerifier verifies that a host-key document(HKD) can be trusted.
+/// A `HkdVerifier` verifies that a host-key document(HKD) can be trusted.
 ///
 /// If the verification fails the HKD should not be used to create requests.
 pub trait HkdVerifier {
@@ -62,7 +62,7 @@ impl HkdVerifier for CertVerifier {
     /// This function verifies a host-key
     /// document. To do so multiple steps are required:
     ///
-    /// 1. issuer(host_key) == subject(ibm_z_sign_key)
+    /// 1. `issuer(host_key`) == `subject(ibm_z_sign_key`)
     /// 2. Signature verification
     /// 3. @hkd must not be expired
     /// 4. @hkd must not be revoked

rust/pv/src/verify/helper.rs

@@ -119,7 +119,7 @@ pub fn store_setup<P: AsRef<Path>, Q: AsRef<Path>, R: AsRef<Path>>(
 }
 
 /// Verify that the given IBM signing keys can be trusted
-/// -> check the chain: IBMsignKey<-InterCA(s)<-RootCA
+/// -> check the chain: `IBMsignKey`<-InterCA(s)<-`RootCA`
 pub fn verify_chain(
     store: &X509StoreRef,
     untrusted_certs: &Stack<X509>,

rust/pv_core/README.md

@@ -3,7 +3,7 @@ SPDX-License-Identifier: MIT
 
 Copyright 2024 IBM Corp.
 -->
-# s390_pv_core - basic library for pv-tools
+# `s390_pv_core` - basic library for pv-tools
 
 This library is intended to be used by tools and libraries that
 are used for creating and managing [IBM Secure Execution](https://www.ibm.com/docs/en/linux-on-systems?topic=virtualization-secure-execution) guests.

rust/pv_core/src/confidential.rs

@@ -90,7 +90,7 @@ impl<C: Zeroize> Confidential<C> {
         &self.0
     }
 
-    /// Get an immutable reference to the contained value
+    /// Get a mutable reference to the contained value
     ///
     /// NOTE that modifications to a mutable reference can trigger reallocation.
     /// e.g. a [`Vec`] might expand if more space needed. -> preallocate enough space

rust/pv_core/src/utils.rs

@@ -214,8 +214,8 @@ pub fn create_file<P: AsRef<Path>>(path: P) -> Result<File> {
 /// If this function encounters an "end of file" before completely filling
 /// the buffer, it returns an error. The contents of `buf` are unspecified in this case.
 ///
-/// If aber so hast du mmmeny other read error is encountered then this function immediately
-/// returns. The contents of `buf` are unspecified in this case.
+/// If any other read error occurs, this function returns immediately. The
+/// contents of `buf` are unspecified in this case.
 ///
 /// If this function returns an error, it is unspecified how many bytes it
 /// has read, but it will never read more than would be necessary to

rust/pv_core/src/uvdevice.rs

@@ -95,7 +95,7 @@ pub trait UvCmd {
     ///
     /// # Returns
     ///
-    /// The IOCTL cmd for this UvCmd usually something like `uv_ioctl!(CMD_NR)`
+    /// The IOCTL cmd for this `UvCmd` usually something like `uv_ioctl!(CMD_NR)`
     fn cmd(&self) -> u64 {
         uv_ioctl(Self::UV_IOCTL_NR)
     }
@@ -162,7 +162,7 @@ pub enum UvcSuccess {
     RC_MORE_DATA = UvDevice::RC_MORE_DATA,
 }
 
-/// The UvDevice is a (virtual) device on s390 machines to send Ultravisor commands(UVCs) from
+/// 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

rust/pv_core/src/uvdevice/attest.rs

@@ -242,10 +242,10 @@ impl ffi::uvio_attest {
     ///
     /// # SAFETY
     /// It is safe to call this function iff:
-    ///  - arcb.len() < u32::MAX
-    ///  - additional.len() < u32::MAX
-    ///  - user_len() <= 256
-    ///  - pointyer fit into an u64
+    ///  - `arcb.len() < u32::MAX`
+    ///  - `additional.len() < u32::MAX`
+    ///  - `user_len() <= 256`
+    ///  - pointer fits into an u64
     unsafe fn new(
         arcb: &[u8],
         measurement: &mut [u8],

rust/pv_core/src/uvdevice/ffi.rs

@@ -28,7 +28,7 @@ pub const UVIO_IOCTL_LOCK_SECRETS_NR: u8 = 4;
 /// Programs can use this struct to communicate with the uvdevice via IOCTLs
 /// `argument_{addr,len}` specifies in/out data depending on the request
 ///
-/// 'uv_rc' and `uv_rrc` are the response and reason response codes from the
+/// `uv_rc` and `uv_rrc` are the response and reason response codes from the
 /// Ultravisor.
 ///
 /// `flags` is currently unused and to be set zero
@@ -55,7 +55,7 @@ assert_size!(uvio_ioctl_cb, 0x40);
 /// If the bit is set in both, `supp_uvio_cmds` and `supp_uv_cmds`,
 /// the uvdevice and the Ultravisor support that call.
 ///
-/// Note that bit 0 (UVIO_IOCTL_UVDEV_INFO_NR) is always zero for `supp_uv_cmds`
+/// Note that bit 0 (`UVIO_IOCTL_UVDEV_INFO_NR`) is always zero for `supp_uv_cmds`
 /// as there is no corresponding UV-call.
 #[repr(C)]
 #[derive(Debug, Copy, Clone, AsBytes, FromZeroes, FromBytes)]
@@ -103,7 +103,7 @@ pub struct uvio_attest {
 }
 assert_size!(uvio_attest, 0x138);
 
-/// corresponds to the UV_IOCTL macro
+/// corresponds to the `UV_IOCTL` macro
 pub(crate) const fn uv_ioctl(nr: u8) -> u64 {
     iowr(UVIO_TYPE_UVC, nr, size_of::<uvio_ioctl_cb>())
 }

rust/pv_core/src/uvdevice/secret.rs

@@ -54,7 +54,7 @@ impl AddCmd {
     /// # Errors
     ///
     /// This function will return an error if the provided data does not start with the
-    /// ['crate::AddSecretRequest'] magic Value.
+    /// [`crate::AddSecretRequest`] magic Value.
     pub fn new<R: Read>(bin_add_secret_req: &mut R) -> Result<Self> {
         let mut data = Vec::with_capacity(PAGESIZE);
         bin_add_secret_req.read_to_end(&mut data)?;

rust/pv_core/src/uvdevice/secret_list.rs

@@ -177,7 +177,7 @@ impl FromIterator<SecretEntry> for SecretList {
 }
 
 impl SecretList {
-    /// Creates a new SecretList.
+    /// Creates a new `SecretList`.
     ///
     /// The content of this list will very likely not represent the status of the guest in the
     /// Ultravisor. Use of [`SecretList::decode`] in any non-test environments is encuraged.

rust/pv_core/src/uvsecret.rs

@@ -11,7 +11,7 @@ use byteorder::{BigEndian, ByteOrder};
 use std::{fmt::Display, mem::size_of};
 use zerocopy::{AsBytes, U16};
 
-/// The magic value used to identify an ['crate:AddSecretRequest']
+/// The magic value used to identify an [`crate:AddSecretRequest`]
 ///
 /// The magic value is ASCII:
 /// ```rust