Extend Flash API to support writing half-pages

This commit includes C code and a binary blob. Please refer to the
comments in the commit on why this is necessary.

Author: hannobraun

build.rs

@@ -1,5 +1,5 @@
 use std::env;
-use std::fs::File;
+use std::fs::{self, File};
 use std::io::Write;
 use std::path::PathBuf;
 
@@ -48,4 +48,23 @@ fn main() {
     }
 
     println!("cargo:rerun-if-changed=build.rs");
+
+
+    // Copy the binary blog required by the Flash API somewhere the linker can
+    // find it, and tell Cargo to link it.
+
+    let blob_name = "flash";
+    let blob_file = format!("lib{}.a", blob_name);
+    let blob_path = format!("flash-code/{}", blob_file);
+
+    fs::copy(
+        &blob_path,
+        out.join(format!("{}", blob_file)),
+    )
+    .expect("Failed to copy binary blog for Flash API");
+
+    println!("cargo:rustc-link-lib=static={}", blob_name);
+    println!("cargo:rustc-link-search={}", out.display());
+
+    println!("cargo:rerun-if-changed={}", blob_path);
 }

examples/flash.rs

@@ -59,6 +59,19 @@ fn main() -> ! {
         assert_eq!(word, 0);
     }
 
+    let words = [
+        0x0, 0x1, 0x2, 0x3, 0x4, 0x5, 0x6, 0x7,
+        0x8, 0x9, 0xa, 0xb, 0xc, 0xd, 0xe, 0xf,
+    ];
+
+    flash.write_flash_half_page(address, &words)
+        .expect("Failed to write Flash half-page");
+
+    for (i, &expected) in words.iter().enumerate() {
+        let actual = unsafe { *address.offset(i as isize) };
+        assert_eq!(expected, actual);
+    }
+
     // Blink LED to indicate we haven't panicked.
     loop {
         led.set_high().unwrap();

flash-code/.gitignore

@@ -0,0 +1,2 @@
+# C compiler output
+/*.o

flash-code/README.md

@@ -0,0 +1,3 @@
+C code used by the FLASH API to write half-pages. Contains both the source code, as well as a precompiled binary.
+
+The binary can be compiled using `compile.sh` in this directory. See `src/flash.rs` for an explanation of why this is necessary.

flash-code/compile.sh

@@ -0,0 +1,12 @@
+#!/bin/sh
+
+# Compiles `flash.c` using the GCC toolchain. `build.rs` makes sure that the
+# resulting library is linked.
+#
+# Since requiring all users of this HAL to have the GCC toolchain installed
+# would be inconvenient for many, the resulting library is checked into the
+# repository. After every change to `flash.c`, you need to call this script
+# manually and commit the updated binary.
+
+arm-none-eabi-gcc -march=armv6s-m -ffreestanding -O2 -c flash.c &&
+arm-none-eabi-ar r libflash.a flash.o

flash-code/flash.c

@@ -0,0 +1,13 @@
+#include <stdint.h>
+
+
+// Called from src/flash.rs. See comment there for an explanation of why a C
+// function is necessary.
+__attribute__((section(".data")))
+void write_half_page(uint32_t *address, uint32_t *words) {
+    uint32_t i = 0;
+    while (i < 16) {
+        *(address + i) = *(words + i);
+        i++;
+    }
+}

flash-code/libflash.a

@@ -160,6 +160,59 @@ impl FLASH {
         })
     }
 
+    /// Writes a half-page (16 words) of Flash  memory
+    ///
+    /// The memory written to must have been erased before, otherwise this
+    /// method will return an error.
+    ///
+    /// # Panics
+    ///
+    /// This method will panic, unless all of the following is true:
+    /// - `address` points to Flash memory
+    /// - `address` is aligned to a half-page boundary (16 words, 64 bytes)
+    /// - `words` has a length of 16
+    pub fn write_flash_half_page(&mut self, address: *mut u32, words: &[u32])
+        -> Result
+    {
+        self.unlock(|self_| {
+            let memory = self_.verify_address(address);
+
+            if !memory.is_flash() {
+                panic!("Address does not point to Flash memory");
+            }
+            if address as u32 & 0x3f != 0 {
+                panic!("Address is not aligned to half-page boundary");
+            }
+            if words.len() != 16 {
+                panic!("`words` is not exactly a half-page of memory");
+            }
+
+            // Wait, while the memory interface is busy.
+            while self_.flash.sr.read().bsy().is_active() {}
+
+            // Enable write operation
+            self_.flash.pecr.modify(|_, w| {
+                // Half-page programming mode
+                w.fprg().set_bit();
+                // Required for mass operations in Flash memory
+                w.prog().set_bit();
+
+                w
+            });
+
+            // Safe, because we've verified the valididty of `address` and the
+            // length `words`.
+            unsafe { write_half_page(address, words.as_ptr()); }
+
+            // Wait for operation to complete
+            while self_.flash.sr.read().bsy().is_active() {}
+
+            self_.check_errors()
+
+            // No need to reset PECR flags, that's done by `unlock`.
+        })
+    }
+
     fn unlock(&mut self, f: impl FnOnce(&mut Self) -> Result) -> Result {
         // Unlock everything that needs unlocking
         self.flash.pekeyr.write(|w| w.pekeyr().bits(0x89ABCDEF));
@@ -261,6 +314,28 @@ pub fn flash_size_in_kb() -> u32 {
 }
 
 
+extern {
+    /// Writes a half-page at the given address
+    ///
+    /// Unfortunately this function had to be implemented in C. No access to
+    /// Flash memory is allowed after the first word has been written, and that
+    /// includes execution of code that is located in Flash. This means the
+    /// function that writes the half-page has to be executed from memory, and
+    /// is not allowed to call any functions that are not located in memory.
+    ///
+    /// Unfortunately I found this impossible to achieve in Rust. I can write
+    /// a Rust function that is located in RAM, using `#[link_section=".data"]`,
+    /// but I failed to write any useful Rust code that doesn't include function
+    /// calls to _something_ that is outside of my control, as so much of Rust's
+    /// functionality is defined in terms of function calls.
+    ///
+    /// I ended up writing it in C, as that was the only solution I could come
+    /// up with that will run on the stable channel (is nightly is acceptable,
+    /// we could use a Rust function with inline assembly).
+    fn write_half_page(address: *mut u32, words: *const u32);
+}
+
+
 #[derive(Copy, Clone, Eq, PartialEq)]
 enum Memory {
     Flash,