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 use inv 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).