Refactor guidelines for unsafe operations in Rust

Removed visibility section and updated examples for compliance with Rust Edition 2024. Clarified unsafe usage in function declarations and attributes.

Author: rcseacord

src/coding-guidelines/attributes/gui_ZDLZzjeOwLSU.rst.inc

@@ -45,14 +45,10 @@
             * Prevents accidental use of ``unsafe`` operations without conscious decision
             * Aligns with the principle of "defense in depth" in safety-critical systems
 
-        * Visibility
-
-            * Encouraging visibility discourages hiding unsafe operations inside safe-looking abstractions without proper encapsulation
-            * Macros that expand to unsafe code should preserve the ``unsafe`` token visibility
-
         * Static Analysis and Tooling
 
-            * Tools like ``cargo-geiger`` :cite:`gui_cD3eGh4iJk5l:CARGO-GEIGER`, ``unsafe-inspect``, and custom linters can automatically locate and count unsafe blocks
+            * Tools like ``cargo-geiger`` :cite:`gui_cD3eGh4iJk5l:CARGO-GEIGER`, ``unsafe-inspect``,
+              and custom linters can automatically locate and count unsafe blocks
             * Enables metrics like "unsafe density" for safety assessments
             * Supports qualification evidence required by certification standards
 
@@ -68,23 +64,43 @@
 
         The ``#[no_mangle]`` attribute is unsafe because it can be used to declare a 
         function identifier that conflicts with an existing symbol.
-        This noncompliant example declares an unmangled function named 'malloc'.
-        This identifier may conflict with the 'malloc' function from C,
-        if the C library is linked with the executable.
+        This noncompliant example declares an unmangled function named 'convert'.
+        This symbol may conflict with another 'convert' symbol defined in a different crate at link time,
+        resulting in undefined behavior.
+        It is even possible for an unmangled symbol to conflict with a mangled symbol.
 
         This noncompliant example requires Rust Edition 2021 or earlier to compile.
 
         .. rust-example::
-           :compile_fail:
+..           :compile_fail:
 
             // Undefined behavior by the linker or loader is possible 
-            // if another 'something' function is defined.
+            // if another 'convert' function is defined.
             #[no_mangle]
-            fn malloc() {}
+            fn convert() {}
 
             fn main() {
                 // Call the unmangled function
-                malloc();
+                convert();
+            }
+
+    .. compliant_example::
+        :id: compl_ex_wR1FEyLRKmrr
+        :status: draft
+
+        Rust Edition 2024 enforces that the ``no_mangle`` attribute requires an ``unsafe`` keyword,
+        as shown in this compliant example.
+
+        NOTE:  This code can still have undefined behavior if the 'convert' function symbol is define more than once.
+
+        .. rust-example::
+
+            #[unsafe(no_mangle)] // compliant.
+            fn convert() {}
+
+            fn main() {
+                // Call the no_mangle function (safe to call)
+                convert();
             }
 
     .. non_compliant_example::
@@ -99,7 +115,7 @@
         This noncompliant example requires Rust Edition 2021 or earlier to compile.
 
         .. rust-example::
-           :compile_fail:
+..           :compile_fail:
 
            use std::ffi;
 
@@ -121,74 +137,21 @@
                }
            }
 
-    .. non_compliant_example::
-        :id: non_compl_ex_Hk3mNp5qRs7t
-        :status: draft
-
-        The ``#[export_name]`` and ``#[link_section]`` attributes can cause undefined behavior if misused,
-        as they affect symbol resolution and memory layout at link time.
-        Without the ``unsafe`` keyword, these hazards are not visible to reviewers or tools.
-
-        This noncompliant example has two problems.
-        First, it uses an ``#[export_name]`` attribute without an unsafe wrapper.
-        This attribute controls the symbol name used during linking.
-        If another symbol with the same name exists, it causes undefined behavior.
-        Rust 2024 requires it to be marked ``unsafe``.
-
-        The second problem is that this noncompliant example uses a ``#[link_section]`` attribute without unsafe wrapper.
-        This attribute places the item in a specific linker section.
-        Incorrect section placement can cause undefined behavior
-        (e.g., placing mutable data in read-only sections, or interfering with special sections like ``.init``).
-
-        This noncompliant example requires Rust Edition 2021 or earlier to compile.
-
-        .. rust-example::
-           :compile_fail:
-
-            // Missing unsafe marker - noncompliant in Rust 2024
-            #[export_name = "custom_symbol"]
-            pub fn my_function() {}
-
-            // Missing unsafe marker - noncompliant in Rust 2024
-            #[link_section = ".custom_section"]
-            static DATA: u32 = 42;
-
-    .. non_compliant_example::
-        :id: non_compl_ex_Jm4oQr6sUv8w
-        :status: draft
-
-        Macros that generate unsafe code without preserving the ``unsafe`` token visibility
-        obscure safety-critical code from auditors and static analysis tools.
-
-        .. rust-example::
-
-            // This macro hides the unsafe token from callers - noncompliant
-            macro_rules! hidden_unsafe_call {
-                ($ptr:expr) => {
-                    unsafe { *$ptr }
-                };
-            }
-
-            fn main() {
-                let x = 42;
-                let ptr = &x as *const i32;
-                // The unsafe operation is hidden from the caller
-                let val = hidden_unsafe_call!(ptr);
-            }
-
     .. compliant_example::
         :id: compl_ex_wR1FEyLRKmrq
         :status: draft
 
-        Using at least Rust Edition 2024 enforces that these things that involve safety obligations require the ``unsafe`` token.
+        Rust Edition 2024 enforces that ``extern "C"`` blocks require an ``unsafe`` keyword,
+        as shown in this compliant example.
+
+        NOTE:  This code can still have undefined behavior if the declared 'malloc' function is incompatible with
+        the actual definition of the 'malloc' function.  To eliminate this undefined behavior, the declaration for
+        ``malloc`` used in this compliant example has been correct to accept one argument of type ``usize``.
 
         .. rust-example::
 
             use std::ffi;
 
-            #[unsafe(no_mangle)]
-            fn something() {}
-
             unsafe extern "C" {
                 // Here the assumption is that malloc is the one defined by C's stdlib.h
                 // and that size_of::<usize>() == size_of::<size_t>()
@@ -197,9 +160,6 @@
             }
 
             fn main() {
-                // Call the no_mangle function (safe to call)
-                something();
-
                 // Call the extern functions (requires unsafe block)
                 unsafe {
                     let ptr = malloc(1024);
@@ -210,43 +170,52 @@
                 }
             }
 
-    .. compliant_example::
-        :id: compl_ex_xY2zAb3cDe4f
+    .. non_compliant_example::
+        :id: non_compl_ex_Hk3mNp5qRs7t
         :status: draft
 
-        The ``#[export_name]`` and ``#[link_section]`` attributes must use the ``unsafe()`` wrapper
-        to make their safety implications visible.
+        The ``#[export_name]`` and ``#[link_section]`` attributes can cause undefined behavior if misused,
+        as they affect symbol resolution and memory layout at link time.
+        Without the ``unsafe`` keyword, these hazards are not visible to reviewers or tools.
+
+        This noncompliant example has two separate problems.
+        First, it uses an ``#[export_name]`` attribute without an unsafe wrapper.
+        This attribute controls the symbol name used during linking.
+        If another symbol with the same name exists, it causes undefined behavior.
+        Rust 2024 requires it to be marked ``unsafe``.
+
+        The second problem is that this noncompliant example uses a ``#[link_section]`` attribute without unsafe wrapper.
+        This attribute places the item in a specific linker section.
+        Incorrect section placement can cause undefined behavior
+        (e.g., placing mutable data in read-only sections, or interfering with special sections like ``.init``).
+
+        This noncompliant example requires Rust Edition 2021 or earlier to compile.
 
         .. rust-example::
+           :compile_fail:
 
-            #[unsafe(export_name = "custom_symbol")]
-            pub fn my_function() {}
+            // Missing unsafe marker - noncompliant in Rust 2024
+            #[export_name = "custom_symbol"] // error: unsafe attribute used without unsafe
+            pub fn my_function() {}  
 
-            #[unsafe(link_section = ".custom_section")]
+            // Missing unsafe marker - noncompliant in Rust 2024
+            #[link_section = ".custom_section"] // error: unsafe attribute used without unsafe
             static DATA: u32 = 42;
 
     .. compliant_example::
-        :id: compl_ex_gH5iJk6lMn7o
+        :id: compl_ex_xY2zAb3cDe4f
         :status: draft
 
-        Macros that involve unsafe operations should require the caller to provide the ``unsafe``
-        token, preserving visibility for auditors and tools.
+        The ``#[export_name]`` and ``#[link_section]`` attributes must use the ``unsafe()`` wrapper
+        to make their safety implications visible.
 
         .. rust-example::
 
-            // This macro requires the caller to acknowledge the unsafe operation - compliant
-            macro_rules! unsafe_deref {
-                ($ptr:expr) => {
-                    *$ptr
-                };
-            }
+            #[unsafe(export_name = "custom_symbol")]
+            pub fn my_function() {}
 
-            fn main() {
-                let x = 42;
-                let ptr = &x as *const i32;
-                // The unsafe operation is visible at the call site
-                let val = unsafe { unsafe_deref!(ptr) };
-            }
+            #[unsafe(link_section = ".custom_section")]
+            static DATA: u32 = 42;
 
     .. enforcement::
         :id: enf_pQ8rSt9uVw0x