From 8ca4fd800a9348ad692ec82fc96afa68a93ca1ec Mon Sep 17 00:00:00 2001
From: Rebecca Buckingham <rebeccabuckingham@users.noreply.github.com>
Date: Tue, 6 Aug 2024 11:33:19 -0400
Subject: [PATCH] Minor updates to docs.

---
 doc/.gitignore           |  1 +
 doc/hardware-updates.org | 54 ++++++++++++++++++++++++++++++++++++++++
 todo.org => doc/todo.org |  2 +-
 3 files changed, 56 insertions(+), 1 deletion(-)
 create mode 100644 doc/.gitignore
 create mode 100644 doc/hardware-updates.org
 rename todo.org => doc/todo.org (95%)

diff --git a/doc/.gitignore b/doc/.gitignore
new file mode 100644
index 0000000..b467be9
--- /dev/null
+++ b/doc/.gitignore
@@ -0,0 +1 @@
+w65c265s_datasheet.pdf
diff --git a/doc/hardware-updates.org b/doc/hardware-updates.org
new file mode 100644
index 0000000..2abbe22
--- /dev/null
+++ b/doc/hardware-updates.org
@@ -0,0 +1,54 @@
+hardware updates
+
+* hardware updates take place at regular intervals:
+- screen refresh (60 hz)
+- system timer (100 hz)
+
+* emulator itself has to process SDL events at around 60 hz.
+  - this could be handled separately from the cpu loop.
+
+* the way this often is handled
+  - we know our clock speed, 8 Mhz.
+  - something synchronizes the emulated clock speed to keep it at 8 Mhz.
+  - all events happen at certain clock intervals
+    - each clock cycle is 125 ns.
+** example: screen refresh
+  - 100 hz timer with 1 msec resolution.
+    - need to update the timer value every 1 msec
+      1 msec = 1,000,000 ns
+      1 msec = 1,000,000 ns / 125 ns per cycle = 8000 cycles
+    - after 100,000 updates, the timer fires an IRQ
+*** problems
+  - instructions take varying numbers of cycles
+  - updates could be delayed or slightly irregular
+
+hardware update (event) table.  gets updated as events occur.
+
+| event        | freq   | last update | next update | notes             |
+| ------------ | ------ | ----------- | ----------- | ----------------- |
+| 100 hz timer | 8000   | 0           | 8000        | 1 msec resolution |
+| 60 hz timer  | 133333 | 0           | 133333      | 60 hz resolution  |
+|              |        |             |             |                   |
+
+60 hz timer, assuming all 2 cycle instructions, will update
+
+* alternate approach: alter system clock so 60 hz divides cleanly
+  *idea* Could get around this by altering the system clock enough to at least
+    make the 60 hz timer work correctly.  i.e. so that we have an exact number of
+    clock cycles.  
+
+* alternate approach: accept that any event might be a bit off and pick better divisors
+  *idea* make the timer 60 hz timer 50 hz instead.  in that case,
+    50 hz = 20,000,000 ns / 125 ns = 160000 cycles.
+
+    compare to 60 hz = 16,666,666.66 ns / 125 ns = 133333.33 cycles.
+
+    ^-- sticks with the cycle-timed approach, but gets us better accuracy.
+        that kind of means that anything that doesn't fit the cycle time is 
+        going to be a bit off, but that might be true anyway.  
+
+* other thoughts
+  - smallest instruction is 2 cycles, or 300 ns.
+  - largest instruction is 8 cycles, or 1000 ns.
+    -> effectively, our resolution can only be as good as 1000 ns.
+  - 60 hz is 16.66 msec, or 133333.33 cycles
diff --git a/todo.org b/doc/todo.org
similarity index 95%
rename from todo.org
rename to doc/todo.org
index 531ea05..3509565 100644
--- a/todo.org
+++ b/doc/todo.org
@@ -20,7 +20,7 @@
   - maybe at $DF20-$DF6F
 * TODO SDL_Event logic
   - update sdl_events.c logic to process keyboard events and put them info memory.
-* TODO Possibly rewrite dispatch loop to be more readable.
+* DONE Possibly rewrite dispatch loop to be more readable.
   - we don't *have* to be as general as the library intends.
 * TODO Add more hardware to emulation.
 ** TODO 65C816 Timer(s) - Start with Timer #5 for now.