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.
Note that cobble is a submodule of cobalt which is used as a submodule here.
git clone --recursiveor if already checked out:
git submodule update --init --recursive
or
git pull recurse-submodulesIn 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.
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 as well as some further tips here 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 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.
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.
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
- You need a copy of buck2 built locally. The official
Instructions are here but note that the buck2 version
is intrinsically tied to the checkout of the submodules, and as such, our currently supported
buck2 version is installed like this:
cargo +nightly-2024-03-17 install --git https://github.com/facebook/buck2.git --rev 008ed92cdb27faee83b5c636c0e365ced4b5c5d3 buck2See this issue for more info - 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 nvc (https://github.com/nickg/nvc). For linux, this can be obtained as a .deb from the releases section, for windows there are also compiled binaries in the releases section. Current minimum supported version is 1.13.1
LongPathsEnabled in regedit at
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\FileSystem to 1 and rebooting.
- When building Xilinx design, Vivado will need to be installed and on your
$PATH. - Adjusting paths may require restarting of the buck2 background process so that it notices
the changes. This can be done with
buck2 clean
There are simulation-only XPM macros available in the vnd/xpm/xpm_vhdl submodule, provided
by the https://github.com/fransschreuder/xpm_vhdl project.
There is a BUCK file at vnd/xpm so you can add //vnd/xpm:xpm as a dependency to any
module that needs to use the XPM library.
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 /...
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.
multitool is a collection of quality of live utilities built in-tree for regular use, but whose function is small enough to not warrant a self-contained project.
There is basic support for generating vhdl_ls.toml files from the BUCK files. This is tested and is working with the https://github.com/VHDL-LS/rust_hdl_vscode vscode extension.
Using bxl, the following command queries the build graph for VHDL files, outputs a
json blob to stdout which is then converted into vhdl_ls.toml. Ideally we'd have an
editor hook do this and have it be a little more standalone.
you can now do the following:
buck2 run //tools/multitool:multitool -- lsp-toml
The vunit sources are not currently enumerated in BUCK files as their installation location can vary, but multitool -- lsp-toml now attempts to discover an add these so a .vhdl_ls.toml in your home directory is no longer required or recommended.
This generates some basic testbench and test harness boiler plate with some basic
assumptions built in, but once generated you can modify as needed for your project
buck2 run //tools/multitool:multitool -- tb-gen --name <testbench_name> --path <path to sims folder>
We're using vhdl-style-guide to provide
consistent formatting. Our custom ruleset is in the repo root (vsg_config.json) and we provide a wrapper to run this tool against all of our 1st-party VHDL code.
You can run buck2 run //tools/multitool:multitool -- format to auto-format our code
and you can run buck2 run //tools/multitool:multitool -- format --no-fix to see a
report of the formatter without changing the code. This is especially useful when
trying to identify a target rule for adjustment or disablement.
Right now, this has to be run manually by a user before code check-in, we'll look into editor automation as we stabilize the rules and have time to do so.