{"id":24005350,"url":"https://github.com/betrusted-io/gateware","last_synced_at":"2025-07-18T07:07:09.457Z","repository":{"id":43071262,"uuid":"243190844","full_name":"betrusted-io/gateware","owner":"betrusted-io","description":"IP submodules, formatted for easier CI integration","archived":false,"fork":false,"pushed_at":"2023-11-24T07:33:40.000Z","size":1834,"stargazers_count":29,"open_issues_count":2,"forks_count":5,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-06-05T11:06:29.956Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Verilog","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/betrusted-io.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","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":"2020-02-26T06:59:47.000Z","updated_at":"2024-12-06T10:43:28.000Z","dependencies_parsed_at":"2023-11-24T08:30:53.616Z","dependency_job_id":"c4892fa0-92c3-4d8b-93fe-6e8a14e66675","html_url":"https://github.com/betrusted-io/gateware","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/betrusted-io/gateware","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/betrusted-io%2Fgateware","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/betrusted-io%2Fgateware/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/betrusted-io%2Fgateware/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/betrusted-io%2Fgateware/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/betrusted-io","download_url":"https://codeload.github.com/betrusted-io/gateware/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/betrusted-io%2Fgateware/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265716306,"owners_count":23816354,"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":"2025-01-08T02:54:53.002Z","updated_at":"2025-07-18T07:07:09.437Z","avatar_url":"https://github.com/betrusted-io.png","language":"Verilog","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Gateware Modules\n\n## Structure and Prerequisites\n\nThese are RTL description files that are meant to be instantiated as submodules\nunder a BaseSoC class from Litex. They exist in a separate submodule directory\nto facilitate IP sharing between projects and to streamline CI integration.\n\nManaging Python paths is painful, because everyone has their way to do it. This\nproject is no exception.\n\nWe assume this gateware assumes a project structure modeled around the\nlxbuildenv methodology. Thus, we assume the gateware submodule is cloned\ninto the parent project's `deps` directory:\n\n `\u003cproject_root\u003e/deps/gateware`\n\nWithin this gateware repo, production hardware descriptions are contained\nin the gateware/ subdir: \n\n `\u003cproject_root\u003e/deps/gateware/gateware/\u003cmodule\u003e.py`\n\n Simulation testbenches in the sim/ subdir:\n \n `\u003cproject_root\u003e/deps/gateware/sim/\u003cmodule\u003e/dut.py`\n \nIt is recommended to create new simulation testbenches by using the\n`new_sim.py -s \u003cmodule\u003e` command in the `sim/` directory. This script manages\na couple of subtleties that ensure the Rust workspace framework built around\nthis simulation works correctly.\n\n## Environment \n\nIn order to run the `dut.py` script, we assume two items (or the latest equivalent) are in your path:\n\n - RISCV_TOOLS=/tools/riscv64-unknown-elf-gcc-8.3.0-2019.08.0-x86_64-linux-ubuntu14\n - VIVADO=/tools/Xilinx/Vivado/2019.2\n\nIf you don't have these installed, please refer to the README at\nhttps://github.com/betrusted-io/betrusted-soc for how to obtain and\ninstall these.\n\nWe also assume the presence of a stable Rust environment that targets \nthe riscv32-imac target, and that the svd2rust and form packages are installed:\n\n  - `curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh`\n  - `cargo install svd2rust`\n  - `cargo install form`\n  - `rustup target add riscv32imac-unknown-none-elf`\n\nsvd2rust and form are necessary to generate a peripheral access crate for each\ntest environment, which is a set of macros the test author can optionally\nuse to make the code a little bit safer/prettier.\n\nBuilds are tested on an x86_64 system running Ubuntu 18.04LTS. \n\n### Gateware\n\n\"Gateware\" is the Litex/migen term for stuff that gets compiled LUTS and\n routing within an FPGA bitstream. \n \n The code for gateware is located in the `gateware/` directory, and each\n .py file describes a migen `Module` that can be submoduled into a\n BaseSoC instance as a hardware peripheral. This methodology supports\n both CSR and/or wishbone attached modules.\n\n### Simulation\n\nThe test benches for a given gateware is located in a directory names as follows:\n\n `sim/\u003cgateware-root-name\u003e/`\n\nWhere if the python module is called \"zomg_mod.py\", then `\u003cgateware-root-name\u003e` is \"zomg_mod\".\n\nThere is a `sim_common` directory which contains several important properties that\nare inherited into every test bench. The idea is to put as much of the non-module specific\nintegration into `sim_common`. For example, the `csr_paging` parameter and memory\nmap are specified in `sim_common`, so if these parameters are changed in the target SoC\nall the module simulations can be regression-tested against these changes automatically.\n\nWithin the `\u003cgateware-root-name\u003e` subdirectory, the following artifacts are expected:\n\n - A file called `dut.py`. This is the script that builds the testbench, code, and runs the simulation itself.\n It inherits SoC properties from a `sim_bench.py` file.\n - A `top_tb.v` file which wires up the test bench. It is copied to the run/ directory before integrating\n   with the generated `top.v` file. Usually `top_tb.v` is pretty minimal for simple IP blocks.\n - A `test` directory which contains a Rust program. The test starts with the `run()` method. \n - Any other helper models that are required by the test bench\n\nThe test framework essentially does a minimal setup of the runtime environment and jumps to `run()`. \nThis happens within about 20us of simulation time (about 2k CPU cycles @ 100MHz, of which half \nis spent waiting for the PLL to lock).  \n\n### Rust notes\n\nDuring test development, you should be able to change into the `test` directory and build\nthe simulation code using `cargo build --release`. __NOTE__: this only works after\nyou've run the `dut.py` script once, as that script creates the `soc.svd` file and the `memory.x`\nfiles needed by the Rust build system.\n \n### CI\n\nFor CI, the strategy would then be to descend into every subdirectory of sim/ and\nrun script `dut.py -c`. The `-c` argument informs the script it should run with no GUI.\n\nThe test harness builds three signals on the top level that are mandatory:\n\n- done, a 1-bit signal that is set when the test should be terminated\n- success, a 1-bit signal that indicates the test passed when set\n- report, a 16-bit signal for extra reporting to CI\n\nThe simulator writes to a `ci.vcd` file in the `run/` directory. This is automatically\nparsed by the test bench to look for the `done` transition, and then based on the\nvalue of `success` at the rising edge of `done`, the script returns either 0 for\npass, or 1 for fail.\n\n# Methodology Notes\n\nThere are two goals of the testbenches in this repository:\n\n 1. Create a record of the tests performed to validate a given gateware IP block.\n 2. Ensure that this record is usable as dependencies change\n\nCI integration achieves goal #\u0026ZeroWidthSpace;2: we want to know when upstream\ndependencies (e.g. Litex) change and break our testbenches, so we\ndon't accrue huge technical debt on the test benches. The current\nproblem is that Litex is very actively developed and growing, and so\nit's subject to massive refactoring of core APIs that tend to break\neverything. This motivates splitting out the top_tb.v and code into\n\"stub\" files that allows for recursive search-and-replace strategies\nto fix changing paths or API names.\n\nGoal #\u0026ZeroWidthSpace;1 is achieved by the original designer, and baked into the\ntestbench.  The quality and depth of coverage for the IP is not baked\ninto this methodology. However, typically the test vectors originate\nfrom the simulated soft-core CPU, and the simulated CPU is responsible\nfor checking results and reporting errors. This is a bit faster and\nmore flexible than e.g. attempting to write verilog statements and\nasserts that try to catch every deviation. This methodology is\npreferred in part because in reality, if there is a refactor of the\nwishbone bus in the Litex directory that causes subtle changes in the\nbus timing that doesn't break the functionality of the IP, we are okay\nwith that. A verilog assert is thus a bit too aggressive and\nlow-level. Similarly, a verilog assert at the IP API level won't catch\nproblems like refactoring of the cache hierarchy in the CPU, which can\nbreak some IP cores in subtle ways. Thus, by driving the simulation\nprimarily from the standpoint of the CPU, we are saying \"so long as\nthe CPU gets the results it expects, we're probably OK, even if the\nexact bus timings and reset conditions shift around by a cycle or\ntwo because of upstream refactoring\".\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbetrusted-io%2Fgateware","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbetrusted-io%2Fgateware","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbetrusted-io%2Fgateware/lists"}