Add safety comments to unsafe attributes (#592)

Part of #288. This is not yet enforced by clippy
(rust-lang/rust-clippy#13316), but we should
be doing it anyways.

Author: smalis-msft

openhcl/build_info/src/lib.rs

@@ -60,9 +60,13 @@ impl BuildInfo {
 // a debugger. With a debugger, the non-mangled name is easier
 // to use.
 
-// UNSAFETY: link_section and export_name are considered unsafe.
+// UNSAFETY: link_section and export_name are unsafe.
 #[expect(unsafe_code)]
+// SAFETY: The build_info section is custom and carries no safety requirements.
 #[unsafe(link_section = ".build_info")]
+// SAFETY: The name "BUILD_INFO" is only declared here in OpenHCL and shouldn't
+// collide with any other symbols. It is a special symbol intended for
+// post-mortem debugging, and no runtime functionality should depend on it.
 #[unsafe(export_name = "BUILD_INFO")]
 static BUILD_INFO: BuildInfo = BuildInfo::new();
 

openhcl/minimal_rt/src/arch/aarch64/intrinsics.rs

@@ -5,6 +5,8 @@
 
 /// Hand rolled implementation of memcpy.
 #[cfg(minimal_rt)]
+// SAFETY: The minimal_rt_build crate ensures that when this code is compiled
+// there is no libc for this to conflict with.
 #[unsafe(no_mangle)]
 unsafe extern "C" fn memcpy(mut dest: *mut u8, src: *const u8, len: usize) -> *mut u8 {
     // SAFETY: the caller guarantees the pointers and length are correct.
@@ -31,6 +33,8 @@ unsafe extern "C" fn memcpy(mut dest: *mut u8, src: *const u8, len: usize) -> *m
 
 /// Hand rolled implementation of memset.
 #[cfg(minimal_rt)]
+// SAFETY: The minimal_rt_build crate ensures that when this code is compiled
+// there is no libc for this to conflict with.
 #[unsafe(no_mangle)]
 unsafe extern "C" fn memset(mut ptr: *mut u8, val: i32, len: usize) -> *mut u8 {
     // SAFETY: the caller guarantees the pointer and length are correct.

openhcl/minimal_rt/src/arch/x86_64/intrinsics.rs

@@ -5,6 +5,8 @@
 
 /// Hand rolled implementation of memset.
 #[cfg(minimal_rt)]
+// SAFETY: The minimal_rt_build crate ensures that when this code is compiled
+// there is no libc for this to conflict with.
 #[unsafe(no_mangle)]
 unsafe extern "C" fn memset(mut ptr: *mut u8, val: i32, len: usize) -> *mut u8 {
     // SAFETY: The caller guarantees that the pointer and length are correct.
@@ -22,6 +24,8 @@ unsafe extern "C" fn memset(mut ptr: *mut u8, val: i32, len: usize) -> *mut u8 {
 
 /// Hand rolled implementation of memcpy.
 #[cfg(minimal_rt)]
+// SAFETY: The minimal_rt_build crate ensures that when this code is compiled
+// there is no libc for this to conflict with.
 #[unsafe(no_mangle)]
 unsafe extern "C" fn memcpy(mut dest: *mut u8, src: *const u8, len: usize) -> *mut u8 {
     // SAFETY: The caller guarantees that the pointers and length are correct.

openhcl/minimal_rt/src/rt.rs

@@ -24,6 +24,8 @@ mod instead_of_builtins {
     }
 
     /// Implementation cribbed from compiler_builtins.
+    // SAFETY: The minimal_rt_build crate ensures that when this code is compiled
+    // there is no libc for this to conflict with.
     #[unsafe(no_mangle)]
     unsafe extern "C" fn memmove(dest: *mut u8, src: *const u8, n: usize) -> *mut u8 {
         let delta = (dest as usize).wrapping_sub(src as usize);
@@ -47,6 +49,8 @@ mod instead_of_builtins {
     /// This implementation is cribbed from compiler_builtins. It would be nice to
     /// use those implementation for all the above functions, but those require
     /// nightly as these are not yet stabilized.
+    // SAFETY: The minimal_rt_build crate ensures that when this code is compiled
+    // there is no libc for this to conflict with.
     #[unsafe(no_mangle)]
     unsafe extern "C" fn bcmp(s1: *const u8, s2: *const u8, n: usize) -> i32 {
         // SAFETY: The caller guarantees that the pointers and length are correct.

support/openssl_crypto_only/src/lib.rs

@@ -33,6 +33,8 @@ macro_rules! openssl_crypto_only {
         /// # Safety
         ///
         /// The caller must call as documented for `OPENSSL_init_ssl`.
+        // SAFETY: We are purposefully overriding this symbol and we have made
+        // sure the definition is compatible with the original.
         #[unsafe(no_mangle)]
         unsafe extern "C" fn OPENSSL_init_ssl(
             opts: u64,

support/win_prng_support/src/lib.rs

@@ -2,6 +2,9 @@
 // Licensed under the MIT License.
 
 //! Support for running in smaller Windows editions such as Win1.
+//!
+//! This crate purposefully overrides symbols normally provided by system DLLs.
+//! In order for this to be safe the definitions are compatible with the originals.
 
 #![cfg(windows)]
 // UNSAFETY: needed to call internal Windows functions and to export unmangled
@@ -25,6 +28,7 @@ macro_rules! use_win10_prng_apis {
         $($crate::use_win10_prng_apis!(@x $lib);)*
     };
     (@x advapi32) => {
+        // SAFETY: see module level safety justification
         #[unsafe(no_mangle)]
         pub unsafe extern "system" fn SystemFunction036(data: *mut u8, len: u32) -> u8 {
             // SAFETY: passing through guarantees.
@@ -33,11 +37,13 @@ macro_rules! use_win10_prng_apis {
 
         /// If a call to SystemFunction036 is marked as a dllimport, then it may be an indirect call
         /// through __imp_SystemFunction036 instead.
+        // SAFETY: see module level safety justification
         #[unsafe(no_mangle)]
         pub static __imp_SystemFunction036: unsafe extern "system" fn(*mut u8, u32) -> u8 =
             SystemFunction036;
     };
     (@x bcrypt) => {
+        // SAFETY: see module level safety justification
         #[unsafe(no_mangle)]
         pub unsafe extern "system" fn BCryptOpenAlgorithmProvider(
             handle: *mut ::core::ffi::c_void,
@@ -56,6 +62,7 @@ macro_rules! use_win10_prng_apis {
             }
         }
 
+        // SAFETY: see module level safety justification
         #[unsafe(no_mangle)]
         pub unsafe extern "system" fn BCryptCloseAlgorithmProvider(
             handle: *mut ::core::ffi::c_void,
@@ -65,6 +72,7 @@ macro_rules! use_win10_prng_apis {
             unsafe { $crate::private::BCryptCloseAlgorithmProvider(handle, flags) }
         }
 
+        // SAFETY: see module level safety justification
         #[unsafe(no_mangle)]
         pub unsafe extern "system" fn BCryptGenRandom(
             algorithm: usize,
@@ -78,6 +86,7 @@ macro_rules! use_win10_prng_apis {
 
         /// If a call to BCryptGenRandom is marked as a dllimport, then it may be an indirect call
         /// through __imp_BCryptGenRandom instead.
+        // SAFETY: see module level safety justification
         #[unsafe(no_mangle)]
         pub static __imp_BCryptGenRandom: unsafe extern "system" fn(
             usize,
@@ -86,6 +95,7 @@ macro_rules! use_win10_prng_apis {
             u32,
         ) -> u32 = BCryptGenRandom;
 
+        // SAFETY: see module level safety justification
         #[unsafe(no_mangle)]
         pub static __imp_BCryptOpenAlgorithmProvider: unsafe extern "system" fn(
             *mut ::core::ffi::c_void,
@@ -94,6 +104,7 @@ macro_rules! use_win10_prng_apis {
             u32,
         ) -> u32 = BCryptOpenAlgorithmProvider;
 
+        // SAFETY: see module level safety justification
         #[unsafe(no_mangle)]
         pub static __imp_BCryptCloseAlgorithmProvider: unsafe extern "system" fn(
             *mut ::core::ffi::c_void,

vm/vmgs/vmgs_lib/src/lib.rs

@@ -48,6 +48,7 @@ pub enum VmgsError {
 ///
 /// `file_path` must point to a valid null-terminated utf-8 string.
 /// `in_len` must be the size of `in_buf` in bytes and match the value returned from query_size_vmgs
+// SAFETY: In this library this function name is unique.
 #[unsafe(no_mangle)]
 pub unsafe extern "C" fn read_vmgs(
     file_path: *const c_char,
@@ -152,6 +153,7 @@ async fn do_read(
 ///
 /// `file_path` and `data_path` must point to valid null-terminated utf-8 strings.
 /// `encryption_key` must be null-terminated and nonnull if using encryption
+// SAFETY: In this library this function name is unique.
 #[unsafe(no_mangle)]
 pub unsafe extern "C" fn write_vmgs(
     file_path: *const c_char,
@@ -239,6 +241,7 @@ async fn do_write(
 /// # Safety
 ///
 /// `path` must point to a valid null-terminated utf-8 string.
+// SAFETY: In this library this function name is unique.
 #[unsafe(no_mangle)]
 pub unsafe extern "C" fn create_vmgs(
     path: *const c_char,
@@ -335,6 +338,7 @@ async fn do_create(
 ///
 /// `path` pointer must point to a valid, null-terminated utf-8 string.
 /// `out_size` pointer must be nonnull
+// SAFETY: In this library this function name is unique.
 #[unsafe(no_mangle)]
 pub unsafe extern "C" fn query_size_vmgs(
     path: *const c_char,