First commit

1 files changed, 74 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..3fceeed
--- /dev/null
+++ b/README.md
@@ -0,0 +1,74 @@
+How long does it take to build a peripheral access crate (PAC) for different i.MX RT MCUs?
+Let's find out!
+[Here](https://www.mciantyre.dev/2025/06/30/imxrt-pac-shootout.html) are my measurements.
+
+We'll use three different PAC representations:
+
+1. the classic [svd2rust] PAC.
+2. the [chiptool] PAC, preferred by [embassy].
+3. the register access layer (RAL) design, first pioneered by [stm32ral] and
+  later adopted by [imxrt-ral].
+
+[svd2rust]: https://github.com/rust-embedded/svd2rust
+[stm32ral]: https://github.com/adamgreig/stm32ral
+[imxrt-ral]: https://github.com/imxrt-rs/imxrt-ral
+[embassy]: https://github.com/embassy-rs
+[chiptool]: https://github.com/embassy-rs/chiptool
+
+With each of these, we'll build PACs for four different i.MX RT MCUs:
+
+1. iMXRT1011
+2. iMXRT1062
+3. iMXRT1176 (Cortex-M7 only)
+4. iMXRT1189 (Cortex-M33 only)
+
+We'll clean-build all PACs in release mode, targeting the best architecture profile for each MCU.
+Note that this also includes the time to build PAC dependencies.
+We'll trust Cargo's reporting of how long it takes.
+
+## Try it out
+
+Clone this repository along with all of its submodules.
+
+```
+git clone --recurse-submodules https://git.mciantyre.dev/imxrt-pac-shootout
+```
+
+Install the Rust targets we're using to build PACs:
+
+```
+rustup target add thumbv7em-none-eabihf thumbv8m.main-none-eabihf
+```
+
+The rest of these commands should automatically build the tools and intermediates
+needed for codegen.
+
+### imxrt-ral
+
+This one is the simplest: clean-build the package for each MCU.
+
+```
+make -j imxrt-ral.shootout
+```
+
+### imxrt-svd2rust
+
+Generate four PACs using `svd2rust`, supplying the same patched SVDs used by imxrt-ral.
+Separate each PAC's modules with `form`, and format them with `rustfmt`.
+Then, build all four PACs.
+
+```
+make -j imxrt-svd2rust.shootout
+```
+
+### imxrt-chiptool
+
+Generate four PACs using `chiptool`, supplying the same patched SVDs used by imxrt-ral.
+Use a transform file that's equivalent to what imxrt-ral uses.
+
+Separate each PAC's modules with `form`, and format them with `rustfmt`.
+Then, build all four PACs.
+
+```
+make -j imxrt-chiptool.shootout
+```