Pineapple GPU P1 Technical Reference Manual

Pineapple GPU P1 is a standalone programmable 3D graphics processor for the Nexys A7-100T (xc7a100tcsg324-1). It renders indexed triangle meshes — textured, lit, depth-tested — with a programmable vertex stage and a programmable fragment stage.

The textured pineapple is the first showcase workload, not the architecture: the same GPU RTL renders the cube asset with no GPU changes (rtl/cube_top.v is parameters only). There is no CPU, no DDR, no flash image; make program loads volatile SRAM only.

Legacy Markdown sources under docs/*.md are preserved alongside this manual; this manual is the central, cross-linked reference.

Inline code denotes RTL identifiers, register names, and file paths. Source listings state their language explicitly:

PineBus command submission → indexed vertex fetch → programmable vertex shader → primitive assembly, cull, and setup → top-left edge rasterizer → perspective interpolation → early depth test → programmable fragment shader and texture unit → RGB444 back buffer → vblank presentation → board scanout.

rtl/gpu/ holds the graphics processor and never knows board pins or asset identity. rtl/board/ owns clocks, buttons, timing, and DVI pins. rtl/host/ (demo FSM plus camera) is the first PineBus host; a future host replaces it without touching rtl/gpu/.

All GPU logic runs on gpu_clk (50 MHz). All scanout logic runs on pix_clk (25 MHz). The only crossing is the framebuffer swap plus scanout read.

Every diagram node maps to exact files, clocks, and widths.

Second-asset proof: rtl/cube_top.v is parameters only (ASSET, INDEX_COUNT). rtl/gpu/ is untouched between pineapple and cube builds.

Only one vertex or fragment is in flight at a time, except at the rasterizer boundary, which uses ready/valid backpressure. Throughput claims about “one fragment per cycle” refer to the rasterizer’s generation rate, not the pipeline’s consumption rate.

Full formats live in Programming model. The pipeline-relevant rules:

vertex_mem[2048]x144 ({uv, normal, pos}), index_mem[16384]x16, shader_mem[512] (8 slots x 64), zmem[57600]x16, two color banks of 57,600x12, texture 16,384x48. (* rom_style="block" *) with $readmemh at build; texture is read-only during draw and packs cleanly.

write + valid → ready; writes commit only while the GPU is idle (ready = (state==0) || read). Reads are combinatorial and always ready; there is no read handshake. demo_host freezes its stream on hold during shader-upload commits so no command double-issues.

Any address with addr[15:8]==1 writes one S18 lane:

The demo host fills the 4 MVP rows as 0x100+component*4 (16 words per frame from assets/camera.mem) plus light and ambient constants at 0x140/0x144/0x148/0x14C. Shader LDU reads the addressed vec4.

Unmapped reads return 0. There is no interrupt, no DMA, no burst — by design.

Number format (S18Q12): signed 18-bit, 12 fractional bits, 1.0 = 4096:

\(wrap18(v) = ((v + 131072)\ mod\ 262144) - 131072\)

Multiply: \(rd = ((ra \cdot rb) >> 12)\) truncated, then wrapped.

Write mask .xyzw defaults to all lanes.

Example — canonical vertex shader (shaders/basic.vert):

New shaders run on the FPGA with no resynthesis. tools/pineload.py assembles a source file and sends it over USB-UART (115200 8N1, RsRx pin C4); rtl/gpu/shader_loader.v stages the payload and commits it to instruction RAM atomically between frames.

Wire frame (PINE magic, LE16 base and count, payload, 8-bit checksum):

Slots in assets/program.mem (seven baked programs, eighth slot free):

Usage:

Select D-pad mode 2 first; the new fragment program takes effect on the next frame.

tools/reference_renderer.py is integer-only and bit-exact with RTL — [s18, mul, edge, project] must be read as the specification, not as an approximation. tools/check_frame.py compares RTL frame dumps against it (CRC plus mismatch count); tools/generate_tests.py produces the randomized shader and raster vectors.

Logs: docs/validation/icarus.log, docs/validation/fpga-summary.log. Photos: docs/validation/hardware-pineapple.jpg, docs/validation/hardware-cube.jpg.

Builds: make program (pineapple), make program-cube (cube).

Live shader upload:

Yosys synthesis → nextpnr-xilinx place-and-route → Project X-Ray bitstream, reusing the installed Tomato hardware/fpga/common.mk flow in place (TOMATO_FPGA override; see root README.md). No Vivado, no CPU firmware, no copied toolchain, no destructive setup targets.

Synthesis uses -nodsp: the installed nextpnr-xilinx cannot reliably route the mapped DSP carry ports, so 18x18 multiplies stay in fabric by choice, not by accident. Widths are unchanged, so timing — not function — is affected.

100 MHz oscillator on E3 → rtl/board/clock_reset.v → divided gpu_clk 50 MHz (GPU, host, keypad, UART) and pix_clk 25 MHz (scanout, DVI), distributed with BUFG. Reset is asserted asynchronously and released synchronously with the pixel clock running (CPU_RESETN on C12).

The fabric-divided clocks are proven but fragile (~0.7% margin on the pineapple build below). Moving to Vivado/MMCM is the first timing-robustness upgrade, not a functional one.

Clock, reset, five D-pad buttons, USB-UART RsRx on C4, and 12-bit TFP410 DVI PMOD across JC/JD only (constr/nexys.xdc). Unused peripheral constraints from the Tomato source are excluded; see docs/provenance.md.

Payload alone is 3,090,432 bits (2x 57,600x12 color + 57,600x16 depth
65,536x12 texture ≈ 84 RAMB36 at ideal packing). Port width and depth rounding plus index, vertex, shader, uniform, and camera tables cost the rest.

Measured v0.2.0: 22% LUT, 42% RAMB18, 41% RAMB36 of the 100T’s 135 RAMB36. Any capacity claim must cite a post-route report, never a bit total.

Hardware PRESENT can add up to one 16.7 ms vblank wait on top. 30 fps is a measured target, never a guarantee.

From counters plus FSM latencies:

Each stage should be a separately reviewable change with passing Icarus tests and synthesis for hardware changes.