{"id":43053579,"url":"https://github.com/scottshuynh/hdlworkflow","last_synced_at":"2026-01-31T11:03:16.418Z","repository":{"id":289096457,"uuid":"969470951","full_name":"scottshuynh/hdlworkflow","owner":"scottshuynh","description":"Seamless FPGA workflows. ","archived":false,"fork":false,"pushed_at":"2026-01-26T09:23:22.000Z","size":112,"stargazers_count":1,"open_issues_count":0,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-01-26T22:40:42.523Z","etag":null,"topics":["cli","fpga","hdl","simulation","synthesis","vhdl","workflow"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/scottshuynh.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-04-20T08:10:52.000Z","updated_at":"2026-01-11T11:05:23.000Z","dependencies_parsed_at":"2025-05-18T05:41:32.863Z","dependency_job_id":"67b601c7-0bcf-4cc0-85d6-55bfcae77578","html_url":"https://github.com/scottshuynh/hdlworkflow","commit_stats":null,"previous_names":["scottshuynh/hdlworkflow"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/scottshuynh/hdlworkflow","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scottshuynh%2Fhdlworkflow","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scottshuynh%2Fhdlworkflow/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scottshuynh%2Fhdlworkflow/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scottshuynh%2Fhdlworkflow/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/scottshuynh","download_url":"https://codeload.github.com/scottshuynh/hdlworkflow/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scottshuynh%2Fhdlworkflow/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28939508,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-31T10:18:23.202Z","status":"ssl_error","status_checked_at":"2026-01-31T10:18:22.693Z","response_time":128,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["cli","fpga","hdl","simulation","synthesis","vhdl","workflow"],"created_at":"2026-01-31T11:03:15.425Z","updated_at":"2026-01-31T11:03:16.412Z","avatar_url":"https://github.com/scottshuynh.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n[![Python](https://img.shields.io/badge/Python-3.10%2B-blue)](https://www.python.org/)\n[![Regression Tests](https://github.com/scottshuynh/hdlworkflow/actions/workflows/regression-tests.yml/badge.svg)](https://github.com/scottshuynh/hdlworkflow/actions/workflows/regression-tests.yml)\n[![PyPI downloads](https://img.shields.io/pypi/dm/hdlworkflow?label=PyPI%20downloads)](https://pypi.org/p/hdlworkflow)\n# hdlworkflow\nSeamless FPGA workflows.\n\nAll HDL simulators follow the same process (analyse, elaborate and simulate) though each uses its own variation of these commands.\n\nSimilarly, all HDL synthesis tools follow the same flow (synthesise, place and route, and generate bitstream).\n\n`hdlworkflow` abstracts away these tool-specific commands, making project setup and usage fast and effortless.\n\n## Supported operating systems\n`hdlworkflow` can be used on Linux and Windows systems.\n\n## Supported tools\n+ [nvc](https://github.com/nickg/nvc)\n+ [Riviera-PRO](https://www.aldec.com/en/products/functional_verification/riviera-pro)\n+ [Vivado](https://www.amd.com/en/products/software/adaptive-socs-and-fpgas/vivado.html)\n\n## Supported waveform viewers\n+ [gtkwave](https://github.com/gtkwave/gtkwave)\n+ [surfer](https://surfer-project.org/)\n\n## Simulation compatibility table\nThe table below shows supported simulators and their compatibility with tools listed in the left-most column.\n\n|           | nvc                   | Riviera-PRO        | Vivado |  \n| ---       | :---:                 | :---:              | :---:  |\n| cocotb    | :white_check_mark:    | :white_check_mark: | :x:    |\n| gtkwave   | :white_check_mark:    | :x:                | :x:    |\n| surfer    | :white_check_mark:    | :x:                | :x:    |\n\n## Install\n`hdlworkflow` is a Python package and can be installed using pip:\n```sh\npip install hdlworkflow\n```\n\nIf you want to install the development version of `hdlworkflow`:\n```sh\npip install git+https://github.com/scottshuynh/hdlworkflow@main\n```\n\n## How to run\n`hdlworkflow` can be run from the command line and requires the following arguments:\n+ EDA tool of choice.\n+ Entity name of top level design.\n+ Path to a file listing all required source files for the top level design (i.e. compile order file).\n\nA directory with the name of the chosen EDA tool will be created in the directory `hdlworkflow` is run. This directory will contain all output artefacts produced by the EDA tool.\n\nSome examples of `hdlworkflow` usage can be found below.\n\n\u003e [!NOTE]\n\u003e By default, all HDL will be compiled into the *work* library.\n\n## Compile order file format\n`hdlworkflow` supports two file formats for compile order: plain text (.txt) and JSON (.json).\n\n### Plain Text\nAn ordered list of path to files required for a simulation or synthesis.\n\n### JSON\nThe JSON file follows the following specification:\n```\ncompile_order.json\n- files: array of objects. Ordered based on compile order.\n    Each object has:\n        - path: string (required). Path to file.\n        - library: string (optional). Library to be compiled into.\n        - type: string (optional). \"vhdl\" or \"verilog\".\n```\n\n---\n### nvc\nSimulate a top level design named `design_tb` using the `nvc` HDL simulator. All files required to simulate `design_tb` are listed as *absolute* paths line by line in `compile_order.txt`:\n```sh\nhdlworkflow nvc design_tb compile_order.txt\n```\n\nIf `design_tb` requires `DATA_WIDTH` and `ADDR_WIDTH` generic declared:\n```sh\nhdlworkflow nvc design_tb compile_order.txt -g DATA_WIDTH=8 -g ADDR_WIDTH=4\n```\n\nIf stopping the simulation after 42 us is required:\n```sh\nhdlworkflow nvc design_tb compile_order.txt --stop-time 42 us\n```\n\nIf the default library is called `my_lib`:\n```sh\nhdlworkflow nvc design_tb compile_order.txt --work my_lib\n```\n\nIf a waveform viewer, gtkwave, is required:\n```sh\nhdlworkflow nvc design_tb compile_order.txt --gui --wave gtkwave\n```\n\u003e [!NOTE]\n\u003e A new waveform view file will be generated automatically, overwriting any previously generated file.\n\nIf gtkwave is required with an existing waveform view file:\n```sh\nhdlworkflow nvc design_tb compile_order.txt --gui --wave gtkwave --waveform-view-file path/to/waveform_view_file.gtkw\n```\n\nIf a waveform viewer, surfer, is required:\n```sh\nhdlworkflow nvc design_tb compile_order.txt --gui --wave surfer\n```\n\u003e [!NOTE]\n\u003e A new waveform view file will be generated automatically, overwriting any previously generated file.\n\nIf surfer is required with an existing waveform view file:\n```sh\nhdlworkflow nvc design_tb compile_order.txt --gui --wave gtkwave --waveform-view-file path/to/waveform_view_file.ron\n```\n\nIf the testbench `design_tb` is a cocotb test module, and the top level design is called `design`:\n```sh\nhdlworkflow nvc design compile_order.txt --cocotb design_tb\n```\n\nCocotb test modules will be discovered in the same directory that `hdlworkflow` is run.\nAdding to `PYTHONPATH` environment variable is also supported:\n```sh\nhdlworkflow nvc design compile_order.txt --cocotb design_tb --pythonpath /abs/path/to/python/module --pythonpath relative/path/to/python/module\n```\n\n---\n### Riviera-PRO\nSimulate a top level design named `design_tb` using the `riviera` HDL simulator. All files required to simulate `design_tb` are listed as *absolute* paths line by line in `compile_order.txt`:\n```sh\nhdlworkflow riviera design_tb compile_order.txt\n```\n\nIf `design_tb` requires `DATA_WIDTH` and `ADDR_WIDTH` generic declared:\n```sh\nhdlworkflow riviera design_tb compile_order.txt -g DATA_WIDTH=8 -g ADDR_WIDTH=4\n```\n\nIf stopping the simulation after 42 us is required:\n```sh\nhdlworkflow riviera design_tb compile_order.txt --stop-time 42 us\n```\n\nIf the default library is called `my_lib`:\n```sh\nhdlworkflow riviera design_tb compile_order.txt --work my_lib\n```\n\nIf Vivado specific libraries (XPM and UNISIM) need to be searched to elaborate `design_tb`:\n```sh\nhdlworkflow riviera design_tb compile_order.txt -l xpm -l unisim\n```\n\u003e [!NOTE]\n\u003e Requires user to follow steps to [install pre-compiled vendor libraries for Riviera-PRO](https://www.aldec.com/en/support/resources/documentation/articles/1105) and mapping those libraries as global.\n\nIf a GUI is required to view waveforms:\n```sh\nhdlworkflow riviera design_tb compile_order.txt --gui\n```\n\u003e [!NOTE]\n\u003e A new waveform view file will be generated automatically, overwriting any previously generated file.\n\nIf a GUI is required with an existing waveform view file:\n```sh\nhdlworkflow riviera design_tb compile_order.txt --gui --waveform-view-file path/to/waveform_view_file.awc\n```\n\nIf the testbench `design_tb` is a cocotb test module, and the top level design is called `design`:\n```sh\nhdlworkflow riviera design compile_order.txt --cocotb design_tb\n```\n\nCocotb test modules will be discovered in the same directory that `hdlworkflow` is run.\nAdding to `PYTHONPATH` is also supported:\n```sh\nhdlworkflow riviera design compile_order.txt --cocotb design_tb --pythonpath /abs/path/to/python/module --pythonpath relative/path/to/python/module\n```\n\nIf the path to libstdc++ is required to resolve [GLIBCXX_3.4.XX not found](https://docs.cocotb.org/en/development/troubleshooting.html#glibcxx-3-4-xx-not-found):\n```sh\nhdlworkflow riviera design compile_order.txt --cocotb design_tb --libstdcpp /abs/path/to/libstdc++.so.6\n```\n\nIf the path to glbl.v is required to resolve [Unresolved hierarchical reference to\"glbl.GSR\"](https://www.aldec.com/en/support/resources/documentation/faq/1172):\n```sh\nhdlworkflow riviera design_tb compile_order.txt --glbl /abs/path/to/glbl.v\n```\n\n---\n### Vivado\nSimulate a top design named `design_tb` using `Vivado`. All files required to simulate `design_tb` are listed as *absolute* paths line by line in `compile_order.txt`:\n```sh\nhdlworkflow vivado design_tb compile_order.txt\n```\n\nIf `design_tb` requires `DATA_WIDTH` and `ADDR_WIDTH` generic declared:\n```sh\nhdlworkflow vivado design_tb compile_order.txt -g DATA_WIDTH=8 -g ADDR_WIDTH=4\n```\n\nIf stopping the simulation after 42 us is required:\n```sh\nhdlworkflow vivado design_tb compile_order.txt --stop-time 42 us\n```\n\nIf the default library is called `my_lib`:\n```sh\nhdlworkflow vivado design_tb compile_order.txt --work my_lib\n```\n\nIf a GUI is required to view waveforms:\n```sh\nhdlworkflow vivado design_tb compile_order.txt --gui\n```\n\u003e [!NOTE]\n\u003e A new waveform view file will be generated automatically, overwriting any previously generated file.\n\nIf a GUI is required with an existing waveform configuration file:\n```sh\nhdlworkflow vivado design_tb compile_order.txt --gui --waveform-view-file path/to/waveform_view_file.wcfg\n```\n\nIf synthesis of `design` is required instead of simulating:\n```sh\nhdlworkflow vivado design compile_order.txt --synth\n```\n\nIf synthesis + implementation of `design` is required instead of simulating:\n```sh\nhdlworkflow vivado design compile_order.txt --impl\n```\n\nIf synthesis + implementation + generate bitstream of `design` is required instead of simulating:\n```sh\nhdlworkflow vivado design compile_order.txt --bitstream\n```\n\nIf an out-of-context (OOC) synthesis of `design` is required instead of simulating:\n```sh\nhdlworkflow vivado design compile_order.txt --synth --ooc\n```\n\nIf an OOC synthesis + implementation of `design` is required instead of simulating:\n```sh\nhdlworkflow vivado design compile_order.txt --impl --ooc\n```\n\nAdditionally, if a clock period constraints on clock port `clk_a` for OOC synthesis + implementation is required:\n```sh\nhdlworkflow vivado design compile_order.txt --impl --ooc --clk-period-constraint clk_a=10 --clk-period-constraint clk_b=2.000\n```\n\nAdditionally, if the part number `xczu7ev-ffvc1156-2-e` for OOC synthesis + implementation is required:\n```sh\nhdlworkflow vivado design compile_order.txt --impl --ooc --clk-period-constraint clk_a=10 --clk-period-constraint clk_b=2.000 --part xczu7ev-ffvc1156-2-e\n```\n\nAdditionally, if the board part (`ZCU106`) for OOC synthesis + implementation is required:\n```sh\nhdlworkflow vivado design compile_order.txt --impl --ooc --clk-period-constraint clk_a=10 --clk-period-constraint clk_b=2.000 --part xczu7ev-ffvc1156-2-e --board xilinx.com:zcu106:part0:2.6  \n```\n\u003e [!NOTE]\n\u003e + `hdlworkflow` will configure `Vivado` with [Artix-7](https://www.amd.com/en/products/adaptive-socs-and-fpgas/fpga/artix-7.html) `xc7a35ticsg324-1L` as the default part number. Use `--part` and/or `--board` arguments to specify target hardware.\n\u003e + When running synthesis, the compile order file should contain all requisite files used to synthesise the design: a list of ordered source files, vendor-specific files and constraint files.\n\u003e + When running synthesis, `Vivado` will default to use eight logical cores or half of the number of available logical cores, whichever is smaller.\n\n---\n### Positional Arguments\n#### `eda_tool`\nEDA tool to run.\n\n#### `top`\nEntity name of top design file.\n\n#### `path_to_compile_order`\nPath to a file containing a list of all requisite files for the top design. See [file formats](#compile-order-file-format).\n\n### Options\n#### `--gui`\n(Optional) Opens the EDA tool GUI, if supported.\n\n#### `--wave WAVEFORM_VIEWER`\n(Optional) Waveform viewer to run for simulators that do not have native waveform viewers. Defaults to \"gtkwave\".\n\n#### `--waveform-view-file WAVEFORM_VIEW_FILE`\n(Optional) Waveform view file path.\n\n#### `-g GENERIC=VALUE, --generic GENERIC=VALUE`\n(Optional) Generics used to elaborate top design file.\n\n#### `-l LIBRARY_NAME, --libraries LIBRARY_NAME`\n(Optional) Libraries searched during top level design instantiation in simulation.\n\n#### `--stop-time INTEGER_PERIOD TIME_UNITS`\n(Optional) Simulation stops after the specified period.\n\n#### `-v VERBOSE_LEVEL, --verbose VERBOSE_LEVEL`\n(Optional) Logging verbosity. Valid values for `VERBOSE_LEVEL` are 0, 1, 2.\n\n#### `--cocotb COCOTB_MODULE`\n(Optional) Cocotb test module to run during simulation.\n\n#### `--pythonpath PYTHONPATH`\n(Optional) Path to append to `PYTHONPATH` environment variable. Used in cocotb simulations.\n\n#### `--libstdcpp LIBSTDC++`\n(Optional) Path to libstdc++ shared object. Used in cocotb simulations to resolve [GLIBCXX_3.4.XX not found](https://docs.cocotb.org/en/development/troubleshooting.html#glibcxx-3-4-xx-not-found).\n\n#### `--glbl GLBL.V`\n(Optional) Path to glbl.v. Used in simulations that use Xilinx XPM library. Resolves [Unresolved hierarchical reference to\"glbl.GSR\"](https://www.aldec.com/en/support/resources/documentation/faq/1172).\n\n#### `--work DEFAULT_LIB`\n(Optional) Name of the default library.\n\n#### `--part PART`\n(Optional) Part number used to set up `Vivado` project. Only used in `Vivado` workflow.\n\n#### `--board BOARD`\n(Optional) Board part used to set up `Vivado` project. Only used in `Vivado` workflow.\n\n#### `--synth`\n(Optional) `Vivado` will run synthesis instead of simulation. Only used in `Vivado` workflow.\n\n#### `--impl`\n(Optional) `Vivado` will run synthesis + implementation instead of simulation. Only used in `Vivado` workflow.\n\n#### `--bitfile`\n(Optional) `Vivado` will run synthesis + implementation + generate bitstream instead of simulation. Only used in `Vivado` workflow.\n\n#### `--ooc`\n(Optional) `Vivado` will set synthesis mode to out-of-context. Only used in `Vivado` workflow.\n\n#### `--clk-period-constraint CLK_PORT=PERIOD_NS`\n(Optional) Clock period constraint for `Vivado` project. Only used in `Vivado` workflow.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fscottshuynh%2Fhdlworkflow","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fscottshuynh%2Fhdlworkflow","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fscottshuynh%2Fhdlworkflow/lists"}