libhw: Update comments and asserts about clock rate

1 files changed, 16 insertions, 6 deletions

diff --git a/libhw/rp2040_include/libhw/rp2040_hwspi.h b/libhw/rp2040_include/libhw/rp2040_hwspi.h
index 76e0709..a1d85d4 100644
--- a/libhw/rp2040_include/libhw/rp2040_hwspi.h
+++ b/libhw/rp2040_include/libhw/rp2040_hwspi.h
@@ -48,12 +48,22 @@ LO_IMPLEMENTATION_H(spi, struct rp2040_hwspi, rp2040_hwspi)
  * the CPU.  This is because the PL022 has a maximum of 16-bit frames,
  * but we need to be able to do *at least* 32-bit frames (and ideally,
  * much larger).  By managing it ourselves, we can just keep CS pulled
- * low extra-long, making the frame extra-long.  However, this means
- * that we can't SPI so fast that the CPU can't do things in time;
- * experimentally much faster than 60MHz seems to be when I start
- * getting mangled messages.  We wouldn't have this speed limit with a
- * PIO-based SPI driver, because it could toggle CLK and CS in
- * lock-step with receiving data from the FIFO.
+ * low extra-long, making the frame extra-long.
+ *
+ * Restrictions on baudrate:
+ *
+ * - The PL022 requires that the baudrate is an even-number fraction
+ *   of clk_peri.
+ *    + This implies that the maximum baudrate is clk_peri/2.
+ *    + Pico-SDK' default clk_peri is 125MHz, max is 200MHz.
+ * - The CS-from-GPIO hack above means that that we can't go so fast
+ *   that the CPU can't do things in time.
+ *    + Experimentally:
+ *      | clk_sys=125MHz | baud=31.25MHz | works OK                         |
+ *      | clk_sys=125MHz | baud=62.5 MHz | messages get shifted right a bit |
+ *
+ * Both of these restrictions aught to be avoidable by using a
+ * PIO-based SPI driver instead of this PLL02-based driver.
  */
 #define rp2040_hwspi_init(self, name,                                    \
                           inst_num, mode, baudrate_hz,                   \