Update NVM API (#674)

* Nvm: Derive Copy and Clone for `nvm::Bank`

* Nvm: refactor focused on extending the userpage API

Overview:

- Make the NVM bitfield structs' methods public
- Add setters for the `Userpage` bitfield struct
    - CalibrationArea and TemperaturesCalibrationArea do not need
    setters as they cannot be modified.
- Extend the `Userpage` struct to cover the whole page (512 bytes)
- Split `Nvm::write` and `Nvm::erase` method into "main address space
flash" and "userpage flash" oriented APIs
- Add idempotent `Nvm::modify_userpage` (avoids unnecessary
flash erase & write)

Breaking changes:
- Switch to `*mut 32` from `u32` for address arguments
- `Nvm::userpage` -> `Nvm::read_userpage`
- `Nvm::write` -> `Nvm::write_flash`
- `Nvm::write_from_slice` -> `Nvm::write_flash_from_slice`
- `Nvm::erase` -> `Nvm::erase_flash`
    Note:
        Block erase granularity is assumed for main address space
        flash erasure; thus `granularity` disappeared from the
        signature.

* Nvm: expose extra commands and raw registers

New methods providing access to the following NVM commands
- SSB (Enable Security Bit)
- CELCK (Enable Chip-Erase Lock)
- CEULCK (Disable Chip-Erase Lock)

Also, expose unsafely underlying `NVMCTRL` register type as an
escape hatch (`Nvm::registers`).

* Add NVM API changes to CHANGELOG

* Refactor error handling in NVMCTRL

* Add `region_lock` API

* Fix and invert the condition

* Update CHANGELOG.md

* Clarify region lock doc comment

---------

Co-authored-by: Gabriel Górski <[email protected]>

Author: nilfit

boards/feather_m4/examples/nvm_dsu.rs

@@ -15,7 +15,7 @@ use bsp::entry;
 use ehal::digital::v2::ToggleableOutputPin;
 use hal::clock::GenericClockController;
 use hal::dsu::Dsu;
-use hal::nvm::{retrieve_bank_size, Bank, EraseGranularity, Nvm, BLOCKSIZE};
+use hal::nvm::{retrieve_bank_size, Bank, Nvm, WriteGranularity, BLOCKSIZE};
 use hal::pac::{interrupt, CorePeripherals, Peripherals};
 use hal::usb::UsbBus;
 
@@ -105,17 +105,14 @@ fn main() -> ! {
         if crc32_checksum_active_bank != crc32_checksum_inactive_bank {
             serial_writeln!("Checksums differ: overwrite inactive bank with active one");
             serial_writeln!("Erase inactive bank");
-            nvm.erase(
-                inactive_bank_address,
-                bank_size_in_blocks,
-                EraseGranularity::Block,
-            )
-            .unwrap();
+            nvm.erase_flash(inactive_bank_address as *mut _, bank_size_in_blocks)
+                .unwrap();
             serial_writeln!("Overwrite inactive bank with active bank");
-            nvm.write(
-                inactive_bank_address,
-                active_bank_address,
+            nvm.write_flash(
+                inactive_bank_address as *mut _,
+                active_bank_address as *const _,
                 bank_size_in_words,
+                WriteGranularity::Page,
             )
             .unwrap();
             serial_writeln!("Swapping banks & reset!");

hal/CHANGELOG.md

@@ -10,6 +10,17 @@
 - Fix failing `bsp_pins!` invocation with no aliases (#605 fixes #599)
 - Add Advanced Encryption Standard (AES) peripheral support including RustCrypto compatible backend
 - Add embedded-hal `InputPin` trait to EIC pins
+- Change NVM API
+  - Add the ability to modify the user row
+  - Add security bit and chip-erase lock management
+  - Add escape hatch to access the underlying NVMCTRL PAC
+  - Add `Nvm::region_lock` method
+  - Change flash read/write/erase method signatures
+      - `Nvm::userpage` -> `Nvm::read_userpage`
+      - `Nvm::write` -> `Nvm::write_flash`
+      - `Nvm::write_from_slice` -> `Nvm::write_flash_from_slice`
+      - `Nvm::erase` -> `Nvm::erase_flash`
+  - Refactor `Nvm::command_sync` to be less error-prone
 
 # v0.15.1