{"id":13773086,"url":"https://github.com/NVlabs/matchlib","last_synced_at":"2025-05-11T05:34:18.125Z","repository":{"id":34604726,"uuid":"176341843","full_name":"NVlabs/matchlib","owner":"NVlabs","description":"SystemC/C++ library of commonly-used hardware functions and components for HLS.","archived":false,"fork":false,"pushed_at":"2025-04-24T16:46:06.000Z","size":1731,"stargazers_count":266,"open_issues_count":2,"forks_count":43,"subscribers_count":34,"default_branch":"main","last_synced_at":"2025-04-24T17:46:45.394Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://nvlabs.github.io/matchlib/","language":"C++","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/NVlabs.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}},"created_at":"2019-03-18T17:59:52.000Z","updated_at":"2025-04-24T16:46:11.000Z","dependencies_parsed_at":"2024-01-15T09:04:42.054Z","dependency_job_id":"0e687503-b234-4f94-b219-27fe993fae2f","html_url":"https://github.com/NVlabs/matchlib","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NVlabs%2Fmatchlib","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NVlabs%2Fmatchlib/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NVlabs%2Fmatchlib/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NVlabs%2Fmatchlib/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/NVlabs","download_url":"https://codeload.github.com/NVlabs/matchlib/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253523690,"owners_count":21921815,"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-08-03T17:01:11.183Z","updated_at":"2025-05-11T05:34:17.760Z","avatar_url":"https://github.com/NVlabs.png","language":"C++","funding_links":[],"categories":["Circuit Compilers"],"sub_categories":[],"readme":"MatchLib\n========\n[![GitHub Pages](https://github.com/NVlabs/matchlib/actions/workflows/gh-pages.yml/badge.svg)](https://github.com/NVlabs/matchlib/actions/workflows/gh-pages.yml)\n\nMatchLib is a SystemC/C++ library of commonly-used hardware functions and components that can\nbe synthesized by most commercially-available HLS tools into RTL.\n\nDoxygen-generated documentation can be found [here](https://NVlabs.github.io/matchlib/).\n\nMatchLib is based on the Connections latency-insensitive channel implementation.\nConnections is included with the Catapult HLS tool and is available open-source on\n[HLSLibs](https://github.com/hlslibs/matchlib_connections).\nAdditional documentation on the Connections latency-insensitive channel implementation\ncan be found in the [Connections Guide](https://github.com/hlslibs/matchlib_connections/blob/master/pdfdocs/connections-guide.pdf).\n\n# Getting Started\n\n## Tool versions\n\nMatchLib is regressed against the following tool/dependency versions:\n\n* `gcc` - 10.3.0\n* `boost` - 1.68.0\n* `doxygen` - 1.8.11\n* `make` - 3.82\n* `binutils` - 2.34\n* `catapult` - 2024.1\\_1\n* `systemc` - 2.3.3 (included with Catapult)\n* `connections` - 2.1.1 (included with Catapult)\n* `vcs` - 2023.03\n* `verdi` - 2023.03\n* `python` - 3.6.1\n* `rapidjson` - 06d58b9 (included as submodule)\n\n## Environment requirements\n\nMakefiles assume the appropriate definition of the following environment variables:\n\n* `BOOST_HOME`\n* `CATAPULT_HOME`\n* `VCS_HOME`\n* `NOVAS_INST_DIR`\n\nIn addition, the boost and systemc library locations are expected to be in `LD_LIBRARY_PATH`.\n\n## Build and run\n\n### C++ compile and simulate\n    cd cmod/\u003cmodule\u003e\n    make\n    make run \n\n### C++ compile and simulate all\n    cd cmod\n    make -f regress_Makefile\n\n### HLS run and Verilog simulate\n    cd hls/\u003cmodule\u003e\n    make\n\n### HLS run and Verilog simulate all\n    cd hls\n    make -f regress_Makefile\n\n### Design Checker run\n    cd hls/\u003cmodule\u003e\n    make cdc\n\n### Design Checker run all\n    cd hls\n    make -f regress_Makefile RUN_CDESIGN_CHECKER=1\n\n# Directory structure\n\n* `cmod/include/*.h` contains header files for functions and classes from MatchLib\n* `cmod/\u003cmodule\u003e` sub-directories contain SystemC modules from MatchLib\n* `cmod/examples/\u003cmodule\u003e` sub-directories contain SystemC example modules\n* `cmod/unittests/\u003cmodule\u003e` sub-directories contain SystemC wrappers, testbenches and tests for various MatchLib functions, classes, and modules\n* `hls/\u003cmodule\u003e` sub-directories contain HLS scripts for modules\n* `doc` contains Makefiles for building Doxygen-based documentation\n\n# Preprocessor Macro Definitions\n\n* `HLS_CATAPULT` - Select if Catapult is selected as the HLS target. Catapult header files will not be included if not set. If enabled, `NVINT` is defined as `ac_int`. If disabled, `NVINT` is defined as `sc_int`. Currently MatchLib only supports Catapult, so `HLS_CATAPULT` must be set.\n* `HLS_ALGORITHMICC` - Set to enable AlgorithmicC-specific optimizations in the code.\n* `HLS_STRATUS` - Set to indicate that HLS is being performed with Stratus tool. This disables Catapult-specific flags and optimizations like the use of ac_types. This feature is not fully tested.\n* `SC_INCLUDE_DYNAMIC_PROCESSES` - Set to enable SystemC dynamic processes.\n* `__SYNTHESIS__` - Set by Catapult during the HLS flow (but not during sc_verify).\n* `_SYNTHESIS_` - Flag to set when calling the HLS tool during both HLS and sc_verify.\n* `SKIP_LV2TYPE` - Set to enable complex types to be stored as logic vectors in certain design-specific cases.\n* `COV_ENABLE` - Set to enable coverage collection with CTC.\n* `NVHLS_VERIFY_ISVCSMX` - Set for standalone VCS-MX co-simulations of SystemC with Catapult-generated RTL. Do not use in SystemC simulation or Catapult sc_verify.\n* `ENABLE_SYNC_RESET` - Enables synchronous, active-low reset instead of asynchronous, active-low reset in MatchLib.\n* `NVHLS_CONTINUE_ON_ASSERT` - Raise an `SC_ERROR` on assertion failures rather than exiting. Do not use during Catapult HLS, only during simulation.\n\nAdditional macros such as `AUTO_PORT`, `FORCE_AUTO_PORT`, `CONNECTIONS_ACCURATE_SIM`, `CONNECTIONS_FAST_SIM`, `CONNECTIONS_SIM_ONLY`, `CONN_RAND_STALL`, `CONN_RAND_STALL_PRINT_DEBUG`, `CONNECTIONS_ASSERT_ON_QUERY`, and `DISABLE_PACER` may be used in MatchLib. These macros are primarily defined, implemented, and documented in Connections. For more detail on these macros, see the [Connections documentation](https://github.com/hlslibs/matchlib_connections).\n\n# Command-line Simulation Settings\n\nMany of the flags above are design-specific, and so are typically codified into design Makefiles. However, some of the variables pertain to different simulation modes, and it is desirable to simulate the same design under different settings for different purposes. Accordingly, we provide the following command-line environment flags for use with the cmod or hls steps:\n\n* `SIM_MODE` - Set this variable to 1 (default) to use Connections sim-accurate mode, so that Connections ports and channels simulated in SystemC closely match the cycle-by-cycle behavior of their HLS-generated RTL counterparts. Set this variable to 2 to enable a TLM-based Connections mode that is faster to simulate but does not track the cycle behavior of HLS-generated RTL as closely. Set this variable to 0 to directly simulate the synthesized representation of Connections ports and channels (not recommended, as it may result in spurious failures).\n* `RAND_STALL` - Set this variable to 1 to enable random stalling on Connections ports and channels. Set to 0 (default) to disable random stalling.\n* `DEBUG_LEVEL` - Set to control the amount of debug information printed to the command line during execution. In general, higher debug levels will enable debug information from additional modules.\n* `NVHLS_RAND_SEED` - Set to a number to use as a fixed seed for nvhls_rand (defaults to 0).\n\nTo accurately simulate expected RTL performance, use the default settings. For robust verification, simulate with four different modes: both `SIM_MODE=1` and `SIM_MODE=2`, with random stalling both enabled and disabled and various random seeds.\n\n# Questions and Contributions\n\nWe welcome feedback and contributions from the open-source hardware community.\nIf you have a question or problem, please file an issue on GitHub.\nTo contribute bugfixes or new features, submit a pull request.\nFor business inquiries, please contact researchinquiries@nvidia.com.\nFor press and other inquiries, please contact Hector Marinez at hmarinez@nvidia.com.\n\n# Contributors\n\nMatchLib originated as a project of [NVIDIA Research](https://research.nvidia.com).\n\nContributors to the initial open-source release (alphabetical): Jason Clemons, Christopher Fletcher, Davide Giri, Ben Keller, Brucek Khailany, Alicia Klinefelter, Evgeni Krimer, Hyoukjun Kwon, Ziyun Li, Michael Pellauer, Nathaniel Pinckney, Antonio Puglielli, Sophia Shao, Shreesha Srinath, Gopalakrishnan Srinivasan, Christopher Torng, Rangharajan Venkatesan, Sam Xi\n\nPortions of MatchLib are derived from code in Mentor Graphics' Algorithmic C Datatypes v3.7.1 (also released under the Apache 2.0 license). See individual file headers for details.\n\nMatchLib's back annotation feature is dependent on RapidJSON released under the MIT License. \n\n# Attribution\n\nIf used for research, please cite the [DAC paper](https://research.nvidia.com/sites/default/files/pubs/2018-06_A-Modular-Digital//dac2018.submitted.pdf):\n\nBrucek Khailany, Evgeni Krimer, Rangharajan Venkatesan, Jason Clemons, Joel S. Emer, Matthew Fojtik, Alicia Klinefelter, Michael Pellauer, Nathaniel Pinckney, Yakun Sophia Shao, Shreesha Srinath, Christopher Torng, Sam (Likun) Xi, Yanqing Zhang, and Brian Zimmer, \"A modular digital VLSI flow for high-productivity SoC design,\" in _Proceedings of the ACM/IEEE Design Automation Conference_, June 2018.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FNVlabs%2Fmatchlib","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FNVlabs%2Fmatchlib","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FNVlabs%2Fmatchlib/lists"}