From 430bf508e29d528f82211f7722e1abb540d4e4a5 Mon Sep 17 00:00:00 2001
From: equation314 <equation618@gmail.com>
Date: Tue, 30 Oct 2018 23:18:15 +0800
Subject: [PATCH] aarch64: add some comments to crate bcm2837

---
 crate/bcm2837/src/gpio.rs      | 12 +++++++-----
 crate/bcm2837/src/mini_uart.rs |  1 +
 2 files changed, 8 insertions(+), 5 deletions(-)

diff --git a/crate/bcm2837/src/gpio.rs b/crate/bcm2837/src/gpio.rs
index 4465303..1b340c7 100644
--- a/crate/bcm2837/src/gpio.rs
+++ b/crate/bcm2837/src/gpio.rs
@@ -6,7 +6,7 @@ use volatile::{ReadOnly, Volatile, WriteOnly};
 /// The base address of the `GPIO` registers.
 const GPIO_BASE: usize = IO_BASE + 0x200000;
 
-/// An alternative GPIO function.
+/// An alternative GPIO function. (ref: peripherals 6.1, page 92)
 #[repr(u8)]
 pub enum Function {
     Input = 0b000,
@@ -19,6 +19,7 @@ pub enum Function {
     Alt5 = 0b010,
 }
 
+/// GPIO registers starting from `GPIO_BASE` (ref: peripherals 6.1, page 90)
 #[repr(C)]
 #[allow(non_snake_case)]
 struct Registers {
@@ -81,6 +82,7 @@ impl<T> Gpio<T> {
     }
 
     /// Set the Gpio pull-up/pull-down state for values in `pin_value`
+    /// (ref: peripherals 6.1, page 101)
     pub fn set_gpio_pd(&mut self, pud_value: u8) {
         unsafe {
             let index = if self.pin >= 32 { 1 } else { 0 };
@@ -118,10 +120,10 @@ impl Gpio<Uninitialized> {
     pub fn into_alt(self, function: Function) -> Gpio<Alt> {
         let select = (self.pin / 10) as usize;
         let offset = 3 * (self.pin % 10) as usize;
-        let mut value = self.registers.FSEL[select].read();
-        value &= !(0b111 << offset);
-        value |= (function as u32) << offset;
-        self.registers.FSEL[select].write(value);
+        self.registers.FSEL[select].update(|value| {
+            *value &= !(0b111 << offset);
+            *value |= (function as u32) << offset;
+        });
         self.transition()
     }
 
diff --git a/crate/bcm2837/src/mini_uart.rs b/crate/bcm2837/src/mini_uart.rs
index d4dcf35..5816017 100644
--- a/crate/bcm2837/src/mini_uart.rs
+++ b/crate/bcm2837/src/mini_uart.rs
@@ -15,6 +15,7 @@ enum LsrStatus {
     TxAvailable = 1 << 5,
 }
 
+/// MU registers starting from `AUX_ENABLES` (ref: peripherals 2.1, page 8)
 #[repr(C)]
 #[allow(non_snake_case)]
 struct Registers {