From 138eb3e6bc175e6675f22702b09bd8756b317003 Mon Sep 17 00:00:00 2001
From: uvok
Date: Tue, 6 Jan 2026 19:46:26 +0100
Subject: Documentation

---
 README.txt                    | 13 ++++++++++++-
 nandgame/README.txt           |  7 +++++++
 nandgame/assembler/README.txt | 11 +++++++++++
 3 files changed, 30 insertions(+), 1 deletion(-)
 create mode 100644 nandgame/README.txt
 create mode 100644 nandgame/assembler/README.txt

diff --git a/README.txt b/README.txt
index 18c6ece..0865867 100644
--- a/README.txt
+++ b/README.txt
@@ -1,3 +1,10 @@
+This is a collection of Verilog files.
+Written as I'm learning about the language and FPGAs.
+
+Contents:
+- This directory
+- nandgame: Implementation of the nandgame.com CPU
+
 Learnings:
 
 - Anything that needs to "store" a state must be a reg?
@@ -18,10 +25,14 @@ Questions:
 - Does yosys and other tools "automatically" determine the
   "perfect" wire/register (bus) width if I just specify e.g.
   wire BLA = 1374;
-  ?
+  - Nope, that's a single bit, it will be truncated
 - The book tasked me with writing a serial-to-parallel and parallel-to-serial converter.
   But I think I wrote it "wrong"?
   If I used this in the real world, and chained both components together,
   things would go wrong. as the output is flipped at the rising clock
   edge - violating timings and leading to unpredictable behavior?
   Or not?
+  - nope, synthesis tools "take care of and check" timing.
+    It "somehow just works".
+    Or rather, stuff is delayed by one clock cycle, e.g.
+    when chaining flip-flops together.
diff --git a/nandgame/README.txt b/nandgame/README.txt
new file mode 100644
index 0000000..e84462f
--- /dev/null
+++ b/nandgame/README.txt
@@ -0,0 +1,7 @@
+This contains the implementation of the nandgame computer.
+I didn't bother with building the low-level gates / flip-flops / latches, though.
+I just use what Verilog already offers.
+
+Contents:
+- This directory
+- assembler: Assembler and disassembler
diff --git a/nandgame/assembler/README.txt b/nandgame/assembler/README.txt
new file mode 100644
index 0000000..4dbe14a
--- /dev/null
+++ b/nandgame/assembler/README.txt
@@ -0,0 +1,11 @@
+Contents:
+- createbin.py: Create a binary file with all possible instructions.
+  At least ones that "do something". Not just loading a value.
+- disas.py: disassembler
+- disas_test.py: Test cases for disassembler
+
+Assembly language:
+I have no idea, I just know that I don't like
+the syntax introduced by nandgame / nand2teris.
+I prefer a more "classical" approach.
+See disassembler for an example.
-- 
cgit v1.2.3