1pub use bitloom_builder::{
4 CombInline, Elaboratable, ElaborateSession, GeneratedInstance, HwCaptureKind, HwCaptureRef,
5 LegalEmptyClosure, LegalSimpleClosure, SeqInline, SeqOwnershipViolation,
6 SeqOwnershipViolationKind, SynthesizableClosure, SynthesizableClosureViolation,
7 SynthesizableClosureViolationKind, diagnose_seq_ownership_violations,
8 diagnose_synthesizable_closure_violations,
9};
10pub use bitloom_hir::{Diagnostics, FrozenHir, GroundType, PortDirection, PortValues, Span};
11pub use bitloom_macro::Bundle;
13
14pub mod ip;
16
17pub mod rhdl {
26 pub use bitloom_macro::{
27 abstraction, both, bridge, combinational, fsm, functional_model, hls, module, process,
28 sequential, top,
29 };
30}
31
32pub mod bitloom {
36 pub use bitloom_macro::{fsm, top};
37}
38
39pub trait FsmLabels {
44 const FSM_ID: &'static str;
46 fn state_labels() -> &'static [&'static str];
48}
49
50#[derive(Debug, Clone, Copy, PartialEq, Eq)]
52pub enum ViewKind {
53 FunctionalModel,
54 Bridge,
55 Abstraction,
56 Both,
57}
58
59pub trait HostView {
65 const KIND: ViewKind;
66}
67
68pub trait StartWaitComplete {
78 fn is_busy(&self) -> bool;
80
81 fn tick(&mut self);
83
84 fn start_wait_complete<F>(&mut self, start_fn: F)
89 where
90 F: FnOnce(&mut Self),
91 {
92 start_fn(self);
93 self.tick();
94 while self.is_busy() {
95 self.tick();
96 }
97 }
98}
99
100pub fn start_wait_complete<H, F>(
105 host: &mut H,
106 mut tick: impl FnMut(&mut H),
107 is_busy: impl Fn(&H) -> bool,
108 start_fn: F,
109) where
110 F: FnOnce(&mut H),
111{
112 start_fn(host);
113 tick(host);
114 while is_busy(host) {
115 tick(host);
116 }
117}
118
119#[derive(Debug, Clone, Copy)]
121pub struct HlsMark;
122
123#[derive(Debug, Clone, Copy, PartialEq, Eq)]
125pub enum ProcessKindMark {
126 Combinational,
127 Sequential,
128}
129
130#[derive(Debug, Clone, Copy, PartialEq, Eq)]
132pub enum PortDir {
133 Input,
134 Output,
135}
136
137pub trait PortField {
144 fn flatten(field: &str) -> Vec<(String, PortDir, GroundType)>;
146}
147
148#[derive(Debug, Clone, Copy, Default)]
150pub struct Bool;
151
152#[derive(Debug, Clone, Copy)]
153pub struct Bits<const N: u32>;
154
155#[derive(Debug, Clone, Copy)]
156pub struct UInt<const N: u32>;
157
158#[derive(Debug, Clone, Copy)]
159pub struct SInt<const N: u32>;
160
161#[derive(Debug, Clone, Copy, Default)]
162pub struct Clock;
163
164#[derive(Debug, Clone, Copy, Default)]
165pub struct Reset;
166
167#[derive(Debug, Clone, Copy, Default)]
169pub struct Input<T>(pub T);
170
171#[derive(Debug, Clone, Copy, Default)]
173pub struct Output<T>(pub T);
174
175pub trait Bundle {
196 fn leaves() -> &'static [(&'static str, GroundType)];
198
199 fn nested_bundles() -> &'static [(&'static str, fn() -> &'static [(&'static str, GroundType)])]
205 {
206 &[]
207 }
208}
209
210#[derive(Debug, Clone, Copy, Default)]
216pub struct HwVec<T, const N: u32>(pub core::marker::PhantomData<T>);
217
218#[derive(Debug, Clone, Copy, Default)]
232pub struct ClockDomain<const ID: u32>;
233
234#[derive(Debug, Clone, Copy, Default)]
251pub struct DoubleFlop;
252
253impl DoubleFlop {
254 pub const STAGES: u32 = 2;
256 pub const LATENCY_DST_TICKS: u32 = 2;
258}
259
260impl Elaboratable for DoubleFlop {
261 fn elaborate() -> Result<FrozenHir, Diagnostics> {
262 Self::elaborate_width(1)
263 }
264}
265
266impl DoubleFlop {
267 pub fn elaborate_width(width: u32) -> Result<FrozenHir, Diagnostics> {
269 let ty = GroundType::UInt { width };
270 let mut s = ElaborateSession::new("DoubleFlop");
271 s.begin_module("DoubleFlop", Span::default());
272 s.add_input("clk", GroundType::Clock, Span::default());
273 s.add_input("rst", GroundType::Reset, Span::default());
274 s.add_input("din", ty.clone(), Span::default());
275 s.add_output("dout", ty.clone(), Span::default());
276 s.bind_domain("din", 0);
278 s.bind_domain("dout", 1);
279 let (ff0, ff1) = s.declare_double_flop_stages("sync", ty, 1, Span::default());
280 s.begin_combinational(Span::default());
281 s.assign_net("dout", &ff1, Span::default());
282 s.end_process();
283 s.begin_sequential(Span::default());
284 s.connect_double_flop(&ff0, &ff1, "din", Span::default());
285 s.end_process();
286 s.end_module();
287 s.finish()
288 }
289}
290
291#[derive(Debug, Clone, Copy)]
305pub struct SyncFIFO<const DEPTH: u32, const WIDTH: u32>;
306
307impl<const DEPTH: u32, const WIDTH: u32> SyncFIFO<DEPTH, WIDTH> {
308 pub const DEPTH: u32 = DEPTH;
310 pub const WIDTH: u32 = WIDTH;
312 pub const PTR_WIDTH: u32 = {
314 match DEPTH {
315 4 => 3,
316 _ => 3, }
318 };
319 pub const LATENCY_PTR_SYNC_TICKS: u32 = DoubleFlop::LATENCY_DST_TICKS;
321 pub const LATENCY_REG_READ_TICKS: u32 = 1;
323}
324
325impl Elaboratable for SyncFIFO<4, 8> {
326 fn elaborate() -> Result<FrozenHir, Diagnostics> {
327 Self::elaborate_cdc()
328 }
329}
330
331impl SyncFIFO<4, 8> {
332 pub fn elaborate_cdc() -> Result<FrozenHir, Diagnostics> {
334 const DEPTH: u32 = 4;
335 const WIDTH: u32 = 8;
336 const PTR_W: u32 = 3;
337 let data_ty = GroundType::UInt { width: WIDTH };
338 let ptr_ty = GroundType::UInt { width: PTR_W };
339 let bit_ty = GroundType::UInt { width: 1 };
340
341 let mut s = ElaborateSession::new("SyncFIFO");
342 s.begin_module("SyncFIFO", Span::default());
343 s.add_input("clk", GroundType::Clock, Span::default());
344 s.add_input("rst", GroundType::Reset, Span::default());
345 s.add_input("wr_en", bit_ty.clone(), Span::default());
346 s.add_input("rd_en", bit_ty.clone(), Span::default());
347 s.add_input("data_in", data_ty.clone(), Span::default());
348 s.add_output("data_out", data_ty.clone(), Span::default());
349 s.add_output("full", bit_ty.clone(), Span::default());
350 s.add_output("empty", bit_ty.clone(), Span::default());
351
352 s.bind_domain("wr_en", 0);
354 s.bind_domain("data_in", 0);
355 s.bind_domain("full", 0);
356 s.bind_domain("rd_en", 1);
357 s.bind_domain("data_out", 1);
358 s.bind_domain("empty", 1);
359
360 s.declare_mem("ram", DEPTH, WIDTH, Span::default());
361 s.declare_reg("wr_ptr", ptr_ty.clone(), Span::default());
362 s.declare_reg("rd_ptr", ptr_ty.clone(), Span::default());
363 s.declare_reg("dout", data_ty, Span::default());
364 s.bind_domain("wr_ptr", 0);
365 s.bind_domain("rd_ptr", 1);
366 s.bind_domain("dout", 1);
367
368 let (w2r_ff0, w2r_ff1) =
370 s.declare_double_flop_stages("w2r", ptr_ty.clone(), 1, Span::default());
371 let (r2w_ff0, r2w_ff1) =
372 s.declare_double_flop_stages("r2w", ptr_ty.clone(), 0, Span::default());
373
374 s.declare_wire("c0_1", bit_ty.clone(), Span::default());
376 s.declare_wire("c1_1", bit_ty.clone(), Span::default());
377 s.declare_wire("c0_3", ptr_ty.clone(), Span::default());
378 s.declare_wire("c1_3", ptr_ty.clone(), Span::default());
379 s.declare_wire("c3_3", ptr_ty.clone(), Span::default());
380 s.declare_wire("c7_3", ptr_ty.clone(), Span::default());
381 s.declare_wire("wr_ptr_p1", ptr_ty.clone(), Span::default());
382 s.declare_wire("rd_ptr_p1", ptr_ty.clone(), Span::default());
383 s.declare_wire("wr_ptr_shr", ptr_ty.clone(), Span::default());
384 s.declare_wire("rd_ptr_shr", ptr_ty.clone(), Span::default());
385 s.declare_wire("wr_gray", ptr_ty.clone(), Span::default());
386 s.declare_wire("rd_gray", ptr_ty.clone(), Span::default());
387 s.declare_wire("wr_addr", ptr_ty.clone(), Span::default());
388 s.declare_wire("rd_addr", ptr_ty.clone(), Span::default());
389 s.declare_wire("rd_sync_shr", ptr_ty.clone(), Span::default());
390 s.declare_wire("rd_sync_hi_x", ptr_ty.clone(), Span::default());
391 s.declare_wire("rd_sync_hi", ptr_ty.clone(), Span::default());
392 s.declare_wire("rd_sync_hi_shl", ptr_ty.clone(), Span::default());
393 s.declare_wire("rd_sync_lo", ptr_ty.clone(), Span::default());
394 s.declare_wire("rd_fold", ptr_ty.clone(), Span::default());
395 s.declare_wire("can_wr", bit_ty.clone(), Span::default());
396 s.declare_wire("can_rd", bit_ty.clone(), Span::default());
397 s.declare_wire("next_wr", ptr_ty.clone(), Span::default());
398 s.declare_wire("next_rd", ptr_ty.clone(), Span::default());
399 s.declare_wire("not_full", bit_ty.clone(), Span::default());
400 s.declare_wire("not_empty", bit_ty, Span::default());
401
402 s.bind_domain("wr_gray", 0);
403 s.bind_domain("rd_fold", 0);
404 s.bind_domain("can_wr", 0);
405 s.bind_domain("next_wr", 0);
406 s.bind_domain("rd_gray", 1);
407 s.bind_domain("can_rd", 1);
408 s.bind_domain("next_rd", 1);
409 s.mark_cdc_bridge("wr_gray");
411 s.mark_cdc_bridge("rd_gray");
412
413 s.begin_combinational(Span::default());
414 s.assign_lit("c0_1", 0, Span::default());
415 s.assign_lit("c1_1", 1, Span::default());
416 s.assign_lit("c0_3", 0, Span::default());
417 s.assign_lit("c1_3", 1, Span::default());
418 s.assign_lit("c3_3", 3, Span::default());
419 s.assign_lit("c7_3", 7, Span::default());
420
421 s.assign_add("wr_ptr_p1", "wr_ptr", "c1_3", Span::default());
422 s.assign_add("rd_ptr_p1", "rd_ptr", "c1_3", Span::default());
423 s.assign_and("wr_addr", "wr_ptr", "c3_3", Span::default());
424 s.assign_and("rd_addr", "rd_ptr", "c3_3", Span::default());
425
426 s.assign_shr("wr_ptr_shr", "wr_ptr", "c1_3", Span::default());
428 s.assign_xor("wr_gray", "wr_ptr", "wr_ptr_shr", Span::default());
429 s.assign_shr("rd_ptr_shr", "rd_ptr", "c1_3", Span::default());
430 s.assign_xor("rd_gray", "rd_ptr", "rd_ptr_shr", Span::default());
431
432 s.assign_shr("rd_sync_shr", &r2w_ff1, "c1_3", Span::default());
435 s.assign_xor("rd_sync_hi_x", "rd_sync_shr", "c7_3", Span::default());
436 s.assign_and("rd_sync_hi", "rd_sync_hi_x", "c3_3", Span::default());
437 s.assign_shl("rd_sync_hi_shl", "rd_sync_hi", "c1_3", Span::default());
438 s.assign_and("rd_sync_lo", &r2w_ff1, "c1_3", Span::default());
439 s.assign_or("rd_fold", "rd_sync_hi_shl", "rd_sync_lo", Span::default());
440
441 s.assign_eq("full", "wr_gray", "rd_fold", Span::default());
442 s.assign_eq("empty", "rd_gray", &w2r_ff1, Span::default());
443 s.assign_mux("not_full", "full", "c0_1", "c1_1", Span::default());
445 s.assign_mux("not_empty", "empty", "c0_1", "c1_1", Span::default());
446 s.assign_and("can_wr", "wr_en", "not_full", Span::default());
447 s.assign_and("can_rd", "rd_en", "not_empty", Span::default());
448 s.assign_mux("next_wr", "can_wr", "wr_ptr_p1", "wr_ptr", Span::default());
449 s.assign_mux("next_rd", "can_rd", "rd_ptr_p1", "rd_ptr", Span::default());
450 s.assign_net("data_out", "dout", Span::default());
451 s.end_process();
452
453 s.begin_sequential(Span::default());
454 s.assign_mem_write_en("ram", "wr_addr", "data_in", "can_wr", Span::default());
455 s.assign_reg_d_mem_read("dout", "ram", "rd_addr", Span::default());
456 s.assign_reg_d_from("wr_ptr", "next_wr", Span::default());
457 s.assign_reg_d_from("rd_ptr", "next_rd", Span::default());
458 s.connect_double_flop(&w2r_ff0, &w2r_ff1, "wr_gray", Span::default());
459 s.connect_double_flop(&r2w_ff0, &r2w_ff1, "rd_gray", Span::default());
460 s.end_process();
461 s.end_module();
462 s.finish()
463 }
464}
465
466#[derive(Debug, Clone, Copy)]
468pub struct SyncReadMem<const DEPTH: u32, const WIDTH: u32>;
469
470#[derive(Debug, Clone, Copy)]
472pub struct Mem<const DEPTH: u32, const WIDTH: u32>;
473
474pub use bitloom_builder::{generate_mem_init_words as generate_mem_init, mask_mem_word};
493
494trait AsGround {
528 fn ground() -> GroundType;
529}
530
531impl AsGround for Bool {
532 fn ground() -> GroundType {
533 GroundType::Bool
534 }
535}
536
537impl AsGround for Clock {
538 fn ground() -> GroundType {
539 GroundType::Clock
540 }
541}
542
543impl AsGround for Reset {
544 fn ground() -> GroundType {
545 GroundType::Reset
546 }
547}
548
549impl<const N: u32> AsGround for Bits<N> {
550 fn ground() -> GroundType {
551 GroundType::UInt { width: N }
552 }
553}
554
555impl<const N: u32> AsGround for UInt<N> {
556 fn ground() -> GroundType {
557 GroundType::UInt { width: N }
558 }
559}
560
561impl<const N: u32> AsGround for SInt<N> {
562 fn ground() -> GroundType {
563 GroundType::SInt { width: N }
564 }
565}
566
567fn scalar_leaves(field: &str, dir: PortDir, gt: GroundType) -> Vec<(String, PortDir, GroundType)> {
568 vec![(field.to_string(), dir, gt)]
569}
570
571fn bundle_leaves<B: Bundle>(field: &str, dir: PortDir) -> Vec<(String, PortDir, GroundType)> {
572 let mut out: Vec<(String, PortDir, GroundType)> = B::leaves()
573 .iter()
574 .map(|(member, gt)| (format!("{field}_{member}"), dir, gt.clone()))
575 .collect();
576 for (nested, nested_leaves) in B::nested_bundles() {
577 for (leaf, gt) in nested_leaves() {
578 out.push((format!("{field}_{nested}_{leaf}"), dir, gt.clone()));
579 }
580 }
581 out
582}
583
584fn hwvec_leaves<T: AsGround, const N: u32>(
585 field: &str,
586 dir: PortDir,
587) -> Vec<(String, PortDir, GroundType)> {
588 const {
589 assert!(N > 0, "HwVec length must be non-zero");
590 }
591 (0..N)
592 .map(|i| (format!("{field}_{i}"), dir, T::ground()))
593 .collect()
594}
595
596macro_rules! impl_ground_port_field {
597 ($ty:ty) => {
598 impl PortField for Input<$ty> {
599 fn flatten(field: &str) -> Vec<(String, PortDir, GroundType)> {
600 scalar_leaves(field, PortDir::Input, <$ty as AsGround>::ground())
601 }
602 }
603 impl PortField for Output<$ty> {
604 fn flatten(field: &str) -> Vec<(String, PortDir, GroundType)> {
605 scalar_leaves(field, PortDir::Output, <$ty as AsGround>::ground())
606 }
607 }
608 };
609}
610
611impl_ground_port_field!(Bool);
612impl_ground_port_field!(Clock);
613impl_ground_port_field!(Reset);
614
615impl<const N: u32> PortField for Input<Bits<N>> {
616 fn flatten(field: &str) -> Vec<(String, PortDir, GroundType)> {
617 scalar_leaves(field, PortDir::Input, Bits::<N>::ground())
618 }
619}
620impl<const N: u32> PortField for Output<Bits<N>> {
621 fn flatten(field: &str) -> Vec<(String, PortDir, GroundType)> {
622 scalar_leaves(field, PortDir::Output, Bits::<N>::ground())
623 }
624}
625
626impl<const N: u32> PortField for Input<UInt<N>> {
627 fn flatten(field: &str) -> Vec<(String, PortDir, GroundType)> {
628 scalar_leaves(field, PortDir::Input, UInt::<N>::ground())
629 }
630}
631impl<const N: u32> PortField for Output<UInt<N>> {
632 fn flatten(field: &str) -> Vec<(String, PortDir, GroundType)> {
633 scalar_leaves(field, PortDir::Output, UInt::<N>::ground())
634 }
635}
636
637impl<const N: u32> PortField for Input<SInt<N>> {
638 fn flatten(field: &str) -> Vec<(String, PortDir, GroundType)> {
639 scalar_leaves(field, PortDir::Input, SInt::<N>::ground())
640 }
641}
642impl<const N: u32> PortField for Output<SInt<N>> {
643 fn flatten(field: &str) -> Vec<(String, PortDir, GroundType)> {
644 scalar_leaves(field, PortDir::Output, SInt::<N>::ground())
645 }
646}
647
648impl<T: Bundle> PortField for Input<T> {
649 fn flatten(field: &str) -> Vec<(String, PortDir, GroundType)> {
650 bundle_leaves::<T>(field, PortDir::Input)
651 }
652}
653impl<T: Bundle> PortField for Output<T> {
654 fn flatten(field: &str) -> Vec<(String, PortDir, GroundType)> {
655 bundle_leaves::<T>(field, PortDir::Output)
656 }
657}
658
659impl<T: AsGround, const N: u32> PortField for Input<HwVec<T, N>> {
660 fn flatten(field: &str) -> Vec<(String, PortDir, GroundType)> {
661 hwvec_leaves::<T, N>(field, PortDir::Input)
662 }
663}
664impl<T: AsGround, const N: u32> PortField for Output<HwVec<T, N>> {
665 fn flatten(field: &str) -> Vec<(String, PortDir, GroundType)> {
666 hwvec_leaves::<T, N>(field, PortDir::Output)
667 }
668}
669
670pub fn add_port_field<P: PortField>(session: &mut ElaborateSession, field: &str, span: Span) {
672 for (name, dir, gt) in P::flatten(field) {
673 match dir {
674 PortDir::Input => session.add_input(name, gt, span),
675 PortDir::Output => session.add_output(name, gt, span),
676 }
677 }
678}