Linux ZynqMP GQSPI Driver


This page provides information about the ZynqMP  and Versal QSPI driver which can be found on Xilinx Git as spi-zynqmp-gqspi.c
Drivers can be found at /drivers/spi/spi-zynqmp-gqspi.c

MTD layer handles all the flash devices used with QSPI. This layer handles flash devices of different makes (Micron/Numonyx, Winbond and Spansion being
the most common)
of different sizes from 128Mbit to 1Gbit. The features of all flash devices are not alike and hence handled through different flags indicating the support.
This layer was customized by xilinx to support parallel and stacked configurations. It can be found at drivers/mtd/devices/m25p80.c on Xilinx Git

HW/IP Features

The GQSPI controller used in Zynqmp and Versal supports the following features.
  • Support Low level (Generic) Access
  • Support Future Commands
  • Supports 3,4,6…N byte addressing
  • Supports Command Queuing (Generic FIFO depth is 32)
  • Supports 4 or 8-bit interface
  • Supports 2 Chip Select Lines
  • Supports 4-Bit Bi-Directional I/O signals
  • Supports x1/x2/x4 Read/Write
  • Supports 44-bit address space on AXI in DMA mode
  • Supports byte stripe when two data buses are connected
  • Supports single interrupt for QSPI/DMA Interrupt status

Driver Features

The Zynqmp and Versal GQSPI supports the following features:
  • Supports DMA for receiving the aligned data from the tx fifo.
  • Supports PIO read for receiving the unaligned data from the rx fifo.
  • Supports PIO write from programing page to the flash.
  • Supports extended addressing.
  • Supports SIngle,Dual Parallel and Dual Stacked configurations.
  • Supports Normal and Quad read modes

Missing Features and known Issues/Limitations in Driver

  • This driver supports GenericQSPI(GQSPI) not Linear QSPI(LQSPI)

Important AR links

  • Kernel boot failed while mounting JFFS2 filesystem in QSPI boot mode - AR-71114

Kernel Configuration Options

The following config options need to be enabled
It depends on SPI_MASTER and HAS_DMA
If required, enable MTD block devices support - MTD_BLKDEVS


Refer to spi-zynqmp-qspi.txt for complete description.
These are some specific points to be noted about the qspi properties:
- is-dual - Set if parallel. Reset if single or stacked.

The following example shows adding a QSPI node to the devicetree in single mode.

Testing Procedure

This section details the common tests using jffs2 and flashcp.
In order to test different flash sizes and configurations (single, parallel, stacked), the above devicetree should be modified and relevant hardware and design should be used.

QSPI flash testing with flashcp

#List the MTD partitions present and select a partition
cat /proc/mtd
#Creating a file to be written to the flash\
dd if=/dev/urandom of=./sample.bin bs=1024 count=4096
#Write the file to the partition - this erases the partition, writes the file and verifies
flashcp -v ./smaple.bin /dev/mtd0

QSPI flash testing with jffs2

dev: size erasesize name

mtd0: 00400000 00020000 "qspi-fsbl-uboot"
mtd1: 01a00000 00020000 "qspi-linux"
mtd2: 00010000 00020000 "qspi-device-tree"
mtd3: 05000000 00020000 "qspi-rootfs"
mtd4: 005e0000 00020000 "qspi-bitstream"

Erasing 128 Kibyte @ 5c0000 - 97% complete. Cleanmarker written at 5c0000.

Erasing 128 Kibyte @ 5e0000 - 100% complete.

4096+0 records in

4096+0 records out
4194304 bytes (4.0MB) copied, 3.227253 seconds, 1.2MB/s


Expected Ouput

Performance Details


Read: 32000 LB/s
Write: 759 KB/s


Read: 51200 KB/s
Write: 907 KB/s

Mainline Status

Not Mainlined

Change Log

  • 2016.3

    • Summary
      • Add support for 44-bit address space on AXI in DMA mode
      • Don't change spi clock frequency for every transfer 
      • Added tap dealy support for higher frequencies
    • Commits
  • 2016.4

    • Summary
      • None
    • Commits
      • None
  • 2017.1

    • Summary
      • Update driver to support both IO and dma modes
      • Add support for context loss
      • Add support for context loss
    • Commits
  • 2017.2

    • Summary
      • None
    • Commits
      • None
  • 2017.3

    • Summary
      • Cut the clock after restore
      • Fixed warnings reported by kernel-doc
      • Fixed warnings reported by checkpatch
      • Fixed sparse warning in driver
      • Use new firmware.h instead of pm.h
    • Commits
  • 2017.4

    • Summary
      • Direct read of data from the flash made word aligned.
    • Commits
  • 2018.1

    • Summary
      • Added a support for variable tx bus width
      • Use firmware IOCTL for device control
    • Commits
  • 2018.2

    • Summary
      • Fix for qspi dma when accessing address space beyond 32-bit.
      • Use dma mode only if the buffer is not vmalloced.
    • Commits
  • 2018.3

    • Summary
      • Fixed kerneldoc format
      • Removed the interrupts not required to be handled
      • Added runtime idle support
    • Commits
  • 2019.1

    • Summary
      • Defer driver probe if ZynqMp firmware is not ready.
      • Updated driver as per the new spi-nor framework.
      • Updated driver to set recommended clock and data tap delay values
    • Commits
  • 2019.2

    • Summary
      • Set recommended tap delay values for Versal 
      • Fixed erase size issue in dual parallel connection.
      • Fixed die crossover issue.
      • Fix incorrect buffer access.
  • 2020.1

    • Summary
      • Resolved slab-out-of-bounds bug.
      • Update driver to write appropriate dummy cycle as per tx_buswidth
    • Commits
  • 2020.2

    • Summary
      • Do hardware initialization later in probe
      • Update correct value for DLY1 bit field
      • Set correct clock and data tap delay values in probe
      • Disable interrupts before registering interrupt handler
    • Commits

Related Links