Versal QSPI differences

hal/versal.c

@@ -22,9 +22,23 @@
  * Target: VMK180 Evaluation Board (VM1802 Versal Prime)
  *
  * Features:
- *   - UART driver (Cadence UART)
+ *   - UART driver (Cadence UART / ARM PL011)
  *   - ARM Generic Timer
- *   - Flash stubs (OSPI/SD to be implemented)
+ *   - QSPI flash driver (GQSPI - dual parallel MT25QU01GBBB)
+ *
+ * QSPI Driver Notes:
+ *   This driver is a port of the ZynqMP GQSPI driver (hal/zynq.c) with the
+ *   following Versal-specific adaptations:
+ *
+ *   1. Different base address (0xF1030000 vs 0xFF0F0000)
+ *   2. Tap delay bypass register is in QSPI block (not IOU_SLCR)
+ *   3. Preserves PLM's QSPI configuration instead of full reset
+ *   4. UART init skips MIO/clock setup when EL2 (PLM already did it)
+ *
+ *   The register layout, GenFIFO format, and DMA interface are identical
+ *   to ZynqMP since both use the same Xilinx GQSPI IP block.
+ *
+ *   See hal/versal.h for detailed comparison with ZynqMP.
  */
 
 #ifdef TARGET_versal
@@ -260,10 +274,31 @@ void hal_delay_us(uint32_t us)
 
 
 /* ============================================================================
- * QSPI Flash Driver
+ * QSPI Flash Driver (GQSPI)
  * ============================================================================
- * Bare-metal QSPI driver for Versal VMK180
- * Dual parallel MT25QU01GBBB (128MB each, 256MB total)
+ * Bare-metal QSPI driver for Versal VMK180.
+ * Hardware: Dual parallel MT25QU01GBBB (128MB each, 256MB total).
+ *
+ * This driver is adapted from the ZynqMP GQSPI driver (hal/zynq.c).
+ * Both platforms use the same Xilinx GQSPI IP block with identical:
+ *   - Register offsets (GQSPI at +0x100, DMA at +0x800 from base)
+ *   - GenFIFO entry format (command, address, data, stripe bits)
+ *   - Interrupt status bits and DMA interface
+ *
+ * Versal-specific differences from ZynqMP:
+ *   - Base address: 0xF1030000 (vs 0xFF0F0000 on ZynqMP)
+ *   - Tap delay register: In QSPI block (vs IOU_SLCR on ZynqMP)
+ *   - Initialization: Preserves PLM config (vs full reset on ZynqMP)
+ *
+ * Supported modes (same as ZynqMP):
+ *   - DMA mode (default) or IO polling mode (GQSPI_MODE_IO)
+ *   - Quad SPI (4-bit), Dual SPI (2-bit), or Standard SPI (1-bit)
+ *   - 4-byte addressing for flash >16MB (GQPI_USE_4BYTE_ADDR)
+ *   - Dual parallel with hardware striping (GQPI_USE_DUAL_PARALLEL)
+ *   - EXP (exponent) length mode for large transfers
+ *
+ * Clock: 300MHz ref / (2 << DIV) = 75MHz default (DIV=1)
+ *        MT25QU01GBBB supports up to 133MHz for Quad Output Read.
  */
 
 #ifdef EXT_FLASH

hal/versal.h

@@ -293,8 +293,38 @@
 /* ============================================================================
  * QSPI (Quad SPI) Flash Controller - GQSPI
  * ============================================================================
- * Versal QSPI is similar to ZynqMP but at different base address.
- * VMK180 uses dual parallel MT25QU01GBBB (128MB each, 256MB total)
+ * The Versal GQSPI controller is derived from the ZynqMP GQSPI IP block.
+ * VMK180 uses dual parallel MT25QU01GBBB (128MB each, 256MB total).
+ *
+ * Key differences from ZynqMP (see hal/zynq.c for comparison):
+ *
+ * 1. BASE ADDRESS:
+ *    - ZynqMP: 0xFF0F0000
+ *    - Versal: 0xF1030000
+ *
+ * 2. TAP DELAY BYPASS REGISTER:
+ *    - ZynqMP: Located in IOU_SLCR block at 0xFF180390
+ *    - Versal: Integrated in QSPI block at BASE + 0x03C
+ *
+ * 3. INITIALIZATION:
+ *    - ZynqMP: Full init including FIFO reset and loopback delay tuning
+ *    - Versal: Preserves PLM configuration, only drains RX FIFO
+ *              (PLM already configured clocks, MIO, and controller)
+ *
+ * 4. CLOCK CONFIGURATION:
+ *    - Both use same divisor formula: QSPI_CLK = REF_CLK / (2 << DIV)
+ *    - Default: 300MHz ref, DIV=1 -> 75MHz (within MT25QU01G 133MHz spec)
+ *
+ * 5. REGISTER LAYOUT:
+ *    - Identical offsets from base (+0x100 for GQSPI, +0x800 for DMA)
+ *    - Same GenFIFO format, interrupt bits, and DMA interface
+ *
+ * 6. BUILD OPTIONS (same as ZynqMP):
+ *    - GQSPI_MODE_IO: Use polling instead of DMA (DMA is default)
+ *    - GQPI_USE_DUAL_PARALLEL: Enable dual parallel flash striping
+ *    - GQPI_USE_4BYTE_ADDR: Enable 4-byte addressing for >16MB flash
+ *    - GQSPI_CLK_DIV: Clock divider (0-7)
+ *    - DEBUG_QSPI: Enable verbose debug logging
  */
 #define VERSAL_QSPI_BASE        0xF1030000UL