First commit

1 files changed, 59 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..20a3adf
--- /dev/null
+++ b/README.md
@@ -0,0 +1,59 @@
+This repository contains [flash programming algorithms][fpa] for i.MX RT MCUs.
+The algorithms are designed for use in [probe-rs]. They're written in Rust and
+support a variety of MCUs and flash parts.
+
+These flash programming algorithms compete with NXP's flash programming
+algorithms, which are distributed in device family packs (DFPs). NXP's
+algorithms also work with probe-rs, so prefer those if you want something
+official.
+
+I've found these algorithms can program flash 2x to 4x faster than NXP's
+offerings. These algorithms definitely support page crossings; meaning, if the
+debug probe wants to program 4KiB into flash, the algorithm will automatically
+chunk it into pages of 256 bytes. This trick reduces I/O overhead between host
+and debug probe. (Admittedly, NXP's algorithms might support this, but I never
+tried. It's fun writing these algorithms!)
+
+Supported boards include
+
+- IMXRT1010EVK
+- IMXRT1040EVK
+- IMXRT1160EVK
+- IMXRT1170EVK
+
+You'll find the algorithms in their respective top-level directories. These
+four boards sport four different MCUs, which you'll also find in the top-level
+directories. Furthermore, those four boards have three different flash parts;
+the flash part implementation is in `src/` as part of the core package.
+
+Before attempting to generate the flash programming algorithms for [probe-rs],
+install the `target-gen` tool. It's available in the probe-rs repository. [My
+fork][probe-rs-fork] has some `target-gen` patches that might be useful.
+
+Here's how to generate the algorithm, represented as YAML, for the 1010EVK:
+
+```
+cargo --config .cargo/flash_algo.toml run --release --package=imxrt1010evk
+```
+
+To generate the algorithm for a different EVK, change the `--package` selection.
+
+Some of the EVKs have a smoke test that checks read, erase, and write with its
+flash part. Keep in mind that this will manipulate your board's flash, and it
+might change something you care about!
+
+To run the smoke test on the 1010EVK, power on your EVK and connect it to your
+host. Then, submit
+
+```
+cargo --config .cargo/imxrt1010.toml run --release --package=imxrt1010evk --example=smoke
+```
+
+to flash the example with probe-rs. If you change the EVK, change the Cargo
+configuration for your MCU as well as your package.
+
+[fpa]: https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/flashAlgorithm.html
+[probe-rs]: https://probe.rs
+[probe-rs-fork]: https://github.com/mciantyre/probe-rs
+
+License: APACHE-2.0