rust_hdl/docs/
mod.rs

1use crate::docs::vcd2svg::vcd_to_svg;
2use embed_doc_image::embed_doc_image;
3
4///
5/// ## Blinky!
6///
7///The definitive example in FPGA firmware land is a simple LED blinker.  This typically
8///involves a clock that is fed to the FPGA with a pre-defined frequency, and an output
9///signal that can control an LED.  Because we don't know what FPGA we are using, we will
10///do this in simulation first.  We want a blink that is 250 msec long every second, and
11/// our clock speed is (a comically slow) 10kHz.  Here is a minimal working Blinky! example:
12///
13///```rust
14///use std::time::Duration;
15///use rust_hdl::core::prelude::*;
16///use rust_hdl::docs::vcd2svg::vcd_to_svg;
17///use rust_hdl::widgets::prelude::*;
18///
19///const CLOCK_SPEED_HZ : u64 = 10_000;
20///
21///
22///#[derive(LogicBlock)]
23///struct Blinky {
24///    pub clock: Signal<In, Clock>,
25///    pulser: Pulser,
26///    pub led: Signal<Out, Bit>,
27///}
28///
29///impl Default for Blinky {
30///   fn default() -> Self {
31///       Self {
32///         clock: Default::default(),
33///         pulser: Pulser::new(CLOCK_SPEED_HZ, 1.0, Duration::from_millis(250)),
34///         led: Default::default(),
35///       }
36///    }
37///}
38///
39///impl Logic for Blinky {
40///    #[hdl_gen]
41///    fn update(&mut self) {
42///       self.pulser.clock.next = self.clock.val();
43///       self.pulser.enable.next = true.into();
44///       self.led.next = self.pulser.pulse.val();
45///    }
46///}
47///
48///let mut sim = simple_sim!(Blinky, clock, CLOCK_SPEED_HZ, ep, {
49///    let mut x = ep.init()?;
50///    wait_clock_cycles!(ep, clock, x, 4*CLOCK_SPEED_HZ);
51///    ep.done(x)
52///});
53///
54///let mut uut = Blinky::default();
55///uut.connect_all();
56///sim.run_to_file(Box::new(uut), 5*SIMULATION_TIME_ONE_SECOND, "/tmp/blinky.vcd").unwrap();
57///vcd_to_svg("/tmp/blinky.vcd","images/blinky_all.svg",&["uut.clock", "uut.led"], 0, 4_000_000_000_000).unwrap();
58///vcd_to_svg("/tmp/blinky.vcd","images/blinky_pulse.svg",&["uut.clock", "uut.led"], 900_000_000_000, 1_500_000_000_000).unwrap();
59///```
60///Running the above (a release run is highly recommended) will generate a `vcd` file (which is
61/// a trace file for FPGAs and hardware in general).  You can open this using e.g., `gtkwave`.
62/// Here you will see (with some manipulation of the UI)
63///
64/// ![Full Simulation Time][full_sim_time]
65///
66/// And a zoom in shows the 250 msec pulse.
67///
68/// ![Pulse detail][pulse_detail]
69///
70#[embed_doc_image("full_sim_time", "images/blinky_all.svg")]
71#[embed_doc_image("pulse_detail", "images/blinky_pulse.svg")]
72pub struct BlinkyExample;
73pub mod vcd2svg;
rust_hdl/docs/mod.rs

rust_hdl/docs/
mod.rs
