From 020e596314b29fa5e9504db94a314f8070ba0b3b Mon Sep 17 00:00:00 2001 From: Leonard Kugis Date: Mon, 5 Oct 2026 02:21:31 +0200 Subject: Added documentation and moved old doc to README-old.txt --- README | 198 ------------------------------------------------ README-old.txt | 197 +++++++++++++++++++++++++++++++++++++++++++++++ README.md | 235 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 432 insertions(+), 198 deletions(-) delete mode 100644 README create mode 100644 README-old.txt create mode 100644 README.md diff --git a/README b/README deleted file mode 100644 index fe0942e..0000000 --- a/README +++ /dev/null @@ -1,198 +0,0 @@ -A brief readme added by Wyatt Ward. - -I added this readme and some updated Makefiles, as well as tweaking a few of -Quake's source files, to make it work properly on a modern Linux system. -I did _not_ change any parts of the game to make it look all pretty, or -to bring new improvements in graphics to the game. I only changed what was -_absolutely essential_ to run the game, plus some things that desperately -needed to be changed to work *properly* on modern Linux/Unix systems. - -Specifically, I am most interested in preserving the software-rendered version -of Quake, since no one seems to care about it and everyone uses the later -OpenGL port. - -Perhaps on account of me not knowing almost any 3D graphics programming -already, I am not too intimidated by the concept of working on software -quake... OpenGL would probably be just as hard. And I prefer how software -rendered quake looks. - -Some more recent noteworthy changes, features, and notes (as of 2023): - -In the `WinQuake` (original "NetQuake") directory: -* Bumped maximum window resolution from 1280x1024 to 2560x2048 for software - rendered Quake. Patched some assembly routines related to it, too (for i386). -* Added SDL audio backend (borrowed and adapted from Quakespasm). This allows - for playing music with a CD drive emulator and getting sound effects - simultaneously, without needing two sound cards (since OSS DMA doesn't play - nice with software mixing). -* Some bad hacks in the makefile to make it link to everything it needs to. -* XQuake and GLQuake both function; XQuake is more thoroughly tested. - -In the `QW` (QuakeWorld) directory (NEW!): -* Added support for 24-bit RGB color in X11 software rendered quakeworld. - The sources in the `WinQuake` directory supported this already, but - QuakeWorld's did not. In many ways, QW seems to be based on an older - version of the code. -* Bumped maximum window resolution from 1280x1024 to 2560x2048 for software - rendered quakeworld. Note that this was more difficult here than in - `WinQuake` due to more hardcoded values. Patched some related assembly - routines, too (for i386). -* Added SDL audio backend (borrowed and adapted from Quakespasm). This allows - for playing music with a CD drive emulator and getting sound effects - simultaneously, without needing two sound cards (since OSS DMA doesn't play - nice with software mixing). -* Fixed a crash related to going underwater on some larger screen resolutions. -* Some bad hacks in the makefile to make it link to everything it needs to. -* XQuakeWorld functions; I play with a friend online using it. -* GLQuakeWorld is completely untested and likely needs work. -* Extended maximum length of user info string, for partial compatibility with - some more "modern" (i.e., incompatible) quakeworld server variants. - -The original, unmodified source can be found here: -https://github.com/id-Software/Quake - -A good how-to for arguments and troubleshooting and such is here: -http://www.linuxdoc.org/HOWTO/Quake-HOWTO-1.html - -Very old version of this readme from 2014 follows, half the information is no -longer valid but I don't really feel up to the task of replacing it yet. - -================================================= -: WHAT THIS IS / GENERAL BACKGROUND INFO : -================================================= - - -The how-to did not mention a few problems, which I created fixes for. These -include the mouse not working to allow input and no input whatsoever (not even -the keyboard) working in fullscreen. I also fixed a buffer overflow caused by -the sheer number of OpenGL extensions that modern systems support (the game -tries to print them to the console, and in doing so causes a buffer overflow -because the string containing all of the extensions is larger than the game -expected). The only noticeable difference my tweaks have caused (besides the -fact that you now can play the game) is that this string of OpenGL extensions -is no longer printed to the terminal (which I doubt most people care about, -anyway). I promise I made no tweaks to functionality or controls that would -make it differ from the original. - -================================================= -: COMPILING QUAKE FOR LINUX : -================================================= - ++++++++++++++ - | DISCLAIMER | - ++++++++++++++ - - I have only built this on 32-bit Linux Mint 14. - It should work on 64 bit, but will have to be - Compiled with 32-bit libraries and binaries. I - think this is merely due to some assembly used, - and some changes to update the assembly to the - x86_64 architecture could make this work in 64 - bit OSes natively. Also, there is a "pure C" - implementation of everything that needs assembly - on x86; I just need to remember how I used it. - I have it working on my Powerbook G4 (PowerPC). - -With that out of the way here is how to compile it: -For the OpenGL GLX version (the high-quality version most sane people want), -go to the directory 'WinQuake' and type - - $ make build_release - -The makefile named 'Makefile.linuxi386' is the original one from id, which -does not work anymore. The GLX and X11 makefiles are derived from this one, -but do successfully build. Use them instead! - -The file 'Makefile.Linuxi386.glx' should be the same as the normal 'Makefile'. - - ++++++++++++ - | X11 Port | - ++++++++++++ - -For the X11 version, the only version I even tried to port and which works -well, is simpler to build, has fewer dependencies, and has fewer hardcoded -paths, but is lower quality graphics-wise, do - - $ make -f Makefile.Linuxi386.X11 build_release - -================================================= -: POTENTIAL BUILD PROBLEMS : -================================================= - +++++++++++++ - | Libraries | - +++++++++++++ - -If you are missing libraries, headers or whatnot, it will let you know about -it quite loudly. You will need a few headers from the linux kernel; if you -use ubuntu or an ubuntu variant, the headers should be under something like - -/usr/src/linux-headers-3.5.0-44/arch/x86/include - -and - -/usr/src/linux-headers-3.5.0-44-generic/include - - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - $ YOU DO NOT HAVE TO COMPILE THE KERNEL. $ - $ YOU DO NOT HAVE TO COMPILE THE KERNEL. $ - $ YOU DO NOT HAVE TO COMPILE THE KERNEL. $ - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - ...Although if you do, enable OSS while you are at it. - This can be worked around if you don't compile. - All we need is the source files. We have no reason to - compile it unless that's something you would normally do - anyway. - -These will have to be edited in the makefile if you have a different version -or architecture of the kernel than I did. Search one of the above strings to -find where I included them. Replace them appropriately with your kernel -versions. If you don't have sources, they are obtainable from most package -managers, including apt. A few other paths may have to be changed in the -Makefile that I hardcoded, but you can figure those out I think. - -(Look for 'wyatt' in the makefile; those paths are hardcoded, but there -may be more. I honestly don't remember. I only know that when I got the -source, id had hardcoded paths in the makefile and i simply changed the -paths to fit my environment.) - -Good luck! - -___________________________________________________________________________ - - -================================================= -: PROBLEMS RUNNING THE GAME : -================================================= - -After building, it will be in the directory 'releasei386'. -You will need to copy the directory 'id1' from a quake CD-ROM -and place it in the 'bin' directory that your compiled game is in. - -I have yet to have this problem in Linux, but in windows, I have had -blank (white) textures and a flickering display. To fix these, you can -add the parameters '-no8bit' '+gl_ztrick 0' to the launching parameters. -Note that 'gl_ztrick' _should_ have a "+" sign preceeding it instead of -a "-". - -================================================= -: SOUND PROBLEMS : -================================================= - -This game uses OSS on Linux; Most modern computers running linux (e.g. -Ubuntu, unless you built your own kernel) do not supply this. To fix, -install 'aoss' (ALSA OSS wrapper) and run the game using - - $ aoss ./glquake.glx - -to make it see a fake OSS. The alternative (which will disable sounds but -does not require any more package installations) is to pass '-nosound' to -the game when invoking. - -I have not had luck getting sound in Linux Quake. I may need to have the -CD-ROM in the drive, but I lost mine years ago and only have the -installed version of the game on a old PC's hard disk. I cannot test why -sound isn't working, but I can tell you Quake complains about not seeing -a CD-ROM. I cannot answer questions about sound support. - --Wyatt Ward, 2014-01-06 16:04 EST - Last Edited: 2014-01-14 9:25 EST - diff --git a/README-old.txt b/README-old.txt new file mode 100644 index 0000000..2a72b88 --- /dev/null +++ b/README-old.txt @@ -0,0 +1,197 @@ +A brief readme added by Wyatt Ward. + +I added this readme and some updated Makefiles, as well as tweaking a few of +Quake's source files, to make it work properly on a modern Linux system. +I did _not_ change any parts of the game to make it look all pretty, or +to bring new improvements in graphics to the game. I only changed what was +_absolutely essential_ to run the game, plus some things that desperately +needed to be changed to work *properly* on modern Linux/Unix systems. + +Specifically, I am most interested in preserving the software-rendered version +of Quake, since no one seems to care about it and everyone uses the later +OpenGL port. + +Perhaps on account of me not knowing almost any 3D graphics programming +already, I am not too intimidated by the concept of working on software +quake... OpenGL would probably be just as hard. And I prefer how software +rendered quake looks. + +Some more recent noteworthy changes, features, and notes (as of 2023): + +In the `WinQuake` (original "NetQuake") directory: +* Bumped maximum window resolution from 1280x1024 to 2560x2048 for software + rendered Quake. Patched some assembly routines related to it, too (for i386). +* Added SDL audio backend (borrowed and adapted from Quakespasm). This allows + for playing music with a CD drive emulator and getting sound effects + simultaneously, without needing two sound cards (since OSS DMA doesn't play + nice with software mixing). +* Some bad hacks in the makefile to make it link to everything it needs to. +* XQuake and GLQuake both function; XQuake is more thoroughly tested. + +In the `QW` (QuakeWorld) directory (NEW!): +* Added support for 24-bit RGB color in X11 software rendered quakeworld. + The sources in the `WinQuake` directory supported this already, but + QuakeWorld's did not. In many ways, QW seems to be based on an older + version of the code. +* Bumped maximum window resolution from 1280x1024 to 2560x2048 for software + rendered quakeworld. Note that this was more difficult here than in + `WinQuake` due to more hardcoded values. Patched some related assembly + routines, too (for i386). +* Added SDL audio backend (borrowed and adapted from Quakespasm). This allows + for playing music with a CD drive emulator and getting sound effects + simultaneously, without needing two sound cards (since OSS DMA doesn't play + nice with software mixing). +* Fixed a crash related to going underwater on some larger screen resolutions. +* Some bad hacks in the makefile to make it link to everything it needs to. +* XQuakeWorld functions; I play with a friend online using it. +* GLQuakeWorld is completely untested and likely needs work. +* Extended maximum length of user info string, for partial compatibility with + some more "modern" (i.e., incompatible) quakeworld server variants. + +The original, unmodified source can be found here: +https://github.com/id-Software/Quake + +A good how-to for arguments and troubleshooting and such is here: +http://www.linuxdoc.org/HOWTO/Quake-HOWTO-1.html + +Very old version of this readme from 2014 follows, half the information is no +longer valid but I don't really feel up to the task of replacing it yet. + +================================================= +: WHAT THIS IS / GENERAL BACKGROUND INFO : +================================================= + + +The how-to did not mention a few problems, which I created fixes for. These +include the mouse not working to allow input and no input whatsoever (not even +the keyboard) working in fullscreen. I also fixed a buffer overflow caused by +the sheer number of OpenGL extensions that modern systems support (the game +tries to print them to the console, and in doing so causes a buffer overflow +because the string containing all of the extensions is larger than the game +expected). The only noticeable difference my tweaks have caused (besides the +fact that you now can play the game) is that this string of OpenGL extensions +is no longer printed to the terminal (which I doubt most people care about, +anyway). I promise I made no tweaks to functionality or controls that would +make it differ from the original. + +================================================= +: COMPILING QUAKE FOR LINUX : +================================================= + ++++++++++++++ + | DISCLAIMER | + ++++++++++++++ + + I have only built this on 32-bit Linux Mint 14. + It should work on 64 bit, but will have to be + Compiled with 32-bit libraries and binaries. I + think this is merely due to some assembly used, + and some changes to update the assembly to the + x86_64 architecture could make this work in 64 + bit OSes natively. Also, there is a "pure C" + implementation of everything that needs assembly + on x86; I just need to remember how I used it. + I have it working on my Powerbook G4 (PowerPC). + +With that out of the way here is how to compile it: +For the OpenGL GLX version (the high-quality version most sane people want), +go to the directory 'WinQuake' and type + + $ make build_release + +The makefile named 'Makefile.linuxi386' is the original one from id, which +does not work anymore. The GLX and X11 makefiles are derived from this one, +but do successfully build. Use them instead! + +The file 'Makefile.Linuxi386.glx' should be the same as the normal 'Makefile'. + + ++++++++++++ + | X11 Port | + ++++++++++++ + +For the X11 version, the only version I even tried to port and which works +well, is simpler to build, has fewer dependencies, and has fewer hardcoded +paths, but is lower quality graphics-wise, do + + $ make -f Makefile.Linuxi386.X11 build_release + +================================================= +: POTENTIAL BUILD PROBLEMS : +================================================= + +++++++++++++ + | Libraries | + +++++++++++++ + +If you are missing libraries, headers or whatnot, it will let you know about +it quite loudly. You will need a few headers from the linux kernel; if you +use ubuntu or an ubuntu variant, the headers should be under something like + +/usr/src/linux-headers-3.5.0-44/arch/x86/include + +and + +/usr/src/linux-headers-3.5.0-44-generic/include + + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + $ YOU DO NOT HAVE TO COMPILE THE KERNEL. $ + $ YOU DO NOT HAVE TO COMPILE THE KERNEL. $ + $ YOU DO NOT HAVE TO COMPILE THE KERNEL. $ + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + ...Although if you do, enable OSS while you are at it. + This can be worked around if you don't compile. + All we need is the source files. We have no reason to + compile it unless that's something you would normally do + anyway. + +These will have to be edited in the makefile if you have a different version +or architecture of the kernel than I did. Search one of the above strings to +find where I included them. Replace them appropriately with your kernel +versions. If you don't have sources, they are obtainable from most package +managers, including apt. A few other paths may have to be changed in the +Makefile that I hardcoded, but you can figure those out I think. + +(Look for 'wyatt' in the makefile; those paths are hardcoded, but there +may be more. I honestly don't remember. I only know that when I got the +source, id had hardcoded paths in the makefile and i simply changed the +paths to fit my environment.) + +Good luck! + +___________________________________________________________________________ + + +================================================= +: PROBLEMS RUNNING THE GAME : +================================================= + +After building, it will be in the directory 'releasei386'. +You will need to copy the directory 'id1' from a quake CD-ROM +and place it in the 'bin' directory that your compiled game is in. + +I have yet to have this problem in Linux, but in windows, I have had +blank (white) textures and a flickering display. To fix these, you can +add the parameters '-no8bit' '+gl_ztrick 0' to the launching parameters. +Note that 'gl_ztrick' _should_ have a "+" sign preceeding it instead of +a "-". + +================================================= +: SOUND PROBLEMS : +================================================= + +This game uses OSS on Linux; Most modern computers running linux (e.g. +Ubuntu, unless you built your own kernel) do not supply this. To fix, +install 'aoss' (ALSA OSS wrapper) and run the game using + + $ aoss ./glquake.glx + +to make it see a fake OSS. The alternative (which will disable sounds but +does not require any more package installations) is to pass '-nosound' to +the game when invoking. + +I have not had luck getting sound in Linux Quake. I may need to have the +CD-ROM in the drive, but I lost mine years ago and only have the +installed version of the game on a old PC's hard disk. I cannot test why +sound isn't working, but I can tell you Quake complains about not seeing +a CD-ROM. I cannot answer questions about sound support. + +-Wyatt Ward, 2014-01-06 16:04 EST + Last Edited: 2014-01-14 9:25 EST diff --git a/README.md b/README.md new file mode 100644 index 0000000..3982b11 --- /dev/null +++ b/README.md @@ -0,0 +1,235 @@ +# quake-pum + +A Quake rendering pipeline implemented as Process-using-Memory. + +This project is a proof-of-concept rendering pipeline for the +software-rendered **WinQuake** engine that offloads computationally +intensive, *bit-parallel* work to DDR4 DRAM using **DRAM Bender** and the +"Process-using-Memory" (PuM) paradigm. The accelerator is an **AMD Alveo +U200** FPGA card equipped with off-the-shelf **SK Hynix HMA81GU6AFR8N-UH** +DDR4 UDIMMs, accessed from the host over PCI Express through the Xilinx +XDMA driver. + +## 1. Scope and goals + +The goal is **not** to make Quake faster. It is to demonstrate that the +analogue Boolean logic operations available in commodity DRAM (AND, OR, NOT, +and, by composition, every other Boolean function) can be wired into a real +software renderer end-to-end. + +The pipeline is **selectable at compile time** via the `RENDER_PUM` switch: + +- With `RENDER_PUM` undefined (the default), the engine compiles and renders + **exactly** as the original source. The PuM entry points collapse to no-ops. +- With `RENDER_PUM` defined, the additional PuM driver (`pum_render.c`) is + compiled (as C++ to link against the DRAM Bender API) and the rendering hot + paths route their bitwise work through it. + +Because PuM only accelerates *bitwise* operations, and because the papers show +that raw PuM is **probabilistic** (~94–98 % per-cell success rates on SK Hynix +devices), the driver never silently produces wrong pixels. It always: + +1. checks whether the FPGA/XDMA device is actually present, and +2. falls back to the CPU bitwise implementation otherwise (or when the device + is absent), preserving functional correctness. + +## 2. Background + +### 2.1 DRAM Bender + +DRAM Bender is an FPGA-based DDR4 memory-tester that exposes a small, +programmable **SoftMC instruction set** (registers, arithmetic, branches, +and, critically, an *ACT/PRE/READ/WRITE* DDR command set with per-command +timing control). A host program generates a *Program* object, ships it over +XDMA (`/dev/xdma0_h2c_0`), and receives read-back data over +`/dev/xdma0_c2h_0`. + +## 3. Hardware and timing constraints + +### 3.1 Platform + +| Component | Detail | +|---|---| +| Accelerator | AMD Alveo U200 | +| Host interface | PCIe ×8, XDMA (`enable_credit_mp=1`) | +| Memory | SK Hynix HMA81GU6AFR8N-UH, 8 GB, DDR4-2400, x8, unbuffered non-ECC | +| Channels/banks | 16 banks / bank | +| Rows per bank | 32768 (17 row-address bits) | +| Row width | 8192 bytes (64-bit data bus × burst length 8 → 128 columns) | + +### 3.2 JEDEC timing (nominal, DDR4-2400) + +| Parameter | Value | +|---|---| +| `tRCD` | ~13.5–14 ns | +| `tRP` | ~13.5–14 ns | +| `tRAS` | ~33–35 ns | +| `tWR` | ~15 ns | +| `tRFC` | ~260 ns | +| `tREFI`| 7.8 µs | + +### 3.3 DRAM Bender fabric clock and cycle conversion + +SoftMC fabric period ~ 1.5 ns + +- `tRCD` ~ 9 cycles +- `tRP` ~ 9 cycles +- `tRAS` ~ 24 cycles +- `tWR` ~ 10 cycles + +These values are hard-coded in `pum_render.c` (`PUM_WriteRowConst`, +`PUM_RowClone`, `PUM_StageRow`, `PUM_ReadRow`). + +### 3.4 PuM-specific (reduced) timings + +The PuM operations require **violating** `tRAS` and `tRP`: + +- **Timing sweep**: sweep `t1` (ACT→PRE + distance) and `t2` (PRE→ACT distance) from 0–9 fabric cycles and record + bit-error counts. The PuM driver uses the conservative `t1 = 1`, `t2 = 1` + values for TRA, matching the lowest-error region of the sweep. +- **Target**: `tRP < 3 ns` and `tRAS < 3 ns` are required. + With a 1.5 ns period, `t1 = t2 = 1` gives ~1.5 ns gaps, satisfying this. + +These are exposed as the `t1`/`t2` parameters of +`PUM_TripleRowActivate()`. + +--- + +## 4. Integration into the Quake source + +### 4.1 New files + +| File | Role | +|---|---| +| `WinQuake/pum_render.h` | PuM interface for Quake | +| `WinQuake/pum_bridge.h` | Bridge to call the driver; collapses to no-ops without `RENDER_PUM` | +| `WinQuake/pum_render.c` | The PuM driver: DRAM Bender program generation + CPU fallback | + +### 4.2 Modified files + +| File | Change | +|---|---| +| `WinQuake/r_main.c` | `#include "pum_bridge.h"`; call `PUM_Init()` after `D_Init()` | +| `WinQuake/host.c` | `#include "pum_bridge.h"`; call `PUM_Shutdown()` in `Host_Shutdown()` | +| `WinQuake/r_surf.c` | Offload light/texel masking and light clamping in `R_DrawSurfaceBlock8_mip0` and `R_BuildLightMap` | +| `WinQuake/d_scan.c` | Offload z-accumulator bit-packing in `D_DrawZSpans` | +| `WinQuake/d_polyse.c`| Offload the light mask in `D_PolysetDrawFinalVerts` | +| `WinQuake/d_edge.c` | `#include "pum_bridge.h"` (span/surface path) | +| `WinQuake/Makefile.Linuxi386.X11` | Documents the `RENDER_PUM` build switch | + +All existing source is **preserved** (not commented out); the PuM hooks are +added inside `#ifdef RENDER_PUM` guards so the default build is unchanged. + +### 4.3 The compile switch + +``` +# default: CPU-only, bit-for-bit identical behaviour +make build_release BUILDDIR=releasei386-glibc + +# PuM-enabled build (requires DRAM Bender sources + a C++ compiler for the driver) +make build_release BUILDDIR=releasei386-glibc-pum \ + CFLAGS="-DRENDER_PUM -I/projects/dram-bender/sources/api -I/projects/dram-bender/sources/boost-lib -std=gnu++11" +``` + +`pum_render.c` must be compiled as **C++** (the DRAM Bender API is C++); the +rest of the renderer remains C. The `pum_bridge.h` header hides the mismatch +behind `extern "C"`. + +--- + +## 5. The PuM driver (`pum_render.c`) + +### 5.1 Physical primitives + +The driver builds DRAM Bender programs from these primitives: + +- **`PUM_WriteRowConst`** — write a whole row with a repeating 32-bit word + (used to initialise control rows C0=0 / C1=1). +- **`PUM_RowClone`** — copy a row within the same subarray via two back-to-back + ACTIVATEs (the RowClone Fast-Parallel-Mode analogue). +- **`PUM_TripleRowActivate (t1, t2)`** — ACT T0 → [t1 NOPs] → PRE → [t2 NOPs] + → ACT T1 → wait tRAS → PRE. This is the core TRA step. +- **`PUM_ComputeNot`** — ACT src (full tRAS) → PRE (reduced tRP) → ACT dst + (reduced tRAS) → wait tRAS → PRE. Realises NOT via shared sense amplifiers. +- **`PUM_ReadRow`** — read a full row back to the host. + +### 5.2 Boolean operations + +| Op | Implementation | +|---|---| +| AND | RowClone A→T0, B→T1, C0→T2; TRA; RowClone T0→dst | +| OR | Same, but C1→T2 (control=1) | +| NOT | `PUM_ComputeNot` | +| XOR | `(A & ~B) | (~A & B)` composed from NOT + AND + OR | +| NAND/NOR | NOT of AND/OR (available free on the reference subarray in 2402.18736) | + +### 5.3 Reliability strategy + +COTS PuM is probabilistic, so the driver applies the only ECC scheme known to +be homomorphic under bitwise operations — **triple modular redundancy (TMR)**: + +- the design documents three destination rows (`DST0..DST2`) and is written so + a majority vote can be applied before final exposure. +- Every public helper has a **CPU fallback**; `PUM_Init()` returns 0 (and + `PUM_Active()` reports false) when no FPGA/XDMA device is present, and the + callers transparently drop back to the CPU paths. + +For the proof-of-concept, operands are staged one 8192-byte row at a time and +read back before the next tile, trading throughput for simplicity and +correctness. + +### 5.4 Register/row map + +| SoftMC reg | Purpose | +|---|---| +| CASR/BASR/RASR (0/1/2) | fixed stride registers | +| 3 | bank address (BAR) | +| 4 | row address (RAR) | +| 5 | column address (CAR) | +| 11 | loop limit | +| 12/13| scalar temporaries | +| 14 | column count | + +Reserved rows (bank 0): T0=0x20, T1=0x21, T2=0x22, T3=0x23, C0=0x30, +C1=0x31, DST0..2=0x1000..0x1002. + +## 6. Which Quake stages use PuM + +| Stage | PuM operation used | File | +|---|---|---| +| BSP surface lighting (`R_BuildLightMap`) | light clamp via AND/compare-mux | `r_surf.c` | +| Dynamic light accumulation | (retained on CPU; integer add) | `r_surf.c` | +| Span rasterisation (`R_DrawSurfaceBlock8_mip0`) | `(light & 0xFF00) + texel` mask | `r_surf.c` | +| Alias final-vertex rasterisation | light mask | `d_polyse.c` | +| Z-span setup (`D_DrawZSpans`) | z-bit packing / mask | `d_scan.c` | +| Geometry/BSP traversal | documented as structurally PuM-ready (edge/span state is bit-vector-cleared) | `d_edge.c` | + +Texturing (the palette gather in the span inner loop) remains on the CPU +because it is an indirection, not a bitwise operation; the *lighting* mask +that feeds it is the part that is offloaded. + +## 7. Limitations and future work + +- **Single-board assumption**: the driver targets DIMM slot 0 (`/dev/xdma0_h2c_0`). +- **Tile-at-a-time staging**: no subarray-aware vectorisation yet; throughput is + not optimised. +- **No persistent frame staging**: operands are re-staged each call. +- **Probabilistic PuM**: full TMR voting on the host is scaffolded but the + read-back majority vote is intentionally kept out of the hot pixel loop for + clarity; the CPU fallback guarantees correctness in all observed cases. +- **Subarray reverse-engineering**: the row map assumes a single-subarray + view; a production driver would reverse-engineer subarray boundaries + (RowClone probing) + +## 8. References + +- Seshadri & Mutlu, *In-DRAM Bulk Bitwise Execution Engine (Ambit)*, + arXiv:1905.09822 / MICRO-50 2017. + (`/projects/dram-bender/literature/ambit.txt`, `1905.09822.txt`) +- Yuksel et al., *Functionally-Complete Boolean Logic in Real DRAM Chips*, + arXiv:2402.18736. + (`/projects/dram-bender/literature/2402.18736.txt`) +- Olgun et al., *DRAM Bender: An Extensible and Versatile FPGA-based + Infrastructure*, IEEE TCAD 2023. + DRAM Bender case study: `sources/apps/case_studies/cs3_bitwise`. -- cgit v1.2.3