Remove references to static mut

rust/#114447 made `&mut MY_STATIC_MUT` a warning, with the intention of
disallowing it entirely in the 2024 edition. We never used this in the crate
itself, but it is used in many examples.

This commit removes these references from the examples. In general the new
approach is to change `static mut` of type `X` to type `MaybeUninit<X>`. These
can then cleanly be accessed with
[`MY_STATIC_MUT.write()`](https://doc.rust-lang.org/core/mem/union.MaybeUninit.html#method.write)
followed by
[`MY_STATIC_MUT.assume_init_mut()`](https://doc.rust-lang.org/core/mem/union.MaybeUninit.html#method.assume_init_mut).

Where we need to cast a `MaybeUninit<[X; N]>` to a `[MaybeUninit<X>; N]` in
order to initialise it element-by-element, the
`&mut *ptr::addr_of_mut!(MY_STATIC_MUT)` construction is still used. After
initialisation, we can then access it with `MY_STATIC_MUT.assume_init_mut()`.

In a few DMA Examples we were taking a reference `&mut TARGET_BUFFER` without
initialising TARGET_BUFFER. This commit changes this to
`TARGET_BUFFER.assume_init_mut()` *without* initialising `TARGET_BUFFER`. This
was and remains UB.

* USB Examples: `static mut EP_MEMORY` now has type `MaybeUninit<[u32; 1024]>`
* Ethernet Examples: `static mut DES_RING` now has type `MaybeUninit<ethernet::DesRing<4, 4>>`

Author: richardeoin

examples/adc_dma.rs

@@ -4,6 +4,7 @@
 //! For an example of using ADC1 and ADC2 together, see examples/adc12.rs
 //! For an example of using ADC1 and ADC2 in parallel, see examples/adc12_parallel.rs
 
+#![deny(warnings)]
 #![no_main]
 #![no_std]
 
@@ -33,8 +34,11 @@ fn main() -> ! {
 
     let adc_buffer: &'static mut [u16; 32_768] = {
         // Convert an uninitialised array into an array of uninitialised
-        let buf: &mut [MaybeUninit<u16>; 32_768] =
-            unsafe { mem::transmute(&mut BUFFER) };
+        let buf: &mut [MaybeUninit<u16>; 32_768] = unsafe {
+            &mut *(core::ptr::addr_of_mut!(BUFFER)
+                as *mut [MaybeUninit<_>; 32_768])
+        };
+
         // Initialise memory to valid values
         for slot in buf.iter_mut() {
             // Never create even a _temporary_ reference to uninitialised memory

examples/dma.rs

@@ -1,11 +1,10 @@
 //! Example of Memory to Memory Transfer with the DMA
 
-#![allow(clippy::transmute_ptr_to_ptr)]
 #![deny(warnings)]
 #![no_main]
 #![no_std]
 
-use core::{mem, mem::MaybeUninit};
+use core::mem::MaybeUninit;
 
 use cortex_m_rt::entry;
 #[macro_use]
@@ -57,15 +56,17 @@ fn main() -> ! {
     // Initialise the source buffer with truly random data, without taking any
     // references to uninitialisated memory
     let source_buffer: &'static mut [u32; 20] = {
-        let buf: &mut [MaybeUninit<u32>; 20] =
-            unsafe { mem::transmute(&mut SOURCE_BUFFER) };
+        let buf: &mut [MaybeUninit<u32>; 20] = unsafe {
+            &mut *(core::ptr::addr_of_mut!(SOURCE_BUFFER)
+                as *mut [MaybeUninit<u32>; 20])
+        };
 
         for value in buf.iter_mut() {
             unsafe {
                 value.as_mut_ptr().write(rng.gen().unwrap());
             }
         }
-        unsafe { mem::transmute(buf) }
+        unsafe { SOURCE_BUFFER.assume_init_mut() }
     };
     // Save a copy on the stack so we can check it later
     let source_buffer_cloned = *source_buffer;
@@ -85,7 +86,9 @@ fn main() -> ! {
         Transfer::init(
             streams.4,
             MemoryToMemory::new(),
-            unsafe { mem::transmute(&mut TARGET_BUFFER) }, // Uninitialised memory
+            unsafe {
+                (*core::ptr::addr_of_mut!(TARGET_BUFFER)).assume_init_mut()
+            }, // Uninitialised memory
             Some(source_buffer),
             config,
         );
@@ -97,7 +100,7 @@ fn main() -> ! {
 
     // Now the target memory is actually initialised
     let target_buffer: &'static mut [u32; 20] =
-        unsafe { mem::transmute(&mut TARGET_BUFFER) };
+        unsafe { TARGET_BUFFER.assume_init_mut() };
 
     // Comparison check
     assert_eq!(&source_buffer_cloned, target_buffer);

examples/ethernet-nucleo-h743zi2.rs

@@ -13,6 +13,7 @@
 #![no_std]
 
 extern crate cortex_m_rt as rt;
+use core::mem::MaybeUninit;
 use core::sync::atomic::{AtomicU32, Ordering};
 use rt::{entry, exception};
 
@@ -51,7 +52,8 @@ const MAC_ADDRESS: [u8; 6] = [0x02, 0x00, 0x11, 0x22, 0x33, 0x44];
 
 /// Ethernet descriptor rings are a global singleton
 #[link_section = ".sram3.eth"]
-static mut DES_RING: ethernet::DesRing<4, 4> = ethernet::DesRing::new();
+static mut DES_RING: MaybeUninit<ethernet::DesRing<4, 4>> =
+    MaybeUninit::uninit();
 
 // the program entry point
 #[entry]
@@ -112,6 +114,8 @@ fn main() -> ! {
 
     let mac_addr = smoltcp::wire::EthernetAddress::from_bytes(&MAC_ADDRESS);
     let (_eth_dma, eth_mac) = unsafe {
+        DES_RING.write(ethernet::DesRing::new());
+
         ethernet::new(
             dp.ETHERNET_MAC,
             dp.ETHERNET_MTL,
@@ -127,7 +131,7 @@ fn main() -> ! {
                 rmii_txd0,
                 rmii_txd1,
             ),
-            &mut DES_RING,
+            DES_RING.assume_init_mut(),
             mac_addr,
             ccdr.peripheral.ETH1MAC,
             &ccdr.clocks,

examples/ethernet-rtic-nucleo-h723zg.rs

@@ -19,6 +19,8 @@
 #[allow(unused)]
 mod utilities;
 
+use core::mem::MaybeUninit;
+use core::ptr::addr_of_mut;
 use core::sync::atomic::AtomicU32;
 
 use smoltcp::iface::{Config, Interface, SocketSet, SocketStorage};
@@ -47,16 +49,17 @@ const MAC_ADDRESS: [u8; 6] = [0x02, 0x00, 0x11, 0x22, 0x33, 0x44];
 
 /// Ethernet descriptor rings are a global singleton
 #[link_section = ".axisram.eth"]
-static mut DES_RING: ethernet::DesRing<4, 4> = ethernet::DesRing::new();
+static mut DES_RING: MaybeUninit<ethernet::DesRing<4, 4>> =
+    MaybeUninit::uninit();
 
 /// Net storage with static initialisation - another global singleton
 pub struct NetStorageStatic<'a> {
     socket_storage: [SocketStorage<'a>; 8],
 }
 
-static mut STORE: NetStorageStatic = NetStorageStatic {
-    socket_storage: [SocketStorage::EMPTY; 8],
-};
+// MaybeUninit allows us write code that is correct even if STORE is not
+// initialised by the runtime
+static mut STORE: MaybeUninit<NetStorageStatic> = MaybeUninit::uninit();
 
 pub struct Net<'a> {
     iface: Interface,
@@ -161,6 +164,8 @@ mod app {
 
         let mac_addr = smoltcp::wire::EthernetAddress::from_bytes(&MAC_ADDRESS);
         let (eth_dma, eth_mac) = unsafe {
+            DES_RING.write(ethernet::DesRing::new());
+
             ethernet::new(
                 ctx.device.ETHERNET_MAC,
                 ctx.device.ETHERNET_MTL,
@@ -176,7 +181,7 @@ mod app {
                     rmii_txd0,
                     rmii_txd1,
                 ),
-                &mut DES_RING,
+                DES_RING.assume_init_mut(),
                 mac_addr,
                 ccdr.peripheral.ETH1MAC,
                 &ccdr.clocks,
@@ -192,7 +197,20 @@ mod app {
         unsafe { ethernet::enable_interrupt() };
 
         // unsafe: mutable reference to static storage, we only do this once
-        let store = unsafe { &mut STORE };
+        let store = unsafe {
+            let store_ptr = STORE.as_mut_ptr();
+
+            // Initialise the socket_storage field. Using `write` instead of
+            // assignment via `=` to not call `drop` on the old, uninitialised
+            // value
+            addr_of_mut!((*store_ptr).socket_storage)
+                .write([SocketStorage::EMPTY; 8]);
+
+            // Now that all fields are initialised we can safely use
+            // assume_init_mut to return a mutable reference to STORE
+            STORE.assume_init_mut()
+        };
+
         let net = Net::new(store, eth_dma, mac_addr.into());
 
         // 1ms tick

examples/ethernet-rtic-stm32h735g-dk.rs

@@ -45,7 +45,8 @@ const MAC_ADDRESS: [u8; 6] = [0x02, 0x00, 0x11, 0x22, 0x33, 0x44];
 
 /// Ethernet descriptor rings are a global singleton
 #[link_section = ".axisram.eth"]
-static mut DES_RING: ethernet::DesRing<4, 4> = ethernet::DesRing::new();
+static mut DES_RING: MaybeUninit<ethernet::DesRing<4, 4>> =
+    MaybeUninit::uninit();
 
 // This data will be held by Net through a mutable reference
 pub struct NetStorageStatic<'a> {
@@ -157,6 +158,8 @@ mod app {
 
         let mac_addr = smoltcp::wire::EthernetAddress::from_bytes(&MAC_ADDRESS);
         let (eth_dma, eth_mac) = unsafe {
+            DES_RING.write(ethernet::DesRing::new());
+
             ethernet::new(
                 ctx.device.ETHERNET_MAC,
                 ctx.device.ETHERNET_MTL,
@@ -172,7 +175,7 @@ mod app {
                     rmii_txd0,
                     rmii_txd1,
                 ),
-                &mut DES_RING,
+                DES_RING.assume_init_mut(),
                 mac_addr,
                 ccdr.peripheral.ETH1MAC,
                 &ccdr.clocks,

examples/ethernet-rtic-stm32h747i-disco.rs

@@ -52,7 +52,8 @@ const MAC_ADDRESS: [u8; 6] = [0x02, 0x00, 0x11, 0x22, 0x33, 0x44];
 
 /// Ethernet descriptor rings are a global singleton
 #[link_section = ".sram3.eth"]
-static mut DES_RING: ethernet::DesRing<4, 4> = ethernet::DesRing::new();
+static mut DES_RING: MaybeUninit<ethernet::DesRing<4, 4>> =
+    MaybeUninit::uninit();
 
 // This data will be held by Net through a mutable reference
 pub struct NetStorageStatic<'a> {
@@ -167,6 +168,8 @@ mod app {
 
         let mac_addr = smoltcp::wire::EthernetAddress::from_bytes(&MAC_ADDRESS);
         let (eth_dma, eth_mac) = unsafe {
+            DES_RING.write(ethernet::DesRing::new());
+
             ethernet::new(
                 ctx.device.ETHERNET_MAC,
                 ctx.device.ETHERNET_MTL,
@@ -182,7 +185,7 @@ mod app {
                     rmii_txd0,
                     rmii_txd1,
                 ),
-                &mut DES_RING,
+                DES_RING.assume_init_mut(),
                 mac_addr,
                 ccdr.peripheral.ETH1MAC,
                 &ccdr.clocks,

examples/ethernet-stm32h747i-disco.rs

@@ -11,6 +11,7 @@
 #![no_main]
 #![no_std]
 
+use core::mem::MaybeUninit;
 use cortex_m_rt as rt;
 use rt::{entry, exception};
 
@@ -28,7 +29,8 @@ const MAC_ADDRESS: [u8; 6] = [0x02, 0x00, 0x11, 0x22, 0x33, 0x44];
 
 /// Ethernet descriptor rings are a global singleton
 #[link_section = ".sram3.eth"]
-static mut DES_RING: ethernet::DesRing<4, 4> = ethernet::DesRing::new();
+static mut DES_RING: MaybeUninit<ethernet::DesRing<4, 4>> =
+    MaybeUninit::uninit();
 
 // the program entry point
 #[entry]
@@ -85,6 +87,8 @@ fn main() -> ! {
 
     let mac_addr = smoltcp::wire::EthernetAddress::from_bytes(&MAC_ADDRESS);
     let (_eth_dma, eth_mac) = unsafe {
+        DES_RING.write(ethernet::DesRing::new());
+
         ethernet::new(
             dp.ETHERNET_MAC,
             dp.ETHERNET_MTL,
@@ -100,7 +104,7 @@ fn main() -> ! {
                 rmii_txd0,
                 rmii_txd1,
             ),
-            &mut DES_RING,
+            DES_RING.assume_init_mut(),
             mac_addr,
             ccdr.peripheral.ETH1MAC,
             &ccdr.clocks,

examples/i2c4_bdma.rs

@@ -2,12 +2,11 @@
 //!
 //!
 
-#![allow(clippy::transmute_ptr_to_ptr)]
 #![deny(warnings)]
 #![no_std]
 #![no_main]
 
-use core::{mem, mem::MaybeUninit};
+use core::mem::MaybeUninit;
 
 #[macro_use]
 mod utilities;
@@ -93,13 +92,14 @@ fn main() -> ! {
     let config = BdmaConfig::default().memory_increment(true);
 
     // We need to specify the direction with a type annotation
-    let mut transfer: Transfer<_, _, PeripheralToMemory, _, _> = Transfer::init(
-        streams.0,
-        i2c,
-        unsafe { &mut BUFFER }, // uninitialised memory
-        None,
-        config,
-    );
+    let mut transfer: Transfer<_, _, PeripheralToMemory, &mut [u8; 10], _> =
+        Transfer::init(
+            streams.0,
+            i2c,
+            unsafe { BUFFER.assume_init_mut() }, // uninitialised memory
+            None,
+            config,
+        );
 
     transfer.start(|i2c| {
         // This closure runs right after enabling the stream
@@ -128,7 +128,7 @@ fn I2C4_EV() {
     info!("I2C transfer complete!");
 
     // Look at BUFFER, which we expect to be initialised
-    let buffer: &'static mut [u8; 10] = unsafe { mem::transmute(&mut BUFFER) };
+    let buffer: &'static [u8; 10] = unsafe { BUFFER.assume_init_mut() };
 
     assert_eq!(buffer[0], 0xBE);
 

examples/mdma.rs

@@ -1,6 +1,5 @@
 //! Example of Memory to Memory Transfer with the Master DMA (MDMA)
 
-#![allow(clippy::transmute_ptr_to_ptr)]
 #![deny(warnings)]
 #![no_main]
 #![no_std]
@@ -52,15 +51,17 @@ fn main() -> ! {
     // Initialise the source buffer without taking any references to
     // uninitialisated memory
     let source_buffer: &'static mut [u32; 200] = {
-        let buf: &mut [MaybeUninit<u32>; 200] =
-            unsafe { mem::transmute(&mut SOURCE_BUFFER) };
+        let buf: &mut [MaybeUninit<u32>; 200] = unsafe {
+            &mut *(core::ptr::addr_of_mut!(SOURCE_BUFFER)
+                as *mut [MaybeUninit<u32>; 200])
+        };
 
         for value in buf.iter_mut() {
             unsafe {
                 value.as_mut_ptr().write(0x11223344u32);
             }
         }
-        unsafe { mem::transmute(buf) }
+        unsafe { SOURCE_BUFFER.assume_init_mut() }
     };
 
     //
@@ -104,8 +105,7 @@ fn main() -> ! {
     while !transfer.get_transfer_complete_flag() {}
 
     // Decompose the stream to get the source buffer back
-    let (stream, _mem2mem, _target, source_buffer_opt) = transfer.free();
-    let source_buffer = source_buffer_opt.unwrap();
+    let (stream, _mem2mem, _target, _) = transfer.free();
 
     for a in target_buffer.iter() {
         assert_eq!(*a, 0x11223344);
@@ -118,6 +118,7 @@ fn main() -> ! {
     //
 
     // Reset source buffer
+    let source_buffer = unsafe { SOURCE_BUFFER.assume_init_mut() };
     *source_buffer = [0xAABBCCDD; 200];
 
     // New target buffer on the stack