21 NAND Docs 中文

Full-machine architecture

The model machine's main line runs in pure software on a small computer (SBC). This page covers FPGA plus ESP32-C3, a research line that has only run in simulation.

The main line is pure software on an SBC: a runtime we wrote runs the model on a small ARM computer, and fetching firmware from the chain works the same way. See A large model on a small computer. The FPGA plus ESP32-C3 design below is a research line: we designed the circuits ourselves, and so far they have only run in simulation. No physical board exists yet.

Research line: one diagram

 tape container on chain (BSC / X Layer)
   tapeboot/<board>/channel/*.json   channel pointer
   tapeboot/<board>/<seq>/…          manifest and files
        │  read-only eth_call: fileInfo / readRange (if a node fails, try the next; always check hashes)
        ▼
 ESP32-C3: boot firmware + TapeBoot client
   read channel → check signature and hashes → fetch chunk by chunk (cached on microSD)
        │  SPI mailbox: write the runtime and TBW1 into DDR3, then release soft core reset
        ▼
 FPGA (GW2A-18)
   rv32ima soft core ── bus ── DDR3 controller (128 MB)
                         ├─ UART
                         ├─ timer / SYSCON
                         ├─ HDMI text console
                         └─ binary multiply-add unit (XNOR + popcount, reads weights from DDR3 itself)
It runs in simulation now. No physical board exists yet.

Parts

PartWhat it isWhat it does
ESP32-C3Boot chip. Runs the boot firmware, which includes the TapeBoot clientConnects to Wi-Fi and reads the chain; checks signatures and hashes; fetches chunk by chunk; writes DDR3 through the SPI mailbox; watches the heartbeat to decide between commit and rollback
microSDAttached to the C3Chunk cache and the two slots, A and B. With no network, it boots from the most recent slot that passed its checks
GW2A-18 FPGATarget board: Tang Primer 20KHolds the circuits below. The bitstream stays in the onboard flash. You flash it over USB, not from the chain
rv32ima soft coreM-mode, no MMU, compatible with mini-rv32imaStarts running from 0x8000_0000 after reset
DDR3128 MBThe first 16 MB hold the runtime; the rest holds a model of up to 112 MB
Binary multiply-add unitXNOR + popcountComputes a whole matrix-vector product in one go, reading DDR3 by itself
UART8250 subset, 8N1, 115200Serial output
HDMI text console80×30 characters, 2 bytes per cell (character + color)Screen output
RuntimeTBRT bare-metal runtime (main), TapeOut Linux (secondary)Loads the model, runs inference, writes text

Three interfaces

InterfaceTwo sidesWhat it coversSee
IF-1Model ↔ hardware, runtimeLayout of the TBW1 weight file. The whole file goes on chain as is, into DDR3 as is, and the multiply-add unit reads it directly, with no conversion along the wayTBW1 weight format
IF-2Hardware ↔ systemMemory map, multiply-add unit registers, the SPI mailbox between the C3 and the FPGAFurther down this page
IF-3Protocol ↔ systemTapeBoot: on-chain paths, manifest, signature, check order, A/B slotsFetch firmware from the chain, TapeBoot spec

Memory map

Peripheral addresses are the same as in mini-rv32ima, so the TapeOut Linux image on chain can boot as is.

AddressSizeContent
0x8000_000016 MBRuntime / operating system
0x8100_0000Up to 112 MBModel area: the TBW1 file sits here as is
0x1000_00000x100UART
0x1100_4000 / 0x1100_BFF8—mtimecmp / mtime
0x1110_00004SYSCON: write 0x5555 to power off, 0x7777 to restart
0x2000_00000x100Binary multiply-add unit
0x2100_00008 KBHDMI text console
0x2200_00000x100Mailbox: status registers between the C3 and the soft core

Multiply-add unit registers

All are 32 bits. Write the addresses and sizes, set bit0 of CTRL to start, then wait for bit1 of STATUS.

OffsetNameDescription
0x00CTRLbit0 start, bit1 clear interrupt
0x04STATUSbit0 busy, bit1 done, bit2 error
0x08W_ADDRByte address of the weight tensor in DDR3
0x0CX_ADDRInput vector, 64-bit aligned
0x10Y_ADDRint32 output
0x14COLSNumber of columns
0x18ROWSNumber of rows
0x1CSCALE_ADDRAddress of the scale table
0x20SCALE_KINDScaling method, see TBW1
0x24GROUPGroup size
0x28PERF_CYCLESRead-only, cycles used
0x2CACT_BITSInput bit width; 0 and 1 both mean one-bit input
0x30W_KIND0 = one-bit weights (reset value), 1 = INT8, anything else is an error

SPI mailbox

The C3 is the host. Mode 0, most significant bit first, SCK no faster than 1/8 of the FPGA clock. One chip-select low period is one command. All multi-byte fields are little-endian.

CommandFormatWhat it does
0x01 WRITEaddr[4] followed by dataWrites to DDR3. Works only while the soft core is in reset
0x02 READaddr[4] dummy[2], then read continuouslyReads DDR3. Works only while the soft core is in reset
0x03 RESETv[1]bit0 = 1 holds the soft core in reset, 0 releases it. Held by default at power-on
0x04 REG_WRreg[1] v[4]For now it can only write 0x00 BOOT_INFO
0x05 REG_RDreg[1] dummy[1], then read v[4]Reads a register from the table below
RegisterContent
0x00 BOOT_INFOHigh 16 bits = low 16 bits of the manifest's seq; low 16 bits = first 2 bytes of the manifest's sha256. Only lets the runtime print which version it is
0x04 HEARTBEATThe soft core adds 1 every second; cleared during reset
0x08 MSGStatus code from the soft core to the C3; cleared during reset
0x0C STATUSbit0 soft core in reset, bit1 soft core powered off, bit2 DDR3 access refused outside reset, bit3 multiply-add unit busy, bit4 DDR3 calibration done, bit5 calibration failed
0x10 VersionASCII MB01; MB02 when it has the DDR3 calibration bits

Boot order

  1. The FPGA starts from the onboard flash and the DDR3 controller calibrates.
  2. The C3 reads the mailbox version every 10 ms. The FPGA counts as up only when it reads MB01 or MB02. If it reads neither within 2 seconds, it stops: it fetches no files and leaves the slots alone.
  3. Wait for bit4 of STATUS (DDR3 calibration done).
  4. TapeBoot reads the channel, fetches the manifest, checks the signature, then fetches chunk by chunk and checks the hashes. See Fetch firmware from the chain.
  5. Through the mailbox, write the runtime to 0x8000_0000 and TBW1 to 0x8100_0000, then write BOOT_INFO.
  6. Release the soft core reset. The soft core starts running from 0x8000_0000.
  7. If HEARTBEAT goes from 0 to non-zero within 60 seconds, the version counts as healthy and is committed. Otherwise it goes back to the old slot.

Two runtimes

RuntimeUseHealth test
TBRT bare-metal runtime (main line)Runs inference right after start, driving the multiply-add unit and HDMI directlyA heartbeat within 60 seconds
TapeOut Linux (secondary line)Boots the Linux 6.5.12 on chain as is and matches the on-chain machine instruction by instruction; about 41.8 million instructions to bootThe soft core has not powered off 60 seconds after reset is released

The role of a file in the manifest, runtime or os, decides which one starts.

The version without an FPGA

The same TapeBoot also runs as a Linux program on a small ARM computer. Fetching, checking and the A/B slots are all the same; the heartbeat goes through a pipe instead. See A large model on a small computer.