{"id":13648884,"url":"https://github.com/ovh/sv2chisel","last_synced_at":"2025-04-08T00:31:51.516Z","repository":{"id":143177753,"uuid":"290429387","full_name":"ovh/sv2chisel","owner":"ovh","description":"(System)Verilog to Chisel translator","archived":false,"fork":false,"pushed_at":"2022-05-20T15:28:08.000Z","size":504,"stargazers_count":112,"open_issues_count":4,"forks_count":10,"subscribers_count":17,"default_branch":"master","last_synced_at":"2025-03-23T03:11:24.817Z","etag":null,"topics":["chisel","eda","transpiler","verilog"],"latest_commit_sha":null,"homepage":"","language":"Scala","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ovh.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","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":"AUTHORS"}},"created_at":"2020-08-26T07:39:52.000Z","updated_at":"2025-03-20T11:14:21.000Z","dependencies_parsed_at":"2024-01-14T11:09:52.112Z","dependency_job_id":null,"html_url":"https://github.com/ovh/sv2chisel","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ovh%2Fsv2chisel","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ovh%2Fsv2chisel/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ovh%2Fsv2chisel/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ovh%2Fsv2chisel/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ovh","download_url":"https://codeload.github.com/ovh/sv2chisel/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247755388,"owners_count":20990616,"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":["chisel","eda","transpiler","verilog"],"created_at":"2024-08-02T01:04:37.481Z","updated_at":"2025-04-08T00:31:50.914Z","avatar_url":"https://github.com/ovh.png","language":"Scala","funding_links":[],"categories":["Scala"],"sub_categories":[],"readme":"# sv2chisel (System)Verilog to Chisel Translator\n[![Maintenance](https://img.shields.io/maintenance/yes/2022.svg)]() \n[![License](https://img.shields.io/badge/license-BSD%203--Clause-blue)](https://github.com/ovh/sv2chisel/blob/master/LICENSE)\n[![GitHub tag (latest SemVer)](https://img.shields.io/github/v/tag/ovh/sv2chisel.svg?include_prereleases\u0026sort=semver)](https://github.com/ovh/sv2chisel/releases/latest)\n\u003c!-- [![Build Status](https://travis-ci.org/ovh/sv2chisel.svg)](https://travis-ci.org/ovh/sv2chisel)  --\u003e\n**sv2chisel** translates synthesizable (System)Verilog to *low-level* Chisel.\n\nThe resulting Chisel is intended to be manually refactored to benefit from the advanced Chisel's features such as type and functional parameterization thanks to Scala support for polymorphism and high-order functions. \nSeveral research efforts, such as [this paper](https://hal.archives-ouvertes.fr/hal-03157426/document), demonstrate in practice the relevance of such refactoring.\n\n**sv2chisel** has achieved 1:1 translation of several large codebases with few or no manual modifications.\n[Discover all Features \u0026 Limitations](https://github.com/ovh/sv2chisel/blob/master/FEATURES_LIMITATIONS.md#sv2chisel-features--limitations) \n\n**sv2chisel** emerged as a research effort, if you use it or borrow some concepts in your own work, please cite the [associated paper](https://hal.archives-ouvertes.fr/hal-02949112/document) [(bibtex entry below)](#citing-this-work).\n\n### Project Contents\nThe current repository holds the sv2chisel project which is divided in two parts: \n- **sv2chisel** a standalone tool, able to translate (System)Verilog sources into Chisel\n- *sv2chisel-helpers* a Chisel/scala library, sometimes required by the translated Chisel and more generally providing [various utilities to integrate Chisel into HDL projects](https://github.com/ovh/sv2chisel/blob/master/FEATURES_LIMITATIONS.md#generation-utilities-for-chisel-integration-chisel-as-ip)\n\n---\n\n# Getting Started\n \n## Get sv2chisel\n\u003e Note: the version of sv2chisel x.5.x is aligned on Chisel stack 3.5.x and the versioning intends to follow the same evolution as Chisel stack one on minors\n\n#### Native Binaries\nsv2chisel releases provide native standalone binaries for the following platforms:\n- [Linux](https://github.com/ovh/sv2chisel/releases/download/v0.5.0/sv2chisel_linux_amd64) *(tested on a regular basis on Ubuntu 20.04)*\n- [Darwin](https://github.com/ovh/sv2chisel/releases/download/v0.5.0/sv2chisel_darwin_amd64) *(tested on a regular basis on MacOS with Darwin Kernel Version 17.7.0)*\n- [Windows](https://github.com/ovh/sv2chisel/releases/download/v0.5.0/sv2chisel_windows_amd64.exe) *(tested on windows 10 -- git-bash is recommended for colored console printing)*\n\nJust `chmod u+x sv2chisel_\u003cbuild\u003e` and you are all set for your first translation!\n\n#### Fat JAR\nsv2chisel releases also provide a [standalone jar]((https://github.com/ovh/sv2chisel/releases/download/v0.5.0/sv2chisel_jar.tar.gz)) file which only require a jvm installation.\n\nJust `untar -xzf sv2chisel_jar.tar.gz` and you are all set for your first translation! \n\n\n#### From code\nFinally, sv2chisel code can be directly executed with any working sbt installation by cloning this repository, see [direct usage from sources](#direct-usage-from-sources).\n\n## Setup your own Chisel project\nIf this is your first time using [Chisel](https://www.chisel-lang.org), we highly recommend you to follow either the [online bootcamp](https://mybinder.org/v2/gh/freechipsproject/chisel-bootcamp/master) or the [chisel-tutorials](https://github.com/ucb-bar/chisel-tutorial) first.\n\nTo set-up efficiently a new Chisel project, the easiest way is to clone the [chisel-template](https://github.com/freechipsproject/chisel-template).\n\nAs final step, you need to include *sv2chisel-helpers* library in this new project, by adding the following line to your local `build.sbt` file:\n```sbt\n// sv2chisel was first published in 2021, on new sonatype servers hence requiring non default resolvers\nresolvers ++= Seq(\n  \"New Sonatype Snapshots\" at \"https://s01.oss.sonatype.org/content/repositories/snapshots/\",\n  \"New Sonatype Releases\" at \"https://s01.oss.sonatype.org/service/local/repositories/releases/content/\",\n)\n// For simpler usage, sv2chisel minor version is aligned on chisel stack minor version: x.5.x \nlibraryDependencies += \"com.ovhcloud\" %% \"sv2chisel-helpers\" % \"0.5.0\"\n```\n\nThis new project is intended to be used as output target for the Chisel files converted from your (System)Verilog sources.\n\n---\n\n# Usage\nComplete 4-steps process, from (System)Verilog descriptions to upgraded Chisel generators:\n\n1. [Translation](#1-translation)\n2. [Creation of a Chisel main](#2-creation-of-a-chisel-main)\n3. [Correctness Test](#3-test-check-translation-correctness)\n4. [Manual upgrade of the 1-1 translation to more idiomatic scala/chisel syntaxes](#4-upgrade-your-low-level-chisel)\n---\n\n## 1. Translation\n### Option A: Create a config file for your HDL project\nSee https://github.com/ovh/sv2chisel/blob/master/src/main/resources/project/config.yml\n\nThen simply run sv2chisel with this config file:\n```bash\n./sv2chisel -c config.yml\n```\n\nAdditional option (such as verbosity control) can be found with `./sv2chisel -help`\n\n### Option B: Raw CLI Usage\nSee `./sv2chisel -help` to get started, basic usage:\n\n```bash\n./sv2chisel \u003cpath/to/my_verilog_file1.sv\u003e ... \u003cpath/to/my_verilog_fileN.sv\u003e\n```\n\n---\n\n**IMPORTANT TRANSLATION NOTICE**\n\nPlease review and fix (or at least acknowledge) any error (fatal/critical) messages reported by **sv2chisel** before proceeding any further, as the generated Chisel code will probably not be usable in such cases.\n\nDo not hesitate to raise an issue [here](https://github.com/ovh/sv2chisel/issues) in case of trouble.\n\n---\n\n\n## 2. Creation of a Chisel Main \n\nIn order to check the translation correctness of the translation, let's now translate it back to Verilog!\nYeah it sounds silly but it's the way it works: Chisel is an hardware construction language, not intended to be provided directly to synthesis and simulation tools but rather to be executed and produce a low-level Verilog, almost down to netlist.\n\n\nGetting started with Chisel generation API can be a bit frightening for Scala/Chisel newcomers, fortunately sv2chisel is able to generate that boilerplate for you.\nSee [details about specifying a top-level in the config file](https://github.com/ovh/sv2chisel/blob/master/FEATURES_LIMITATIONS.md#translationoptionschiselizertoplevelchiselgenerators-listdict) or [Manual setup example below](#manual-chisel-project-setup).\n\n\u003eIn a nutshell, just set the `translationOptions.Chiselizer.topLevelChiselGenerators` option in your config file, using the syntax presented in the [example config file](https://github.com/ovh/sv2chisel/blob/master/src/main/resources/project/config.yml)\n\nIt will generate an object App such as `object my_moduleGen extends App {/* */}`.\nTo generate your Verilog, run this app with sbt `runMain my_moduleGen` if placed in *src/main/scala* or with sbt `Test / runMain my_moduleGen` if placed in *src/test/scala*.\n\n---\n\n**Error reporting**\n\n- `compile` step should not raise errors, if it does, please raise an issue [here](https://github.com/ovh/sv2chisel/issues)\n- Similarly, Chisel elaboration step (in between `Elaborating...` and `Done elaborating.` message) should not raise errors, if it does, please raise an issue [here](https://github.com/ovh/sv2chisel/issues)\n- Finally, FIRRTL compilation step might raise errors, in particular related to missing connections in your design. \nThis is due to a strict Chisel/FIRRTL toolchain policy: no declared wire shall be left unassigned and no latches are allowed.\nIf you do get such errors, you are welcome to fix them yourself either in the verilog or the generated chisel, but do not hesitate reach the very welcoming [Chisel/FIRRTL community](https://www.chisel-lang.org/community.html) for help!\n\n---\n\n## 3. Test: Check translation correctness\nYou can now integrate the chisel-emitted Verilog into your usual simulation and synthesis flow, and check that it is consistent.\nSimulation should pass and synthesis produce on-par resource usage results.\nIf it is not the case, investigate the translation result, be sure you understand the implication of every warning message and feel free to open an issue for help or to raise a discovered bug.\n\n\u003e Beware that ports are flattened in the resulting verilog, you might hence need a verilog wrapper to integrate the resulting verilog, [*fortunately sv2chisel can bring it to you!*](https://github.com/ovh/sv2chisel/blob/master/FEATURES_LIMITATIONS.md#translationoptionschiselizertoplevelchiselgenerators-listdict)\n\u003e - a port `myport: Vec(n+1, \u003c\u003e)` *(verilog [N:0])* becomes n ports from `myport_0: \u003c\u003e` to `myport_n: \u003c\u003e`\n\u003e - a port `myport: Bundle` *(verilog struct)* becomes several individual ports named after the fields names such as `myport_myfieldA` ... `myport_myfieldN`\n\n\n## 4. Upgrade your low-level Chisel\nYour translated project is working as expected?\nHere is precisely where the whole fun starts, and where this step-by step guide stops.\nPlease refer to [Chisel documentation](https://www.chisel-lang.org) for various user-guides and examples to truly unleash Chisel's generation powers.\n\n---\n\n# Citing this work\nIf you use this work or borrow some concept for your own research, please cite the following [paper](https://hal.archives-ouvertes.fr/hal-02949112/document):\n```bibtex\n@inproceedings{bruant2020sv2chisel,\n  author    = {Jean Bruant and\n               Pierre-Henri Horrein and\n               Olivier Muller and\n               Tristan Grol{\\'{e}}at and\n               Fr{\\'{e}}d{\\'{e}}ric P{\\'{e}}trot},\n  title     = {(System)Verilog to Chisel Translation for Faster Hardware Design},\n  booktitle = {Proceedings of the 31th International Workshop on Rapid System Prototyping,\n               {RSP} 2020, Virtual Conference, September 24-25, 2020},\n  publisher = {{ACM}},\n  year      = {2020},\n}\n```\n\n# Contributing\n\nYou've developed a new cool feature? Fixed an annoying bug? We'd be happy\nto hear from you!\n\n## Getting Started\nIf you have successfully published sv2chisel locally, then you are all set to start hacking into the code, otherwise see [direct usage from sources](#direct-usage-from-sources).\n\n## Documentation \nThe in-code documentation remains yet quite sparse.\nHere is a quick overview of the code base, within *src/main/*:\n1. Lexing \u0026 Parsing to IR\n    - *antlr4/* ANTLR SystemVerilog Lexer \u0026 Parser (generates Java sources within *sv2chisel/target/scala-2.12/src_managed/main/antlr4/sv2chisel/antlr/*)\n    - *scala/sv2chisel/Visitor.scala* Visits the AST generated by the parser and map it into our custom Intermediate Representation (IR)\n    - *scala/sv2chisel/ir/* describe our IR which is based on [Firrtl](https://github.com/freechipsproject/firrtl/). Main content seats within *IR.scala* while the side files provide many convenient implicit functions operating on the IR.\n2. Transforms\n    - *scala/sv2chisel/Driver.scala* contains the list of transforms applied to a project\n    - *scala/sv2chisel/transforms/* folder contains all the transforms\n3. IR to Chisel\n    - *scala/sv2chisel/Chiselizer.scala* provide implicit functions to convert the IR into Chisel tokens. Note that some constructs of the IR are expected to be removed prior this step, thanks to previous transforms.\n    - *scala/sv2chisel/Emitter.scala* synchronize the chisel token stream with the original token stream in order to re-insert comments and some part of the layout into the final Chisel text to be written to file.   \n\n## Testing\nAll unit-tests can be found within *src/test* and can be run with sbt `test` for the whole batch or with `testOnly sv2chiselTests.TestName` for a particular one.\nPlease add new test-cases along with new features or bug fix to highlight the quality of your contribution.\n\nDuring main development process, functional testing was carried out both with the open-source RISC-V core [PicoRV32](https://github.com/cliffordwolf/picorv32/) and some internal verilog libraries at OVHcloud.\n\nContinuous integration system including such automated functional testing is under investigation.\n\n## Sharing your modifications\nHave a look in [CONTRIBUTING.md](https://github.com/ovh/sv2chisel/blob/master/CONTRIBUTING.md) and feel free to submit a pull-request on this repository.\n\n## Release to Maven Central\n### Setup\n- NB: Based on `sbt-pgp` \u0026 `sbt-sonatype` plug-ins\n- Add Credentials in `~/.sbt/1.0/sonatype.sbt`\n```sbt\ncredentials += Credentials(\"Sonatype Nexus Repository Manager\",\n        \"s01.oss.sonatype.org\", // created after 2021\n        \"\u003csonatypeUserName\u003e\",\n        \"\u003csonatypePwd\u003e\")\n```\n- Add PGP private key in your/CI keyring\n\n\n### Release options\n1. *SNAPSHOTS*\n```\nsbt:sv2chisel\u003e publishSigned\nsbt:sv2chisel\u003e helpers/publishSigned\n```\n\n2. *RELEASE:* Based on sbt-release plugin, just follow the instruction of `sbt 'release'`\n\n \n# Related links\n * Contribute: https://github.com/ovh/sv2chisel/blob/master/CONTRIBUTING.md\n * Report bugs: https://github.com/ovh/sv2chisel/issues\n \u003c!-- * Get latest version: TODO: maven publishing --\u003e\n \n# Licenses\n## External licenses\n- [Firrtl](https://github.com/freechipsproject/firrtl/) borrowed sources: https://github.com/ovh/sv2chisel/blob/master/LICENSE.firrtl\n- [Nic30's](https://github.com/Nic30/hdlConvertor) SystemVerilog Parser https://github.com/ovh/sv2chisel/blob/master/LICENSE.Nic30\n\n## sv2chisel license\nSee https://github.com/ovh/sv2chisel/blob/master/LICENSE\n\n---\n\n# Annexes\n\n---\n\n## Direct Usage From Sources\n\n### Prerequisite\n- Install sbt [official documentation](https://www.scala-sbt.org/1.x/docs/Setup.html)\n\n### Publish locally sv2chisel \u0026 sv2chisel-helpers\n```bash\ngit clone https://github.com/ovh/sv2chisel.git\ncd sv2chisel\nsbt\n```\nIn sbt shell\n```sbt\nsbt:sv2chisel\u003e publishLocal\nsbt:sv2chisel\u003e helpers/publishLocal\n```\nThe `publishLocal` commands make sv2chisel and sv2chisel-helpers libraries available locally to be used in other Scala project. \n\n### Translation\n#### Option A: Run the generic application\nEither from shell\n```bash\nsbt 'runMain sv2chisel.Main -c config.yml'\n```\n\nor directly in sbt to avoid sbt startup time\n```bash\nsbt:sv2chisel\u003e runMain sv2chisel.Main -c config.yml\n```\n\nRunning `runMain sv2chisel.Main -help` details available options, in particular control of the level of verbosity.\n\n#### Option B: Create your own translator app\n##### Setup\nCreate a new empty scala project. [Official documentation](https://docs.scala-lang.org/getting-started/sbt-track/getting-started-with-scala-and-sbt-on-the-command-line.html) \n\nTo be able to use **sv2chisel** within this newly created project, just add the following line to your `build.sbt` file.\n```sbt\nlibraryDependencies += \"com.ovhcloud\" %% \"sv2chisel\" % \"0.1.0-SNAPSHOT\"\n```\n\nCreate a new Scala main app template using sv2chisel API, here is a template with a few comments to be used as a starting point to translate your (System)Verilog file(s) or project(s):\nhttps://github.com/ovh/sv2chisel/blob/master/src/main/scala/sv2chisel/AppExample.scala\n\nThis template is to be edited to fit your needs and saved under a proper scala hierarchy such as `\u003cyour-project\u003e/src/main/scala/\u003cMyTranslator.scala\u003e`\n\n##### Translate your code \nIn your translator project sbt: `runMain MyTranslator`\n\n---\n\n## Manual chisel project setup\n\nLet's take an example of input verilog\n```verilog\nmodule test #(\n    param TEST = 1\n  )(\n    input clock,\n    input reset,\n    input a,\n    output b\n  )\n  // module body\nendmodule\n```\n\nthat would be translated into Chisel\n```scala\npackage myproject\n\nimport chisel3._\nimport sv2chisel.helpers.vecconvert._ // assuming module body requires it\n\nclass test extends MultiIOModule (\n    val TEST: Int = 1\n  ){\n    val a = IO(Input(Bool())\n    val b = IO(Output(Bool())\n  \n  // module body\n}\n```\n\nWe will use this small chisel main app to generate it:\n\n```scala\nimport myproject._\nimport chisel3.stage._\n\nobject MyTestGenerator extends App { \n  (new ChiselStage()).emitVerilog(new test(10))\n}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fovh%2Fsv2chisel","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fovh%2Fsv2chisel","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fovh%2Fsv2chisel/lists"}