{"id":14992194,"url":"https://github.com/samitbasu/rust-hdl","last_synced_at":"2025-09-25T14:30:59.952Z","repository":{"id":65967527,"uuid":"532137281","full_name":"samitbasu/rust-hdl","owner":"samitbasu","description":"A framework for writing FPGA firmware using the Rust Programming Language","archived":false,"fork":false,"pushed_at":"2025-01-09T15:21:32.000Z","size":7879,"stargazers_count":343,"open_issues_count":22,"forks_count":21,"subscribers_count":13,"default_branch":"main","last_synced_at":"2025-01-09T16:31:02.124Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/samitbasu.png","metadata":{"files":{"readme":"README.md","changelog":"changelog.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-09-03T02:47:27.000Z","updated_at":"2025-01-09T15:21:38.000Z","dependencies_parsed_at":"2025-01-09T16:30:11.520Z","dependency_job_id":"8c662733-f97c-42c6-994e-e749e59a1b3b","html_url":"https://github.com/samitbasu/rust-hdl","commit_stats":{"total_commits":665,"total_committers":7,"mean_commits":95.0,"dds":"0.24962406015037597","last_synced_commit":"4672ca271dac3aee771eed310d198f4f70c55631"},"previous_names":[],"tags_count":140,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/samitbasu%2Frust-hdl","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/samitbasu%2Frust-hdl/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/samitbasu%2Frust-hdl/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/samitbasu%2Frust-hdl/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/samitbasu","download_url":"https://codeload.github.com/samitbasu/rust-hdl/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":234200175,"owners_count":18795139,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-09-24T15:00:51.276Z","updated_at":"2025-09-25T14:30:58.923Z","avatar_url":"https://github.com/samitbasu.png","language":"Rust","funding_links":[],"categories":["Hardware Description Language","Rust","Frameworks"],"sub_categories":[],"readme":"# RustHDL\n\n** Redirect in Progress **\n\nDue to the concerns about having a project with \"rust\" in the name, I'm\nchanging this project name to `rhdl`, and moving active development there.\nSorry for the trouble, but I'd hate to have the project yanked at some\npoint in the future for something so silly.  \n\nI am also in the process of rebuilding this project from scratch to be\nsignificantly faster and more powerful.  So I will do the new development\nin the `rhdl` crate/repo, and migrate the existing widgets over time.\nAt that point, I will archive this repo.\n\n** New docs launched!  Check them out at https://rust-hdl.org... **\n\n** Write FPGA Firmware using Rust! **\n\n\nRustHDL is a crate that allows you to write FPGA firmware using Rust!\nSpecifically, `rust-hdl` compiles a subset of Rust down to Verilog so that\nyou can synthesize firmware for your FPGA using standard tools.  It also\nprovides tools for simulation, verification, and analysis along with strongly\ntyped interfaces for making sure your design works before heading to the bench.\nThe workflow is very similar to GPU programming.  You write everything in Rust,\nincluding an update `kernel` that compiles down onto the hardware.  You can simulate\nand verify everything from the safety and comfort of your Rust environment, and\nthen head over to standard synthesis tools to get files that program your FPGA.\n\n### Links\n\nYou may want:\n\n- [API Documentation](https://docs.rs/rust-hdl/latest/rust_hdl/)\n- [GitHub](https://github.com/samitbasu/rust-hdl)\n- [Home Page](https://rust-hdl.org)\n\n### Features\n* Safe - have Rust check the validity of your firmware with\nstrongly typed interfaces at **compile** time, as well as at\nrun time, synthesis, and on the device.\n* Fast - Run simulations of your designs straight from your\nRust code, with pretty good simulation performance.\n* Readable - RustHDL outputs Verilog code for synthesis and\nimplementation, and goes through some effort to make sure that\ncode is readable and understandable, in case you need to resolve\ntiming issues or other conflicts.\n* Reusable - RustHDL supports templated firmware for parametric\nuse, as well as a simple composition model based on structs.\n* Batteries Included - RustHDL includes a set of basic firmware\nwidgets that provide FIFOs, RAMs and ROMs, Flip flops, SPI components,\nPWMs etc, so you can get started quickly.\n* Free - Although you can use RustHDL to wrap existing IP cores,\nall of the RustHDL code and firmware is open source and free to use (as in speech and beer).\n* Tested - RustHDL has been used to write firmware that is shipping in commercial products.\nThis includes quite complicated designs that use nearly all of a moderately sized FPGA,\nand take advantage of specialized hardware in the FPGAs themselves.\n\n### Quickstart\n\nThe definitive example in FPGA firmware land is a simple LED blinker.  This typically\ninvolves a clock that is fed to the FPGA with a pre-defined frequency, and an output\nsignal that can control an LED.  Because we don't know what FPGA we are using, we will\ndo this in simulation first.  We want a blink that is 250 msec long every second, and\nour clock speed is (a comically slow) 10kHz.  Here is a minimal working Blinky! example:\n\n```rust\nuse std::time::Duration;\nuse rust_hdl::prelude::*;\nuse rust_hdl::docs::vcd2svg::vcd_to_svg;\n\nconst CLOCK_SPEED_HZ : u64 = 10_000;\n\n#[derive(LogicBlock)]  // \u003c- This turns the struct into something you can simulate/synthesize\nstruct Blinky {\n    pub clock: Signal\u003cIn, Clock\u003e, // \u003c- input signal, type is clock\n    pulser: Pulser,               // \u003c- sub-circuit, a widget that generates pulses\n    pub led: Signal\u003cOut, Bit\u003e,    // \u003c- output signal, type is single bit\n}\n\nimpl Default for Blinky {\n   fn default() -\u003e Self {\n       Self {\n         clock: Default::default(),\n         pulser: Pulser::new(CLOCK_SPEED_HZ, 1.0, Duration::from_millis(250)),\n         led: Default::default(),\n       }\n    }\n}\n\nimpl Logic for Blinky {\n    #[hdl_gen] // \u003c- this turns the update function into an HDL Kernel that can be turned into Verilog\n    fn update(\u0026mut self) {\n       // v-- write to the .next member     v-- read from .val() method\n       self.pulser.clock.next = self.clock.val();\n       self.pulser.enable.next = true.into();\n       self.led.next = self.pulser.pulse.val();\n    }\n}\n\nfn main() {\n    // v--- build a simple simulation (1 testbench, single clock)\n    let mut sim = simple_sim!(Blinky, clock, CLOCK_SPEED_HZ, ep, {\n        let mut x = ep.init()?;\n        wait_clock_cycles!(ep, clock, x, 4*CLOCK_SPEED_HZ);\n        ep.done(x)\n    });\n\n    // v--- construct the circuit\n    let mut uut = Blinky::default();\n    uut.connect_all();\n    sim.run_to_file(Box::new(uut), 5 * SIMULATION_TIME_ONE_SECOND, \"blinky.vcd\").unwrap();\n    vcd_to_svg(\"/tmp/blinky.vcd\",\"images/blinky_all.svg\",\u0026[\"uut.clock\", \"uut.led\"], 0, 4_000_000_000_000).unwrap();\n    vcd_to_svg(\"/tmp/blinky.vcd\",\"images/blinky_pulse.svg\",\u0026[\"uut.clock\", \"uut.led\"], 900_000_000_000, 1_500_000_000_000).unwrap();\n}\n```\n\nRunning the above (a release run is highly recommended) will generate a `vcd` file (which is\na trace file for FPGAs and hardware in general).  You can open this using e.g., `gtkwave`.\nIf you have, for example, an Alchitry Cu board you can generate a bitstream for this exampling\nwith a single call.  It's a little more involved, so we will cover that in the detailed\ndocumentation.  It will also render that `vcd` file into an `svg` you can view with an ordinary\nweb browser.  This is the end result showing the entire simulation:\n![blinky_all](https://github.com/samitbasu/rust-hdl/raw/main/rust-hdl/images/blinky_all.svg)\nHere is a zoom in showing the pulse to the LED\n![blinky_pulse](https://github.com/samitbasu/rust-hdl/raw/main/rust-hdl/images/blinky_pulse.svg)\n\nThe flow behind RustHDL is the following:\n\n- Circuits are modelled using simple `struct`s, composed of other circuit elements and\nsignal wires that interconnect them.\n- A `#[derive(LogicBlock)]` annotation on the struct adds autogenerated code needed by\nRustHDL.\n- You `impl Logic` on your `struct`, and provide the `fn update(\u0026mut self)` method, which\nis the HDL update kernel.\n- That gets annotated with a `#[hdl_gen]` attribute to generate HDL from the Rust code\n- You can then simulate and synthesize your design - either in software, or by using an\nappropriate BSP and toolchain.\n\nThe rest is detail.  Some final things to keep in mind.\n\n- RustHDL is a strict subset of Rust.  The `rustc` compiler must be satisfied with your\ndesign first.  That means types, exhaustive enum matching, etc.\n- The goal is to eliminate a class of mistakes that are easy to make in other HDLs with\nchecks taking place at compile time, via static analysis at run time, and then with\ntestbenches.\n- Although the performance can always be improved, RustHDL is pretty fast, especially in\nrelease mode.\n\n\nLicense: MIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsamitbasu%2Frust-hdl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsamitbasu%2Frust-hdl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsamitbasu%2Frust-hdl/lists"}