| 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? |