21 NAND Docs 中文

TBW1 weight format

TBW1 is the model machine's weight file: a fixed binary layout. The whole file goes on chain as is, goes into memory as is, and is read directly by the binary multiply-accumulate unit.

Overview

File header (64 bytes)

OffsetLengthFieldDescription
04magicASCII TBW1
42versionu16, 1
62n_tensorsu16, number of tensors
84alignu32, 4096
124file_sizeu32, size of the whole file in bytes
1632model_idsha256 of the training config (a converted model holds the sha256 of its source file, for provenance only)
4816ReservedFilled with 0

Tensor table entry (64 bytes)

Entry i is at offset 64 + 64·i.

OffsetTypeFieldDescription
0u32idIndex
4u8kindData type, see the table below
5u8flagsFlags; must be 0 for TRI2SL
6u16groupInputs per group when scale_kind = 3
8u32rowsNumber of rows (output channels)
12u32colsNumber of columns (inputs)
16u32offsetStart of the data, 4096-aligned
20u32bytesSize of the data in bytes
24u32scale_offsetStart of the scale table; 0 if there is none
28u8scale_kindScaling method, see the table below
29char[27]nameTensor name, padded with 0
56u8layoutOnly meaningful for kind = 4, 1 = q2sl v1; 0 for every other type
577 bytesReservedFilled with 0

kind

ValueNamePer elementUsed for
0BIN11 bit, ±1Binary linear layers
1INT81 byte, two's complementEmbedding, output head
2INT162 bytesnorm, bias, config, lookup tables
3FP162 bytesNon-binary parts
4TRI2SLTernary, 2-bit slicesTernary models (only for the runtime on ARM small computers)
5FP324 bytesA ternary model's norm, stored as is

How BIN1 bits are laid out

  1. Row-major: row r holds the weights of output channel r.
  2. Each row is padded to a whole multiple of 64 bits: row_words = ceil(cols / 64), so a row is row_words × 8 bytes.
  3. Each 64-bit word is stored little-endian. Bit i of word w maps to input 64·w + i.
  4. A 1 bit means +1, a 0 bit means −1.
  5. Padding bits are always 0; the multiply-accumulate unit cuts off at cols.

Example: a 512-row × 384-column BIN1 tensor has 6 words, 48 bytes, per row, for 24,576 bytes in total.

scale_kind

ValueMeaningOutput
0No scalingy = acc
1One int16 per row, Q8.8y = (acc · s_r) >> 8
2One int8 shift amount k per rowy = acc << k when k ≥ 0, otherwise y = acc >> −k
3One int16 per group, Q8.8y = (Σ_g acc_g · s_rg) >> 8, one group per group inputs

What the multiply-accumulate unit computes

When the input x is a bit vector (1 means +1):

acc = cnt − 2·popcount((x XOR w_r) & mask)      cnt is the number of inputs taking part

When the input is an n-bit two's complement integer (n = 2–16), x is stored as bit planes; plane b holds bit b of every x_i:

P_b = 2·popcount(x_b & w_r & mask) − popcount(x_b & mask)
acc = Σ_{b<n−1} 2^b·P_b − 2^{n−1}·P_{n−1}        i.e. Σ_i w_i·x_i

Each plane is laid out like one BIN1 row: 64-bit little-endian, padding bits 0, and plane b starts at X_ADDR + b·row_words·8.

profile: tell the model by its tensor names

Has this tensorprofileRuns on
q3.cfgq3s6, ternary Qwen3s6rt on ARM small computers
qexptbt1, binary TransformerTBRT, the model machine runtime
cfg8w1a8TBRT
None of thesebmlp, toy modelTBRT

Example: the toy model

toy_bmlp.tbw1, 102,400 bytes, sha256 11c1c4b177a2308ee64732335335e044e4cf32ce0ddef75210b0d5fa4f5ed568. It is the one that runs on the model machine page.

List the file header and tensor table using only the Python standard library
python3 - toy_bmlp.tbw1 <<'EOF'
import struct, sys
b = open(sys.argv[1], 'rb').read()
magic, ver, n, align, size = struct.unpack_from('<4sHHII', b, 0)
print(magic, ver, n, align, size, len(b))
for i in range(n):
    tid, kind, flags, group, rows, cols, off, nb, s_off, sk, name, layout = struct.unpack_from('<IBBHIIIIIB27sB7x', b, 64 + 64 * i)
    print(tid, name.rstrip(b'\0').decode(), kind, f'{rows}x{cols}', hex(off), nb, sk)
EOF

Output:

idNamekindRows × columnsoffsetbytesscale_kind
0embINT8128 × 160x10002,0480
1h0BIN1512 × 3840x200024,5760
2h0.bINT16512 × 10x80001,0240
3h1BIN1512 × 5120x900032,7680
4h1.bINT16512 × 10x110001,0240
5outBIN1128 × 5120x120008,1921
6out.bINT16128 × 10x150002560
7samp.lutINT16256 × 10x160005120
8promptINT816 × 10x17000160
9cfgINT168 × 10x18000160

The first line prints b'TBW1' 1 10 4096 102400 102400: version 1, 10 tensors, alignment 4096, and both the recorded size and the actual size are 102,400.