Vunit buck2 and RDL buck2 improvements (#119)

* Note: can only deal with same-library VUnit projects right now.
* Runs ghdl and works with waves etc
* VUnit and RDL toolchains set up "properly" the buck2 way with toolchain files for python etc.
* Add vunit to requirements.txt
* VUnit hack to pin to repo-root unless over-ridden
* Update jinja dep
* Added buck2 info to the README and some basic rule docs
Cleaned up references to cobalt and provided pointers
to additional docs
* Adjust things to work in windows also

Author: nathanaelhuffman

.gitignore

@@ -3,10 +3,19 @@ BUILD.vars
 /build
 __pycache__
 
+# Buck2 ignores
+/buck-out
+
+# VUnit ignores
+/vunit_out
+
 devcontainer.json
 
 # VS Code settings
 .vscode
 
+# pycharm
+/.idea
+
 # MacOS metadata
 .DS_Store

BUCK

@@ -1,30 +0,0 @@
-load(":rdl.bzl", "rdl_file", "rdl_gen")
-
-rdl_file(
-    name = "gimlet_seq_fpga_regs",
-    src = "gimlet_seq_fpga_regs.rdl",
-    deps = [],
-)
-
-rdl_gen(
-    name = "gimlet_regs",
-    srcs = [":gimlet_seq_fpga_regs"],
-    outputs = ["gimlet.vhd", "gimlet.html", "gimlet.json", "gimlet.bsv"]
-)
-
-rdl_file(
-    name = "demo_rdl",
-    src = "demo.rdl",
-    deps = [],
-)
-rdl_file(
-    name = "demo_top",
-    src = "demo_top.rdl",
-    deps = [":demo_rdl"],
-)
-
-rdl_gen(
-    name = "demo_test",
-    srcs = [":demo_top"],
-    outputs = ["demo.vhd", "demo.bsv", "demo.json", "demp_test.html"]
- )

BUCK_RULES.md

@@ -0,0 +1,71 @@
+= Flow-specific BUCK rules
+
+== VHDL files/module rule organization
+The expectation is that your BUCK files will have at least one entry
+for each vhdl "module" in your design. As a guideline, you should
+compose your modules such that any level that could be a dependency
+to some other module is factored into its own rule. It would be a
+common case for many VHDL package files to want be re-used in multiple
+places, so they would be put each in their own `vhdl_unit` rule.
+In cases where a package and some number of other files might make
+up a re-usable module all together but not separately, these could
+be put in a single `vhdl_unit` rule.
+
+
+The general VHDL rule in buck is defined [here](tools/hdl.bzl) as
+`vhdl_unit = rule(
+    impl=_hdl_unit_impl,
+    attrs={
+        "deps": attrs.list(
+            attrs.dep(doc="Dependencies as dep types (ie from another rule)"),
+            default=[],
+        ),
+        "srcs": attrs.list(attrs.source(doc="Expected VHDL sources")),
+        "is_tb": attrs.bool(
+            doc=(
+                "Set to True when this is a top-level VUnit testbench\
+            for which a run.py should be generate"
+            ),
+            default=False,
+        ),
+        "_toolchain": attrs.toolchain_dep(
+            doc="Use system python toolchain for running VUnit",
+            default="toolchains//:python",
+        ),
+        "_bins": attrs.exec_dep(
+            doc="Use vunit_gen toolchain for generating VUnit run.pys",
+            default="root//tools/vunit_gen:vunit_gen",
+        ),
+    },
+)`
+
+`srcs` is a list of source files for this module, and glob can be used if it makes sense,
+`srcs = glob(["*.vhd"])` as an example with the paths being relative to the BUCK file.
+
+`deps` expects a list of BUCK target patterns that point to other targets that this module
+depends on, typically RDL targets (see below) or other VHDL module targets. See 
+[vunit_example](hdl/projects/vunit_example/BUCK) for some examples.
+
+The remaining attributes should generally use the defaults and can be ignored.
+
+
+== System RDL
+Another simple rule here, but each RDL file gets its own rule entry.
+
+The rdl rule in buck is defined [here](tools/rdl.bzl) as
+`rdl_file = rule(
+    impl=_rdl_file_impl,
+    attrs={
+        "src": attrs.source(),
+        "deps": attrs.list(attrs.dep(), default=[]),
+        "outputs": attrs.list(attrs.string(), default=[]),
+        "_rdl_gen": attrs.exec_dep(default="root//tools/site_cobble/rdl_pkg:rdl_cli"),
+    },
+)`
+
+The user provides the `src` file path and optionally any other RDL target patterns upon which
+this definition depends, and provides a list of expected `outputs`.  Output type is determined
+by output extension, known possible output extensions are: `.bsv`, `.json`, `.vhd`, `.html`, `.adoc`
+
+The `vhdl_unit` rule knows how to take the RDL targets as a dependency so long as a `.vhd` output is
+generated for the target that will be a dep to a VHDL block.

README.md

@@ -1,13 +1,9 @@
 # Quartz
 
-Quartz is a collection of soft-logic designs and hardware abstraction libraries (HALs) for various
-subsystems found in Oxide hardware. This includes components such as Ignition, power sequencing for
-system boards and QSFP interface management.
-
-Quartz leans heavily on [Cobalt](https://github.com/oxidecomputer/cobalt) and unless a component is
-experimental or specific to an Oxide system, our posture should be to push as much into that project
-as possible. Having said that, it is acceptable to prototype in private under the Quartz project and
-move something to Cobalt once deemed ready.
+Quartz is a collection of soft-logic designs and hardware abstraction libraries
+(HALs) for various subsystems found in Oxide hardware. This includes components
+such as Ignition, power sequencing for system boards and QSFP interface
+management.
 
 # Cloning instructions
 Note that cobble is a submodule of cobalt which is used as a submodule here.
@@ -23,18 +19,64 @@ or if already checked out:
 ```
 
 # Build system help
-At the root of the Quartz directory, the BUILD.vars file controls machine-specific paths.
-It is recommended that you copy the BUILD.vars.example and adapt for your system paths.
-Typically this involves adjusting the [bluespec] [yosys] [nextpnr] sections to point to the tooling in your environment.
+In the long-term, we're migrating to buck2 as out build system but until we have
+reached parity, we are supporting designs that started using cobble still with
+cobble and new design flows using buck2.
+
+## Cobble-based builds
+Currently the cobble build chain supports BSV designs and RDL generate
+targetting the yosys toolchain.
+
+If you're looking for getting started with a cobble-based build see
+[instructions](COBALT_README.md) as well as some further tips
+[here](hdl/projects/gimlet/sequencer/README.md) At the root of the Quartz
+directory, the BUILD.vars file controls machine-specific paths. It is
+recommended that you copy the BUILD.vars.example and adapt for your system
+paths. Typically this involves adjusting the [bluespec] [yosys] [nextpnr]
+sections to point to the tooling in your environment.
+
+### Adding new source files
+In each folder that is scanned, there is a BUILD file that includes the
+information for cobble to determine build targets and a complete dependency
+tree. In general, bluespec files get added as individual bluespec libraries,
+bluespec simulation targets get added as a bluespec_sim target, and
+bluesim_binary target.
+
+For top-level designs that would synthesize to an FPGA, a bluespec_verilog
+target, a yosys_design target and a nextpnr target are needed to properly
+generate bitstreams.
+
+### Adding new hardware targets
+To add support for a totally new chip design, a new "environment" in cobble
+parlance has to be created. This is done up at the root of the quartz repo in
+the BUILD.conf file.
+
+## buck2 builds
+This area is under active development, currently supporting VHDL and RDL flows
+into VUnit simulations.  FPGA toolchain support, and BSV support needs to be
+fleshed out.
+
+The docker image does not currently contain buck2 executables.
+
+For information on building `BUCK` files see [here](BUCK_RULES.md)
+
+### Prerequisites
+- You need a copy of buck2 built locally. [Instructions](https://buck2.build/docs/getting_started/)
+- You'll need python3/pip installed and accessible on your path. We have python 3.10
+working in linux, and python 3.12 working in windows. Python 3.9 did not work in 
+windows at least, we have no other data points on other python versions.
+- You'll need to install required python packages `pip install -r tools/requirements.txt`
+- You'll need to have GHDL installed and on your path (in linux this comes with
+the oss-cad-suite, but oss-cad-suite windows builds don't build GHDL). As of
+Jan '24, the ghdl-MINGW32 bit nightly version was working in windows.
 
-## Adding new source files
-In each folder that is scanned, there is a BUILD file that includes the information for cobble to determine build targets
-and a complete dependency tree. In general, bluespec files get added as individual bluespec libraries, bluespec simulation targets get added
-as a bluespec_sim target, and bluesim_binary target.
+:warning: **Windows Users**: You need to be in Developer Mode for buck2 to be
+able to use symlinks, and should consider setting `LongPathsEnabled` in regedit at
+`HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\FileSystem` to 1 and rebooting.
 
-For top-level designs that would synthesize to an FPGA, a bluespec_verilog target, a yosys_design target and a nextpnr target are needed to
-properly generate bitstreams.
+### buck2 run
+Comprehensive buck2 command line guidance is out of the scope of this document
+but if you want to see a list of all available buck2 targets you can do: `buck2 ctargets /...`
 
-## Adding new hardware targets
-To add support for a totally new chip design, a new "environment" in cobble parlance has to be created. This is done up at the root of the 
-quartz repo in the BUILD.conf file.
+To run a simulation, pick one of the testbench targets and `buck2 run <target>` you may do
+`-- <vunit args>` if you need to pass arguments into VUnit.

demo.rdl

@@ -0,0 +1,33 @@
+load("//tools:hdl.bzl", "vhdl_unit")
+load("//tools:rdl.bzl", "rdl_file")
+
+rdl_file(
+    name = "gimlet_seq_fpga_regs",
+    src = "gimlet_seq_fpga_regs.rdl",
+    deps = [],
+    outputs = ["gimlet.vhd", "gimlet.html", "gimlet.json", "gimlet.bsv"]
+)
+
+vhdl_unit(
+    name = "uart_rx",
+    srcs = ["uart_rx.vhd",],
+)
+
+vhdl_unit(
+    name = "uart_tx",
+    srcs = ["uart_tx.vhd"],
+)
+
+vhdl_unit(
+    name = "tb_uart_rx",
+    srcs = ["tb_uart_rx.vhd"],
+    deps = [":uart_rx", ":gimlet_seq_fpga_regs"],
+    is_tb = True
+)
+
+vhdl_unit(
+    name = "tb_uart_tx",
+    srcs = ["tb_uart_tx.vhd"],
+    deps = [":uart_tx", ":gimlet_seq_fpga_regs"],
+    is_tb = True
+)