Skip to content

Commit d1174cd

Browse files
Kevin7QiKevin7Qi
committed
Release: add Compiler and Simulator documentation
1 parent 653050c commit d1174cd

18 files changed

Lines changed: 3367 additions & 939 deletions

‎app/global.css‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -146,3 +146,15 @@ html {
146146
scrollbar-gutter: stable;
147147
}
148148

149+
/* Flatten the sidebar footer controls (GitHub link + theme toggle).
150+
fumadocs-ui 16.7.16 wraps them in a bordered pill and adds a leading
151+
separator on the theme toggle; we prefer the previous borderless look. */
152+
#nd-sidebar div:has(> a[aria-label="GitHub"]) {
153+
border-width: 0;
154+
background-color: transparent;
155+
}
156+
157+
#nd-sidebar div:has(> a[aria-label="GitHub"]) > button[aria-label="Toggle Theme"] {
158+
border-width: 0;
159+
}
160+

‎content/docs/Compiler/CG-Level.mdx‎

Lines changed: 147 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,147 @@
1+
---
2+
title: CG-Level
3+
description: Graph partitioning and stage-level instruction generation
4+
---
5+
6+
import { Accordion, Accordions } from 'fumadocs-ui/components/accordion';
7+
import { Callout } from 'fumadocs-ui/components/callout';
8+
import { Tabs, Tab } from 'fumadocs-ui/components/tabs';
9+
10+
CG-level compilation converts an ONNX graph into a staged multi-core task graph. The output is a JSON instruction plan organized by core grid position, with keys like `core_0_0`, `core_0_1`.
11+
12+
## CG-Level Processing Steps
13+
14+
<div className="fd-steps [&_h4]:fd-step [&_p]:my-1">
15+
16+
#### ONNX Preprocessing [!toc]
17+
Parse the ONNX model and perform shape inference
18+
19+
#### Dependency Analysis [!toc]
20+
Build a dependency graph centered on convolution operators
21+
22+
#### Stage Partitioning [!toc]
23+
Partition computation stages across the available cores
24+
25+
#### Communication Planning [!toc]
26+
Generate communication operations (`read`, `write`, `send`, `receive`, `wait_write`)
27+
28+
#### Model Simplification [!toc]
29+
Simplify the ONNX graph before partitioning; oversized convolutions may be split
30+
31+
#### Metadata Generation [!toc]
32+
Compute operation counts for throughput metrics
33+
34+
</div>
35+
36+
---
37+
38+
## Commands
39+
40+
<Tabs items={['cim-compiler', 'cimflow compile']}>
41+
<Tab value="cim-compiler">
42+
43+
```bash
44+
cim-compiler cg-level \
45+
-m model.onnx \
46+
-o output/cg \
47+
-T 8 -K 16 -B 16 -C 64 \
48+
--batch-size 8 \
49+
--strategy dp \
50+
--visualize
51+
```
52+
53+
</Tab>
54+
<Tab value="cimflow compile">
55+
56+
```bash
57+
cimflow compile cg \
58+
-m model.onnx \
59+
-o output/cg \
60+
-t 8 -k 16 -b 16 -c 64 \
61+
--batch-size 8 \
62+
--strategy dp
63+
```
64+
65+
</Tab>
66+
</Tabs>
67+
68+
<Callout type="info" title="Visualization">
69+
Add `--visualize` (native) to emit graph and core-allocation plots for inspecting partition results.
70+
</Callout>
71+
72+
---
73+
74+
## Parameters
75+
76+
These parameters define the hardware target and compilation strategy. `T` and `K` control the CIM macro array dimensions within each core, `B` sets the NoC flit size (affecting data transfer granularity), and `C` determines the core grid size (must be a perfect square). See [Configuration and Constraints](/docs/Compiler/Configuration-and-Constraints) for validation rules and config format details.
77+
78+
| Parameter | CLI Option | Required | Description |
79+
| --- | --- | --- | --- |
80+
| `model-path` | `-m`, `--model-path` | Yes | Input ONNX model path |
81+
| `T` | `-T` | No | Macro group size |
82+
| `K` | `-K` | No | Number of macro groups |
83+
| `B` | `-B` | No | NoC flit size (bandwidth parameter) |
84+
| `C` | `-C` | No | Total core count |
85+
| `strategy` | `--strategy` | No | Partition strategy: `dp`, `baseline1`, `baseline2` |
86+
| `batch-size` | `--batch-size` | No | Batch scheduling granularity for instruction generation |
87+
88+
<Accordions>
89+
<Accordion title="Partition Strategy Reference">
90+
91+
| Strategy | Internal Mode | Behavior |
92+
| --- | --- | --- |
93+
| `dp` | `0` | Dynamic-programming partition search (default) |
94+
| `baseline1` | `1` | Greedy baseline without replication |
95+
| `baseline2` | `2` | Greedy baseline with replication |
96+
97+
</Accordion>
98+
</Accordions>
99+
100+
---
101+
102+
## Output Format
103+
104+
CG output file naming:
105+
106+
```text
107+
instructions_<model>_<strategy>_T<T>_K<K>_B<B>_C<C>_batch<N>.json
108+
```
109+
110+
Example structure:
111+
112+
```json
113+
{
114+
"metadata": {
115+
"op_count": 1110836224
116+
},
117+
"core_0_0": {
118+
"stages": {
119+
"0": {
120+
"cluster_id": "Conv_0",
121+
"weight_replica_id": 0,
122+
"instructions": [
123+
{"op": "read", "attr": {"tensor_type": "weight", "shape": [64,3,3,3]}},
124+
{"op": "read", "attr": {"tensor_type": "feature", "shape": [1,3,32,32]}},
125+
{"op": "conv", "attr": {"X_shape": [1,3,32,32], "W_shape": [64,3,3,3]}},
126+
{"op": "write", "attr": {"tensor_type": "feature", "shape": [1,64,32,32], "write_id": "node_0_batch_0"}}
127+
]
128+
}
129+
}
130+
}
131+
}
132+
```
133+
134+
<Accordions>
135+
<Accordion title="Communication and Dependency Details">
136+
137+
- Intra-stage dependencies may use on-chip `send/receive`
138+
- Cross-stage dependencies flow through global-memory `write` and next-stage `read`
139+
- For multi-core mode, CG attaches deterministic `write_id` and expected write counts to support OP-level synchronization lowering
140+
141+
<Callout type="info" title="Inter-Stage Safety">
142+
`wait_write` instructions are inserted before cross-stage reads in multi-core mode to prevent read-before-write races on global memory.
143+
</Callout>
144+
145+
</Accordion>
146+
</Accordions>
147+

‎content/docs/Compiler/CLI-Reference.mdx‎

Lines changed: 199 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,199 @@
1+
---
2+
title: Run and CLI
3+
description: Command reference for CIMFlow compiler commands and native cim-compiler tools
4+
---
5+
6+
import { Accordion, Accordions } from 'fumadocs-ui/components/accordion';
7+
import { Callout } from 'fumadocs-ui/components/callout';
8+
import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
9+
import { Terminal, Cpu } from 'lucide-react';
10+
11+
The compiler can be invoked through `cimflow compile` for standard workflows or the `cim-compiler` native binary for advanced use.
12+
13+
## Which Command to Use
14+
15+
<div className="not-prose grid gap-3 grid-cols-1 sm:grid-cols-2 my-6">
16+
<div className="rounded-lg border border-fd-border p-4 bg-fd-card shadow-sm">
17+
<div className="flex items-center gap-2 mb-2">
18+
<Terminal className="size-5 text-fd-primary" />
19+
<div className="font-semibold text-fd-primary">cimflow compile</div>
20+
</div>
21+
<div className="text-sm text-fd-muted-foreground">Standard CIMFlow workflow with automatic config resolution</div>
22+
</div>
23+
<div className="rounded-lg border border-fd-border p-4 bg-fd-card shadow-sm">
24+
<div className="flex items-center gap-2 mb-2">
25+
<Cpu className="size-5 text-fd-primary" />
26+
<div className="font-semibold text-fd-primary">cim-compiler</div>
27+
</div>
28+
<div className="text-sm text-fd-muted-foreground">Native binary for advanced options, visualization, and developer tools</div>
29+
</div>
30+
</div>
31+
32+
---
33+
34+
## CIMFlow Compile Command
35+
36+
The `cimflow compile` command provides CG-level and OP-level compilation with automatic config resolution.
37+
38+
<Tabs items={['CG-Level', 'OP-Level']}>
39+
<Tab value="CG-Level">
40+
41+
```bash
42+
cimflow compile cg \
43+
-m model.onnx \
44+
-o output/cg \
45+
-t 8 -k 16 -b 16 -c 64 \
46+
--batch-size 8 --strategy dp
47+
```
48+
49+
<Accordions>
50+
<Accordion title="Options">
51+
52+
| Option | Description |
53+
| --- | --- |
54+
| `-m, --model-path` | Path to the ONNX model (required) |
55+
| `-o, --output-dir` | Output directory (required) |
56+
| `-t, --mg-size` | Macro group size (default: 8) |
57+
| `-k, --mg-num` | Number of macro groups (default: 16) |
58+
| `-b, --bandwidth` | NoC bandwidth in flits (default: 16) |
59+
| `-c, --core-num` | Number of cores (default: 64) |
60+
| `--batch-size` | Batch size (default: 8) |
61+
| `--strategy` | Partition strategy (default: `dp`) |
62+
| `--visualize` | Enable visualization of partition results |
63+
| `-l, --log-level` | Log level (`TRACE`, `DEBUG`, `VERBOSE`, `INFO`, `WARNING`, `ERROR`) |
64+
| `--compiler-bin` | Path to `cim-compiler` binary (default: `cim-compiler`) |
65+
| `--paths-cfg` | Path to `tool_paths.json` (see [Framework Configuration](/docs/Framework/configuration)) |
66+
67+
</Accordion>
68+
</Accordions>
69+
70+
</Tab>
71+
<Tab value="OP-Level">
72+
73+
```bash
74+
cimflow compile op \
75+
-i output/cg/instructions_*.json \
76+
-o output/op \
77+
-cf config.json
78+
```
79+
80+
<Accordions>
81+
<Accordion title="Options">
82+
83+
| Option | Description |
84+
| --- | --- |
85+
| `-i, --instruction-file` | CG instruction file (required) |
86+
| `-o, --output-dir` | Output directory (required) |
87+
| `-cf, --config` | Hardware config file (auto-resolved from T/B if omitted) |
88+
| `-cd, --config-dir` | Directory containing hardware configs (overrides `tool_paths.json`) |
89+
| `-t, --mg-size` | Macro group size (required for auto-resolution) |
90+
| `-b, --bandwidth` | NoC bandwidth (required for auto-resolution) |
91+
| `--compiler-bin` | Path to `cim-compiler` binary |
92+
| `--paths-cfg` | Path to `tool_paths.json` |
93+
| `-l, --log-level` | Log level |
94+
95+
</Accordion>
96+
</Accordions>
97+
98+
</Tab>
99+
</Tabs>
100+
101+
---
102+
103+
## Native Binary
104+
105+
The native `cim-compiler` binary provides additional commands and options not exposed through `cimflow compile`.
106+
107+
```bash
108+
cim-compiler [--log-level LEVEL] COMMAND [OPTIONS]
109+
```
110+
111+
### Global Options
112+
113+
| Option | Description |
114+
| --- | --- |
115+
| `--log-level` | `TRACE`, `DEBUG`, `VERBOSE`, `INFO`, `WARNING`, `ERROR` |
116+
| `--version`, `-V` | Print compiler version |
117+
118+
### Compilation Commands
119+
120+
These commands appear when you run `cim-compiler --help`.
121+
122+
<Accordions>
123+
<Accordion title="Network (Full CG + OP Pipeline)">
124+
125+
```bash
126+
cim-compiler network \
127+
-m model.onnx \
128+
-o output \
129+
-c config.json \
130+
-T 8 -K 16 -B 16 -C 64 \
131+
--batch-size 8 --strategy dp
132+
```
133+
134+
Key options:
135+
136+
- `--visualize`: Emit partition visualizations
137+
- `--keep-cg-ir`: Preserve intermediate CG JSON
138+
- `--verify`: Enable OP verify path
139+
140+
</Accordion>
141+
<Accordion title="CG-Level (Stage 1 Only)">
142+
143+
```bash
144+
cim-compiler cg-level \
145+
-m model.onnx \
146+
-o output/cg \
147+
-T 8 -K 16 -B 16 -C 64 \
148+
--batch-size 8 --strategy dp
149+
```
150+
151+
Output: `instructions_<...>.json` (CG instruction plan)
152+
153+
</Accordion>
154+
<Accordion title="OP-Level (Stage 2 Only)">
155+
156+
```bash
157+
cim-compiler op-level \
158+
-i output/cg/instructions_*.json \
159+
-o output/op \
160+
-c config.json \
161+
--verify
162+
```
163+
164+
Output: `isa_<cg_file>.json` (merged per-core ISA)
165+
166+
</Accordion>
167+
</Accordions>
168+
169+
<Callout type="warn" title="Flag Case Difference">
170+
The native `cim-compiler` uses uppercase flags (`-T`, `-K`, `-B`, `-C`) while `cimflow compile` uses lowercase (`-t`, `-k`, `-b`, `-c`).
171+
</Callout>
172+
173+
### Developer Commands
174+
175+
The following commands are not shown in `cim-compiler --help` but are available for specialized use cases: format conversion, instruction inspection, behavioral simulation, and config template generation.
176+
177+
| Command | Purpose |
178+
| --- | --- |
179+
| `compile` | Compile CIM-DSL source to `final_code.json` |
180+
| `convert` | Convert instruction formats (`json`/`asm`) |
181+
| `show` | Display instruction file in human-readable assembly |
182+
| `simulate` | Built-in behavioral simulation (distinct from the cycle-accurate `cim-simulator`) |
183+
| `multi-core-simulate` | Multi-process behavioral simulation |
184+
| `op` | Single-operator compilation/testing workflow |
185+
| `config` | Generate compiler-format config from template |
186+
| `cfg_cimsim` | Generate simulator-format config from template |
187+
188+
### Advanced Examples
189+
190+
```bash
191+
# DSL source -> final_code.json
192+
cim-compiler compile -i code.cim -o output/codegen -c config.json
193+
194+
# JSON ISA -> ASM
195+
cim-compiler convert --src-type json --dst-type asm --src-file isa.json --dst-file isa.asm
196+
197+
# Inspect instruction stream
198+
cim-compiler show -i isa.json --type json
199+
```

0 commit comments

Comments
 (0)