aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorlonkaars <loek@pipeframe.xyz>2023-02-14 16:16:52 +0100
committerlonkaars <loek@pipeframe.xyz>2023-02-14 16:16:52 +0100
commit138cf645be7433022beead33025f8714e35c054f (patch)
tree0616f1ee08345ad0fe18fa8cb89767d656648664
parent480062b87c08a89976428befaac781432cd37474 (diff)
architecture top-level added
-rw-r--r--assets/architecture-level-1.svg3
-rw-r--r--docs/architecture.drawio1
-rw-r--r--docs/architecture.md42
-rw-r--r--docs/gen/doc.m41
4 files changed, 34 insertions, 13 deletions
diff --git a/assets/architecture-level-1.svg b/assets/architecture-level-1.svg
new file mode 100644
index 0000000..77ba88e
--- /dev/null
+++ b/assets/architecture-level-1.svg
@@ -0,0 +1,3 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" version="1.1" width="441px" height="192px" viewBox="-0.5 -0.5 441 192" style="background-color: rgb(255, 255, 255);"><defs/><g><rect x="130" y="0" width="180" height="170" rx="13.6" ry="13.6" fill="none" stroke="rgb(0, 0, 0)" stroke-dasharray="3 3" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility" style="overflow: visible; text-align: left;"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe flex-start; justify-content: unsafe flex-end; width: 178px; height: 1px; padding-top: 177px; margin-left: 130px;"><div data-drawio-colors="color: rgb(0, 0, 0); " style="box-sizing: border-box; font-size: 0px; text-align: right;"><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; pointer-events: all; white-space: normal; overflow-wrap: normal;">Game console</div></div></div></foreignObject><text x="308" y="189" fill="rgb(0, 0, 0)" font-family="Helvetica" font-size="12px" text-anchor="end">Game console</text></switch></g><path d="M 200.5 90 L 200.5 100.5 L 190.5 85 L 200.5 69.5 L 200.5 80 L 219.5 80 L 219.5 69.5 L 229.5 85 L 219.5 100.5 L 219.5 90 Z" fill="none" stroke="rgb(0, 0, 0)" stroke-miterlimit="10" pointer-events="all"/><rect x="140" y="10" width="50" height="150" fill="rgb(255, 255, 255)" stroke="rgb(0, 0, 0)" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility" style="overflow: visible; text-align: left;"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 48px; height: 1px; padding-top: 85px; margin-left: 141px;"><div data-drawio-colors="color: rgb(0, 0, 0); " style="box-sizing: border-box; font-size: 0px; text-align: center;"><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; pointer-events: all; white-space: normal; overflow-wrap: normal;">STM32 CPU</div></div></div></foreignObject><text x="165" y="89" fill="rgb(0, 0, 0)" font-family="Helvetica" font-size="12px" text-anchor="middle">STM32 CPU</text></switch></g><path d="M 100 30 L 120 30 L 135.13 30" fill="none" stroke="rgb(0, 0, 0)" stroke-miterlimit="10" pointer-events="stroke"/><path d="M 138.88 30 L 133.88 32.5 L 135.13 30 L 133.88 27.5 Z" fill="rgb(0, 0, 0)" stroke="rgb(0, 0, 0)" stroke-miterlimit="10" pointer-events="all"/><rect x="0" y="10" width="100" height="40" fill="rgb(255, 255, 255)" stroke="rgb(0, 0, 0)" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility" style="overflow: visible; text-align: left;"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 98px; height: 1px; padding-top: 30px; margin-left: 1px;"><div data-drawio-colors="color: rgb(0, 0, 0); " style="box-sizing: border-box; font-size: 0px; text-align: center;"><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; pointer-events: all; white-space: normal; overflow-wrap: normal;">Gamepad 1</div></div></div></foreignObject><text x="50" y="34" fill="rgb(0, 0, 0)" font-family="Helvetica" font-size="12px" text-anchor="middle">Gamepad 1</text></switch></g><path d="M 100 140 L 120 140 L 135.13 140" fill="none" stroke="rgb(0, 0, 0)" stroke-miterlimit="10" stroke-dasharray="3 3" pointer-events="stroke"/><path d="M 138.88 140 L 133.88 142.5 L 135.13 140 L 133.88 137.5 Z" fill="rgb(0, 0, 0)" stroke="rgb(0, 0, 0)" stroke-miterlimit="10" pointer-events="all"/><rect x="0" y="120" width="100" height="40" fill="rgb(255, 255, 255)" stroke="rgb(0, 0, 0)" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility" style="overflow: visible; text-align: left;"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 98px; height: 1px; padding-top: 140px; margin-left: 1px;"><div data-drawio-colors="color: rgb(0, 0, 0); " style="box-sizing: border-box; font-size: 0px; text-align: center;"><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; pointer-events: all; white-space: normal; overflow-wrap: normal;">Gamepad 2</div></div></div></foreignObject><text x="50" y="144" fill="rgb(0, 0, 0)" font-family="Helvetica" font-size="12px" text-anchor="middle">Gamepad 2</text></switch></g><rect x="340" y="30" width="100" height="40" fill="rgb(255, 255, 255)" stroke="rgb(0, 0, 0)" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility" style="overflow: visible; text-align: left;"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 98px; height: 1px; padding-top: 50px; margin-left: 341px;"><div data-drawio-colors="color: rgb(0, 0, 0); " style="box-sizing: border-box; font-size: 0px; text-align: center;"><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; pointer-events: all; white-space: normal; overflow-wrap: normal;">Display</div></div></div></foreignObject><text x="390" y="54" fill="rgb(0, 0, 0)" font-family="Helvetica" font-size="12px" text-anchor="middle">Display</text></switch></g><rect x="230" y="10" width="70" height="150" fill="rgb(255, 255, 255)" stroke="rgb(0, 0, 0)" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility" style="overflow: visible; text-align: left;"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe flex-end; justify-content: unsafe center; width: 68px; height: 1px; padding-top: 157px; margin-left: 231px;"><div data-drawio-colors="color: rgb(0, 0, 0); " style="box-sizing: border-box; font-size: 0px; text-align: center;"><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; pointer-events: all; white-space: normal; overflow-wrap: normal;">FPGA</div></div></div></foreignObject><text x="265" y="157" fill="rgb(0, 0, 0)" font-family="Helvetica" font-size="12px" text-anchor="middle">FPGA</text></switch></g><rect x="340" y="90" width="100" height="40" fill="rgb(255, 255, 255)" stroke="rgb(0, 0, 0)" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility" style="overflow: visible; text-align: left;"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 98px; height: 1px; padding-top: 110px; margin-left: 341px;"><div data-drawio-colors="color: rgb(0, 0, 0); " style="box-sizing: border-box; font-size: 0px; text-align: center;"><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; pointer-events: all; white-space: normal; overflow-wrap: normal;">Speaker</div></div></div></foreignObject><text x="390" y="114" fill="rgb(0, 0, 0)" font-family="Helvetica" font-size="12px" text-anchor="middle">Speaker</text></switch></g><path d="M 290 50 L 335.13 50" fill="none" stroke="rgb(0, 0, 0)" stroke-miterlimit="10" pointer-events="stroke"/><path d="M 338.88 50 L 333.88 52.5 L 335.13 50 L 333.88 47.5 Z" fill="rgb(0, 0, 0)" stroke="rgb(0, 0, 0)" stroke-miterlimit="10" pointer-events="all"/><rect x="240" y="20" width="50" height="60" fill="rgb(255, 255, 255)" stroke="rgb(0, 0, 0)" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility" style="overflow: visible; text-align: left;"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 48px; height: 1px; padding-top: 50px; margin-left: 241px;"><div data-drawio-colors="color: rgb(0, 0, 0); " style="box-sizing: border-box; font-size: 0px; text-align: center;"><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; pointer-events: all; white-space: normal; overflow-wrap: normal;">PPU</div></div></div></foreignObject><text x="265" y="54" fill="rgb(0, 0, 0)" font-family="Helvetica" font-size="12px" text-anchor="middle">PPU</text></switch></g><path d="M 290 110 L 335.13 110" fill="none" stroke="rgb(0, 0, 0)" stroke-miterlimit="10" pointer-events="stroke"/><path d="M 338.88 110 L 333.88 112.5 L 335.13 110 L 333.88 107.5 Z" fill="rgb(0, 0, 0)" stroke="rgb(0, 0, 0)" stroke-miterlimit="10" pointer-events="all"/><rect x="240" y="80" width="50" height="60" fill="rgb(255, 255, 255)" stroke="rgb(0, 0, 0)" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility" style="overflow: visible; text-align: left;"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 48px; height: 1px; padding-top: 110px; margin-left: 241px;"><div data-drawio-colors="color: rgb(0, 0, 0); " style="box-sizing: border-box; font-size: 0px; text-align: center;"><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; pointer-events: all; white-space: normal; overflow-wrap: normal;">APU</div></div></div></foreignObject><text x="265" y="114" fill="rgb(0, 0, 0)" font-family="Helvetica" font-size="12px" text-anchor="middle">APU</text></switch></g></g><switch><g requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"/><a transform="translate(0,-5)" xlink:href="https://www.diagrams.net/doc/faq/svg-export-text-problems" target="_blank"><text text-anchor="middle" font-size="10px" x="50%" y="100%">Text is not SVG - cannot display</text></a></switch></svg> \ No newline at end of file
diff --git a/docs/architecture.drawio b/docs/architecture.drawio
new file mode 100644
index 0000000..c2ca1af
--- /dev/null
+++ b/docs/architecture.drawio
@@ -0,0 +1 @@
+<mxfile host="Electron" modified="2023-02-14T15:07:19.177Z" agent="5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) draw.io/20.8.16 Chrome/106.0.5249.199 Electron/21.4.0 Safari/537.36" etag="IyX3AqgK_EoGaR4cF0lR" version="20.8.16" type="device"><diagram name="level-1" id="QgeZH-V9oCbBHGh8xkm-">7ZjbbuIwEIafhsuVSBwOvQR62ItWi8SuerkyyTRx62QixxzSp1+bOCcClC7QsNLeoMyfycEz3287dMgkXD8IGgdP6AHv2F1v3SG3HdvuD4j61UKaCY5lBF8wL5OsUpixdzBi16gL5kFSS5SIXLK4LroYReDKmkaFwFU97QV5/akx9aEhzFzKm+oz82SQqcNet9S/A/OD/MlW15wJaZ5shCSgHq4qErnrkIlAlNlRuJ4A17XL65Jdd7/nbPFiAiJ5zAWD5+dw/eQS9mP6+3UCwXsyv/mWl3lJ+cKM+IGGkBU0QVWF7N1lmhdE4CLyQN/T6pDxKmASZjF19dmVIkBpgQy5Of3COJ8gR6HiCCOVNPZoEhSXU+Galg91xJkfqWOR1XO8BCGZasXI6BL17TmdA59iwiRDrbpq/CAq6Y9bCXOUEkOVEOKSzjfj0M8WkLD3aoySykqsQIZqDB6rhga4imIqqd4C1nt7ZBWdV44BDEGKVKXkFxDTj1XJmjU0WlDlbGBEavj2i3uVCKgDQ8EniLhpdBw85QgTopAB+hhRfleq45KJrorKnEfUHdsU5xWkTE2v6UJinRPljVifeeGwHmnXak1SIU1wO+fovukmRPkcQfKUWizwrfBp2RM9gsMdUQPGhXDhkFXM7EOFD/JA3nB3hwVwKtmy/h5n757VsPPs5xPR0mT664CXux97+Rx4O4batD7JV2jv7YK9dynY88Xoi2lvYFpj3UyUG+2e6QFtHlSi72yh75wXdPtI0Pf0+mjQN5eqQdO0khAji2RSufNUCxWE7DpCZGvR+1S6OsieXxJUDOTvobJ3Lqkx9ZRoNXj7Mg/u91yxZ6mazrmY55zr9Vxtc9KaAcm/ZMB8Tj/WgVv5l7EgOWBB+zQL+pwmiUk9hx3ttv3oNGp1y5KY07T17QJxdk7e7ZVq2CjV/fRhdFqdtj9yiq+VMxSwqNj+uX/wpfutXqOAsxjom/p8uzbWbtpmzepd7zLZ2srYP3JldE5cGU/qXL8B+fQKvr3sLcB3rDu7vr36F+O7/5/vRlEGR/Lda5PvQYPv0RXyPbwY3yos/7XNdqzlX9/k7g8=</diagram></mxfile> \ No newline at end of file
diff --git a/docs/architecture.md b/docs/architecture.md
index eb20cce..ea07cdc 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -1,8 +1,18 @@
# General system architecture
-<!-- TODO: top-level system architecture + context diagram -->
+![Top-down system architecture diagram](../assets/architecture-level-1.svg)
-## PPU
+Important notes:
+
+- Gamepad 2 is optionally connected
+- The PPU and APU are implemented on the FPGA
+- The game logic and PPU/APU control logic runs on the STM32 only
+
+# Game controllers
+
+# STM32 software
+
+# PPU
Here's a list of features our PPU has:
@@ -79,9 +89,9 @@ Notable differences:
Our game doesn't need this capability for any visual effects. Leaving this
feature out will lead to a simpler hardware design
-### Hardware design schematics
+## Hardware design schematics
-#### Top (level 1)
+### Top (level 1)
![PPU top-level design](../assets/ppu-level-1.svg)
@@ -104,7 +114,7 @@ Important notes:
- NVSYNC, NHSYNC and the RGB signals refer to the output of the native VGA
signal generator.
-#### Level 2
+### Level 2
![PPU level 2 design (data flows from top to bottom)](../assets/ppu-level-2.svg)
@@ -135,7 +145,7 @@ Important notes:
the RAM in it's own cache memory. The cache updates are fetched during the
VBLANK time between each frame.
-#### Level 3
+### Level 3
This diagram has several flaws, but a significant amount of time has already
been spent on these, so they are highlighted here instead of being fixed.
@@ -162,11 +172,13 @@ Important notes:
each foreground sprite the PPU allows.
- The CIDX lines between the sprite and compositor components is shared by all
sprite components, and is such tri-state. A single sprite component outputs a
- CIDX signal based on the \*EN signal from the compositor.
+ CIDX signal based on the EN signal from the compositor.
- All DATA and ADDR lines are shared between all RAM ports. WEN inputs are
controlled by the address decoder.
-### Registers
+<!--
+
+## Registers
|Address|Size (bytes)|Alias|Description|
|-|-|-|-|
@@ -177,32 +189,36 @@ Important notes:
|`0x00000`|`0x00000`|BAX |[background auxiliary memory][BAX]|
[TMM]: #tilemap-memory
-#### Tilemap memory
+### Tilemap memory
- TODO: list format
[BAM]: #background-attribute-memory
-#### Background attribute memory
+### Background attribute memory
- TODO: list format
[FAM]: #foreground-attribute-memory
-#### Foreground attribute memory
+### Foreground attribute memory
- TODO: list format
[PAL]: #palettes
-#### Palettes
+### Palettes
- TODO: list format
[BAX]: #background-auxiliary-memory
-#### Background auxiliary memory
+### Background auxiliary memory
- background scrolling
+-->
+
[nesppuspecs]: https://www.copetti.org/writings/consoles/nes/
[nesppudocs]: https://www.nesdev.org/wiki/PPU_programmer_reference
[nesppupinout]: https://www.nesdev.org/wiki/PPU_pinout
[custompputimings]: https://docs.google.com/spreadsheets/d/1MU6K4c4PtMR_JXIpc3I0ZJdLZNnoFO7G2P3olCz6LSc
+# APU
+
diff --git a/docs/gen/doc.m4 b/docs/gen/doc.m4
index 1ddf094..5c20483 100644
--- a/docs/gen/doc.m4
+++ b/docs/gen/doc.m4
@@ -4,6 +4,7 @@ define(`docname',
NAME, `research', `Research document',
NAME, `design', `Design document',
NAME, `gameplay', `Game design document',
+ NAME, `architecture', `Architecture document',
`UNKNOWN???'))dnl
<!DOCTYPE html>