Initial commit

Author: Yatekii

.github/FUNDING.yml

@@ -0,0 +1 @@
+github: [probe-rs]

.github/workflows/ci.yml

@@ -0,0 +1,34 @@
+on:
+  push:
+    branches: [master, staging, trying]
+  pull_request:
+
+name: Run CI
+
+env:
+  CARGO_TERM_COLOR: always
+
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v3
+    - name: Install stable toolchain
+      uses: dtolnay/rust-toolchain@stable
+      with:
+        target: thumbv7em-none-eabi
+    - name: Cache Dependencies
+      uses: Swatinem/[email protected]
+    - name: Install Dependencies
+      run: |
+        sudo apt update
+        cargo install cargo-binutils
+        rustup component add llvm-tools-preview
+    - name: Check
+      run: cargo check --target thumbv7em-none-eabi
+    - name: Clippy
+      run: cargo clippy --target thumbv7em-none-eabi
+    - name: Format
+      run: cargo fmt

.gitignore

@@ -0,0 +1,2 @@
+/target
+/Cargo.lock

Cargo.toml

@@ -0,0 +1,11 @@
+[package]
+name = "flash-algorithm"
+version = "0.1.0"
+edition = "2021"
+readme = "README.md"
+keywords = ["no-std", "embedded", "flashing"]
+license = "MIT OR Apache-2.0"
+repository = "https://github.com/probe-rs/flash-algorithm"
+description = "A crate to write CMSIS-DAP flash algorithms for flashing embedded targets."
+
+[dependencies]

README.md

@@ -0,0 +1,19 @@
+# flash-algorithm
+
+A crate to write CMSIS-DAP flash algorithms for flashing embedded targets.
+This crate is an abstrction over https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/flashAlgorithm.html which takes care of proper placement of functions in the respective ELF sections and linking properly.
+
+[![crates.io](https://img.shields.io/crates/v/flash-algorithm)](https://crates.io/crates/flash-algorithm) [![documentation](https://docs.rs/flash-algorithm/badge.svg)](https://docs.rs/flash-algorithm) [![Actions Status](https://img.shields.io/github/actions/workflow/status/probe-rs/flash-algorithm/ci.yml?branch=master)](https://github.com/probe-rs/flash-algorithm/actions) [![chat](https://img.shields.io/badge/chat-probe--rs%3Amatrix.org-brightgreen)](https://matrix.to/#/#probe-rs:matrix.org)
+
+To write a flash algorithm, follow the instructions in https://github.com/probe-rs/flash-algorithm-template.
+
+# License
+
+This thingy is licensed under either of
+
+- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or
+  http://www.apache.org/licenses/LICENSE-2.0)
+
+- MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)
+
+at your option.

build.rs

@@ -0,0 +1,14 @@
+use std::{env, fs::File, io::Write, path::PathBuf};
+
+fn main() {
+    // Put the linker script somewhere the linker can find it
+    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());
+
+    println!("cargo:rerun-if-changed=build.rs");
+    println!("cargo:rerun-if-changed=memory.x");
+}

memory.x

@@ -0,0 +1,44 @@
+SECTIONS {
+    . = DEFINED(ALGO_PLACEMENT_START_ADDRESS) ? ALGO_PLACEMENT_START_ADDRESS : 0x0;
+
+    /*
+     * The PrgCode output section name comes from the CMSIS-Pack flash algorithms
+     * templates and armlink. It is used here because several tools that work
+     * with these flash algorithms expect this section name.
+     *
+     * All input sections are combined into PrgCode because RWPI using R9 is not
+     * currently stable in Rust, thus having separate PrgData sections that the
+     * debug host might locate at a different offset from PrgCode is not safe.
+     */
+    PrgCode : {
+        KEEP(*(.entry))
+        KEEP(*(.entry.*))
+
+        *(.text)
+        *(.text.*)
+
+        *(.rodata)
+        *(.rodata.*)
+
+        *(.data)
+        *(.data.*)
+
+        *(.sdata)
+        *(.sdata.*)
+        
+        *(.bss)
+        *(.bss.*)
+
+        *(.uninit)
+        *(.uninit.*)
+
+        . = ALIGN(4);
+    }
+
+    /DISCARD/ : {
+        /* Unused exception related info that only wastes space */
+        *(.ARM.exidx);
+        *(.ARM.exidx.*);
+        *(.ARM.extab.*);
+    }
+}

src/lib.rs

@@ -0,0 +1,140 @@
+#![no_std]
+#![no_main]
+#![macro_use]
+
+#[cfg(not(test))]
+#[panic_handler]
+fn panic(_info: &core::panic::PanicInfo) -> ! {
+    unsafe {
+        core::arch::asm!("udf #0");
+        core::hint::unreachable_unchecked();
+    }
+}
+
+pub const FUNCTION_ERASE: u32 = 1;
+pub const FUNCTION_PROGRAM: u32 = 2;
+pub const FUNCTION_VERIFY: u32 = 3;
+
+pub type ErrorCode = core::num::NonZeroU32;
+
+pub trait FlashAlgorithm: Sized + 'static {
+    /// Initialize the flash algorithm.
+    ///
+    /// It can happen that the flash algorithm does not need any specific initialization
+    /// for the function to be executed or no initialization at all. It is up to the implementor
+    /// to decide this.
+    ///
+    /// # Arguments
+    ///
+    /// * `address` - The start address of the flash region to program.
+    /// * `clock` - The clock speed in Hertz for programming the device.
+    /// * `function` - The function for which this initialization is for.
+    fn new(address: u32, clock: u32, function: Function) -> Result<Self, ErrorCode>;
+
+    /// Erase entire chip. Will only be called after [`FlashAlgorithm::new()`] with [`Function::Erase`].
+    fn erase_all(&mut self) -> Result<(), ErrorCode>;
+
+    /// Erase sector. Will only be called after [`FlashAlgorithm::new()`] with [`Function::Erase`].
+    ///
+    /// # Arguments
+    ///
+    /// * `address` - The start address of the flash sector to erase.
+    fn erase_sector(&mut self, address: u32) -> Result<(), ErrorCode>;
+
+    /// Program bytes. Will only be called after [`FlashAlgorithm::new()`] with [`Function::Program`].
+    ///
+    /// # Arguments
+    ///
+    /// * `address` - The start address of the flash page to program.
+    /// * `size` - Specifies the size of the data buffer.
+    /// * `data` - The data to be written to the page.
+    fn program_page(&mut self, address: u32, size: u32, data: *const u8) -> Result<(), ErrorCode>;
+}
+
+#[derive(Debug, Copy, Clone, PartialEq, Eq, Hash)]
+pub enum Function {
+    Erase = 1,
+    Program = 2,
+    Verify = 3,
+}
+
+/// A macro to define a new flash algoritm.
+///
+/// It takes care of placing the functions in the correct linker sections
+/// and checking the flash algorithm initialization status.
+#[macro_export]
+macro_rules! algorithm {
+    ($type:ty) => {
+        static mut _IS_INIT: bool = false;
+        static mut _ALGO_INSTANCE: MaybeUninit<$type> = MaybeUninit::uninit();
+
+        #[no_mangle]
+        #[link_section = ".entry"]
+        pub unsafe extern "C" fn Init(addr: u32, clock: u32, function: u32) -> u32 {
+            if _IS_INIT {
+                UnInit();
+            }
+            _IS_INIT = true;
+            let function = match function {
+                1 => $crate::Function::Erase,
+                2 => $crate::Function::Program,
+                3 => $crate::Function::Verify,
+                _ => panic!("This branch can only be reached if the host library sent an unknown function code.")
+            };
+            match <$type as FlashAlgorithm>::new(addr, clock, function) {
+                Ok(inst) => {
+                    _ALGO_INSTANCE.as_mut_ptr().write(inst);
+                    _IS_INIT = true;
+                    0
+                }
+                Err(e) => e.get(),
+            }
+        }
+        #[no_mangle]
+        #[link_section = ".entry"]
+        pub unsafe extern "C" fn UnInit() -> u32 {
+            if !_IS_INIT {
+                return 1;
+            }
+            _ALGO_INSTANCE.as_mut_ptr().drop_in_place();
+            _IS_INIT = false;
+            0
+        }
+        #[no_mangle]
+        #[link_section = ".entry"]
+        pub unsafe extern "C" fn EraseChip() -> u32 {
+            if !_IS_INIT {
+                return 1;
+            }
+            let this = &mut *_ALGO_INSTANCE.as_mut_ptr();
+            match <$type as FlashAlgorithm>::erase_all(this) {
+                Ok(()) => 0,
+                Err(e) => e.get(),
+            }
+        }
+        #[no_mangle]
+        #[link_section = ".entry"]
+        pub unsafe extern "C" fn EraseSector(addr: u32) -> u32 {
+            if !_IS_INIT {
+                return 1;
+            }
+            let this = &mut *_ALGO_INSTANCE.as_mut_ptr();
+            match <$type as FlashAlgorithm>::erase_sector(this, addr) {
+                Ok(()) => 0,
+                Err(e) => e.get(),
+            }
+        }
+        #[no_mangle]
+        #[link_section = ".entry"]
+        pub unsafe extern "C" fn ProgramPage(addr: u32, size: u32, data: *const u8) -> u32 {
+            if !_IS_INIT {
+                return 1;
+            }
+            let this = &mut *_ALGO_INSTANCE.as_mut_ptr();
+            match <$type as FlashAlgorithm>::program_page(this, addr, size, data) {
+                Ok(()) => 0,
+                Err(e) => e.get(),
+            }
+        }
+    };
+}