Merge pull request #8 from chipsalliance/develop/unlsycn

[doc] update readme

readme.md

@@ -1,4 +1,6 @@
-# chisel nix
+# Chisel Nix
+
+## Getting started
 
 Here we provide nix templates for setting up a Chisel project.
 
@@ -14,30 +16,36 @@ It will provide you the below code structure:
 
 * elaborator/: source code to the chisel elaborator
 * gcd/: source code for the [GCD](https://en.wikipedia.org/wiki/Greatest_common_divisor) example
+* gcdemu/: source code for the DPI library
+* configs/: default configurations for GCD and the testbench, which can be generated by elaborator
 * nix/: nix build script for the whole lowering process
 * build.sc & common.sc: Scala build script
 * flake.nix: the root for nix to search scripts
 
+## Usage
+
 Our packaging strategy is using the `overlay.nix` to "overlay" the nixpkgs.
 Every thing that developers want to add or modify should go into the `overlay.nix` file.
 
 This skeleton provides a simple [GCD](https://en.wikipedia.org/wiki/Greatest_common_divisor) example.
 It's build script is in `nix/gcd` folder, providing the below attributes:
 
-* gcd-compiled: JVM bytecode for the GCD and elaborator
-* elaborator: a bash wrapper for running the elaborator with JDK
-* elaborate: Unlowered MLIR bytecode output from firrtl elaborated by elaborator
-* mlirbc: MLIR bytecode lowered by circt framework
-* rtl: system verilog generated from the lowered MLIR bytecode
-* verilated-c-lib: C library verilated from system verilog
+* {gcd,tb}-compiled: JVM bytecode for the GCD/GCDTestbench and elaborator
+* {gcd,tb}-compiled.elaborator: A bash wrapper for running the elaborator with JDK
+* [tb-]elaborate: Unlowered MLIR bytecode output from firrtl elaborated by elaborator
+* [tb-]mlirbc: MLIR bytecode lowered by circt framework
+* [tb-]rtl: SystemVerilog generated from the lowered MLIR bytecode
+* tb-dpi-lib: DPI library written in Rust for both Verilator and VCS
+* verilated[-trace]: C++ simulation executable and libaray generated by Verilator with/without `fst` waveform trace
+* vcs[-trace]: C simulation executable compiled by VCS with/without `fsdb` waveform trace
 
 To get the corresponding output, developers can use:
 
 ```bash
 nix build '.#gcd.<attr>'
 ```
 
-For example, to get the final lowered system verilog, developer can run:
+For instance, if developers wish to obtain the final lowered SystemVerilog, they can execute:
 
 ```bash
 nix build '.#gcd.rtl'
@@ -51,16 +59,59 @@ To have same environment as the build script for developing purpose, developer c
 nix develop '.#gcd.<attr>'
 ```
 
-For example, to modify the GCD sources, developer can run:
+For example, to modify the GCD sources, developer might run:
 
 ```bash
 nix develop '.#gcd.gcd-compiled'
 ```
 
 The above command will provide a new bash shell with `mill`, `circt`, `chisel`... dependencies set up.
 
+Certain attributes support direct execution via Nix, allowing arguments to be passed using `--`:
+
+```bash
+nix run '.#gcd.<attr>'
+```
+
+For example, we use elaborator to generate configs for the design. To generate the config for GCDTestbench, developer can run:
+
+```bash
+nix run '.#gcd.gcd-compiled.elaborator' -- config --width 16 --useAsyncReset false
+```
+
+A JSON file named `GCDMain.json` will be generated in the working directory.
+
+As another example, we can run a VCS simulation with waveform trace by:
+
+```bash
+nix run '.#gcd.vcs-trace' --impure -- +dump-start=0 +dump-end=10000 +wave-path=trace +fsdb+sva_success
+```
+
+The DPI lib can automatically match the arguments and does not interact with VCS. In this case, the first three parameters will be passed to the DPI lib to control waveform generation, and the last parameter will be passed to the VCS to dump the results of all sva statements.
+
+Note that in order to use VCS for simulation, you need to set the environment variables `VC_STATIC_HOME` and `SNPSLMD_LICENSE_FILE` and add the`--impure` flag.
+
 ## References
 
+### Format the source code
+
+To format the Nix code, developers can run:
+
+```bash
+nix fmt
+```
+
+To format the Rust code, developers can run following command in `gcdemu/`:
+
+```bash
+nix develop -c cargo fmt
+```
+
+To format the Scala code, developers can run:
+
+```bash
+nix develop -c bash -c 'mill -i gcd.reformat && mill -i elaborator.reformat'
+```
 
 ### Use the fetchMillDeps function
 
@@ -123,5 +174,6 @@ stdenv.mkDerivation {
 }
 ```
 
-# License
-The build system is released under the Apache-2.0 license, including all Nix and mill build system, All rights reserved by Jiuyang Liu <[email protected]>
+## License
+
+The build system is released under the Apache-2.0 license, including all Nix and mill build system, All rights reserved by Jiuyang Liu <[email protected]>

templates/chisel/elaborator/src/GCD.scala

@@ -9,11 +9,11 @@ import org.chipsalliance.gcd.elaborator.Elaborator
 object GCDMain extends Elaborator {
   @main
   case class GCDParameterMain(
-    @arg(name = "xLen") xLen:                   Int,
+    @arg(name = "width") width:                 Int,
     @arg(name = "useAsyncReset") useAsyncReset: Boolean) {
-    require(xLen > 0, "xLen must be a non-negative integer")
-    require(chisel3.util.isPow2(xLen), "xLen must be a power of 2")
-    def convert: GCDParameter = GCDParameter(xLen, useAsyncReset)
+    require(width > 0, "width must be a non-negative integer")
+    require(chisel3.util.isPow2(width), "width must be a power of 2")
+    def convert: GCDParameter = GCDParameter(width, useAsyncReset)
   }
 
   implicit def GCDParameterMainParser: ParserForClass[GCDParameterMain] =