🔬 FLOW is currently in active development and testing — expect rough edges. A more stable release is on its way. See roadmap →

Stop rebuilding workload generators for every new platform.

v0.2.2  ·  ISA-agnostic  ·  MIT SDK

Legal instruction streams.
Any architecture. Any platform.

FLOW generates varied, constraint-aware instruction sequences for virtual prototyping, SoC simulation, and performance analysis. Describe your architecture and address space — FLOW handles operand legality, constraint enforcement, and reproducibility. Any ISA. Any simulator.

Linux x86-64 Windows x86-64 MIT SDK
flow --plugin toy.so smoke.flow
$ flow --plugin toy.so smoke.flow
ISA-agnostic Seed-reproducible MIT SDK headers C++17 Linux & Windows Platform-aware workloads
overview

Separate simulation intent from ISA knowledge.

Write what you want to run in a small .flow script. Describe your ISA in YAML or as a compiled plugin. FLOW handles legal operand selection, constraint enforcement, and reproducible random draws — your ISA definition never needs to change.

Every new architecture or platform variant starts the same way: the model is ready, but the workload generator isn’t. Hand-writing sequences is slow, error-prone, and doesn’t scale. A new SoC spin shouldn’t mean rebuilding the stimulus from scratch.

FLOW ends that cold-start.

.flow script
scene load_stress {
 random 32
 tags: [mem]
}
→
FLOW engine
random draws
constraint solve
register alloc
RNG (seeded)
→
assembly · binary output
LW r3, r0, 16
SW r4, r5, 8
LH r7, r3, 4
LBU r2, r1, 0

ISA-agnostic by design

FLOW never hard-codes mnemonics, register counts, or encoding rules. Every ISA detail arrives at runtime through a plugin — the same engine runs your custom VLIW, fixed-width, or proprietary microcontroller ISA without recompilation. No engine build from source required.

Reproducible by contract

Pass --seed and get the exact same stream every time, across machines and runs. Determinism is enforced at the engine level — plugins cannot introduce hidden randomness. Bit-identical output in CI, by design.

motivation

Why not write a script?

Most teams do — until the ISA changes, a new SoC variant ships, or the stimulus needs to cover an edge case that hand-written sequences never reach. FLOW makes the right thing easy and the fragile thing unnecessary.

Without FLOW

  • Hand-write assembly sequences for every new test scenario
  • Re-author stimulus for every ISA or SoC variant
  • Register conflicts and illegal encodings caught late in simulation
  • Constrained-random requires a full UVM/SV testbench or bespoke scripts
  • No reproducibility guarantee: different runs produce different sequences
  • Python scaffolding that only one engineer fully understands

With FLOW

  • Write intent, not mechanics — .flow says what, the engine decides how
  • New ISA in a weekend: one plugin, every existing script runs unchanged
  • Illegal sequences rejected before they reach simulation — not after
  • Constrained-random in 3 lines: random 32  tags:[mem, load]
  • --seed 42 — bit-identical output on any machine, any engineer
  • Plain-text scripts your whole team can read, review, and fork
integration

Built for your stack.

FLOW assembly output connects directly to the simulators, assemblers, and virtual platforms you already use — no adapters, no glue scripts.

Any ISA

Your ISA, any variant

Describe any fixed- or variable-width ISA in YAML or C++. Base ISA and extensions coexist in the same plugin. Under an hour to a working Tier‑A plugin.

SystemC / TLM-2

VP stimulus generation

FLOW connects directly to your virtual platform’s stimulus path. Encoded byte streams ready for TLM-2 consumption — no assembler step, no post-processing, no glue code.

SoC platforms

Platform workload generation

Describe your platform’s address space alongside your ISA — FLOW generates load and store sequences that stay within valid regions. Realistic traffic for cache, interconnect, and power analysis, not just instruction-fetch patterns.

ELF pipeline

Assemble, link, and run

FLOW emits standard assembly text. Run your toolchain assembler, link with a minimal runtime, and execute on the target — real silicon or model alike.

CI pipelines

Bit-identical regression

Pass --seed and every run produces the exact same stream. Deterministic output is enforced at the engine level. Diff your golden output — FLOW’s output never drifts.

Custom ISAs

VLIW · DSP · proprietary

No ISA knowledge is baked into the engine. VLIW, DSP, and proprietary microcontroller ISAs are first-class citizens through the same plugin API.

the .flow language

Readable scripts. Reproducible output.

A .flow script expresses simulation intent, not ISA mechanics. Scenes, loops, and inline directives compose naturally. The engine handles constraint solving, register allocation, and random draws — your script stays readable when the ISA changes.

load_stress.flow
# Pull in constraint envelope: reserved regs, global instruction-mix rules include "myarch.rules" # Directed prologue — exact instructions, exact order scene boot_sequence { directed { MOV sp, 0x1000 ADD r1, r0, 0 LDI r2, 0xDEAD } } # Constrained-random: 32 instructions, only mem-tagged, no FENCE or ECALL scene load_stress { random 32 tags: [mem, load] exclude: [HALT, NOP] } # Compose: 4 iterations of load stress + 8 ALU instructions per loop loop 4 { scene load_stress random 8 tags: [alu] } # Directed epilogue scene teardown { directed { JMP .fini } }

Scenes and scripts

A scene is a named, reusable sequence of instructions. Scripts compose scenes, loops, and inline directives — the same scene works across any ISA that exposes matching tags.

Constraint envelope

A .rules file defines the envelope: reserved registers, global instruction-mix ratios, and locked constraints. Scripts inherit the envelope and cannot violate it.

adoption ladder

Start at the tier you need.

Four integration tiers, ordered by the C++ you must write. Begin at the lowest tier that covers your ISA; move up only when you need more control. Most ISAs start and stay at Tier A.

A
no C++ Start here

YAML only

Describe your ISA entirely in instructions.yml and registers.yml. No compilation needed. Under an hour to running output.

  • Full instruction table, register file, instruction tags
  • Constrained-random draws and mix weights
  • Assembly-text output — ready for any ISS with its own assembler
  • Works for most standard RISC-style ISAs with fixed-width formats

  • Upgrade to B for split immediates or binary output
B
minimal C++

YAML + encoding

Add a small encoding step for split immediates, PC-relative targets, or packed fields. Same YAML base; roughly one C++ source file.

  • Everything in A, plus binary byte-stream output
  • Split immediates and PC-relative offset calculation
  • Packed or non-contiguous immediate fields

  • Upgrade to C for cross-operand constraints
C
moderate C++

+ operand rules

Add cross-operand validation for register write-protection, pipeline hazard rules, or instruction pairing constraints.

  • Everything in B, plus cross-operand legality checks
  • Register write-protection and hazard exclusions
  • Alignment rules and instruction-pair restrictions

  • Upgrade to D for exotic formats or grammar extensions
D
full C++

Full C++ plugin

Complete control over every aspect of your ISA — exotic encodings, instruction side effects, and grammar extensions. For the architectures that need it all.

  • Everything in C, plus custom grammar constructs
  • Multi-word encodings and instruction side effects
  • Maximum control — no constraints from YAML schema
quick start

Running in minutes.

Tier A — no C++

Zero-C++ path

Place two YAML files in a directory and point FLOW at it. No compiler, no build step. The fastest path to running output.

ⓘ  Both files must follow the FLOW YAML schema — see sdk/docs/yaml-plugin.md in the SDK for the full field reference.

1
Create a directory with two YAML files
directory layout
my_isa/ instructions.yml registers.yml
2
Run FLOW against your script
terminal
flow --isa-dir my_isa/ tests/smoke.flow
Tier B–D — compiled plugin

Compiled plugin path

Build your ISA as a shared library with the provided CMake helper, then load it at runtime. No engine rebuild required.

1
Register your ISA in CMakeLists.txt
CMakeLists.txt
flow_add_yaml_isa(myisa ${CMAKE_CURRENT_SOURCE_DIR}/data )
2
Build the plugin
terminal
cmake --build build
3
Run FLOW with the compiled plugin
terminal
flow --plugin build/myisa.so script.flow

Three workflow roles

plugin.so  or  *.yml

ISA plugin author

Write the instruction table, register file, and optional encoding hooks. Your plugin is entirely your own work under MIT headers — no engine license obligations.

<name>.rules

Simulation architect

Define the constraint envelope: reserved registers, global instruction mix ratios, and locked constraints that apply across all scripts for a given simulation campaign.

<name>.flow

Script author

Express simulation intent through directed sequences, constrained-random draws, loops, and scenes — without touching the ISA definition or the constraint envelope.

reference

CLI options.

Both flow and flow_validate are single-binary tools. No runtime dependencies beyond the ISA plugin you supply.

OptionDescription
--plugin <path>Load a compiled ISA plugin (.so / .dll)
--isa-dir <path>Load a pure-YAML ISA from a directory (instructions.yml + registers.yml required)
--isa <name>Override ISA name (default: taken from script or YAML)
--seed <n>Fix the RNG seed for reproducible, bit-identical output
--count <n>Number of instruction sequences to generate
--output <file>Write output to file (default: stdout)
--helpPrint usage

--plugin and --isa-dir are mutually exclusive; --plugin takes precedence when both are given.

licensing

SDK headers are MIT.

MIT License — Plugin interface headers and SDK helpers are freely usable, modifiable, and redistributable. Plugins you write against them are entirely your own work and carry no engine license obligations. Use FLOW in commercial SoC projects, proprietary ISA tools, or internal VP flows.

The FLOW engine binary is proprietary and covered by a separate binary license included in every release archive. The engine source is not distributed.

flow/isa/yaml_loader.hYamlIsaBase — Tier A/B/C base class
flow/isa/isa.hIsaDefinition — Tier D base class
flow/isa/descriptor.hInstrDescriptor, OperandDescriptor
flow/isa/encoding.hBitField, InsnWord, encoding helpers
flow/isa/register_file.hRegisterFile, RegisterClass
flow/isa/plugin.hppIISAPlugin, FLOW_REGISTER_ISA() macro
built by
PP
Phaneendra Paluri

Virtual prototyping · SoC modelling · C++ systems · processor architecture

Built FLOW after spending years authoring simulation stimulus by hand for SystemC/TLM2 virtual platforms and custom ISA models. The same cold-start problem repeated on every new SoC variant: working simulation model, no scalable way to exercise it. FLOW is the tool that should have existed.

The design is documented in a blog series written alongside the implementation — from motivation and grammar design through the plugin contract, constrained-random generation, and structural constructs.