README.tercel.md

   1 # ARCHITECTURE
   2
   3 Tercel is a Wishbone-compatible, 32-bit, single+quad SPI Flash controller with XIP support.  Both 3BA and 4BA devices are supported.
   4
   5 Tercel provides two interfaces to the host CPU:
   6 1. A direct MMIO read/write region for the flash device
   7 2. A configuration space where the core can be reconfigured on-line for operation beyond single SPI 3BA mode with fallback clocks (default)
   8
   9 # USAGE
  10
  11 ## General Usage
  12
  13 On reset, the Tercel core provides read-only access in single SPI, 3BA mode to any attached Flash device.  It uses the generic well-known single byte access instructions to provide full XIP support.  Host software is responsible for reading the Flash ID of the attached Flash device and reconfiguring the Tercel core for faster and more advanced operating modes.  This reconfiguration can take place online, with no interruption to the concurrent read operations in progress on the main MMIO Flash window.
  14
  15 By default, with Microwatt, the two bus regions are available at:
  16 Flash MMIO (XIP base):  0xf0000000
  17 Core configuration:     0xc8050000
  18
  19 ## Read Flash ID
  20
  21  - Enable user mode
  22    Set bit 0 of "Core control register 1"
  23
  24  - Send Flash ID command
  25    Write 0x9e to SPI MMIO base address (offset 0x0)
  26
  27  - Read response
  28    Read four bytes from SPI MMIO base address (offset 0x0) and assemble into 32-bit device ID
  29    Read sequence is big endian per Flash device convention
  30
  31  - Disable user mode
  32    Clear bit 0 of "Core control register 1"
  33
  34 # REGISTER MAP
  35
  36 ## [0x00 - 0x07) Device ID
  37
  38  Device make/model unique identifier for PnP functionality
  39  Fixed value: 0x7c5250545350494d
  40
  41 ## [0x08 - 0x0b) Device version
  42
  43  Device revision (stepping)
  44
  45  | Bits  | Description   |
  46  |-------|---------------|
  47  | 31:16 | Major version |
  48  | 15:8  | Minor version |
  49  | 7:0   | Patch level   |
  50
  51 ## [0x0c - 0x0f)
  52
  53  System clock frequency
  54
  55  Can be used to set divisor to meet specific SPI Flash clock frequency requirements
  56
  57 ## [0x10 - 0x13)
  58
  59  PHY configuration register 1
  60  Default: 0x00000a10
  61
  62  | Bits  | Description                                                                                            |
  63  |-------|--------------------------------------------------------------------------------------------------------|
  64  | 31:24 | Insert idle cycles with CS deasserted between SPI operations (cycle count to insert, 0 for none)       |
  65  | 23:22 | Reserved                                                                                               |
  66  | 21    | Enable quad I/O data write in QSPI mode                                                                |
  67  | 20    | Enable quad I/O data read in QSPI mode                                                                 |
  68  | 19    | Enable fast reads (1 == use fast read commands and cycles, 0 == use standard read commands and cycles) |
  69  | 18    | Enable 4BA addressing mode (1 == 4BA, 0 == 3BA)                                                        |
  70  | 17:16 | PHY I/O type (0 == single, 2 == quad, others invalid)                                                  |
  71  | 15:8  | Dummy cycle count                                                                                      |
  72  | 7:0   | SPI clock divisor                                                                                      |
  73
  74  Clock divisor works as follows:
  75   Clock frequency calculation:
  76    spi_clock_frequency = peripheral_bus_clock_frequency / ((spi_clock_divisor - 1) * 2)
  77
  78  | Clock divisor value | Actual division                    |
  79  |---------------------|------------------------------------|
  80  | 0                   | override to standard divide by two |
  81  | 1                   | divide by 1                        |
  82  | 2                   | divide by 2                        |
  83  | 3                   | divide by 4                        |
  84  | 4                   | divide by 6                        |
  85  | 5                   | divide by 8                        |
  86  | 6                   | divide by 10                       |
  87  | 7                   | divide by 12                       |
  88  | ...                 | ...                                |
  89
  90 ## [0x14 - 0x17)
  91
  92  Flash configuration register 1
  93   Default: 0x13031303
  94
  95  | Bits  | Description           |
  96  |-------|-----------------------|
  97  | 31:24 | Reserved              |
  98  | 23:16 | QSPI 3BA read command |
  99  | 15:8  | SPI 4BA read command  |
 100  | 7:0   | SPI 3BA read command  |
 101
 102 ## [0x18 - 0x1b)
 103
 104  Flash configuration register 2
 105   Default: 0xeceb0c0b
 106
 107  | Bits  | Description                |
 108  |-------|----------------------------|
 109  | 31:24 | QSPI 4BA fast read command |
 110  | 23:16 | QSPI 3BA fast read command |
 111  | 15:8  | SPI 4BA fast read command  |
 112  | 7:0   | SPI 3BA fast read command  |
 113
 114 ## [0x1c - 0x1f)
 115
 116  Flash configuration register 3
 117   Default: 0x34321202
 118
 119  | Bits  | Description              |
 120  |-------|--------------------------|
 121  | 31:24 | QSPI 4BA program command |
 122  | 23:16 | QSPI 3BA program command |
 123  | 15:8  | SPI 4BA program command  |
 124  | 7:0   | SPI 3BA program command  |
 125
 126 ## [0x20 - 0x23)
 127
 128  Flash configuration register 4
 129   Default: 0x00000000
 130
 131   Cycles to keep CS asserted after operation completion.  Used to support high-throughput multi-cycle transfers with specific Flash devices.
 132
 133   See also "Flash configuration register 5"
 134
 135 ## [0x24 - 0x27)
 136
 137  Flash configuration register 5
 138   Default: 0x00000000
 139
 140  | Bits | Description             |
 141  |------|-------------------------|
 142  | 31:2 | Reserved                |
 143  | 1    | Allow multicycle writes |
 144  | 0    | Allow multicycle reads  |
 145
 146 ## [0x28 - 0x2b)
 147
 148  Core control register 1
 149   Default: 0x00000000
 150
 151  | Bits | Description |                          |
 152  |------|-------------|--------------------------|
 153  |      | 31:1        | Reserved                 |
 154  |      | 0           | User command mode enable |
 155
 156  User command mode operates in conjunction with "Core data register 1" to support custom (non-data-I/O) SPI commands.
 157
 158 ## [0x2c - 0x2f)
 159
 160  Core data register 1
 161
 162  Data transfer to/from SPI device in user command mode
 163
 164  See also "Core control register 1"
 165
 166 # LICENSE
 167
 168 Tercel is licensed under the terms of the GNU LGPLv3.  See LICENSE.tercel for details.
 169
 170 # DOCUMENTATION CREDITS
 171
 172 (c) 2022 Raptor Engineering, LLC