Merge #337

337: Provides common Nvmc functionality r=jonas-schievink a=huntc

The [embedded-storage](https://github.com/rust-embedded-community/embedded-storage) traits are implemented to provide a higher-level abstraction for reading and writing from/to flash storage. In the first instance, support is provided for the nRF52 boards and the nRF9160, but other boards should be relatively easy to support if required in the future.

Sample usage of writing to flash given some 32 bit aligned slice of bytes:

```rust
// Erase a page
let _ = nvmc.try_erase(0, 4096);

// Write the 32 bit aligned slice
let _ = nvmc.try_write(0, some_u8_slice_on_32_bit_bounds);
```

An example of establishing the `Nvmc` on the nRF9160:

```rust
let mut nvmc = Nvmc::new(board.NVMC_NS, unsafe { &mut CONFIG });
```

...where CONFIG points to flash:

```rust
extern "C" {
    #[link_name = "_config"]
    static mut CONFIG: [u32; 1024];
}
```

...which can be expressed in a memory layout:

```
MEMORY
{
  /* NOTE 1 K = 1 KiBi = 1024 bytes */
  FLASH : ORIGIN = 0x00040000, LENGTH = 764K
  CONFIG : ORIGIN = ORIGIN(FLASH) + LENGTH(FLASH), LENGTH = 4K /* 4K is the flash page size */
  RAM : ORIGIN = 0x20020000, LENGTH = 128K
}

_config = ORIGIN(CONFIG);
```

Testing on the nRF52840 device can be achieved via `cargo test --test nvmc` from within the `nrf52840-hal-tests` folder.

Fixes #336 

TODO:

* [x] Implement the `ReadNorFlash` methods
* [x] Implement the `NorFlash` methods
* [x] Provide an `Instance` for the nRF52840
* [x] Provide an `Instance` for the nRF9160
* [x] Provide a nvmc module in nrf52840-tests for the new abstraction
* [x] Write some more tests to test some boundary conditions
* [x] Go through the code finely and compare it again with the nrfx library
* [x] Provide an example of reading, writing and erasing from/to storage

Co-authored-by: huntc <[email protected]>

Author: bors[bot]

.gitignore

@@ -1,4 +1,4 @@
-/target/
+target/
 .gdb_history
 [._]*.sw[a-p]
 **/*.rs.bk

examples/nvmc-demo/Cargo.toml

@@ -0,0 +1,26 @@
+[package]
+name = "nvmc-demo"
+version = "0.1.0"
+authors = ["Christopher Hunt"]
+edition = "2018"
+publish = false
+
+# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
+
+[dependencies]
+cortex-m = "0.6.2"
+cortex-m-rt = "0.6.12"
+embedded-storage = "0.1.0"
+rtt-target = {version = "0.2.0", features = ["cortex-m"] }
+
+[dependencies.embedded-hal]
+version = "0.2.3"
+features = ["unproven"]
+
+[dependencies.nrf52840-hal]
+features = ["rt"]
+path = "../../nrf52840-hal"
+optional = true
+
+[features]
+52840 = ["nrf52840-hal"]

examples/nvmc-demo/Embed.toml

@@ -0,0 +1,63 @@
+[default.probe]
+# USB vendor ID
+# usb_vid = "1337"
+# USB product ID
+# usb_pid = "1337"
+# Serial number
+# serial = "12345678"
+# The protocol to be used for communicating with the target.
+protocol = "Swd"
+# The speed in kHz of the data link to the target.
+# speed = 1337
+
+[default.flashing]
+# Whether or not the target should be flashed.
+enabled = true
+# Whether or not the target should be halted after reset.
+# DEPRECATED, moved to reset section
+halt_afterwards = false
+# Whether or not bytes erased but not rewritten with data from the ELF
+# should be restored with their contents before erasing.
+restore_unwritten_bytes = false
+# The path where an SVG of the assembled flash layout should be written to.
+# flash_layout_output_path = "out.svg"
+
+[default.reset]
+# Whether or not the target should be reset.
+# When flashing is enabled as well, the target will be reset after flashing.
+enabled = true
+# Whether or not the target should be halted after reset.
+halt_afterwards = false
+
+[default.general]
+# The chip name of the chip to be debugged.
+chip = "nRF52840_xxAA"
+# A list of chip descriptions to be loaded during runtime.
+chip_descriptions = []
+# The default log level to be used. Possible values are one of:
+#   "OFF", "ERROR", "WARN", "INFO", "DEBUG", "TRACE" 
+log_level = "WARN"
+
+[default.rtt]
+# Whether or not an RTTUI should be opened after flashing.
+# This is exclusive and cannot be used with GDB at the moment.
+enabled = true
+# A list of channel associations to be displayed. If left empty, all channels are displayed.
+channels = [
+    # { up = 0, down = 0, name = "name", format = "String" }
+]
+# The duration in ms for which the logger should retry to attach to RTT.
+timeout = 3000
+# Whether timestamps in the RTTUI are enabled
+show_timestamps = true
+# Whether to save rtt history buffer on exit.
+log_enabled = false
+# Where to save rtt history buffer relative to manifest path.
+log_path = "./logs"
+
+[default.gdb]
+# Whether or not a GDB server should be opened after flashing.
+# This is exclusive and cannot be used with RTT at the moment.
+enabled = false
+# The connection string in host:port format wher the GDB server will open a socket.
+# gdb_connection_string

examples/nvmc-demo/build.rs

@@ -0,0 +1,31 @@
+//! This build script copies the `memory.x` file from the crate root into
+//! a directory where the linker can always find it at build time.
+//! For many projects this is optional, as the linker always searches the
+//! project root directory -- wherever `Cargo.toml` is. However, if you
+//! are using a workspace or have a more complicated build setup, this
+//! build script becomes required. Additionally, by requesting that
+//! Cargo re-run the build script whenever `memory.x` is changed,
+//! updating `memory.x` ensures a rebuild of the application with the
+//! new memory settings.
+
+use std::env;
+use std::fs::File;
+use std::io::Write;
+use std::path::PathBuf;
+
+fn main() {
+    // Put `memory.x` in our output directory and ensure it's
+    // on the linker search path.
+    let out = &PathBuf::from(env::var_os("OUT_DIR").unwrap());
+    File::create(out.join("memory.x"))
+        .unwrap()
+        .write_all(include_bytes!("memory.x"))
+        .unwrap();
+    println!("cargo:rustc-link-search={}", out.display());
+
+    // By default, Cargo will re-run a build script whenever
+    // any file in the project changes. By specifying `memory.x`
+    // here, we ensure the build script is only re-run when
+    // `memory.x` is changed.
+    println!("cargo:rerun-if-changed=memory.x");
+}

examples/nvmc-demo/memory.x

@@ -0,0 +1,35 @@
+MEMORY
+{
+  /* NOTE 1 K = 1 KiBi = 1024 bytes */
+  FLASH : ORIGIN = 0x00000000, LENGTH = 1020K
+  CONFIG : ORIGIN = ORIGIN(FLASH) + LENGTH(FLASH), LENGTH = 4K /* 4K is the flash page size */
+  RAM : ORIGIN = 0x20000000, LENGTH = 256K
+}
+
+_config = ORIGIN(CONFIG);
+
+/* This is where the call stack will be allocated. */
+/* The stack is of the full descending type. */
+/* You may want to use this variable to locate the call stack and static
+   variables in different memory regions. Below is shown the default value */
+/* _stack_start = ORIGIN(RAM) + LENGTH(RAM); */
+
+/* You can use this symbol to customize the location of the .text section */
+/* If omitted the .text section will be placed right after the .vector_table
+   section */
+/* This is required only on microcontrollers that store some configuration right
+   after the vector table */
+/* _stext = ORIGIN(FLASH) + 0x400; */
+
+/* Example of putting non-initialized variables into custom RAM locations. */
+/* This assumes you have defined a region RAM2 above, and in the Rust
+   sources added the attribute `#[link_section = ".ram2bss"]` to the data
+   you want to place there. */
+/* Note that the section will not be zero-initialized by the runtime! */
+/* SECTIONS {
+     .ram2bss (NOLOAD) : ALIGN(4) {
+       *(.ram2bss);
+       . = ALIGN(4);
+     } > RAM2
+   } INSERT AFTER .bss;
+*/

examples/nvmc-demo/src/main.rs

@@ -0,0 +1,50 @@
+#![no_std]
+#![no_main]
+
+// Simple NVMC example
+
+#[cfg(feature = "52840")]
+use nrf52840_hal as hal;
+
+use embedded_storage::nor_flash::NorFlash;
+use embedded_storage::nor_flash::ReadNorFlash;
+use hal::nvmc::Nvmc;
+use rtt_target::{rprintln, rtt_init_print};
+
+const CONFIG_SIZE: usize = 1024;
+extern "C" {
+    #[link_name = "_config"]
+    static mut CONFIG: [u32; CONFIG_SIZE];
+}
+
+// To run this: `cargo embed --features "52840" --target thumbv7em-none-eabihf`
+
+#[cortex_m_rt::entry]
+fn main() -> ! {
+    rtt_init_print!();
+
+    let p = hal::pac::Peripherals::take().unwrap();
+
+    #[cfg(feature = "52840")]
+    let mut nvmc = Nvmc::new(p.NVMC, unsafe { &mut CONFIG });
+
+    assert!(nvmc.try_erase(0, CONFIG_SIZE as u32 * 4).is_ok());
+    let write_buf: [u8; 4] = [1, 2, 3, 4];
+    assert!(nvmc.try_write(0, &write_buf).is_ok());
+    let mut read_buf = [0u8; 2];
+    assert!(nvmc.try_read(0, &mut read_buf).is_ok());
+    assert_eq!(read_buf, write_buf[0..2]);
+
+    rprintln!("What was written to flash was read!");
+
+    loop {
+        cortex_m::asm::wfe();
+    }
+}
+
+#[panic_handler] // panicking behavior
+fn panic(_: &core::panic::PanicInfo) -> ! {
+    loop {
+        cortex_m::asm::bkpt();
+    }
+}

nrf-hal-common/Cargo.toml

@@ -26,6 +26,7 @@ fixed = "1.0.0"
 rand_core = "0.6.3"
 cfg-if = "1.0.0"
 embedded-dma = "0.1.1"
+embedded-storage = "0.1.0"
 
 [dependencies.void]
 default-features = false

nrf-hal-common/src/lib.rs

@@ -47,6 +47,8 @@ pub mod i2s;
 pub mod ieee802154;
 #[cfg(not(any(feature = "52811", feature = "52810", feature = "9160")))]
 pub mod lpcomp;
+#[cfg(not(feature = "51"))]
+pub mod nvmc;
 #[cfg(not(feature = "9160"))]
 pub mod ppi;
 #[cfg(not(feature = "51"))]