From 75cf6ff9417c2fd81821f02d93da0062092823ce Mon Sep 17 00:00:00 2001
From: Lewpen <lewpen@lewpen.com>
Date: Sat, 28 Sep 2024 18:19:54 +0100
Subject: [PATCH] Update README.md

---
 README.md | 54 +++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 53 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 72fe6bf..c00affe 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,54 @@
 # 6502_THE_SPREADSHEET
-All 6502 instructions in byte order with all the expressions to update registers and memory for each - allowing for easy construction of emulators and disassemblers. Supports reverse mode for stepping backwards through execution trace.
+
+All 6502 instructions with their actions completely unrolled so you don't have to pick through detailed documentation to understand what they do or how to emulate them accurately.
+
+The spreadsheet is under construction and is at:
+https://docs.google.com/spreadsheets/d/1rCwO6CoIXiCqkJUaZ5Q9W5QZNqmhLpXaAhSthJPuV8I/edit?gid=0#gid=0
+
+## How it works
+
+For each instruction there is a set of expressions for each of the necessary memory reads, register updates, flag updates, and memory writes.
+
+These expressions are provided in a simple portable form, just using the symbols + - << >> & | () and are thus valid expressions in many different programming languages from JavaScript to Go - enabling easy code generation using basic string manipulation of the spreadsheet rows (as TSV, for instance).
+
+## Making an Emulator or Disassembler
+
+Each row can be turned into a small block of code which processes that particular instruction.
+
+The basic flow of the generated code for an emulator would be something like this. After setting up the initial memory, register variables, and PC pointing to the start of the program:
+
+* Get byte at PC; this is the instruction
+
+* Use a set of generated if statements which check for each possible byte value, and if that's the current byte then do the following:
+
+* Do memory fetches for this instruction (if any)
+
+* Calculate updated values for registers and flags (if any)
+
+* Do memory writes (if any)
+
+* Update register and flag variables with the new values (including PC)
+
+* Loop around to get the next instruction or halt if PC has not changed value
+
+## Reversibility
+
+The spreadsheet also details for each instruction what data needs to be saved and what register, flag and memory changes need to be made to roll back the instruction.
+
+This is the information which would otherwise be trashed by the instruction.
+
+If you incorporate the recording of these values into your emulator as it executes, then you gain the ability to step backwards through the previously executed instructions when debugging.
+
+## Keep It Simple
+
+If you don't want to mess around with code generation, your 6502-enabled program can just have the spreadsheet itself in memory - probably broken down into an array of lines - and then do the string processing of the row on the fly to perform the operation or disassemble the instruction.
+
+The expressions for the updates to registers etc. are few enough that you can check for each one as a string specifically and perform the equivalent calculation in code.
+
+## Roadmap:
+
+1) Complete basic list of instructions and first pass of the actions of each
+2) Run through each instruction making sure its expressions are correct
+3) Make codegen examples for JavaScript and Go for disassemblers and emulators
+4) Make test cases and put it through its paces
+