From ef84fb6fcb45a86fce97acda58606a76a937a1da Mon Sep 17 00:00:00 2001
From: "Juan J. Martinez" <jjm@usebox.net>
Date: Mon, 1 May 2023 21:44:35 +0100
Subject: Added the VM player using SDL

- Wired basic functionality (fram-buffer, frame interrupt)
- Bug fixes in the assembler
---
 README.md | 51 +++++++++++++++++++++++++++++++++++++++++++--------
 1 file changed, 43 insertions(+), 8 deletions(-)

(limited to 'README.md')

diff --git a/README.md b/README.md
index 33e39b6..d847d49 100644
--- a/README.md
+++ b/README.md
@@ -7,7 +7,7 @@ TR8 is an 8-bit fantasy console inspired by MIPS, Z80 and 6502 real world CPUs.
 ## Specs
 
 ```
-Display:  128 x 128 pixels 16 colors (from palette of 32)
+Display:  128 x 128 pixels 16 colors
 Memory:   64K
 CPU:      TR-8, 8M VM instr/sec
 Sound:    TBD
@@ -62,7 +62,6 @@ You can then compile and run the example with `make example`.
 
 | Port | Type | Result |
 | --- | --- | --- |
-| 0xe0 to 0xef | write | Color select |
 | 0xf0 | read | Status of the controller 1 |
 | 0xf1 | read | Status of the controller 2 |
 
@@ -87,10 +86,47 @@ controller 1, and `0xf1` for controller 2.
 
 ### Palette
 
-Ports from `0xe0` to `0xef` can be used to select the colors to use in the 16
-color palette from the 32 available.
+TODO: palette colors
 
-TODO: palette colours
+### Frame interrupt
+
+When interrupts are enabled (IF not set), 60 times per second there will be a
+frame interrupt:
+
+* the PC is saved on the stack
+* the F register (flags) is saved on the stack
+* all the flags are cleared and IF is set
+* the execution goes to the address in `0xff00` (the frame interrupt vector)
+* the interruption handler code must return with `IRET`, that will restore
+  the PC and the F register
+
+By default the vector points to `0x0000` so it has to be setup before enabling
+interrupts with `CIF`.
+
+Example:
+
+```asm
+    ; setup an int handler so we
+    ; can use the frame int o sync
+    ld a, 0xff
+    ld x, 0
+    ld b, <int_handler
+    ld [a : x], b
+    inc x
+    ld b, >int_handler
+    ld [a : x], b
+
+    ; enable interrupts
+    cif
+
+loop:
+    halt
+    jmp loop
+
+int_handler:
+    ; just return
+    iret
+```
 
 ### Instructions
 
@@ -363,7 +399,7 @@ Affected flags: IF
 
 CIF  
 Clear IF, enabling the interrupt. If called in an interrupt handler, it won't
-have effect. Use IRET instead to return from the interrupt to unset IF.  
+have effect. Use IRET instead to return from the interrupt.  
 Affected flags: IF
 
 CCF  
@@ -379,8 +415,7 @@ Clear overflow flag.
 Affected flags: OF
 
 IRET  
-Return from an interrupt handler by setting PC to the top 16-bit value popped
-from the stack. It enables interrupts by clearing the interrupt flag.  
+Return from an interrupt handler by restoring F and PC from the stack.  
 Affected flags: IF
 
 ### TR8 file format
-- 
cgit v1.2.3