More formatting/comments/name change for permissions

Change-Id: I15820045ccc5011221203f387371b613a070cb46

kernel/src/process_standard.rs

@@ -36,7 +36,7 @@ use crate::processbuffer::{ReadOnlyProcessBuffer, ReadWriteProcessBuffer};
 use crate::storage_permissions::StoragePermissions;
 use crate::syscall::{self, Syscall, SyscallReturn, UserspaceKernelBoundary};
 use crate::upcall::UpcallId;
-use crate::utilities::capability_ptr::{CapabilityPtr, MetaPermissions};
+use crate::utilities::capability_ptr::{CapabilityPtr, CapabilityPtrPermissions};
 use crate::utilities::cells::{MapCell, NumericCellExt, OptionalCell};
 
 use tock_tbf::types::CommandPermissions;
@@ -621,7 +621,7 @@ impl<C: Chip> Process for ProcessStandard<'_, C> {
                     old_break as *const (),
                     base,
                     (new_break as usize) - base,
-                    MetaPermissions::ReadWrite,
+                    CapabilityPtrPermissions::ReadWrite,
                 );
 
                 Ok(break_result)
@@ -1761,7 +1761,7 @@ impl<C: 'static + Chip> ProcessStandard<'_, C> {
             init_addr as *const (),
             fn_base,
             fn_len,
-            MetaPermissions::Execute,
+            CapabilityPtrPermissions::Execute,
         );
 
         process.tasks.map(|tasks| {
@@ -1934,7 +1934,7 @@ impl<C: 'static + Chip> ProcessStandard<'_, C> {
             init_addr as *const (),
             flash_start as usize,
             (self.flash_end() as usize) - (flash_start as usize),
-            MetaPermissions::Execute,
+            CapabilityPtrPermissions::Execute,
         );
 
         self.enqueue_task(Task::FunctionCall(FunctionCall {

kernel/src/syscall.rs

@@ -70,7 +70,7 @@ use core::fmt::Write;
 
 use crate::errorcode::ErrorCode;
 use crate::process;
-use crate::utilities::capability_ptr::{CapabilityPtr, MetaPermissions};
+use crate::utilities::capability_ptr::{CapabilityPtr, CapabilityPtrPermissions};
 
 pub use crate::syscall_driver::{CommandReturn, SyscallDriver};
 
@@ -678,7 +678,7 @@ impl SyscallReturn {
                     ptr as *const (),
                     ptr as usize,
                     len,
-                    MetaPermissions::ReadWrite,
+                    CapabilityPtrPermissions::ReadWrite,
                 );
                 *a2 = len.into();
             }
@@ -689,7 +689,7 @@ impl SyscallReturn {
                     ptr as *const (),
                     ptr as usize,
                     len,
-                    MetaPermissions::Read,
+                    CapabilityPtrPermissions::Read,
                 );
                 *a2 = len.into();
             }
@@ -701,7 +701,7 @@ impl SyscallReturn {
                     ptr as *const (),
                     ptr as usize,
                     len,
-                    MetaPermissions::ReadWrite,
+                    CapabilityPtrPermissions::ReadWrite,
                 );
                 *a3 = len.into();
             }
@@ -713,7 +713,7 @@ impl SyscallReturn {
                     ptr as *const (),
                     ptr as usize,
                     len,
-                    MetaPermissions::Read,
+                    CapabilityPtrPermissions::Read,
                 );
                 *a3 = len.into();
             }
@@ -724,7 +724,7 @@ impl SyscallReturn {
                     ptr as *const (),
                     ptr as usize,
                     len,
-                    MetaPermissions::Read,
+                    CapabilityPtrPermissions::Read,
                 );
                 *a2 = len.into();
             }
@@ -736,7 +736,7 @@ impl SyscallReturn {
                     ptr as *const (),
                     ptr as usize,
                     len,
-                    MetaPermissions::Read,
+                    CapabilityPtrPermissions::Read,
                 );
                 *a3 = len.into();
             }

kernel/src/utilities/capability_ptr.rs

@@ -9,21 +9,22 @@ use core::ops::AddAssign;
 
 /// A pointer to userspace memory with implied authority.
 ///
-/// A [CapabilityPtr] points to memory a userspace processes may be
+/// A [`CapabilityPtr`] points to memory a userspace process may be
 /// permitted to read, write, or execute. It is sized exactly to a
-/// register that can pass values between userspace and kernel and at
-/// least the size of a word ([usize]) [^note1]. Operations on the
+/// CPU register that can pass values between userspace and the kernel.
+/// Because it is register sized, [`CapabilityPtr`] is guaranteed to be
+/// at least the size of a word ([usize]) [^note1]. Operations on the
 /// pointer may affect permissions, e.g. offsetting the pointer beyond
 /// the bounds of the memory object invalidates it. Like a `*const
-/// ()`, a [CapabilityPtr] may also "hide" information by storing a
+/// ()`, a [`CapabilityPtr`] may also "hide" information by storing a
 /// word of data with no memory access permissions.
 ///
-/// [CapabilityPtr] should be used to store or pass between the kernel
-/// and userspace a value that may represent a valid userspace reference,
+/// [`CapabilityPtr`] should be used to store or pass a value between the
+/// kernel and userspace that may represent a valid userspace reference,
 /// when one party intends the other to access it.
 ///
 /// [^note1]: Depending on the architecture, the size of a
-/// [CapabilityPtr] may be a word size or larger, e.g., if registers
+/// [`CapabilityPtr`] may be a word size or larger, e.g., if registers
 /// can store metadata such as access permissions.
 #[derive(Copy, Clone, PartialEq, Eq, PartialOrd, Ord, Hash, Debug)]
 #[repr(transparent)]
@@ -39,10 +40,10 @@ impl Default for CapabilityPtr {
     }
 }
 
-/// Permission sets a [CapabilityPtr] may grant.
+/// Permission sets a [`CapabilityPtr`] may grant.
 /// These may not be enforced or exist on a given platform.
 #[derive(Copy, Clone, PartialEq)]
-pub enum MetaPermissions {
+pub enum CapabilityPtrPermissions {
     None,
     Read,
     Write,
@@ -51,7 +52,7 @@ pub enum MetaPermissions {
 }
 
 impl From<CapabilityPtr> for usize {
-    /// Returns the address of the [CapabilityPtr].
+    /// Returns the address of the [`CapabilityPtr`].
     /// Provenance note: may not expose provenance.
     #[inline]
     fn from(from: CapabilityPtr) -> Self {
@@ -60,7 +61,7 @@ impl From<CapabilityPtr> for usize {
 }
 
 impl From<usize> for CapabilityPtr {
-    /// Constructs a [CapabilityPtr] with a given address.
+    /// Constructs a [`CapabilityPtr`] with a given address.
     /// Provenance note: may have null provenance.
     #[inline]
     fn from(from: usize) -> Self {
@@ -71,48 +72,52 @@ impl From<usize> for CapabilityPtr {
 }
 
 impl UpperHex for CapabilityPtr {
+    /// Format the capability as an uppercase hex string.
+    /// Will print at least the address, and any platform specific metadata if it exists.
     #[inline]
     fn fmt(&self, f: &mut Formatter<'_>) -> core::fmt::Result {
         UpperHex::fmt(&(self.ptr as usize), f)
     }
 }
 
 impl LowerHex for CapabilityPtr {
+    /// Format the capability as a lowercase hex string.
+    /// Will print at least the address, and any platform specific metadata if it exists.
     #[inline]
     fn fmt(&self, f: &mut Formatter<'_>) -> core::fmt::Result {
         LowerHex::fmt(&(self.ptr as usize), f)
     }
 }
 
 impl AddAssign<usize> for CapabilityPtr {
-    /// Increments the address of a [CapabilityPtr]
+    /// Increments the address of a [`CapabilityPtr`]
     #[inline]
     fn add_assign(&mut self, rhs: usize) {
         self.ptr = (self.ptr as *const u8).wrapping_add(rhs) as *const ();
     }
 }
 
 impl CapabilityPtr {
-    /// Returns the pointer component of a [CapabilityPtr] but without any of the authority.
+    /// Returns the pointer component of a [`CapabilityPtr`] but without any of the authority.
     pub fn as_ptr<T>(&self) -> *const T {
         self.ptr as *const T
     }
 
-    /// Construct a [CapabilityPtr] from a raw pointer, with the authority requested by other
-    /// arguments.
+    /// Construct a [`CapabilityPtr`] from a raw pointer, with authority ranging over
+    /// [`base`, `base + length`) and permissions `perms`.
     /// Provenance note: may derive from a pointer other than the input to provide something with
     /// valid provenance to justify the other arguments.
     #[inline]
     pub fn new_with_metadata(
         ptr: *const (),
         _base: usize,
         _length: usize,
-        _perms: MetaPermissions,
+        _perms: CapabilityPtrPermissions,
     ) -> Self {
         Self { ptr }
     }
 
-    /// If the [CapabilityPtr] is null returns `default`, otherwise applies `f` to `self`.
+    /// If the [`CapabilityPtr`] is null returns `default`, otherwise applies `f` to `self`.
     #[inline]
     pub fn map_or<U, F>(&self, default: U, f: F) -> U
     where
@@ -125,7 +130,7 @@ impl CapabilityPtr {
         }
     }
 
-    /// If the [CapabilityPtr] is null returns `default`, otherwise applies `f` to `self`.
+    /// If the [`CapabilityPtr`] is null returns `default`, otherwise applies `f` to `self`.
     /// default is only evaluated if `self` is not null.
     #[inline]
     pub fn map_or_else<U, D, F>(&self, default: D, f: F) -> U

kernel/src/utilities/mod.rs

@@ -5,17 +5,16 @@
 //! Utility functions and macros provided by the kernel crate.
 
 pub mod binary_write;
+pub mod capability_ptr;
 pub mod copy_slice;
 pub mod helpers;
 pub mod leasable_buffer;
 pub mod math;
 pub mod mut_imut_buffer;
 pub mod peripheral_management;
 pub mod static_init;
-pub mod storage_volume;
-
-pub mod capability_ptr;
 mod static_ref;
+pub mod storage_volume;
 
 pub use self::static_ref::StaticRef;