docs/devel: Document SSI dummy-cycle ownership
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 <bin.meng@processmission.com> Reviewed-by: Philippe Mathieu-Daudé <philmd@oss.qualcomm.com> Message-ID: <20260707083431.219671-11-bin.meng@processmission.com> [PMD: Update MAINTAINERS] Signed-off-by: Philippe Mathieu-Daudé <philmd@oss.qualcomm.com>
Bin Meng committed
Jun 30, 2026 at 21:57 UTC
6387fbad45eb89c160e1d766a4e170e896bc3fff
3 files changed
+134
MAINTAINERS
+1
@@ -2350,6 +2350,7 @@ T: git https://github.com/bonzini/qemu.git scsi-next
2350
SSI
2351
M: Alistair Francis <alistair@alistair23.me>
2352
S: Maintained
2353
+F: docs/devel/ssi.rst
2354
F: hw/ssi/*
2355
F: hw/block/m25p80*
2356
F: include/hw/ssi/ssi.h
docs/devel/index-internals.rst
+1
@@ -20,6 +20,7 @@ Details about QEMU's various subsystems including how to add features to them.
20
reset
21
s390-cpu-topology
22
s390-dasd-ipl
23
+ ssi
24
tracing
25
uefi-vars
26
vfio-iommufd
docs/devel/ssi.rst
new
+132
@@ -0,0 +1,132 @@
1
+================================
2
+SSI devices and SPI flash models
3
+================================
4
+
5
+QEMU's Synchronous Serial Interface (SSI) bus models the full-duplex transfer
6
+of words between a controller and one selected peripheral. Most SPI flash
7
+models, including ``m25p80``, are attached to controllers through this bus.
8
+
9
+This page documents the expected boundary between a controller model and a
10
+flash model for SPI fast-read dummy cycles. The boundary is important because
11
+many real controllers expose dummy-cycle configuration in registers, while the
12
+flash model observes only the byte stream delivered through ``ssi_transfer()``.
13
+
14
+SSI transfer granularity
15
+------------------------
16
+
17
+``ssi_transfer()`` transfers one SSI word. Flash models that implement common
18
+SPI NOR command streams usually consume one 8-bit word at a time:
19
+
20
+* command opcode;
21
+* address bytes;
22
+* optional mode or continuous-read bytes;
23
+* dummy bytes;
24
+* data bytes.
25
+
26
+The SSI core does not model individual clock edges or the number of active SPI
27
+data lines. If a real transaction has a dummy phase expressed in clock cycles,
28
+the device model that generates transfers on the SSI bus must represent that
29
+phase as a number of dummy byte transfers.
30
+
31
+Flash model responsibilities
32
+----------------------------
33
+
34
+A SPI flash model owns the command semantics for the flash device:
35
+
36
+* which opcodes are recognized;
37
+* how many address bytes are required;
38
+* whether a command has mode bytes;
39
+* how many dummy bytes must be consumed before data can be returned;
40
+* manufacturer-specific differences in fast-read command behavior.
41
+
42
+For the ``m25p80`` model, ``needed_bytes`` is a byte count. It must not store
43
+raw dummy cycles. When a flash datasheet describes the dummy phase in cycles,
44
+the flash model converts the cycles to bytes using the bus width used for the
45
+dummy phase::
46
+
47
+ dummy_bytes = DIV_ROUND_UP(dummy_cycles * dummy_bus_width, 8)
48
+
49
+For SPI NOR fast-read commands modeled by ``m25p80``, the dummy phase follows
50
+the address phase width. For example, output-only dual and quad read commands
51
+such as DOR and QOR use one line for command, address, and dummy phases, then
52
+use two or four lines only for the data phase. Dual I/O and Quad I/O commands
53
+such as DIOR and QIOR use the wider bus for both address and dummy phases.
54
+
55
+If the exact dummy phase cannot be represented as a whole number of SSI byte
56
+transfers, the model should round up and log the limitation instead of silently
57
+treating cycles as bytes.
58
+
59
+Controller model responsibilities
60
+---------------------------------
61
+
62
+A controller model owns the behavior of the controller hardware:
63
+
64
+* how guest-visible registers select command, address width, bus width, and
65
+ dummy-cycle count;
66
+* whether the guest supplies dummy bytes in a transmit FIFO;
67
+* whether the controller itself generates the dummy phase for a memory-mapped,
68
+ direct-read, or other automatic transfer mode;
69
+* how chip-select state changes around controller-generated transfers.
70
+
71
+When guest software writes dummy bytes into a transmit FIFO or manual transfer
72
+path, the controller should pass those bytes to ``ssi_transfer()`` like any
73
+other guest-provided byte. It should not add more dummy transfers on behalf of
74
+the flash.
75
+
76
+When hardware registers instruct the controller to generate a dummy phase, the
77
+controller must emit dummy byte transfers before data transfers reach the flash
78
+model. The controller should convert the configured cycle count using the bus
79
+width that the controller uses during the dummy phase. For example:
80
+
81
+* 8 dummy cycles on a single data line become 1 dummy byte;
82
+* 8 dummy cycles on two data lines become 2 dummy bytes;
83
+* 8 dummy cycles on four data lines become 4 dummy bytes.
84
+
85
+The controller should not duplicate flash-specific opcode tables merely to
86
+guess which commands need dummy cycles. In automatic modes the controller
87
+already has enough hardware configuration to know whether it must generate a
88
+dummy phase. In manual modes the guest-provided byte stream is authoritative.
89
+
90
+Avoiding double counting
91
+------------------------
92
+
93
+Exactly one side should generate each dummy byte transfer seen by the flash:
94
+
95
+* If the guest sends dummy bytes through the controller, the controller forwards
96
+ them and the flash consumes them.
97
+* If the guest programs a controller dummy-cycle register, the controller
98
+ converts those cycles to dummy byte transfers and the flash consumes them.
99
+* The flash may know that a command requires dummy bytes, but it does not create
100
+ transfers on the SSI bus.
101
+
102
+Do not implement controller-side snooping that watches manual-mode opcode
103
+streams and injects extra dummy transfers based on flash opcodes. That mixes
104
+flash command semantics into the controller and is fragile when flash models
105
+gain correct dummy-byte accounting.
106
+
107
+Examples in the tree
108
+--------------------
109
+
110
+The following models illustrate the boundary:
111
+
112
+* ``hw/block/m25p80.c`` keeps fast-read dummy requirements as byte counts in
113
+ ``needed_bytes``. Manufacturer-specific helpers convert datasheet dummy
114
+ cycles to the byte stream expected by the model.
115
+* ``hw/ssi/aspeed_smc.c`` generates dummy byte transfers for direct fast-read
116
+ mode from controller registers, but manual user-mode writes are forwarded as
117
+ guest-provided bytes.
118
+* ``hw/ssi/npcm7xx_fiu.c`` converts the direct-read dummy configuration to the
119
+ number of dummy byte transfers sent before reading data.
120
+
121
+Review checklist
122
+----------------
123
+
124
+When adding or changing a SPI flash controller or flash model, check:
125
+
126
+* Are dummy counts stored in byte units when they drive flash state machines?
127
+* If a hardware register stores cycles, is the conversion to bytes based on the
128
+ bus width of the dummy phase?
129
+* Are manual guest-provided dummy bytes forwarded without extra injection?
130
+* Are automatic controller-generated dummy phases modeled by the controller?
131
+* Is flash-specific opcode knowledge kept in the flash model rather than copied
132
+ into controller snooping paths?