On 7/8/2026 8:00 AM, Bin Meng wrote:
> Document the boundary between SPI/SSI controller models and SPI flash
> models when representing fast-read dummy cycles. It explains that
> flash models own command semantics, while controllers own
> hardware-generated dummy transfers and cycle-to-byte conversion.
>
> Signed-off-by: Bin Meng
> Reviewed-by: Philippe Mathieu-Daudé
>
> ---
>
> Changes in v4:
> - fix checkpatch ssi.rst warning
>
> Changes in v3:
> - fix checkpatch MAINTAINERS warning
>
> MAINTAINERS| 1 +
> docs/devel/index-internals.rst | 1 +
> docs/devel/ssi.rst | 134 +
> 3 files changed, 136 insertions(+)
> create mode 100644 docs/devel/ssi.rst
>
> diff --git a/MAINTAINERS b/MAINTAINERS
> index 6171cc7494..77ca6e6c31 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -2347,6 +2347,7 @@ T: git https://github.com/bonzini/qemu.git scsi-next
> SSI
> M: Alistair Francis
> S: Maintained
> +F: docs/devel/ssi.rst
> F: hw/ssi/*
> F: hw/block/m25p80*
> F: include/hw/ssi/ssi.h
> diff --git a/docs/devel/index-internals.rst b/docs/devel/index-internals.rst
> index b89bab9b30..a8f5e310df 100644
> --- a/docs/devel/index-internals.rst
> +++ b/docs/devel/index-internals.rst
> @@ -20,6 +20,7 @@ Details about QEMU's various subsystems including how to
> add features to them.
> reset
> s390-cpu-topology
> s390-dasd-ipl
> + ssi
> tracing
> uefi-vars
> vfio-iommufd
> diff --git a/docs/devel/ssi.rst b/docs/devel/ssi.rst
> new file mode 100644
> index 00..7475d7f241
> --- /dev/null
> +++ b/docs/devel/ssi.rst
> @@ -0,0 +1,134 @@
> +.. SPDX-License-Identifier: GPL-2.0-or-later
> +
> +
> +SSI devices and SPI flash models
> +
> +
> +QEMU's Synchronous Serial Interface (SSI) bus models the full-duplex transfer
> +of words between a controller and one selected peripheral. Most SPI flash
> +models, including ``m25p80``, are attached to controllers through this bus.
> +
> +This page documents the expected boundary between a controller model and a
> +flash model for SPI fast-read dummy cycles. The boundary is important because
> +many real controllers expose dummy-cycle configuration in registers, while
> the
> +flash model observes only the byte stream delivered through
> ``ssi_transfer()``.
> +
> +SSI transfer granularity
> +
> +
> +``ssi_transfer()`` transfers one SSI word. Flash models that implement common
> +SPI NOR command streams usually consume one 8-bit word at a time:
> +
> +* command opcode;
> +* address bytes;
> +* optional mode or continuous-read bytes;
> +* dummy bytes;
> +* data bytes.
> +
> +The SSI core does not model individual clock edges or the number of active
> SPI
> +data lines. If a real transaction has a dummy phase expressed in clock
> cycles,
> +the device model that generates transfers on the SSI bus must represent that
> +phase as a number of dummy byte transfers.
> +
> +Flash model responsibilities
> +
> +
> +A SPI flash model owns the command semantics for the flash device:
> +
> +* which opcodes are recognized;
> +* how many address bytes are required;
> +* whether a command has mode bytes;
> +* how many dummy bytes must be consumed before data can be returned;
> +* manufacturer-specific differences in fast-read command behavior.
> +
> +For the ``m25p80`` model, ``needed_bytes`` is a byte count. It must not store
> +raw dummy cycles. When a flash datasheet describes the dummy phase in cycles,
> +the flash model converts the cycles to bytes using the bus width used for the
> +dummy phase::
> +
> +dummy_bytes = DIV_ROUND_UP(dummy_cycles * dummy_bus_width, 8)
> +
> +For SPI NOR fast-read commands modeled by ``m25p80``, the dummy phase follows
> +the address phase width. For example, output-only dual and quad read commands
> +such as DOR and QOR use one line for command, address, and dummy phases, then
> +use two or four lines only for the data phase. Dual I/O and Quad I/O commands
> +such as DIOR and QIOR use the wider bus for both address and dummy phases.
> +
> +If the exact dummy phase cannot be represented as a whole number of SSI byte
> +transfers, the model should round up and log the limitation instead of
> silently
> +treating cycles as bytes.
> +
> +Controller model responsibilities
> +-
> +
> +A controller model owns the behavior of the controller hardware:
> +
> +* how guest-visible registers select command, address width, bus width, and
> + dummy-cycle count;
> +* whether the guest supplies dummy bytes in a transmit FIFO;
> +* whether the controller itself generates the dummy phase for a
> memory-mapped,
> + direct-read, or other automatic transfer mode;
> +* how chip-select state changes around controller-generated transfers.
> +
> +When guest software writes dummy bytes into a transmit FIFO or manual
> transfer
>
