Fix up some names and documentation in the sync module.

src/io/dma.rs

@@ -143,7 +143,7 @@ impl DMA0 {
   ///
   /// The source pointer must be aligned and valid to read from.
   pub unsafe fn set_source(src: *const u32) {
-    crate::sync::volatile_mark_ro(src);
+    crate::sync::memory_read_hint(src);
     Self::DMA0SAD.write(src);
   }
 
@@ -156,7 +156,7 @@ impl DMA0 {
   /// The source pointer must be aligned and valid to write to.
   pub unsafe fn set_dest(dest: *mut u32) {
     Self::DMA0DAD.write(dest);
-    crate::sync::volatile_mark_rw(dest);
+    crate::sync::memory_write_hint(dest);
   }
 
   /// Assigns the count register.
@@ -206,7 +206,7 @@ impl DMA1 {
   ///
   /// The source pointer must be aligned and valid to read from.
   pub unsafe fn set_source(src: *const u32) {
-    crate::sync::volatile_mark_ro(src);
+    crate::sync::memory_read_hint(src);
     Self::DMA1SAD.write(src);
   }
 
@@ -219,7 +219,7 @@ impl DMA1 {
   /// The source pointer must be aligned and valid to write to.
   pub unsafe fn set_dest(dest: *mut u32) {
     Self::DMA1DAD.write(dest);
-    crate::sync::volatile_mark_rw(dest);
+    crate::sync::memory_write_hint(dest);
   }
 
   /// Assigns the count register.
@@ -269,7 +269,7 @@ impl DMA2 {
   ///
   /// The source pointer must be aligned and valid to read from.
   pub unsafe fn set_source(src: *const u32) {
-    crate::sync::volatile_mark_ro(src);
+    crate::sync::memory_read_hint(src);
     Self::DMA2SAD.write(src);
   }
 
@@ -282,7 +282,7 @@ impl DMA2 {
   /// The source pointer must be aligned and valid to write to.
   pub unsafe fn set_dest(dest: *mut u32) {
     Self::DMA2DAD.write(dest);
-    crate::sync::volatile_mark_rw(dest);
+    crate::sync::memory_write_hint(dest);
   }
 
   /// Assigns the count register.
@@ -333,7 +333,7 @@ impl DMA3 {
   ///
   /// The source pointer must be aligned and valid to read from.
   pub unsafe fn set_source(src: *const u32) {
-    crate::sync::volatile_mark_ro(src);
+    crate::sync::memory_read_hint(src);
     Self::DMA3SAD.write(src);
   }
 
@@ -346,7 +346,7 @@ impl DMA3 {
   /// The source pointer must be aligned and valid to write to.
   pub unsafe fn set_dest(dest: *mut u32) {
     Self::DMA3DAD.write(dest);
-    crate::sync::volatile_mark_rw(dest);
+    crate::sync::memory_write_hint(dest);
   }
 
   /// Assigns the count register.
@@ -388,12 +388,12 @@ impl DMA3 {
       .with_use_32bit(true)
       .with_enabled(true);
     // TODO: destination checking against SRAM
-    crate::sync::volatile_mark_ro(src);
+    crate::sync::memory_read_hint(src);
     Self::DMA3SAD.write(src);
     Self::DMA3DAD.write(dest);
     Self::DMA3CNT_L.write(count);
     Self::DMA3CNT_H.write(FILL_CONTROL);
-    crate::sync::volatile_mark_rw(dest);
+    crate::sync::memory_write_hint(dest);
 
     // Note(Lokathor): Once DMA is set to activate it takes 2 cycles for it to
     // kick in. You can do any non-DMA thing you like before that, but since

src/sync.rs

@@ -10,17 +10,23 @@ mod statics;
 pub use locks::*;
 pub use statics::*;
 
-/// Marks that a given pointer is read by volatile means without actually
-/// reading it.
+/// Marks that a pointer is read without actually reading from this.
+///
+/// This uses an [`asm!`] instruction that marks the parameter as being read,
+/// requiring the compiler to treat this function as if anything could be
+/// done to it.
 #[inline(always)]
-pub fn volatile_mark_ro<T>(val: *const T) {
+pub fn memory_read_hint<T>(val: *const T) {
   unsafe { asm!("/* {0} */", in(reg) val, options(readonly, nostack)) }
 }
 
-/// Marks that a given pointer is read or written by volatile means without
-/// actually reading or writing it.
+/// Marks that a pointer is read or written to without actually writing to it.
+///
+/// This uses an [`asm!`] instruction that marks the parameter as being read
+/// and written, requiring the compiler to treat this function as if anything
+/// could be done to it.
 #[inline(always)]
-pub fn volatile_mark_rw<T>(val: *mut T) {
+pub fn memory_write_hint<T>(val: *mut T) {
   unsafe { asm!("/* {0} */", in(reg) val, options(nostack)) }
 }
 
@@ -43,16 +49,16 @@ pub unsafe extern "C" fn __sync_synchronize() {}
 ///
 /// This should not be done without good reason, as IRQs are usually important
 /// for game functionality.
-pub fn disable_irqs<T>(mut func: impl FnOnce() -> T) -> T {
+pub fn with_irqs_disabled<T>(mut func: impl FnOnce() -> T) -> T {
   let current_ime = IME.read();
   IME.write(IrqEnableSetting::IRQ_NO);
   // prevents the contents of the function from being reordered before IME is disabled.
-  volatile_mark_rw(&mut func);
+  memory_write_hint(&mut func);
 
   let mut result = func();
 
   // prevents the contents of the function from being reordered after IME is reenabled.
-  volatile_mark_rw(&mut result);
+  memory_write_hint(&mut result);
   IME.write(current_ime);
 
   result

src/sync/statics.rs

@@ -34,7 +34,7 @@ unsafe fn transfer<T: Copy>(dst: *mut T, src: *const T) {
     )
   } else {
     // When we don't have an optimized path, we just disable IRQs.
-    disable_irqs(|| ptr::write_volatile(dst, ptr::read_volatile(src)));
+    with_irqs_disabled(|| ptr::write_volatile(dst, ptr::read_volatile(src)));
   }
 }
 
@@ -151,7 +151,7 @@ unsafe fn exchange<T>(dst: *mut T, src: *const T) -> T {
     ptr::read(&new_val as *const _ as *const T)
   } else {
     // fallback
-    disable_irqs(|| {
+    with_irqs_disabled(|| {
       let cur = ptr::read_volatile(dst);
       ptr::write_volatile(dst, ptr::read_volatile(src));
       cur