{"id":37227656,"url":"https://github.com/tom-johnsen/metalfpga","last_synced_at":"2026-01-15T03:23:08.074Z","repository":{"id":330770352,"uuid":"1121852784","full_name":"tom-johnsen/metalfpga","owner":"tom-johnsen","description":"GPU hardware simulation on Apple GPUs: Verilog‑2005 frontend and Metal (MSL) backend that elaborates designs and emits Metal kernels/host runtime + VCDs.","archived":false,"fork":false,"pushed_at":"2026-01-14T00:37:37.000Z","size":2663,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-14T04:22:13.302Z","etag":null,"topics":["apple-silicon","codegen","compiler","eda","gpu","hardware-simulation","hdl","macos","metal","metal-shading-language","msl","rtl","vcd","verilog","verilog-2005"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tom-johnsen.png","metadata":{"files":{"readme":"README.md","changelog":null,"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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-23T16:58:22.000Z","updated_at":"2026-01-14T00:36:28.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/tom-johnsen/metalfpga","commit_stats":null,"previous_names":["tom-johnsen/metalfpga"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/tom-johnsen/metalfpga","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tom-johnsen%2Fmetalfpga","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tom-johnsen%2Fmetalfpga/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tom-johnsen%2Fmetalfpga/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tom-johnsen%2Fmetalfpga/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tom-johnsen","download_url":"https://codeload.github.com/tom-johnsen/metalfpga/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tom-johnsen%2Fmetalfpga/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28442269,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-15T00:55:22.719Z","status":"online","status_checked_at":"2026-01-15T02:00:08.019Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["apple-silicon","codegen","compiler","eda","gpu","hardware-simulation","hdl","macos","metal","metal-shading-language","msl","rtl","vcd","verilog","verilog-2005"],"created_at":"2026-01-15T03:23:07.480Z","updated_at":"2026-01-15T03:23:08.065Z","avatar_url":"https://github.com/tom-johnsen.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# metalfpga\n\nmetalfpga is a Verilog-2005 frontend and Metal (MSL) backend for GPU-based\nhardware simulation on Apple GPUs. It parses and elaborates Verilog designs and\ncan emit Metal kernels and host-side scaffolding for execution.\n\n## Status\n\n- Frontend: Verilog-2005 parsing and elaboration complete; golden tests pass.\n- Backend/runtime: functional for a subset; not yet a full simulator.\n- VCD dumping works, including real signals.\n- Ongoing work: scheduling semantics, timing, and system task behavior.\n\nThis project is best used today for frontend validation and targeted runtime\nexperiments. Full testbench execution is still in progress.\n\n## Components\n\n- Verilog-2005 frontend: parser, elaborator, and netlist flattener.\n- Metal backend/runtime: MSL codegen, host scaffolding, and GPU scheduler.\n- 4-state logic library: X/Z support when `--4state` is enabled.\n- Real math library: high-accuracy real functions used by system tasks\n  (see `docs/GPGA_REAL_API.md`).\n- VCD writer with real signal support.\n\n## Requirements\n\n- macOS with Apple GPU and Metal support\n- CMake + C++17 toolchain\n\n## Build\n\n```sh\ncmake -S . -B build\ncmake --build build\n```\n\nOptional sanity check:\n\n```sh\n./build/metalfpga_smoke\n```\n\nBinaries:\n\n- `./build/metalfpga_cli` - main CLI\n- `./build/metalfpga_smoke` - quick sanity test\n- `./build/metalfpga_crlibm_compare` - real math accuracy tester\n\n## Run\n\n```sh\n# Check syntax and elaborate design\n./build/metalfpga_cli path/to/design.v\n\n# Dump flattened netlist\n./build/metalfpga_cli path/to/design.v --dump-flat\n\n# Emit flattened netlist to a file\n./build/metalfpga_cli path/to/design.v --emit-flat flat.txt\n\n# Emit Metal shader code\n./build/metalfpga_cli path/to/design.v --emit-msl output.metal\n\n# Emit host runtime stub\n./build/metalfpga_cli path/to/design.v --emit-host output.mm\n\n# Run on GPU (runtime support is partial)\n./build/metalfpga_cli path/to/design.v --run\n\n# Enable 4-state logic (X/Z support)\n./build/metalfpga_cli path/to/design.v --4state\n\n# VCD waveform output (requires --run)\n./build/metalfpga_cli path/to/design.v --run --vcd-dir ./waves/\n```\n\n## CLI options\n\n- `--emit-msl PATH` - write Metal shader source.\n- `--emit-host PATH` - write host-side runtime stub.\n- `--emit-flat PATH` - write flattened design.\n- `--dump-flat` - print flattened design.\n- `--top MODULE` - select top-level module.\n- `--4state` - enable 4-state logic (X/Z).\n- `--auto` - auto-discover `.v` files under the input directory.\n- `--strict-1364` - stricter IEEE-1364 parsing and semantics checks.\n- `--sdf PATH` - load SDF and match timing checks.\n- `--version` - print version and exit.\n- `--run` - execute on GPU (runtime support is partial).\n- `--count N` - number of kernel instances.\n- `--service-capacity N` - service record buffer capacity.\n- `--max-steps N` - max scheduler steps per dispatch.\n- `--max-proc-steps N` - max scheduler steps per process.\n- `--dispatch-timeout-ms N` - GPU dispatch timeout.\n- `--run-verbose` - verbose runtime logging.\n- `--source-bindings` - use source-level shader bindings.\n- `--vcd-dir PATH` - directory for VCD output.\n- `--vcd-steps N` - scheduler step interval between VCD samples.\n- `+ARG[=VALUE]` - plusargs for `$test$plusargs` and `$value$plusargs`.\n\n## CRLIBM options\n\nThe `metalfpga_crlibm_compare` tool compares the real math library against\nCRlibm on the CPU. Results are written to `artifacts/real_ulp/\u003ctag\u003e` by default.\n\n- `--func list|all` - function list (comma-separated) or `all`.\n- `--mode rn|rd|ru|rz|all` - rounding mode selection.\n- `--count N` - number of random vectors per function/mode.\n- `--seed N` - RNG seed.\n- `--out-dir PATH` - output directory for summary and artifacts.\n- `--trace` - emit per-vector `results.csv`.\n\nSee `docs/CRLIBM_ULP_COMPARE.md` for methodology and artifact layout.\n\n## Environment variables\n\n- `METALFPGA_STRING_PAD=zero|space` - string literal padding (default `zero`).\n- `METALFPGA_SPECIFY_DELAY_SELECT=fast|slow` - specify delay selection (default `fast`).\n- `METALFPGA_NEGATIVE_SETUP_MODE=allow|clamp|error` - negative setup handling (default `allow`).\n- `METALFPGA_SDF_VERBOSE=1` - log SDF match/mismatch details.\n\n## Documentation\n\n- Implementation-defined behavior decisions: `docs/IEEE_1364_2005_IMPLEMENTATION_DEFINED_BEHAVIORS.md`\n- VARY decisions: `docs/IEEE_1364_2005_VARY_DECISIONS.md`\n- Real math API: `docs/GPGA_REAL_API.md`\n- 4-state API: `docs/GPGA_4STATE_API.md`\n\n## License\n\nSee `LICENSE` and `LICENSE.COMMERCIAL`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftom-johnsen%2Fmetalfpga","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftom-johnsen%2Fmetalfpga","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftom-johnsen%2Fmetalfpga/lists"}