diff options
| -rw-r--r-- | docs/abbreviations.md | 20 | ||||
| -rw-r--r-- | docs/architecture.md | 85 | ||||
| -rw-r--r-- | docs/gen/doc.m4 | 4 | ||||
| -rw-r--r-- | docs/makefile | 8 |
4 files changed, 93 insertions, 24 deletions
diff --git a/docs/abbreviations.md b/docs/abbreviations.md new file mode 100644 index 0000000..76bd046 --- /dev/null +++ b/docs/abbreviations.md @@ -0,0 +1,20 @@ +# List of abbreviations + +- MSB (most significant bit) +- LSB (least significant bit) +- DMA (direct memory access) +- LUT (lookup table) +- RAM (random access memory) +- PPU (picture processing unit) + - NES (Nintendo entertainment system) + - OAM (object attribute memory) + - TMM (tilemap memory) + - BAM (background attribute memory) + - FAM (foreground attribute memory) + - PAL (palette memory) + - AUX (auxiliary memory) + - HUD (heads-up display) +- APU (audio processing unit) + - PWM (pulse width modulation) + - ADSR (attack, decay, sustain, release) +- CPU (central processing unit) diff --git a/docs/architecture.md b/docs/architecture.md index 6b37604..a60e0da 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -224,51 +224,96 @@ Important notes: ## Registers -|Address|Size (bytes)|Alias|Description| +- The PPU's memory bus has 16-bit addresses and 16-bit words. +- Some memory regions use physical word sizes smaller than 16-bits, so + "unneeded" bits will be discarded by the PPU. +- All "fields" or words containing multiple bit strings representing different + pieces of information are ordered from MSB to LSB. + +|Address offset|Size (16-bit words)|Alias|Description| |-|-|-|-| -|`0x00000`|`0x00000`|TMM |[tilemap memory][TMM]| -|`0x00000`|`0x00000`|BAM |[background attribute memory][BAM]| -|`0x00000`|`0x00000`|FAM |[foreground attribute memory][FAM]| -|`0x00000`|`0x00000`|PAL |[palettes][PAL]| -|`0x00000`|`0x00000`|AUX |[auxiliary memory][AUX]| +|`0x0000`|`0xc000`|TMM |[tilemap memory][TMM]| +|`0xc000`|`0x04b0`|BAM |[background attribute memory][BAM]| +|`0xc800`|`0x0100`|FAM |[foreground attribute memory][FAM]| +|`0xcc00`|`0x0040`|PAL |[palettes][PAL]| +|`0xce00`|`0x0002`|AUX |[auxiliary memory][AUX]| + +This table contains the "official" PPU register offsets and sizes. Due to the +way the address decoder works, some of these memory regions might be duplicated +in the address ranges between the memory regions. This is considered undefined +behavior, so the CPU should not attempt to write in these locations because +there is no address validity checking. [TMM]: #tilemap-memory ### Tilemap memory -- TODO: list format +- Each sprite takes up 768 bits spread across 48 16-bit words +- Sprites and pixels are stored adjacently in memory without padding +- Pixel order is from top-left to bottom-right in (English) reading order. [BAM]: #background-attribute-memory ### Background attribute memory -- 15-bit words (padded with 1 bit) -- 11-bit address width (1200 15-bit words with padding 1) +- 15-bit words (MSB discarded in hardware) +- Address indicates which background sprite is currently targeted in reading order + e.g. $\textrm{addr} = c000_{\textrm{hex}} + x + y*w$ where $x$ and $y$ are the background tile, and $w$ is the amount of horizontal tiles fit on the background layer (40) + +Word format: -- TODO: list format +|Range (VHDL)|Description| +|-|-| +|`15`|Flip horizontally| +|`14`|Flip vertically| +|`13`|(unused)| +|`12 downto 10`|Palette index for tile| +|`9 downto 0`|Tilemap index| [FAM]: #foreground-attribute-memory ### Foreground attribute memory -- 2 * 16-bit words -- 8-bit address width (256 16-bit words for 128 * 32-bit) +- 32-bit words +- Sprites with lower addresses are drawn "before" sprites with higher addresses + +Word format: -- TODO: list format +|Range (VHDL)|Description| +|-|-| +|`31`|Flip horizontally| +|`30`|Flip vertically| +|`29 downto 21`|horizontal position (offset by -16)| +|`20 downto 13`|vertical position (offset by -16)| +|`12 downto 10`|Palette index for tile| +|`9 downto 0`|Tilemap index| [PAL]: #palettes ### Palettes -- 12-bit words -- 6-bit address width (2^6 = 64 colors total) +- 12-bit words (4 MSB discarded in hardware) +- Address formula for palette color is $p_i*8 + p_c$ where $p_i$ is the palette + index and $p_c$ is the color index within a given palette. -- TODO: list format +Word format: + +|Range (VHDL)|Description| +|-|-| +|`15 downto 13`|(discarded)| +|`12 downto 8`|Red value| +|`7 downto 4`|Green value| +|`3 downto 0`|Blue value| [AUX]: #auxiliary-memory ### Auxiliary memory -- background scrolling (8 + 9 bits) -- fetch foreground sprites bit (1 bit) +- no words + +Format: -- 16-bit words -- 1-bit address width +|Range (VHDL)|Description| +|-|-| +|`31 downto 18`|(unused)| +|`17`|Fetch foreground sprites flag| +|`16 downto 8`|Horizontal background scroll (offset from left edge)| +|`7 downto 0`|Vertical background scroll (offset from top edge)| [custompputimings]: https://docs.google.com/spreadsheets/d/1MU6K4c4PtMR_JXIpc3I0ZJdLZNnoFO7G2P3olCz6LSc diff --git a/docs/gen/doc.m4 b/docs/gen/doc.m4 index b98eb64..c9cbcf5 100644 --- a/docs/gen/doc.m4 +++ b/docs/gen/doc.m4 @@ -6,7 +6,8 @@ define(`docname', NAME, `gameplay', `Game design document', NAME, `architecture', `Architecture document', `UNKNOWN???'))dnl - +define(`abbreviations',`undivert(`abbreviations.con')')dnl +dnl <!DOCTYPE html> <html lang="en-US"> <link> @@ -43,6 +44,7 @@ define(`docname', Niels Stunnebrink <b>(2184532)</b> </span> </div> + ifelse(NAME, `architecture', `abbreviations', `') <h1>Table of contents</h1> undivert(NAME`.toc') undivert(NAME`.con') diff --git a/docs/makefile b/docs/makefile index e4fcb15..a729024 100644 --- a/docs/makefile +++ b/docs/makefile @@ -5,7 +5,9 @@ CHROME = chromium --headless --run-all-compositor-stages-before-draw --virtual-t CURL = curl PUP = pup -SRCS = $(wildcard *.md) +SRCS += gameplay.md \ + research.md \ + architecture.md HTML_T = $(SRCS:.md=.html) PDF_T = $(SRCS:.md=.pdf) @@ -22,8 +24,8 @@ gen/paged.polyfill.js: %.toc: %.md $(PANDOC) $< -s --toc --to=html 2> /dev/null | $(PUP) '#TOC' | sed -r 's/<(.?)ul>/<\1ol>/g' > $@ -%.html: %.con %.toc gen/doc.m4 gen/paged.polyfill.js gen/style.css - $(M4) -Igen -DNAME=$(basename $<) gen/doc.m4 > $@ +%.html: %.con %.toc gen/doc.m4 gen/paged.polyfill.js gen/style.css abbreviations.con + $(M4) -Igen -I. -DNAME=$(basename $<) gen/doc.m4 > $@ %.pdf: %.html $(CHROME) --print-to-pdf=$@ $< 2> /dev/null |