Add safety comments and use consistent format for existing ones. (#1981)

We should have safety comments on all `unsafe` blocks, to set a good
example.

src/exercises/bare-metal/rtc/src/main.rs

@@ -52,22 +52,22 @@ const PL031_IRQ: IntId = IntId::spi(2);
 // ANCHOR: main
 #[no_mangle]
 extern "C" fn main(x0: u64, x1: u64, x2: u64, x3: u64) {
-    // Safe because `PL011_BASE_ADDRESS` is the base address of a PL011 device,
-    // and nothing else accesses that address range.
+    // SAFETY: `PL011_BASE_ADDRESS` is the base address of a PL011 device, and
+    // nothing else accesses that address range.
     let uart = unsafe { Uart::new(PL011_BASE_ADDRESS) };
     logger::init(uart, LevelFilter::Trace).unwrap();
 
     info!("main({:#x}, {:#x}, {:#x}, {:#x})", x0, x1, x2, x3);
 
-    // Safe because `GICD_BASE_ADDRESS` and `GICR_BASE_ADDRESS` are the base
+    // SAFETY: `GICD_BASE_ADDRESS` and `GICR_BASE_ADDRESS` are the base
     // addresses of a GICv3 distributor and redistributor respectively, and
     // nothing else accesses those address ranges.
     let mut gic = unsafe { GicV3::new(GICD_BASE_ADDRESS, GICR_BASE_ADDRESS) };
     gic.setup();
     // ANCHOR_END: main
 
-    // Safe because `PL031_BASE_ADDRESS` is the base address of a PL031 device,
-    // and nothing else accesses that address range.
+    // SAFETY: `PL031_BASE_ADDRESS` is the base address of a PL031 device, and
+    // nothing else accesses that address range.
     let mut rtc = unsafe { Rtc::new(PL031_BASE_ADDRESS) };
     let timestamp = rtc.read();
     let time = Utc.timestamp_opt(timestamp.into(), 0).unwrap();

src/exercises/bare-metal/rtc/src/pl011.rs

@@ -122,8 +122,8 @@ impl Uart {
         // Wait until there is room in the TX buffer.
         while self.read_flag_register().contains(Flags::TXFF) {}
 
-        // Safe because we know that self.registers points to the control
-        // registers of a PL011 device which is appropriately mapped.
+        // SAFETY: We know that self.registers points to the control registers
+        // of a PL011 device which is appropriately mapped.
         unsafe {
             // Write to the TX buffer.
             addr_of_mut!((*self.registers).dr).write_volatile(byte.into());
@@ -139,6 +139,8 @@ impl Uart {
         if self.read_flag_register().contains(Flags::RXFE) {
             None
         } else {
+            // SAFETY: We know that self.registers points to the control
+            // registers of a PL011 device which is appropriately mapped.
             let data = unsafe { addr_of!((*self.registers).dr).read_volatile() };
             // TODO: Check for error conditions in bits 8-11.
             Some(data as u8)
@@ -146,8 +148,8 @@ impl Uart {
     }
 
     fn read_flag_register(&self) -> Flags {
-        // Safe because we know that self.registers points to the control
-        // registers of a PL011 device which is appropriately mapped.
+        // SAFETY: We know that self.registers points to the control registers
+        // of a PL011 device which is appropriately mapped.
         unsafe { addr_of!((*self.registers).fr).read_volatile() }
     }
 }

src/exercises/bare-metal/rtc/src/pl031.rs

@@ -61,24 +61,24 @@ impl Rtc {
 
     /// Reads the current RTC value.
     pub fn read(&self) -> u32 {
-        // Safe because we know that self.registers points to the control
-        // registers of a PL031 device which is appropriately mapped.
+        // SAFETY: We know that self.registers points to the control registers
+        // of a PL031 device which is appropriately mapped.
         unsafe { addr_of!((*self.registers).dr).read_volatile() }
     }
 
     /// Writes a match value. When the RTC value matches this then an interrupt
     /// will be generated (if it is enabled).
     pub fn set_match(&mut self, value: u32) {
-        // Safe because we know that self.registers points to the control
-        // registers of a PL031 device which is appropriately mapped.
+        // SAFETY: We know that self.registers points to the control registers
+        // of a PL031 device which is appropriately mapped.
         unsafe { addr_of_mut!((*self.registers).mr).write_volatile(value) }
     }
 
     /// Returns whether the match register matches the RTC value, whether or not
     /// the interrupt is enabled.
     pub fn matched(&self) -> bool {
-        // Safe because we know that self.registers points to the control
-        // registers of a PL031 device which is appropriately mapped.
+        // SAFETY: We know that self.registers points to the control registers
+        // of a PL031 device which is appropriately mapped.
         let ris = unsafe { addr_of!((*self.registers).ris).read_volatile() };
         (ris & 0x01) != 0
     }
@@ -88,8 +88,8 @@ impl Rtc {
     /// This should be true if and only if `matched` returns true and the
     /// interrupt is masked.
     pub fn interrupt_pending(&self) -> bool {
-        // Safe because we know that self.registers points to the control
-        // registers of a PL031 device which is appropriately mapped.
+        // SAFETY: We know that self.registers points to the control registers
+        // of a PL031 device which is appropriately mapped.
         let ris = unsafe { addr_of!((*self.registers).mis).read_volatile() };
         (ris & 0x01) != 0
     }
@@ -100,19 +100,19 @@ impl Rtc {
     /// interrupt is disabled.
     pub fn enable_interrupt(&mut self, mask: bool) {
         let imsc = if mask { 0x01 } else { 0x00 };
-        // Safe because we know that self.registers points to the control
-        // registers of a PL031 device which is appropriately mapped.
+        // SAFETY: We know that self.registers points to the control registers
+        // of a PL031 device which is appropriately mapped.
         unsafe { addr_of_mut!((*self.registers).imsc).write_volatile(imsc) }
     }
 
     /// Clears a pending interrupt, if any.
     pub fn clear_interrupt(&mut self) {
-        // Safe because we know that self.registers points to the control
-        // registers of a PL031 device which is appropriately mapped.
+        // SAFETY: We know that self.registers points to the control registers
+        // of a PL031 device which is appropriately mapped.
         unsafe { addr_of_mut!((*self.registers).icr).write_volatile(0x01) }
     }
 }
 
-// Safe because it just contains a pointer to device memory, which can be
+// SAFETY: `Rtc` just contains a pointer to device memory, which can be
 // accessed from any context.
 unsafe impl Send for Rtc {}