Skip to content

cli.md

Latest commit

 

History

History
385 lines (290 loc) · 12.2 KB

cli.md

File metadata and controls

385 lines (290 loc) · 12.2 KB
Raw

Raven CLI Reference

Leia em Português

Raven has a full headless CLI alongside the interactive TUI. Run raven help at any time to see a summary.

Subcommands

Subcommand Description
raven build <file> [options] Assemble a .s source file
raven run <file> [options] Assemble and simulate
raven export-config [options] Export the default unified config (.rcfg)
raven check-config <file> [options] Validate and inspect a .rcfg file
raven debug-run-controls [options] Dump Run Controls text and hitboxes for hover debugging
raven debug-help-layout [options] Dump help button / popup layout for a tab
raven debug-pipeline-stage [options] Dump a pipeline stage line preview for layout debugging
raven help Print usage summary

A single .rcfg file now holds all configuration — simulation settings, the cache hierarchy, and pipeline behavior — under [sim], [cache] and [pipeline] sections. The old separate .fcache / .pcfg files and their subcommands have been removed.

raven build

Assembles a .s source file and writes a FALC binary (.bin).

raven build <input> [output] [options]
Argument / Flag Description
<input> Path to the .s source file (required)
[output] Output path for the .bin file (second positional arg)
--out <path> Same as above; takes priority over the positional arg
--nout Check-only — assemble but write no output file

Examples

# Assemble and write program.bin
raven build program.s

# Write to a custom path
raven build program.s out/prog.bin
raven build program.s --out out/prog.bin

# Syntax-check only, no output
raven build program.s --nout

On success, Raven prints the instruction count and data size to stderr. On error, it prints the offending line number and message, then exits with code 1.

raven run

Assembles and simulates a program. Accepts .s source, FALC .bin, or ELF32 RISC-V binaries.

raven run <file> [options]
Flag Default Description
--config <file> built-in defaults Load the unified config (sim + cache + pipeline) from a .rcfg file
--pipeline off Run with the pipeline simulator instead of the sequential executor
--pipeline-trace-out <file> off Write a per-cycle pipeline trace JSON file; requires --pipeline
--cores <n> settings or 1 Maximum physical cores available to hart_start during the run
--mem <size> sim-settings or 16mb RAM size — accepts kb, mb, gb suffix (e.g. 256kb, 1gb)
--max-cycles <n> 1000000000 Instruction limit; a warning is printed if reached
--expect-exit <code> off Fail if the final exit code differs
--expect-stdout <text> off Fail if captured stdout differs exactly
--expect-reg <reg=value> off Assert a final integer register value; repeatable
--expect-mem <addr=value> off Assert a final 32-bit memory word; repeatable
--out <file> stdout Write simulation results to a file instead of stdout
--nout — Suppress results output entirely (program stdout still shown)
--format json|rstats|csv json Results format

--mem takes priority over the mem_kb or legacy mem_mb value in .rcfg. If neither is given, the default is 16mb.

Examples

# Run with defaults, print JSON stats to stdout
raven run program.s

# Run without printing stats
raven run program.s --nout

# Write stats to a file
raven run program.s --out results.json

# Use a custom config (cache + CPI tuning + memory) and write CSV stats
raven run program.s --config my.rcfg --format csv --out stats.csv

# Run through the pipeline simulator with an explicit config
raven run program.s --pipeline --config my.rcfg --format json

# Assert the final program state
raven run program.s --expect-exit 0 --expect-reg a0=42 --expect-mem 0x1000=0x2a

# Emit a cycle-by-cycle pipeline trace
raven run program.s --pipeline --pipeline-trace-out trace.json --nout

# Allow up to 4 cores for multi-hart programs
raven run program.s --cores 4 --nout

# Run with 64 MB RAM (overrides sim-settings)
raven run program.s --mem 64mb

# Run a pre-assembled binary or ELF
raven run prog.bin
raven run target/riscv32im-unknown-none-elf/debug/my_crate

Interactive input

If the program reads from stdin (syscalls 3 / 1003), raven run reads from the terminal interactively — any pending output is flushed before the prompt so the user sees it. Pipe or redirect stdin as usual:

echo "hello" | raven run io_echo.s --nout
printf "42\n" | raven run calculator.s --nout

Output formats

Format Description
json Machine-readable JSON with all stats
rstats Human-readable unified results (.rstats) with [program], [cache], [pipeline] and [tlb] sections
csv Spreadsheet-friendly CSV

When --pipeline is enabled, Raven still writes the normal cache statistics, but also includes a pipeline summary:

  • scope (selected for pipeline-only export, aggregate in cache/program summaries)
  • committed instructions
  • pipeline cycles
  • stall count
  • flush count
  • pipeline CPI
  • stall-tag breakdown (RAW, load-use, branch, FU, mem)

Assertions

The --expect-* flags turn raven run into a regression-friendly CLI. If any assertion fails, Raven exits with code 1.

  • --expect-exit <code> compares against the final syscall exit code.
  • --expect-stdout <text> compares against the program's full captured stdout.
  • --expect-reg <reg=value> compares the final integer register value.
  • --expect-mem <addr=value> compares a final 32-bit word in memory.

Values accept decimal or hexadecimal (0x...) syntax. Registers use the normal integer aliases, such as a0, sp, t3, or x10.

Pipeline trace JSON

--pipeline-trace-out <file> writes a structured per-cycle trace that records:

  • current cycle
  • committed instruction PC/class
  • fetch PC
  • stage occupancy (IF, ID, EX, MEM, WB)
  • speculation / stall metadata on each stage
  • hazard and forwarding traces for that cycle

This option is only valid together with --pipeline.

raven export-config

Writes the built-in default unified configuration to a .rcfg file so you can edit it. The file contains [sim], [cache] and [pipeline] sections.

raven export-config [--out <file>]

If --out is omitted, the config is printed to stdout.

raven export-config                        # print to stdout
raven export-config --out default.rcfg     # write to file

See the Config file format section below for a full field description.

raven check-config

Parses and validates a .rcfg file, prints a summary of every section (sim settings, each cache level, pipeline behavior), and optionally re-exports the normalized config.

raven check-config <file> [--out <file>]

raven check-config my.rcfg
raven check-config my.rcfg --out normalized.rcfg

raven debug-run-controls

Dumps the current Run Controls text line and the hover/click hitbox column ranges that the mouse handler sees. This is useful when visual offsets appear between the rendered controls and the hover logic.

raven debug-run-controls [options]
Flag Default Description
--width <n> 160 Virtual UI width for the dump
--height <n> 40 Virtual UI height for the dump
--cores <n> 1 Simulated max core count
--selected-core <n> 0 Selected core index
--view ram|regs|dyn ram Run sidebar mode
--running off Render state as RUN
--out <file> stdout Write dump to file 
raven debug-run-controls
raven debug-run-controls --cores 4 --selected-core 2 --view dyn
raven debug-run-controls --running --out run-controls.txt

raven debug-help-layout

Dumps the help button and popup layout for a given UI tab. Useful for verifying that key-hint positions match what the TUI actually renders at a given terminal size.

raven debug-help-layout [options]
Flag Default Description
--width <n> 160 Virtual UI width for the dump
--height <n> 40 Virtual UI height for the dump
--tab editor|run|cache|pipeline|docs|config editor Tab to inspect
--out <file> stdout Write dump to file 
raven debug-help-layout
raven debug-help-layout --tab cache
raven debug-help-layout --tab pipeline --width 120 --height 30

raven debug-pipeline-stage

Dumps a pipeline stage line preview. Useful for verifying that badge layout and disassembly truncation look correct at a given stage width.

raven debug-pipeline-stage [options]
Flag Default Description
--width <n> 24 Virtual stage inner width
--stage <name> EX Stage label
--disasm <text> addi t4, t4, 1 Disassembly preview text
--badges <csv> LOAD,RAW,FWD Badge list
--pred <text> — Optional speculative badge text
--out <file> stdout Write dump to file 
raven debug-pipeline-stage
raven debug-pipeline-stage --width 24 --disasm "addi t4, t4, 1" --badges LOAD,RAW,FWD
raven debug-pipeline-stage --stage MEM --pred SPEC

Config file format

A single .rcfg file (# Raven Config v3) holds all configuration under three sections. Export it from the TUI with Ctrl+e and re-import with Ctrl+l from any of the Cache, Config or Pipeline tabs; on the CLI use raven export-config / raven check-config.

# Raven Config v3

[sim]
cache_enabled=true
pipeline_enabled=true
vm_mode=off
trace_syscalls=false
run_scope=focus
max_cores=1
mem_kb=16384
# CPI (cycles per instruction)
cpi.alu=1
cpi.mul=3
cpi.div=20
cpi.load=0
cpi.store=0
cpi.branch_taken=3
cpi.branch_not_taken=1
cpi.jump=2
cpi.system=10
cpi.fp=5

[cache]
levels=0
icache.size=1024
icache.line_size=16
icache.associativity=2
icache.replacement=Lru
icache.write_policy=WriteBack
icache.write_alloc=WriteAllocate
icache.hit_latency=1
icache.miss_penalty=50
# ... dcache.* mirrors icache.* ; extra levels use l2.* / l3.* ; tlb.* for the TLB

[pipeline]
enabled=true
bypass.ex_to_ex=true
bypass.mem_to_ex=true
bypass.wb_to_id=true
bypass.store_to_load=false
mode=SingleCycle
fu.alu=1
fu.mul=1
fu.div=1
fu.fpu=1
fu.lsu=1
fu.sys=1
branch_resolve=Ex
predict=NotTaken
speed=Normal

[sim] — simulation settings

  • cache_enabled=false bypasses the entire cache hierarchy (all accesses go directly to RAM).
  • pipeline_enabled toggles the global pipeline state used by the TUI Config tab.
  • vm_mode — off, sv32, custom, or manual.
  • trace_syscalls controls the syscall debug log.
  • run_scope accepts all or focus.
  • max_cores defaults to 1 when omitted and should stay in the range 1..=32.
  • mem_kb sets the default RAM size in kilobytes and is snapped to the nearest power of two. Legacy mem_mb is still accepted. The --mem CLI flag overrides this value.
  • Headless --pipeline currently supports only --cores 1.
  • CPI values are extra cycles added on top of cache latency for the corresponding instruction class.

[cache] — cache hardware

Describes the cache hierarchy: I-cache, D-cache, any extra levels (L2, L3…) and the unified TLB. See Cache Config Reference for the full field list.

[pipeline] — pipeline behavior

  • enabled — pipeline enabled in the TUI
  • bypass.ex_to_ex / bypass.mem_to_ex / bypass.wb_to_id / bypass.store_to_load — forwarding paths
  • mode — mapped in the UI as Serialized or Parallel UFs
  • fu.alu / fu.mul / fu.div / fu.fpu / fu.lsu / fu.sys — functional-unit counts used by Parallel UFs mode
  • branch_resolve — Id, Ex, or Mem
  • predict — NotTaken, Taken, Btfnt, or TwoBit
  • speed — TUI playback speed (Slow, Normal, Fast, Instant)

Exit codes

Code Meaning
0 Success
1 Assembly error, simulation fault, or bad argument
`--arch <riscv32 toy16>selects the assembler backend;riscv32` is the default.

--arch <riscv32|toy16> selects the runtime backend. Toy16 intentionally does not accept RV32-only pipeline, cache config, JIT, multicore, ELF, or screen options.