gary/README.md

92 lines
4.0 KiB
Markdown
Raw Permalink Normal View History

# 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.
![functional diagram of GARY](images/gary-architecture.jpg)
You can also look at [the design requirements](Requirements.md) 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](https://github.com/b-Lang-org/bsc), 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](https://github.com/b-Lang-org/bsc)
- [Yosys](https://github.com/YosysHQ/yosys) and
[nextpnr](https://github.com/YosysHQ/nextpnr) with Lattice ECP5
support
- [OpenFPGALoader](https://trabucayre.github.io/openFPGALoader/) to
program designs onto an FPGA
- A [Go compiler](https://go.dev/) if you want to use the debugger
- [Invoke](https://www.pyinvoke.org/) to drive the build system
- Some kind of VCD waveform viewer like
[GTKWave](https://github.com/gtkwave/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](https://ulx3s.github.io/) 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`).