From 138cf645be7433022beead33025f8714e35c054f Mon Sep 17 00:00:00 2001
From: lonkaars <loek@pipeframe.xyz>
Date: Tue, 14 Feb 2023 16:16:52 +0100
Subject: architecture top-level added

---
 docs/architecture.drawio |  1 +
 docs/architecture.md     | 42 +++++++++++++++++++++++++++++-------------
 docs/gen/doc.m4          |  1 +
 3 files changed, 31 insertions(+), 13 deletions(-)
 create mode 100644 docs/architecture.drawio

(limited to 'docs')

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>
-- 
cgit v1.2.3