From 4770325bb7b4beca1b2b108674ce5dfbcf17a49f Mon Sep 17 00:00:00 2001
From: 9names <60134748+9names@users.noreply.github.com>
Date: Sun, 14 Jan 2024 13:21:50 +1100
Subject: [PATCH] Additional features docs for embassy-rp

---
 embassy-rp/Cargo.toml | 41 ++++++++++++++++++++++++-----------------
 1 file changed, 24 insertions(+), 17 deletions(-)

diff --git a/embassy-rp/Cargo.toml b/embassy-rp/Cargo.toml
index edb152a89..794f1109c 100644
--- a/embassy-rp/Cargo.toml
+++ b/embassy-rp/Cargo.toml
@@ -22,17 +22,17 @@ features = ["defmt", "unstable-pac", "time-driver"]
 
 [features]
 default = [ "rt" ]
-## Enable the RP runtime.
+## Enable the rt feature of [`rp-pac`](https://docs.rs/crates/rp-pac). This brings in the [`cortex-m-rt`](https://docs.rs/cortex-m-rt) crate, which adds startup code and minimal runtime initialization.
 rt = [ "rp-pac/rt" ]
 
-## Enable defmt.
+## Enable [defmt support](https://docs.rs/defmt) and enables `defmt` debug-log messages and formatting in embassy drivers.
 defmt = ["dep:defmt", "embassy-usb-driver/defmt", "embassy-hal-internal/defmt"]
 
-## critical section that is safe for multicore use.
+## Configure the critical section crate to use an implementation that is safe for multicore use on rp2040.
 critical-section-impl = ["critical-section/restore-state-u8"]
 
 ## Reexport the PAC for the currently enabled chip at `embassy_rp::pac`.
-## This is unstable because semver-minor (non-breaking) releases of embassy-rp may major-bump (breaking) the PAC version.
+## This is unstable because semver-minor (non-breaking) releases of `embassy-rp` may major-bump (breaking) the PAC version.
 ## If this is an issue for you, you're encouraged to directly depend on a fixed version of the PAC.
 ## There are no plans to make this stable.
 unstable-pac = []
@@ -40,15 +40,18 @@ unstable-pac = []
 ## Enable the timer for use with `embassy-time` with a 1MHz tick rate.
 time-driver = ["dep:embassy-time-driver", "embassy-time-driver?/tick-hz-1_000_000"]
 
-## Enable ROM function cache.
+## Enable ROM function cache. This will store the address of a ROM function when first used, improving performance of subsequent calls.
 rom-func-cache = []
-## Enable intrinsics.
+## Enable implementations of some compiler intrinsics using functions in the rp2040 Mask ROM.
+## These should be as fast or faster than the implementations in compiler-builtins. They also save code space and reduce memory contention.
+## Compiler intrinsics are used automatically, you do not need to change your code to get performance improvements from this feature.
 intrinsics = []
-## Enable ROM v2 intrinsics.
+## Enable intrinsics based on extra ROM functions added in the v2 version of the rp2040 Mask ROM.
+## This version added a lot more floating point operations - many f64 functions and a few f32 functions were added in ROM v2.
 rom-v2-intrinsics = []
 
-## Allow using QSPI pins as GPIO pins. This is mostly not what you want (because your flash lives there)
-## and would add both code and memory overhead when enabled needlessly.
+## Allow using QSPI pins as GPIO pins. This is mostly not what you want (because your flash is attached via QSPI pins)
+## and adds code and memory overhead when this feature is enabled.
 qspi-as-gpio = []
 
 ## Indicate code is running from RAM.
@@ -57,20 +60,24 @@ qspi-as-gpio = []
 run-from-ram = []
 
 #! ### boot2 flash chip support
-#! If none of these are enabled, w25q080 is used by default (used on the pico)
-## AT25SF128a.
+#! RP2040's internal bootloader is only able to run code from the first 256 bytes of flash.
+#! A 2nd stage bootloader (boot2) is required to run larger programs from external flash.
+#! Select from existing boot2 implementations via the following features. If none are selected,
+#! boot2-w25q080 will be used (w25q080 is the flash chip used on the pico).
+#! Each implementation uses flash commands and timings specific to a QSPI flash chip family for better performance.
+## Use boot2 with support for Renesas/Dialog AT25SF128a SPI flash.
 boot2-at25sf128a = []
-## GD25Q64cs.
+## Use boot2 with support for Gigadevice GD25Q64C SPI flash.
 boot2-gd25q64cs = []
-## generic-03h.
+## Use boot2 that only uses generic flash commands - these are supported by all SPI flash, but are slower.
 boot2-generic-03h = []
-## IS25LP080.
+## Use boot2 with support for ISSI IS25LP080 SPI flash.
 boot2-is25lp080 = []
-## ram-memcpy.
+## Use boot2 that copies the entire program to RAM before booting. This uses generic flash commands to perform the copy.
 boot2-ram-memcpy = []
-## W25Q080.
+## Use boot2 with support for Winbond W25Q080 SPI flash.
 boot2-w25q080 = []
-## W25X10cl.
+## Use boot2 with support for Winbond W25X10CL SPI flash.
 boot2-w25x10cl = []
 
 [dependencies]