David Anderson 770f515a72 | ||
---|---|---|
blinky | ||
debugger | ||
experiments | ||
hardware | ||
images | ||
lib | ||
scripts | ||
sim | ||
vram | ||
.gitignore | ||
.svlint.toml | ||
LICENSE | ||
README.md | ||
Requirements.md | ||
flake.lock | ||
flake.nix | ||
go.mod | ||
go.sum | ||
tasks.py |
README.md
GARY: Graphics Adapter for Retropixel Yeeting
This is a project to build a graphics adapter for the Sentinel 65X, as an upgrade to the VERA graphics core. It's a work in progress.
Current status
Still building it. Unless you want to tinker or hack on the design, it's not yet ready for use. As of 2024-09, the high level architecture looks like this, with grayed out modules being the TODOs.
You can also look at the design requirements to get an idea of why this exists and roughly where we're going, although it's a fairly loose set of guidelines and may change as development progresses.
Requirements
GARY is written in Bluespec
SystemVerilog, and synthesized
with the Yosys/Nextpnr open source FPGA toolchain. If you can use nix,
the flake.nix in this repository provides the necessary tools, which
you can make available with nix develop
. Otherwise, consult
flake.nix for a list of software. At a minimum you'll need:
- The Bluespec SystemVerilog toolchain
- Yosys and nextpnr with Lattice ECP5 support
- OpenFPGALoader to program designs onto an FPGA
- A Go compiler if you want to use the debugger
- Invoke to drive the build system
- Some kind of VCD waveform viewer like GTKWave to debug failing tests.
If you want to run this on hardware, you'll also need supported hardware. Currently, the only working target is the ULX3S board with a Lattice ECP5 LFE5U-85 FPGA. Once the design is fully working, it may be ported to other boards or FPGAs.
Developing
GARY uses Invoke as a small build system. You can read tasks.py to see the details, but these are the main available commands:
inv build <build target>
: run the Bluespec compiler on the given target.inv synth <synth target>
: run full synthesis to bitstream on the given target.inv test <test target>
: run unit tests in Bluesim.inv clean
: delete build outputs.inv genclk
: generate clock configuration for the Lattice ECP5 PLL primitive.
The overall workflow looks like this:
- Write Bluespec SystemVerilog in .bsv files, possibly with supporting Verilog-2005 in .v files.
- Use
inv build
to check the Bluespec design and elaborate the modules marked for synthesis. - Write unit tests in
<module name>_Test.bsv
files, and useinv test
to run them. The tests run in Bluesim, and output VCD waveform files if you need to debug failures. - Create a top-level module in
<some dir>/Top.bsv
, with an accompanying<some dir>/pin_map.lpf
to map I/Os to physical pins and set timing constraints. - Run
inv synth
to synthesize the top-level module into a bitstream for flashing to target. - Use
openFPGALoader
to program your hardware of choice.
Most development time should be spent in the upper parts of this list, writing tests and running them in a simulator and maybe synthesizing some test designs to see how well/poorly modules turn into hardware. Trying to diagnose buggy designs on hardware is going to be very frustrating, do yourself a favor and only move to hardware with code you've already tested a whole bunch in simulation.
Build targets can be a single Bluespec file (inv build lib/UART.bsv
), or a directory to build all Bluespec in that subtree
(inv build lib
).
Test targets can be a single test file (inv test lib/Strobe_Test.bsv
) or a directory to run all tests in that subtree
(inv test lib
, inv test .
).
Synthesis targets can be a single Bluespec file (inv synth hack/Top.bsv
), a directory containing a Top.bsv
file
(inv synth experiments/vram
), or the name of a hardware target
as found in the hardware
subdirectory (inv synth ulx3s
).