miset and miget: Machine Image Symbol Tools

Overview

miset and miget are companion tools for writing to and reading from the Cerebras machine image (.img / .obj) binary format. They use a symbol map file (bench.map) to translate symbolic names into physical tile coordinates and memory addresses, enabling symbolic access to data in the compiled binary image and post-simulation core dumps.

Tool	Purpose
miget	Read data from an image using symbolic names; output as text or binary
miset	Write raw binary data into an image using dimension ordering/slicing

The 3D Fabric Address Space

The fabric uses three orthogonal axes:

Axis	Index	Meaning	Typical Range
W	0	Memory word offset within a tile	`0x0000`–`0x7FFF`
X	1	Column (tile X coordinate on the fabric)	0–fabw
Y	2	Row (tile Y coordinate on the fabric)	0–fabh

Every piece of data in the system is uniquely addressed by a (W, X, Y) triple: word W in tile at column X, row Y.

The `bench.map` File Format

The bench.map file is a symbol table that maps symbolic names to 3D fabric address ranges. It is produced by paint during compilation and consumed by tools including miget and miset.

bench.map holds the symbols of the first parameter-specialized variant of each code block.

Syntax

Each line defines a symbol:

name [ dim₁<extent₁ dim₂<extent₂ ... ] ( W-expr  X-expr  Y-expr )

Fields

Field	Description
`name`	Symbol identifier (e.g., `send.buf`, `router`, `gpr`). Supports dotted compound names.
`dim<extent`	Named dimension with its size. E.g., `y<1 x<3 r<24` defines 3 dimensions.
`( W X Y )`	Affine expressions mapping dimensions to the 3 fabric axes.

Affine Expressions

The (W X Y) triple uses affine (linear + constant) expressions referencing the dimension variables:

( base_W + coeff₁*dim₁ + coeff₂*dim₂   base_X + coeff₃*dim₃   base_Y + coeff₄*dim₄ )

Each expression is a sum of a constant (the origin on that axis) and linear terms in the dimension variables (the strides).

Example `bench.map`

router   [ y<1 x<3 r<24 ]     ( 0x7c00+r        0+x 0 )
switch   [ y<1 x<3 r<24 n<4 ] ( 0x7c80+4*r+n    0+x 0 )
send.a   [ n<16 ]             ( 0x0+n           0   0 )
send.buf [ n<64 _word<2 ]     ( 0x10+2*n+_word  0   0 )
recv.a   [ n<16 ]             ( 0x0+n           2   0 )
gpr      [ y<1 x<3 r<16 ]     ( 0x7d10+r        0+x 0 )

An array's entry uses the array's own dimension names (xp a[n=16] gives n<16), after the dimensions of a replicated region (y<3 x<2 for a rect named in Paint with 'x 'y). A 32-bit element (sp, u32) is two words, so its entry has a last dimension _word<2: word 0 is the low half. The map also has entries for each kernel's queues, descriptors and code, such as send.OQ0, send.tx_w_X0 and send.main.

Parsing `router [ y<1 x<3 r<24 ] ( 0x7c00+r 0+x 0 )`

Component	Value
Name	`router`
Dimensions	`y` (size 1), `x` (size 3), `r` (size 24)
W origin	`0x7c00`
W stride	`+1` along `r`
X origin	`0`
X stride	`+1` along `x`
Y origin	`0`
Y stride	`0` (constant)

This means the router symbol spans:

3 tiles at columns 0, 1, 2 (via the x dimension)
Row 0 (via the y dimension, trivially size 1)
24 words per tile starting at address 0x7c00 (via the r dimension)

Compound Symbol Lookup

bench.map supports compound (dotted) names like send.buf. The lookup algorithm:

First, count exact matches for the full name send.buf:
- One exact match is returned directly.
- More than one exact match emits a warning and returns the first map entry, preserving deterministic map-order behavior. Give replicated Paint instances unique qualifications with name(...) to select a specific instance.
If there are no exact matches, split at the last .:
- Look up send. as a prefix → provides the X, Y tile coordinates
- Look up buf as a suffix → provides the W memory address
- Combine the tile coordinates with the memory offset

This enables the pattern where send names a tile and .buf names a memory region within that tile.

miget — Read Data from Image

Command-Line Usage

miget image=<file> map=<mapfile> symbol=<name> [data=<outfile>] [options]

Or with implicit map inference, giving the image and symbol positionally:

miget bench.img send.a [options]
## Automatically uses bench.map (same basename)

Options

Option	Description
`image=<file>`	Input machine image (`.img`, or a simulation's `-sim.core`)
`map=<file>`	Symbol map file (required with `image=`; inferred from the basename only for a positional image)
`symbol=<name>`	Symbol name to read
`data=<file>`	Output file (stdout if omitted)
`text`	Text output mode — hex (default)
`binary`	Binary output mode — raw little-endian u16 words
`decimal`	Decimal text output, unsigned (an `xp` -2 prints as 65534)
`hp`	Half-precision float text output
`sp`	Single-precision float text output
`width=<n>`	Words per line in text mode
`order="<dims>"`	Same as a bracketed list: space-separated names and slices (`order="y=2 x n"`); commas are rejected
`debug`	Dump internal data structures

Dimension Ordering and Slicing

miget image=bench.img map=bench.map symbol=router [x=0:2 r=0:23]
miget image=bench.img map=bench.map symbol=router [r x]           # reorder only
miget image=bench.img map=bench.map symbol=router [x=1 r=5:10]    # pin x=1, slice r

Each dimension can specify:

Full range: [r x] — iterate over all values
Slice: [r=5:10] — inclusive range from 5 to 10
Pin: [x=1] — fix to a single value

The first dimension listed is the major one and the last varies fastest. A dimension the list leaves out is read at index 0.

Examples

## Read input data as binary (for cmp comparison)
miget image=bench.img map=bench.map symbol=send.a data=input.bin

## Read simulation output as half-precision floats
miget image=bench-sim.core map=bench.map symbol=recv.a hp

## Read with dimension slicing
miget image=bench.img map=bench.map symbol=router [x=1 r=0:15] text

## Read as single-precision (2 words per element)
miget image=bench-sim.core map=bench.map symbol=recv.weights sp

## Read as decimal
miget image=bench.img map=bench.map symbol=send.count decimal

miset — Write Raw Binary Data

Command-Line Usage

miset image=<input.img> map=<mapfile> symbol=<name> \
      data=<datafile> order="dim1 dim2" [slice="dim=val"] out=<output.img>

Options

Option	Required	Description
`image=`	Optional	Existing image to modify (fresh if omitted)
`map=`	Yes	The `.map` file
`symbol=`	Yes	Symbol name to write
`data=`	Yes	Raw binary data file (little-endian u16 words)
`order=`	Yes	Dimension names, separated by spaces or commas — controls data layout
`slice=`	Optional	Pin dimensions: `dim=value` (comma-separated)
`out=`	Yes	Output image file; naming the `image=` file updates it in place

The data file lists the values with the first dimension of order= as the major one and the last varying fastest. A dimension that order= leaves out gets the same data at every index: order="n" for a symbol with dimensions y x n writes one row of n values to every tile.

A 32-bit element needs _word as the last name in order=, and the file holds its low word first, as NumPy writes <f4 and <u4 arrays. order="n" alone is short of the _word dimension, and a file of sp values for it is reported as too long.

Example

## Write 16 values into send.a across tile (0,0)
miset image=bench.img map=bench.map symbol=send.a \
      data=input.bin order="n" out=bench.img

## Write 64 sp values into send.buf, from python3 -c "import numpy as np; np.arange(64, dtype='<f4').tofile('buf.bin')"
miset image=bench.img map=bench.map symbol=send.buf \
      data=buf.bin order="n _word" out=bench.img

Common Debug Workflows

Inspecting Pre-Simulation Data

## View the initial data loaded into a tile's memory
miget image=bench.img map=bench.map symbol=send.a text

## View as half-precision floats
miget image=bench.img map=bench.map symbol=send.buf hp

## Extract to binary for comparison
miget image=bench.img map=bench.map symbol=send.a data=expected_input.bin

Inspecting Post-Simulation Data

## Read results from the core dump
miget image=bench-sim.core map=bench.map symbol=recv.a hp

## Compare input vs output
miget image=bench.img map=bench.map symbol=send.a data=in.bin
miget image=bench-sim.core map=bench.map symbol=recv.a data=out.bin
cmp in.bin out.bin

## Inspect specific tiles and ranges
miget image=bench-sim.core map=bench.map symbol=router [x=1 r=0:15] text

Modifying Image Data

## Inject test data before simulation
miset image=bench.img map=bench.map symbol=send.a \
      data=test_input.bin order="n" out=bench.img

Inspecting Internal State

## View router configuration
miget image=bench-sim.core map=bench.map symbol=router text

## View switch table
miget image=bench-sim.core map=bench.map symbol=switch text

## View general-purpose registers
miget image=bench-sim.core map=bench.map symbol=gpr [x=0 r=0:15] text

Overview​

The 3D Fabric Address Space​

The bench.map File Format​

Syntax​

Fields​

Affine Expressions​

Example bench.map​

Parsing router [ y<1 x<3 r<24 ] ( 0x7c00+r 0+x 0 )​

Compound Symbol Lookup​

miget — Read Data from Image​

Command-Line Usage​

Options​

Dimension Ordering and Slicing​

Examples​

miset — Write Raw Binary Data​

Command-Line Usage​

Options​

Example​

Common Debug Workflows​

Inspecting Pre-Simulation Data​

Inspecting Post-Simulation Data​

Modifying Image Data​

Inspecting Internal State​

Overview

The 3D Fabric Address Space

The `bench.map` File Format

Syntax

Fields

Affine Expressions

Example `bench.map`

Parsing `router [ y<1 x<3 r<24 ] ( 0x7c00+r 0+x 0 )`

Compound Symbol Lookup

miget — Read Data from Image

Command-Line Usage

Options

Dimension Ordering and Slicing

Examples

miset — Write Raw Binary Data

Command-Line Usage

Options

Example

Common Debug Workflows

Inspecting Pre-Simulation Data

Inspecting Post-Simulation Data

Modifying Image Data

Inspecting Internal State