use std::fs;
use std::path::{Path, PathBuf};
use std::process::Command;
pub const HLS_BACKEND: &str = "bambu";
pub const HLS_BACKEND_VERSION: &str = "2024.10";
#[derive(Debug)]
pub enum HlsError {
Message(String),
}
impl std::fmt::Display for HlsError {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
match self {
HlsError::Message(m) => write!(f, "{m}"),
}
}
}
impl std::error::Error for HlsError {}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum HlsClosureConstraintClass {
HlsFree,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum HlsDataflowClosureViolationKind {
CapturingOrStateful,
WrongPathForSynthesizable,
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct HlsDataflowClosureViolation {
pub kind: HlsDataflowClosureViolationKind,
pub message: String,
}
impl HlsDataflowClosureViolation {
pub fn capturing(message: impl Into<String>) -> Self {
Self {
kind: HlsDataflowClosureViolationKind::CapturingOrStateful,
message: message.into(),
}
}
pub fn wrong_path_synthesizable(message: impl Into<String>) -> Self {
Self {
kind: HlsDataflowClosureViolationKind::WrongPathForSynthesizable,
message: message.into(),
}
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum HlsDataflowOp {
Identity,
AddConst(u32),
XorConst(u32),
MulConst(u32),
AddInputs,
}
#[derive(Debug, Clone)]
pub struct DissolvedHlsDataflow {
pub fn_name: String,
pub constraint_class: HlsClosureConstraintClass,
pub op: HlsDataflowOp,
pub c_source: String,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum InTreeScheduleKind {
LoopUnroll { trip_count: u32 },
Pipeline {
initiation_interval: u32,
stages: u32,
},
Handshake { channels: u32 },
CirctHandshake {
channels: u32,
clock_domains: u32,
elastic_depth: u32,
},
CirctHandshakeDeepen {
channels: u32,
clock_domains: u32,
elastic_depth: u32,
},
CirctHandshakeLowerDeepen {
channels: u32,
clock_domains: u32,
elastic_depth: u32,
},
}
pub fn meets_fr110_commercial_depth(kind: &InTreeScheduleKind) -> bool {
matches!(
kind,
InTreeScheduleKind::Pipeline {
initiation_interval,
stages
} if *initiation_interval >= 1 && *stages >= 2
)
}
pub fn meets_fr121_handshake(kind: &InTreeScheduleKind) -> bool {
matches!(kind, InTreeScheduleKind::Handshake { channels } if *channels >= 1)
}
pub fn meets_fr129_circt_handshake(kind: &InTreeScheduleKind) -> bool {
matches!(
kind,
InTreeScheduleKind::CirctHandshake {
channels,
clock_domains,
elastic_depth
} if *channels >= 1 && *clock_domains >= 2 && *elastic_depth >= 1
)
}
pub fn meets_fr180_handshake_deepen(kind: &InTreeScheduleKind) -> bool {
matches!(
kind,
InTreeScheduleKind::CirctHandshakeDeepen {
channels,
clock_domains,
elastic_depth
} if *channels >= 1 && *clock_domains >= 2 && *elastic_depth >= 1
)
}
pub fn meets_fr187_handshake_lower_deepen(kind: &InTreeScheduleKind) -> bool {
matches!(
kind,
InTreeScheduleKind::CirctHandshakeLowerDeepen {
channels,
clock_domains,
elastic_depth
} if *channels >= 1 && *clock_domains >= 2 && *elastic_depth >= 1
)
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ScheduleStage {
pub index: u32,
pub op: HlsDataflowOp,
pub label: String,
}
#[derive(Debug, Clone)]
pub struct InTreeScheduleArtifact {
pub fn_name: String,
pub kind: InTreeScheduleKind,
pub stages: Vec<ScheduleStage>,
pub schedule_ir: String,
pub rtl_stub: String,
}
pub fn resolve_bambu() -> Result<PathBuf, HlsError> {
if let Some(p) = std::env::var_os("BITLOOM_BAMBU_PATH").map(PathBuf::from) {
return Ok(p);
}
if let Some(p) = std::env::var_os("RHDL_BAMBU_PATH").map(PathBuf::from) {
return Ok(p);
}
which("bambu").ok_or_else(|| {
HlsError::Message(format!(
"pinned HLS backend {HLS_BACKEND} {HLS_BACKEND_VERSION} not found; \
set BITLOOM_BAMBU_PATH (or RHDL_BAMBU_PATH) to the bambu binary, or install \
AppImage https://release.bambuhls.eu/bambu-{HLS_BACKEND_VERSION}.AppImage \
(AD-25 / FR35)"
))
})
}
pub fn check_hls_dataflow_closure(
class: HlsClosureConstraintClass,
violations: &[HlsDataflowClosureViolation],
) -> Result<(), HlsError> {
match class {
HlsClosureConstraintClass::HlsFree => {
if violations.is_empty() {
Ok(())
} else {
let detail = violations
.iter()
.map(|v| format!("{:?}: {}", v.kind, v.message))
.collect::<Vec<_>>()
.join("; ");
Err(HlsError::Message(format!(
"HLS dataflow closure rejected (D1 / Cap-R-62, class={class:?}): {detail}"
)))
}
}
}
}
fn c_source_for_op(fn_name: &str, op: &HlsDataflowOp) -> String {
let header = format!(
"/* generated by bitloom for {HLS_BACKEND} {HLS_BACKEND_VERSION}; no scheduling in bitloom */\n\
/* FR76: dataflow transform expanded before external HLS lower (NFR36 clean) */\n"
);
let body = match op {
HlsDataflowOp::Identity => format!(
"unsigned {fn_name}(unsigned x) {{\n\
return x;\n\
}}\n"
),
HlsDataflowOp::AddConst(k) => format!(
"unsigned {fn_name}(unsigned x) {{\n\
return x + {k}u;\n\
}}\n"
),
HlsDataflowOp::XorConst(k) => format!(
"unsigned {fn_name}(unsigned x) {{\n\
return x ^ {k}u;\n\
}}\n"
),
HlsDataflowOp::MulConst(k) => format!(
"unsigned {fn_name}(unsigned x) {{\n\
return x * {k}u;\n\
}}\n"
),
HlsDataflowOp::AddInputs => format!(
"unsigned {fn_name}(unsigned a, unsigned b) {{\n\
return a + b;\n\
}}\n"
),
};
format!("{header}{body}")
}
pub fn assert_no_closure_residue_in_c(c_source: &str) -> Result<(), HlsError> {
let lower = c_source.to_lowercase();
for n in ["closure", "callback", "fnonce", "fnmut", "dyn fn"] {
if lower.contains(n) {
return Err(HlsError::Message(format!(
"NFR36: dissolved HLS C must not contain closure residue (found `{n}`)"
)));
}
}
if c_source.contains("||") {
return Err(HlsError::Message(
"NFR36: dissolved HLS C must not contain `||` closure token".into(),
));
}
for needle in ["Fn(", "Fn ("] {
if c_source.contains(needle) {
return Err(HlsError::Message(format!(
"NFR36: dissolved HLS C must not contain `{needle}`"
)));
}
}
Ok(())
}
pub fn dissolve_dataflow_transform<F>(
fn_name: &str,
violations: &[HlsDataflowClosureViolation],
transform: F,
) -> Result<DissolvedHlsDataflow, HlsError>
where
F: FnOnce() -> HlsDataflowOp,
{
check_hls_dataflow_closure(HlsClosureConstraintClass::HlsFree, violations)?;
let op = transform();
let c_source = c_source_for_op(fn_name, &op);
assert_no_closure_residue_in_c(&c_source)?;
Ok(DissolvedHlsDataflow {
fn_name: fn_name.to_string(),
constraint_class: HlsClosureConstraintClass::HlsFree,
op,
c_source,
})
}
pub fn parse_dataflow_alias(alias: &str) -> Result<HlsDataflowOp, HlsError> {
match alias {
"add" | "add_inputs" => Ok(HlsDataflowOp::AddInputs),
"id" | "identity" => Ok(HlsDataflowOp::Identity),
"add1" => Ok(HlsDataflowOp::AddConst(1)),
"xor_a5" | "map_xor_a5" => Ok(HlsDataflowOp::XorConst(0xa5)),
other => Err(HlsError::Message(format!(
"unknown HLS dataflow alias `{other}`; \
expected add|identity|add1|xor_a5 (FR76)"
))),
}
}
pub fn emit_c_dissolved(
dissolved: &DissolvedHlsDataflow,
out_dir: &Path,
) -> Result<PathBuf, HlsError> {
fs::create_dir_all(out_dir).map_err(|e| HlsError::Message(e.to_string()))?;
let path = out_dir.join(format!("{}.c", dissolved.fn_name));
fs::write(&path, &dissolved.c_source).map_err(|e| HlsError::Message(e.to_string()))?;
Ok(path)
}
pub fn emit_c_stub(fn_name: &str, out_dir: &Path) -> Result<PathBuf, HlsError> {
let dissolved = dissolve_dataflow_transform(fn_name, &[], || HlsDataflowOp::AddInputs)?;
emit_c_dissolved(&dissolved, out_dir)
}
pub fn run_hls_dissolved(
dissolved: &DissolvedHlsDataflow,
out_dir: &Path,
emit_only: bool,
) -> Result<PathBuf, HlsError> {
run_hls_dissolved_with_backend(dissolved, out_dir, emit_only, None)
}
pub fn run_hls_dissolved_with_backend(
dissolved: &DissolvedHlsDataflow,
out_dir: &Path,
emit_only: bool,
bambu_override: Option<&Path>,
) -> Result<PathBuf, HlsError> {
let c = emit_c_dissolved(dissolved, out_dir)?;
if emit_only
|| matches!(
std::env::var("BITLOOM_HLS_EMIT_ONLY").as_deref(),
Ok("1") | Ok("true") | Ok("yes")
)
{
return Ok(c);
}
let bambu = match bambu_override {
Some(p) => Ok(p.to_path_buf()),
None => resolve_bambu(),
}?;
let status = Command::new(&bambu)
.arg(c.as_os_str())
.arg(format!("--top-fname={}", dissolved.fn_name))
.current_dir(out_dir)
.status()
.map_err(|e| HlsError::Message(format!("spawn {HLS_BACKEND}: {e}")))?;
if !status.success() {
return Err(HlsError::Message(format!(
"{HLS_BACKEND} {HLS_BACKEND_VERSION} exited non-zero (AD-25 / FR35 / FR76)"
)));
}
find_rtl_artifact(out_dir, &dissolved.fn_name)
}
pub fn run_hls(fn_name: &str, out_dir: &Path, emit_only: bool) -> Result<PathBuf, HlsError> {
let dissolved = dissolve_dataflow_transform(fn_name, &[], || HlsDataflowOp::AddInputs)?;
run_hls_dissolved(&dissolved, out_dir, emit_only)
}
pub fn run_hls_dataflow(
fn_name: &str,
dataflow_alias: &str,
out_dir: &Path,
emit_only: bool,
) -> Result<PathBuf, HlsError> {
run_hls_dataflow_with_backend(fn_name, dataflow_alias, out_dir, emit_only, None)
}
pub fn run_hls_dataflow_with_backend(
fn_name: &str,
dataflow_alias: &str,
out_dir: &Path,
emit_only: bool,
bambu_override: Option<&Path>,
) -> Result<PathBuf, HlsError> {
let op = parse_dataflow_alias(dataflow_alias)?;
let dissolved = dissolve_dataflow_transform(fn_name, &[], || op)?;
run_hls_dissolved_with_backend(&dissolved, out_dir, emit_only, bambu_override)
}
fn op_label(op: &HlsDataflowOp) -> String {
match op {
HlsDataflowOp::Identity => "identity".into(),
HlsDataflowOp::AddConst(k) => format!("add_const_{k}"),
HlsDataflowOp::XorConst(k) => format!("xor_const_{k}"),
HlsDataflowOp::MulConst(k) => format!("mul_const_{k}"),
HlsDataflowOp::AddInputs => "add_inputs".into(),
}
}
fn verilog_expr(op: &HlsDataflowOp, input: &str) -> String {
match op {
HlsDataflowOp::Identity => input.to_string(),
HlsDataflowOp::AddConst(k) => format!("({input} + 32'd{k})"),
HlsDataflowOp::XorConst(k) => format!("({input} ^ 32'd{k})"),
HlsDataflowOp::MulConst(k) => format!("({input} * 32'd{k})"),
HlsDataflowOp::AddInputs => {
format!("({input} /* binary AddInputs collapsed to unary MVP */)")
}
}
}
fn build_schedule_ir(
fn_name: &str,
kind: &InTreeScheduleKind,
stages: &[ScheduleStage],
fr96: bool,
) -> String {
let mut lines = Vec::new();
lines.push("{".into());
match kind {
InTreeScheduleKind::Handshake { .. } => {
lines.push(" \"fr121\": true,".into());
lines.push(" \"handshake\": true,".into());
lines.push(" \"semantics\": \"handshake-dynamic-df\",".into());
lines.push(" \"path\": \"in-tree-handshake\",".into());
}
InTreeScheduleKind::CirctHandshake { .. } => {
lines.push(" \"fr129\": true,".into());
lines.push(" \"circt_handshake\": true,".into());
lines.push(" \"semantics\": \"circt-handshake-dialect\",".into());
lines.push(" \"path\": \"in-tree-circt-handshake\",".into());
}
InTreeScheduleKind::CirctHandshakeDeepen { .. } => {
lines.push(" \"fr129\": true,".into());
lines.push(" \"fr180\": true,".into());
lines.push(" \"circt_handshake\": true,".into());
lines.push(" \"handshake_deepen\": true,".into());
lines.push(" \"semantics\": \"circt-handshake-dialect-deepen\",".into());
lines.push(" \"path\": \"in-tree-circt-handshake-deepen\",".into());
}
InTreeScheduleKind::CirctHandshakeLowerDeepen { .. } => {
lines.push(" \"fr129\": true,".into());
lines.push(" \"fr180\": true,".into());
lines.push(" \"fr187\": true,".into());
lines.push(" \"circt_handshake\": true,".into());
lines.push(" \"handshake_deepen\": true,".into());
lines.push(" \"handshake_lower_deepen\": true,".into());
lines.push(" \"semantics\": \"circt-handshake-lower-deepen\",".into());
lines.push(" \"path\": \"in-tree-circt-handshake-lower-deepen\",".into());
}
_ => {
lines.push(" \"fr95\": true,".into());
lines.push(" \"path\": \"in-tree\",".into());
}
}
if fr96 {
lines.push(" \"fr96\": true,".into());
lines.push(" \"dataflow_transform\": \"dissolved\",".into());
}
lines.push(format!(" \"fn_name\": \"{fn_name}\","));
match kind {
InTreeScheduleKind::LoopUnroll { trip_count } => {
lines.push(" \"kind\": \"loop-unroll\",".into());
lines.push(format!(" \"trip_count\": {trip_count},"));
}
InTreeScheduleKind::Pipeline {
initiation_interval,
stages: n,
} => {
lines.push(" \"kind\": \"pipeline\",".into());
lines.push(format!(" \"initiation_interval\": {initiation_interval},"));
lines.push(format!(" \"ii\": {initiation_interval},"));
lines.push(format!(" \"pipeline_stages\": {n},"));
if *n >= 2 {
lines.push(" \"fr110\": true,".into());
}
}
InTreeScheduleKind::Handshake { channels } => {
lines.push(" \"kind\": \"handshake\",".into());
lines.push(format!(" \"channels\": {channels},"));
}
InTreeScheduleKind::CirctHandshake {
channels,
clock_domains,
elastic_depth,
} => {
lines.push(" \"kind\": \"circt-handshake\",".into());
lines.push(format!(" \"channels\": {channels},"));
lines.push(format!(" \"clock_domains\": {clock_domains},"));
lines.push(format!(" \"elastic_depth\": {elastic_depth},"));
lines.push(format!(" \"elastic_buffers\": {elastic_depth},"));
lines.push(" \"dialect\": \"circt.handshake\",".into());
lines.push(" \"ops\": [\"handshake.func\", \"handshake.buffer\"],".into());
}
InTreeScheduleKind::CirctHandshakeDeepen {
channels,
clock_domains,
elastic_depth,
} => {
lines.push(" \"kind\": \"circt-handshake-deepen\",".into());
lines.push(format!(" \"channels\": {channels},"));
lines.push(format!(" \"clock_domains\": {clock_domains},"));
lines.push(format!(" \"elastic_depth\": {elastic_depth},"));
lines.push(format!(" \"elastic_buffers\": {elastic_depth},"));
lines.push(" \"dialect\": \"circt.handshake\",".into());
lines.push(
" \"ops\": [\"handshake.func\", \"handshake.buffer\", \"handshake.fork\", \"handshake.join\"],"
.into(),
);
}
InTreeScheduleKind::CirctHandshakeLowerDeepen {
channels,
clock_domains,
elastic_depth,
} => {
lines.push(" \"kind\": \"circt-handshake-lower-deepen\",".into());
lines.push(format!(" \"channels\": {channels},"));
lines.push(format!(" \"clock_domains\": {clock_domains},"));
lines.push(format!(" \"elastic_depth\": {elastic_depth},"));
lines.push(format!(" \"elastic_buffers\": {elastic_depth},"));
lines.push(" \"dialect\": \"circt.handshake\",".into());
lines.push(
" \"ops\": [\"handshake.func\", \"handshake.buffer\", \"handshake.fork\", \"handshake.join\", \"handshake.branch\", \"handshake.merge\"],"
.into(),
);
}
}
lines.push(format!(" \"stage_count\": {},", stages.len()));
lines.push(" \"stages\": [".into());
for (i, st) in stages.iter().enumerate() {
let comma = if i + 1 == stages.len() { "" } else { "," };
lines.push(format!(
" {{\"index\": {}, \"label\": \"{}\", \"op\": \"{}\"}}{comma}",
st.index,
st.label,
op_label(&st.op)
));
}
lines.push(" ]".into());
lines.push("}".into());
lines.join("\n")
}
fn build_rtl_stub(fn_name: &str, kind: &InTreeScheduleKind, stages: &[ScheduleStage]) -> String {
if let InTreeScheduleKind::Handshake { channels } = kind {
return build_handshake_rtl_stub(fn_name, *channels, stages);
}
if let InTreeScheduleKind::CirctHandshake {
channels,
clock_domains,
elastic_depth,
} = kind
{
return build_circt_handshake_rtl_stub(
fn_name,
*channels,
*clock_domains,
*elastic_depth,
stages,
CirctHandshakeStubDepth::Base,
);
}
if let InTreeScheduleKind::CirctHandshakeDeepen {
channels,
clock_domains,
elastic_depth,
} = kind
{
return build_circt_handshake_rtl_stub(
fn_name,
*channels,
*clock_domains,
*elastic_depth,
stages,
CirctHandshakeStubDepth::Deepen,
);
}
if let InTreeScheduleKind::CirctHandshakeLowerDeepen {
channels,
clock_domains,
elastic_depth,
} = kind
{
return build_circt_handshake_rtl_stub(
fn_name,
*channels,
*clock_domains,
*elastic_depth,
stages,
CirctHandshakeStubDepth::LowerDeepen,
);
}
let kind_note = match kind {
InTreeScheduleKind::LoopUnroll { trip_count } => {
format!("loop-unroll trip_count={trip_count}")
}
InTreeScheduleKind::Pipeline {
initiation_interval,
stages: n,
} => {
let depth = if *n >= 2 {
"FR110 commercial-depth"
} else {
"FR95 secondary"
};
format!("pipeline II={initiation_interval} stages={n} ({depth})")
}
InTreeScheduleKind::Handshake { .. }
| InTreeScheduleKind::CirctHandshake { .. }
| InTreeScheduleKind::CirctHandshakeDeepen { .. }
| InTreeScheduleKind::CirctHandshakeLowerDeepen { .. } => {
unreachable!()
}
};
let mut body = String::new();
let honesty = if matches!(
kind,
InTreeScheduleKind::Pipeline { stages, .. } if *stages >= 2
) {
" // FR110 in-tree depth: multi-stage pipeline + II (not a full commercial HLS compiler)\n"
} else {
" // FR95 in-tree-mvp: combinatorial unroll/pipeline sketch (not commercial HLS quality)\n"
};
body.push_str(honesty);
let mut cur = "x".to_string();
for st in stages {
let next = format!("s{}", st.index);
let expr = verilog_expr(&st.op, &cur);
body.push_str(&format!(" wire [31:0] {next} = {expr};\n"));
cur = next;
}
format!(
"// generated by bitloom FR95 in-tree-mvp ({kind_note}); no Bambu\n\
module {fn_name}(\n\
input wire [31:0] x,\n\
output wire [31:0] y\n\
);\n\
{body}\
assign y = {cur};\n\
endmodule\n"
)
}
fn build_handshake_rtl_stub(fn_name: &str, channels: u32, stages: &[ScheduleStage]) -> String {
let mut body = String::new();
let mut cur = "x_data".to_string();
for st in stages {
let next = format!("s{}", st.index);
let expr = verilog_expr(&st.op, &cur);
body.push_str(&format!(" wire [31:0] {next} = {expr};\n"));
cur = next;
}
format!(
"// generated by bitloom FR121 Handshake default synthesizable (channels={channels}); no Bambu\n\
// ready/valid dynamic dataflow channels (documented default synthesizable DF semantics)\n\
module {fn_name}(\n\
input wire clk,\n\
input wire rst_n,\n\
input wire [31:0] x_data,\n\
input wire x_valid,\n\
output wire x_ready,\n\
output wire [31:0] y_data,\n\
output wire y_valid,\n\
input wire y_ready\n\
);\n\
// FR121: Handshake / dynamic-DF (not in-tree-mvp static schedule alone)\n\
{body}\
assign x_ready = y_ready;\n\
assign y_valid = x_valid;\n\
assign y_data = {cur};\n\
endmodule\n"
)
}
#[derive(Clone, Copy)]
enum CirctHandshakeStubDepth {
Base,
Deepen,
LowerDeepen,
}
fn build_circt_handshake_rtl_stub(
fn_name: &str,
channels: u32,
clock_domains: u32,
elastic_depth: u32,
stages: &[ScheduleStage],
depth: CirctHandshakeStubDepth,
) -> String {
let mut clk_ports = String::new();
for d in 0..clock_domains {
clk_ports.push_str(&format!(" input wire clk{d},\n"));
}
let mut body = String::new();
body.push_str(&format!(
" // handshake.func {fn_name} — CIRCT Handshake dialect subset (FR129)\n"
));
body.push_str(&format!(
" // handshake.buffer depth={elastic_depth} elastic_buffers={elastic_depth} across {clock_domains} clock domains\n"
));
match depth {
CirctHandshakeStubDepth::Base => {}
CirctHandshakeStubDepth::Deepen => {
body.push_str(" // handshake.fork — FR180 dialect deepen (control fan-out)\n");
body.push_str(" // handshake.join — FR180 dialect deepen (control fan-in)\n");
}
CirctHandshakeStubDepth::LowerDeepen => {
body.push_str(" // handshake.fork — FR180 dialect deepen (control fan-out)\n");
body.push_str(" // handshake.join — FR180 dialect deepen (control fan-in)\n");
body.push_str(" // handshake.branch — FR187 lower deepen (control branch)\n");
body.push_str(" // handshake.merge — FR187 lower deepen (control merge)\n");
}
}
let mut cur = "x_data".to_string();
for st in stages {
let next = format!("s{}", st.index);
let expr = verilog_expr(&st.op, &cur);
body.push_str(&format!(" wire [31:0] {next} = {expr};\n"));
cur = next;
}
let (fr_tag, beyond) = match depth {
CirctHandshakeStubDepth::LowerDeepen => (
"FR187",
"beyond FR180 fork+join: dialect ops handshake.branch / handshake.merge (+ fork/join + func/buffer + multi-clock elastic)",
),
CirctHandshakeStubDepth::Deepen => (
"FR180",
"beyond FR129 C1–C4: dialect ops handshake.fork / handshake.join (+ func/buffer + multi-clock elastic)",
),
CirctHandshakeStubDepth::Base => (
"FR129",
"beyond FR121 ready/valid: dialect ops handshake.func / handshake.buffer + multi-clock elastic buffers",
),
};
format!(
"// generated by bitloom {fr_tag} CIRCT Handshake (channels={channels}, clock_domains={clock_domains}, elastic_depth={elastic_depth}); no Bambu\n\
// {beyond}\n\
module {fn_name}(\n\
{clk_ports}\
input wire rst_n,\n\
input wire [31:0] x_data,\n\
input wire x_valid,\n\
output wire x_ready,\n\
output wire [31:0] y_data,\n\
output wire y_valid,\n\
input wire y_ready\n\
);\n\
// {fr_tag}: CIRCT Handshake dialect markers\n\
{body}\
assign x_ready = y_ready;\n\
assign y_valid = x_valid;\n\
assign y_data = {cur};\n\
endmodule\n"
)
}
pub fn schedule_in_tree(
fn_name: &str,
op: HlsDataflowOp,
kind: InTreeScheduleKind,
) -> Result<InTreeScheduleArtifact, HlsError> {
if fn_name.is_empty() {
return Err(HlsError::Message(
"FR95 in-tree schedule: fn_name must be non-empty".into(),
));
}
let stage_count = match kind {
InTreeScheduleKind::LoopUnroll { trip_count } => {
if trip_count == 0 {
return Err(HlsError::Message(
"FR95 in-tree loop-unroll: trip_count must be >= 1".into(),
));
}
trip_count
}
InTreeScheduleKind::Pipeline {
initiation_interval,
stages,
} => {
if initiation_interval == 0 || stages == 0 {
return Err(HlsError::Message(
"FR95 in-tree pipeline: initiation_interval and stages must be >= 1".into(),
));
}
stages
}
InTreeScheduleKind::Handshake { channels } => {
if channels == 0 {
return Err(HlsError::Message(
"FR121 Handshake: channels (通道) must be >= 1; zero-channel is not a valid \
default synthesizable Handshake path"
.into(),
));
}
channels
}
InTreeScheduleKind::CirctHandshake {
channels,
clock_domains,
elastic_depth,
} => {
if channels == 0 || clock_domains < 2 || elastic_depth == 0 {
return Err(HlsError::Message(format!(
"FR129 CIRCT Handshake: require channels>=1, clock_domains>=2, elastic_depth>=1 \
(got channels={channels} clock_domains={clock_domains} elastic_depth={elastic_depth}); \
FR121 ready/valid alone ≠ FR129"
)));
}
channels
}
InTreeScheduleKind::CirctHandshakeDeepen {
channels,
clock_domains,
elastic_depth,
} => {
if channels == 0 || clock_domains < 2 || elastic_depth == 0 {
return Err(HlsError::Message(format!(
"FR180 Handshake deepen: require channels>=1, clock_domains>=2, elastic_depth>=1 \
(got channels={channels} clock_domains={clock_domains} elastic_depth={elastic_depth}); \
FR129/FR175/FR121 alone ≠ FR180"
)));
}
channels
}
InTreeScheduleKind::CirctHandshakeLowerDeepen {
channels,
clock_domains,
elastic_depth,
} => {
if channels == 0 || clock_domains < 2 || elastic_depth == 0 {
return Err(HlsError::Message(format!(
"FR187 Handshake lower deepen: require channels>=1, clock_domains>=2, elastic_depth>=1 \
(got channels={channels} clock_domains={clock_domains} elastic_depth={elastic_depth}); \
FR180/FR129/FR175 alone ≠ FR187"
)));
}
channels
}
};
let stages: Vec<ScheduleStage> = (0..stage_count)
.map(|index| ScheduleStage {
index,
op,
label: format!("stage_{index}_{}", op_label(&op)),
})
.collect();
let schedule_ir = build_schedule_ir(fn_name, &kind, &stages, false);
let rtl_stub = build_rtl_stub(fn_name, &kind, &stages);
Ok(InTreeScheduleArtifact {
fn_name: fn_name.to_string(),
kind,
stages,
schedule_ir,
rtl_stub,
})
}
pub fn schedule_in_tree_fr110(
fn_name: &str,
op: HlsDataflowOp,
initiation_interval: u32,
pipeline_stages: u32,
) -> Result<InTreeScheduleArtifact, HlsError> {
let kind = InTreeScheduleKind::Pipeline {
initiation_interval,
stages: pipeline_stages,
};
if !meets_fr110_commercial_depth(&kind) {
return Err(HlsError::Message(format!(
"FR110 commercial depth: require pipeline with ii>=1 and pipeline_stages>=2 \
(got ii={initiation_interval} stages={pipeline_stages}); \
FR95 MVP loop-unroll / single-stage pipeline alone ≠ FR110"
)));
}
schedule_in_tree(fn_name, op, kind)
}
pub fn schedule_handshake_default(
fn_name: &str,
op: HlsDataflowOp,
channels: u32,
) -> Result<InTreeScheduleArtifact, HlsError> {
let kind = InTreeScheduleKind::Handshake { channels };
if !meets_fr121_handshake(&kind) {
return Err(HlsError::Message(format!(
"FR121 Handshake: require channels>=1 (got channels={channels}); \
FR95 MVP loop-unroll / FR110 pipeline alone ≠ FR121"
)));
}
if fn_name.is_empty() {
return Err(HlsError::Message(
"FR121 Handshake schedule: fn_name must be non-empty".into(),
));
}
schedule_in_tree(fn_name, op, kind)
}
pub fn schedule_handshake_from_transform<F>(
fn_name: &str,
violations: &[HlsDataflowClosureViolation],
channels: u32,
transform: F,
) -> Result<InTreeScheduleArtifact, HlsError>
where
F: FnOnce() -> HlsDataflowOp,
{
let dissolved = dissolve_dataflow_transform(fn_name, violations, transform)?;
let mut artifact = schedule_handshake_default(&dissolved.fn_name, dissolved.op, channels)?;
artifact.schedule_ir =
build_schedule_ir(&artifact.fn_name, &artifact.kind, &artifact.stages, true);
artifact.rtl_stub = format!(
"// FR96: dataflow transform dissolved before FR121 Handshake schedule (AD-18)\n{}",
artifact.rtl_stub
);
Ok(artifact)
}
pub fn schedule_circt_handshake(
fn_name: &str,
op: HlsDataflowOp,
channels: u32,
clock_domains: u32,
elastic_depth: u32,
) -> Result<InTreeScheduleArtifact, HlsError> {
let kind = InTreeScheduleKind::CirctHandshake {
channels,
clock_domains,
elastic_depth,
};
if !meets_fr129_circt_handshake(&kind) {
return Err(HlsError::Message(format!(
"FR129 CIRCT Handshake: require channels>=1, clock_domains>=2, elastic_depth>=1 \
(got channels={channels} clock_domains={clock_domains} elastic_depth={elastic_depth}); \
FR95/FR110/FR121 alone ≠ FR129"
)));
}
if fn_name.is_empty() {
return Err(HlsError::Message(
"FR129 CIRCT Handshake schedule: fn_name must be non-empty".into(),
));
}
schedule_in_tree(fn_name, op, kind)
}
pub fn schedule_circt_handshake_from_transform<F>(
fn_name: &str,
violations: &[HlsDataflowClosureViolation],
channels: u32,
clock_domains: u32,
elastic_depth: u32,
transform: F,
) -> Result<InTreeScheduleArtifact, HlsError>
where
F: FnOnce() -> HlsDataflowOp,
{
let dissolved = dissolve_dataflow_transform(fn_name, violations, transform)?;
let mut artifact = schedule_circt_handshake(
&dissolved.fn_name,
dissolved.op,
channels,
clock_domains,
elastic_depth,
)?;
artifact.schedule_ir =
build_schedule_ir(&artifact.fn_name, &artifact.kind, &artifact.stages, true);
artifact.rtl_stub = format!(
"// FR96: dataflow transform dissolved before FR129 CIRCT Handshake schedule (AD-18)\n{}",
artifact.rtl_stub
);
Ok(artifact)
}
pub fn schedule_circt_handshake_deepen(
fn_name: &str,
op: HlsDataflowOp,
channels: u32,
clock_domains: u32,
elastic_depth: u32,
) -> Result<InTreeScheduleArtifact, HlsError> {
if std::env::var_os("BITLOOM_HANDSHAKE_DEEPEN_FORCE_MISSING").as_deref()
== Some(std::ffi::OsStr::new("1"))
{
return Err(HlsError::Message(
"FR180 Handshake deepen unavailable (BITLOOM_HANDSHAKE_DEEPEN_FORCE_MISSING=1); \
refusing silent success"
.into(),
));
}
let kind = InTreeScheduleKind::CirctHandshakeDeepen {
channels,
clock_domains,
elastic_depth,
};
if !meets_fr180_handshake_deepen(&kind) {
return Err(HlsError::Message(format!(
"FR180 Handshake deepen: require channels>=1, clock_domains>=2, elastic_depth>=1 \
(got channels={channels} clock_domains={clock_domains} elastic_depth={elastic_depth}); \
FR129/FR175/FR121 alone ≠ FR180"
)));
}
if fn_name.is_empty() {
return Err(HlsError::Message(
"FR180 Handshake deepen schedule: fn_name must be non-empty".into(),
));
}
schedule_in_tree(fn_name, op, kind)
}
pub fn schedule_circt_handshake_deepen_from_transform<F>(
fn_name: &str,
violations: &[HlsDataflowClosureViolation],
channels: u32,
clock_domains: u32,
elastic_depth: u32,
transform: F,
) -> Result<InTreeScheduleArtifact, HlsError>
where
F: FnOnce() -> HlsDataflowOp,
{
let dissolved = dissolve_dataflow_transform(fn_name, violations, transform)?;
let mut artifact = schedule_circt_handshake_deepen(
&dissolved.fn_name,
dissolved.op,
channels,
clock_domains,
elastic_depth,
)?;
artifact.schedule_ir =
build_schedule_ir(&artifact.fn_name, &artifact.kind, &artifact.stages, true);
artifact.rtl_stub = format!(
"// FR96: dataflow transform dissolved before FR180 Handshake deepen schedule (AD-18)\n{}",
artifact.rtl_stub
);
Ok(artifact)
}
pub fn schedule_circt_handshake_lower_deepen(
fn_name: &str,
op: HlsDataflowOp,
channels: u32,
clock_domains: u32,
elastic_depth: u32,
) -> Result<InTreeScheduleArtifact, HlsError> {
if std::env::var_os("BITLOOM_HANDSHAKE_LOWER_FORCE_MISSING").as_deref()
== Some(std::ffi::OsStr::new("1"))
{
return Err(HlsError::Message(
"FR187 Handshake lower deepen unavailable (BITLOOM_HANDSHAKE_LOWER_FORCE_MISSING=1); \
refusing silent success"
.into(),
));
}
let kind = InTreeScheduleKind::CirctHandshakeLowerDeepen {
channels,
clock_domains,
elastic_depth,
};
if !meets_fr187_handshake_lower_deepen(&kind) {
return Err(HlsError::Message(format!(
"FR187 Handshake lower deepen: require channels>=1, clock_domains>=2, elastic_depth>=1 \
(got channels={channels} clock_domains={clock_domains} elastic_depth={elastic_depth}); \
FR180/FR129/FR175 alone ≠ FR187"
)));
}
if fn_name.is_empty() {
return Err(HlsError::Message(
"FR187 Handshake lower deepen schedule: fn_name must be non-empty".into(),
));
}
schedule_in_tree(fn_name, op, kind)
}
pub fn schedule_circt_handshake_lower_deepen_from_transform<F>(
fn_name: &str,
violations: &[HlsDataflowClosureViolation],
channels: u32,
clock_domains: u32,
elastic_depth: u32,
transform: F,
) -> Result<InTreeScheduleArtifact, HlsError>
where
F: FnOnce() -> HlsDataflowOp,
{
let dissolved = dissolve_dataflow_transform(fn_name, violations, transform)?;
let mut artifact = schedule_circt_handshake_lower_deepen(
&dissolved.fn_name,
dissolved.op,
channels,
clock_domains,
elastic_depth,
)?;
artifact.schedule_ir =
build_schedule_ir(&artifact.fn_name, &artifact.kind, &artifact.stages, true);
artifact.rtl_stub = format!(
"// FR96: dataflow transform dissolved before FR187 Handshake lower deepen schedule (AD-18)\n{}",
artifact.rtl_stub
);
Ok(artifact)
}
pub fn schedule_in_tree_from_transform<F>(
fn_name: &str,
violations: &[HlsDataflowClosureViolation],
kind: InTreeScheduleKind,
transform: F,
) -> Result<InTreeScheduleArtifact, HlsError>
where
F: FnOnce() -> HlsDataflowOp,
{
let dissolved = dissolve_dataflow_transform(fn_name, violations, transform)?;
let mut artifact = schedule_in_tree(&dissolved.fn_name, dissolved.op, kind)?;
artifact.schedule_ir =
build_schedule_ir(&artifact.fn_name, &artifact.kind, &artifact.stages, true);
artifact.rtl_stub = format!(
"// FR96: dataflow transform dissolved before in-tree schedule\n{}",
artifact.rtl_stub
);
Ok(artifact)
}
pub fn emit_in_tree_schedule(
artifact: &InTreeScheduleArtifact,
out_dir: &Path,
) -> Result<(PathBuf, PathBuf), HlsError> {
fs::create_dir_all(out_dir).map_err(|e| HlsError::Message(e.to_string()))?;
let sched_path = out_dir.join(format!("{}.schedule.json", artifact.fn_name));
let rtl_path = out_dir.join(format!("{}.v", artifact.fn_name));
fs::write(&sched_path, &artifact.schedule_ir).map_err(|e| HlsError::Message(e.to_string()))?;
fs::write(&rtl_path, &artifact.rtl_stub).map_err(|e| HlsError::Message(e.to_string()))?;
Ok((sched_path, rtl_path))
}
pub fn run_hls_in_tree(
fn_name: &str,
op: HlsDataflowOp,
kind: InTreeScheduleKind,
out_dir: &Path,
) -> Result<(PathBuf, PathBuf), HlsError> {
let artifact = schedule_in_tree(fn_name, op, kind)?;
emit_in_tree_schedule(&artifact, out_dir)
}
pub fn run_hls_in_tree_from_transform<F>(
fn_name: &str,
violations: &[HlsDataflowClosureViolation],
kind: InTreeScheduleKind,
transform: F,
out_dir: &Path,
) -> Result<(PathBuf, PathBuf), HlsError>
where
F: FnOnce() -> HlsDataflowOp,
{
let artifact = schedule_in_tree_from_transform(fn_name, violations, kind, transform)?;
emit_in_tree_schedule(&artifact, out_dir)
}
fn find_rtl_artifact(out_dir: &Path, fn_name: &str) -> Result<PathBuf, HlsError> {
let candidates = [
out_dir.join(format!("{fn_name}.v")),
out_dir.join(format!("{fn_name}.sv")),
out_dir.join("hls_output.v"),
];
for cand in &candidates {
if cand.is_file() {
return Ok(cand.clone());
}
}
if let Ok(rd) = fs::read_dir(out_dir) {
for ent in rd.flatten() {
let p = ent.path();
if let Some(ext) = p.extension().and_then(|e| e.to_str()) {
if matches!(ext, "v" | "sv") {
return Ok(p);
}
}
}
}
Err(HlsError::Message(format!(
"{HLS_BACKEND} finished but no synthesizable .v/.sv found under {}; \
check backend version (expected {HLS_BACKEND_VERSION}) and logs",
out_dir.display()
)))
}
fn which(name: &str) -> Option<PathBuf> {
let path = std::env::var_os("PATH")?;
for dir in std::env::split_paths(&path) {
let cand = dir.join(name);
if cand.is_file() {
return Some(cand);
}
}
None
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn in_tree_loop_unroll_without_bambu() {
let a = schedule_in_tree(
"demo",
HlsDataflowOp::AddConst(1),
InTreeScheduleKind::LoopUnroll { trip_count: 3 },
)
.unwrap();
assert_eq!(a.stages.len(), 3);
assert!(a.schedule_ir.contains("fr95"));
assert!(a.schedule_ir.contains("loop-unroll"));
assert!(a.rtl_stub.contains("in-tree-mvp"));
}
#[test]
fn missing_bambu_is_readable_error() {
let dir = std::env::temp_dir().join("bitloom_hls_stub_unit");
let p = emit_c_stub("add", &dir).unwrap();
let text = std::fs::read_to_string(p).unwrap();
assert!(text.contains("no scheduling in bitloom"));
assert!(!text.contains("schedule"));
assert!(text.contains(HLS_BACKEND_VERSION));
}
#[test]
fn emit_only_skips_backend() {
let dir = std::env::temp_dir().join("bitloom_hls_emit_only");
let p = run_hls("add", &dir, true).unwrap();
assert!(p.extension().and_then(|e| e.to_str()) == Some("c"));
}
#[test]
fn emit_stub_without_scheduling() {
let dir = std::env::temp_dir().join("bitloom_hls_stub");
let p = emit_c_stub("add", &dir).unwrap();
let text = std::fs::read_to_string(p).unwrap();
assert!(text.contains("no scheduling in bitloom"));
assert!(!text.contains("schedule"));
}
#[test]
fn dissolve_xor_has_no_fn_residue() {
let d =
dissolve_dataflow_transform("map_xor", &[], || HlsDataflowOp::XorConst(0xa5)).unwrap();
assert!(
d.c_source.contains("^ 165u") || d.c_source.contains("^ 0xa5"),
"c={}",
d.c_source
);
assert!(!d.c_source.contains("Fn"));
assert!(!d.c_source.contains("||"));
assert!(!d.c_source.to_lowercase().contains("closure"));
}
#[test]
fn capturing_violation_rejects_before_dissolve() {
let err = dissolve_dataflow_transform(
"bad",
&[HlsDataflowClosureViolation::capturing("holds &mut state")],
|| HlsDataflowOp::Identity,
)
.unwrap_err();
let msg = err.to_string();
assert!(msg.contains("CapturingOrStateful") || msg.contains("rejected"));
}
}