gary/Requirements.md

# GARY: Graphics Adapter for Retropixel Yeeting

Tentative requirements and wishlist for an FPGA-based media processor
for retrocomputing.

## Target hardware/era

The design is intended to feel at home in a retrocomputer with a "late
16-bit era" feel, like the Sentinel 65X: 16-bit CPU clocked around
5-15MHz with a wide main bus shared by multiple memory-mapped
peripherals. It aims for capabilities comparable to early VGA graphics
and early PC audio.

Initially, we'll tailor the design to the Sentinel 65X's needs and
wants, as a potential replacement for the VERA processor developed for
the Commander X16.

## Overview

![schematic diagram of a hypothetical 65X computer with GARY. The
important parts of the schematic are described in text following the
image.](images/65x-gary-system-overview.png)

This is a general system overview. The 65C816 main processor connects
to the board's main bus, with peripherals like system RAM and
expansion ports. GARY also connects to this bus. It has dedicated
attached video RAM, and provides audio and video output as well as a
few GPIOs. It also has a dedicated interrupt line, to serve as an
offboard interrupt controller to the main CPU.

Initially the plan is to mirror the design and features of the VERA
processor, and modify from there.

![schematic diagram of GARY's graphics rendering pipeline. The system
bus hooks to a bus interface, which writes data to video RAM and
configures the other components. Video RAM feeds into two tile engines
and a sprite engine, their output is merged by a compositor, and
finally pixels are output by the palette DAC, which also reads palette
information from video RAM.](images/65x-gary-graphics.png)

## Feature/wish list

Roughly, start from VERA and evolve from there.

- 640x480@60Hz "industry standard" VGA output.
- RGB color output, 12bpp (4 bits per colour), into a resistor DAC to
  convert to analog VGA signals.
- Modifiable 256 color palette.
- 128KiB video RAM, accessible from CPU.
- Various tile and sprite modes (same as VERA's, tentatively).
- Glitch-free video, correct clock domain crossing (unlike VERA).
- PCM audio with output to I2S DAC. Samples fed directly from CPU.
- Written in Bluespec SystemVerilog, an high level HDL that makes it
  hard to screw up timing/synchronization/types. (Not strictly
  required, but Dave's doing it this way so if you want him to make
  the thing...)
- Well tested, good simulator support (again to not go mad trying to
  debug subtle problems on live hardware).

Desires to better fit 65X's needs than VERA. These mostly rely on having more I/O available, so would require moving up to a low-end Lattice ECP5 instead of a maxed out ICE40.

- Directly expose internal address space on system bus, instead of a
  narrow window to wider internal space. Full 24 address + 8 data
  lanes into GARY.
- Programmable interrupt controller, 8 GPIOs and some timers to
  trigger interrupts.
- Absorb the glue logic from the separate CPLD/7400 chips [TODO: what
  does said logic need to do exactly?]

I want a pony! Things that should be doable, but are more radical
departures from VERA in various ways. Definitely would need an ECP5.

- Palette in main VRAM, at configurable location (unlike VERA, which
  has a separate palette memory). Specifically support reconfiguring
  the palette during frame drawing, to enable cool beam-racing
  nonsense.
- Support for palette colour cycling: specify [start:end] range in
  palette and cycle speed, palette DAC rolls colours by itself.
- Direct double-buffered framebuffer mode, for GUI stuff. 1bpp and
  2bpp palettized possible within VERA's RAM budget, more would
  require larger VRAM.
- S-Video output in addition to VGA. Require YPbPr conversion to
  output luma+chroma signals.
- HDMI or DisplayPort output in addition to VGA. Same
  resolution/depth, different transport. Requires 8b/10b encoder and
  additional signals.
- Support for 65C816's 16-bit move instructions. Normal move sends 8
  bits every 7 PHI2 clock cycles, 16-bit move sends 2x8 bits on two
  consecutive PHI2 cycles.
- Display lists? As in https://www.atariarchives.org/dere/chapt02.php
  . Effectively a small DSP ISA/very primitive GPU
  programming. Significant architecture change from VERA.
- Higher resolution output? Would be nice to hit SVGA resolutions like
  1024x768 or 1280x1024. Requires gateware running at higher
  frequency, use of more complex I/O hardware, larger video RAM. Even
  moreso if we want 24bpp per SVGA, rather than palettized output.