================================ 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 path, the controller should pass those bytes to ssi_transfer() like any other guest-provided byte. It should not add more dummy transfers on behalf of the flash.

When hardware registers instruct the controller to generate a dummy phase, the controller must emit dummy byte transfers before data transfers reach the flash model. The controller should convert the configured cycle count using the bus width that the controller uses during the dummy phase. For example:

• 8 dummy cycles on a single data line become 1 dummy byte;
• 8 dummy cycles on two data lines become 2 dummy bytes;
• 8 dummy cycles on four data lines become 4 dummy bytes.

The controller should not duplicate flash-specific opcode tables merely to guess which commands need dummy cycles. In automatic modes the controller already has enough hardware configuration to know whether it must generate a dummy phase. In manual modes the guest-provided byte stream is authoritative.

Avoiding double counting

Exactly one side should generate each dummy byte transfer seen by the flash:

• If the guest sends dummy bytes through the controller, the controller forwards them and the flash consumes them.
• If the guest programs a controller dummy-cycle register, the controller converts those cycles to dummy byte transfers and the flash consumes them.
• The flash may know that a command requires dummy bytes, but it does not create transfers on the SSI bus.

Do not implement controller-side snooping that watches manual-mode opcode streams and injects extra dummy transfers based on flash opcodes. That mixes flash command semantics into the controller and is fragile when flash models gain correct dummy-byte accounting.

Examples in the tree

The following models illustrate the boundary:

• hw/block/m25p80.c keeps fast-read dummy requirements as byte counts in needed_bytes. Manufacturer-specific helpers convert datasheet dummy cycles to the byte stream expected by the model.
• hw/ssi/aspeed_smc.c generates dummy byte transfers for direct fast-read mode from controller registers, but manual user-mode writes are forwarded as guest-provided bytes.
• hw/ssi/npcm7xx_fiu.c converts the direct-read dummy configuration to the number of dummy byte transfers sent before reading data.

Review checklist

When adding or changing a SPI flash controller or flash model, check:

• Are dummy counts stored in byte units when they drive flash state machines?
• If a hardware register stores cycles, is the conversion to bytes based on the bus width of the dummy phase?
• Are manual guest-provided dummy bytes forwarded without extra injection?
• Are automatic controller-generated dummy phases modeled by the controller?
• Is flash-specific opcode knowledge kept in the flash model rather than copied into controller snooping paths?