Hi there, welcome to Cobalt. Cobalt is a collection of Bluespec interfaces and modules, used by Oxide Computer to implement custom logic for its new computer. Since we developed some of these pieces on readily available development boards using a fully open source synthesis toolchain, we figured this work and the implementation of its build system may serve as practical examples for others on how to use Bluespec in their own projects.

To get started with the examples found in this repo you may want to follow the following steps to get up and running.

To clone the repo, including its Cobble dependency, run the following. Use the URL [email protected]:oxidecomputer/cobalt if SSH is your transport of choice.

git clone --recursive https://github.com/oxidecomputer/cobalt

If you happen to have cloned the repo without the submodules, you can initialize them like so:

git submodule update --init --recursive

The Bluespec compiler is currently only available in source form. Please head over to the build instructions and install yourself a copy.

The easiest way to get the Yosys/nextpnr synthesis toolchain installed is by heading over to YosysHQ and downloading a build for your favorite OS. Alternatively, the Yosys and nextpnr repos have build instructions if you'd rather build from source.

Finally, Cobble requires a Python 3 (version 3.6+ is probably sufficient, we do not actually know). Please install a copy if your system does not already have one.

In order to point Cobble at the right toolchain pieces, copy BUILD.vars.example and edit the paths in this file to match your installed toolchain:

cp BUILD.vars.example BUILD.vars
$EDITOR BUILD.vars

And at long last we are ready to initialize the build graph and build one of the examples like so:

mkdir build; cd build
../vnd/cobble/cobble init ..

To build and run one of the test benches:

./cobble build latest/hdl/examples/uart_loopback_test && latest/hdl/examples/uart_loopback_test

The output of the command above should be the following, indicating successful "transmission" of two bytes:

% latest/hdl/examples/uart_loopback_test
'h55
'haa

To build the Blinky example Lattice ECP5 EVN board and flash the SRAM of the FPGA:

./cobble build latest/hdl/boards/ecp5_evn/blinky_ecp5_evn.bit
ecpprog -S latest/hdl/boards/ecp5_evn/blinky_ecp5_evn.bit

Finally, to build all possible targets simply run:

./cobble build

If you are wondering where to go from here, we suggest heading over to the examples directory or building and trying one of the bitstreams for the other supported boards. Happy hacking!

Q: Bluesim test benches fail with the following error:

latest/hdl/examples/uart_loopback_test: line 3: bluetcl: command not found
latest/hdl/examples/uart_loopback_test: line 12: /tcllib/bluespec/bluesim.tcl: No such file or directory
latest/hdl/examples/uart_loopback_test: line 12: exec: /tcllib/bluespec/bluesim.tcl: cannot execute: No such file or directory

A: Make sure the bluetcl can be found using the $PATH variables. If the Bluespec compiler was installed outside the usual system paths, because its bin direction is present in $PATH.