documentation update, added STATUS.md document

STATUS.md

@@ -0,0 +1,113 @@
+# New features
+
+
+Here are the features of the Open ROMs not found in the original ROMs from the 80s:
+
+* improved keyboard scanning, supports multi-key roll-over and rejection of spurious joystick input
+* joystick (port 1) can be used to move text cursor
+* banking in the BASIC interpreter: 61436 bytes free
+* LOAD start/end addresses are displayed, in the Final cartridge style
+* LOAD command with just the file name tries to use the last device if it's number seems sane; otherwise uses 8
+
+
+# Features missing
+
+
+The following ROM features are currently missing:
+
+* most BASIC commands
+* BASIC variables
+* BASIC expression parsing
+* floating point routines
+* tape support
+* RS-232 support
+* warm start (RUN/STOP + RESTORE) - NMI is not implemented at all
+* breaking Kernal routines with RUN/STOP key
+
+Features currently being worked on:
+
+* IEC support
+* DOS wedge
+
+
+# API status
+
+
+Status of the various APIs and variables from the original ROMs
+
+
+## Page 0
+
+
+TODO
+
+
+## Pages 2 & 3
+
+
+TODO
+
+
+## BASIC
+
+
+TODO
+
+
+## Kernal
+
+
+Note: only the jump table addresses are currently supported, real routine addresses are different!
+
+
+### Official Kernal routines
+
+NOTE: Even the 'DONE' routines won't support features described as missing in one of the previous chapters!
+
+
+| Address | Name   | Status   |  Remarks                                |
+| ------- | :----: | :------: | :-------------------------------------: |
+| $FF81   | CINT   | PARTIAL  | at least PAL/NTSC detection is missing  |
+| $FF84   | IOINIT | PARTIAL  | at least SID volume handling is missing |
+| $FF87   | RAMTAS | DONE     |                                         |
+| $FF8A   | RESTOR | PARTIAL  | CBINV, NMINV, and USRCMD missing        |
+| $FF8D   | VECTOR | DONE     |                                         |
+| $FF90   | SETMSG | DONE     |                                         |
+| $FF93   | SECOND | PARTIAL  | * work in progress                      |
+| $FF96   | TKSA   | PARTIAL  | should probably also do a turnaround    |
+| $FF99   | MEMTOP | DONE     |                                         |
+| $FF9C   | MEMBOT | DONE     |                                         |
+| $FF9F   | SCNKEY | DONE     | could be better integrated with ROM     |
+| $FFA2   | SETTMO | NOT DONE |                                         |
+| $FFA5   | ACPTR  | NOT DONE | * work in progress                      |
+| $FFA8   | CIOUT  | PARITAL  | * work in progress                      |
+| $FFAB   | UNTLK  | PARITAL  | * work in progress                      |
+| $FFAE   | UNLSN  | PARITAL  | * work in progress                      |
+| $FFB1   | LISTEN | PARTIAL  | * work in progress                      |
+| $FFB4   | TALK   | PARTIAL  | * work in progress                      |
+| $FFB7   | READST | DONE     |                                         |
+| $FFBA   | SETFLS | DONE     |                                         |
+| $FFBD   | SETNAM | DONE     |                                         |
+| $FFC0   | OPEN   | NOT DONE | * work in progress                      |
+| $FFC3   | CLOSE  | PARTIAL  | * work in progress                      |
+| $FFC6   | CHKIN  | NOT DONE | * work in progress                      |
+| $FFC9   | CHKOUT | NOT DONE | * work in progress                      |
+| $FFCC   | CLRCHN | NOT DONE | * work in progress                      |
+| $FFCF   | CHRIN  | NOT DONE | * work in progress                      |
+| $FFD2   | CHROUT | NOT DONE | * work in progress                      |
+| $FFD5   | LOAD   | PARTIAL  | no VERIFY support yet                   |
+| $FFD8   | SAVE   | NOT DONE | * work in progress                      |
+| $FFDB   | SETTIM | NOT DONE |                                         |
+| $FFDE   | RDTIM  | NOT DONE |                                         |
+| $FFE1   | STOP   | PARTIAL  | no connection with UDTIM                |
+| $FFE4   | GETIN  | PARTIAL  | * work in progress                      |
+| $FFE7   | CLALL  | PARTIAL  | * work in progress                      |
+| $FFEA   | UDTIM  | NOT DONE |                                         |
+| $FFED   | SCREEN | DONE     |                                         |
+| $FFF0   | PLOT   | NOT DONE |                                         |
+| $FFF3   | IOBASE | DONE     |                                         |
+
+
+### Unofficial Kernal locations
+
+TODO

c64/kernal/chrin.s

@@ -8,6 +8,7 @@
 ;; CPU registers that has to be preserved (see [RG64]): .Y
 ;;
 
+;; XXX currently does not preserve register Y, to be fixed!
 
 	;;  Reads a byte of input, unless from keyboard.
 	;; If from keyboard, then it gets a whole line of input, and returns the first char.

c64/kernal/ciout.s

@@ -1,7 +1,16 @@
-; Function defined on pp272-273 of C64 Programmers Reference Guide
-ciout:
 
-	;; This routine is documented in 'Compute's Mapping the Commodore 64', page 224
+;;
+;; Official Kernal routine, described in:
+;;
+;; - [RG64] C64 Programmer's Reference Guide   - page 279/280
+;; - [CM64] Compute's Mapping the Commodore 64 - page 224
+;;
+;; CPU registers that has to be preserved (see [RG64]): .X, .Y
+;;
+
+;; XXX currently does not preserve registers, to be fixed!
+
+ciout:
 
 	pha
 	lda C3PO

c64/kernal/clall.s

@@ -1,15 +1,26 @@
 
+;;
+;; Official Kernal routine, described in:
+;;
+;; - [RG64] C64 Programmer's Reference Guide   - page 281
+;; - [CM64] Compute's Mapping the Commodore 64 - page 230
+;;
+;; CPU registers that has to be preserved (see [RG64]): .Y
+;;
+
+;; XXX currently does not preserve register Y, to be fixed!
+
 clall:
 
-	;; Implemented according to 'C64 Programmer's Reference Guide', page 281
-	;; Not entirely sure if it just sets LDTND to 0 or actually calls CLOSE,
-	;; but calling CLOSE for all open channels seems to be the safest
+	;; Original routine probably just sets LDTND to 0, but this is not really safe,
+	;; so we actually close all the channels; at least IDE64 does the same for
+	;; it's channels, see CLALL description in the IDE64 User's Guide
 
 	ldy LDTND
 	beq +
 	dey
 	lda LAT, y
-	jsr close
+	jsr close ; XXX jump through ICLOSE?
 	jmp clall
 *
 	;; 'C64 Programmers Reference Guide', page 281, claims it calls CLRCHN too

c64/kernal/close.s

@@ -1,7 +1,14 @@
-; Function defined on pp272-273 of C64 Programmers Reference Guide
-close:
 
-	;; Implemented accorging to 'C64 Programmers Reference Guide', page 281
+;;
+;; Official Kernal routine, described in:
+;;
+;; - [RG64] C64 Programmer's Reference Guide   - page 281/282
+;; - [CM64] Compute's Mapping the Commodore 64 - page 229/230
+;;
+;; CPU registers that has to be preserved (see [RG64]): none
+;;
+
+close:
 
 	;; XXX this needs more testing (opening 10 files at once, closing in various orders, etc) once the code is more mature
 

c64/kernal/clrchn.s

@@ -1,3 +1,12 @@
-; Function defined on pp272-273 of C64 Programmers Reference Guide
+
+;;
+;; Official Kernal routine, described in:
+;;
+;; - [RG64] C64 Programmer's Reference Guide   - page 282
+;; - [CM64] Compute's Mapping the Commodore 64 - page 230
+;;
+;; CPU registers that has to be preserved (see [RG64]): .Y
+;;
+
 clrchn:
 	rts

c64/kernal/fff3.jiobase.s

@@ -1,8 +1,18 @@
-; $FFF3 - Get page of IO devices
-; Returns Y=$DC, X=$00
-; (http://codebase64.org/doku.php?id=base:kernalreference)
-;
-; As there is nothing between here and $FFFA, we can just hard code this in place.
+
+;;
+;; Official Kernal routine, described in:
+;;
+;; - [RG64] C64 Programmer's Reference Guide   - page 284
+;; - [CM64] Compute's Mapping the Commodore 64 - page 214
+;; - http://codebase64.org/doku.php?id=base:kernalreference (original source)
+;;
+;; CPU registers that has to be preserved (see [RG64]): .A
+;;
+
+
+;; As there is nothing between here and $FFFA, we can just hard code this in place.
+
+iobase:
     ldy #$DC
     ldx #$00
     rts

c64/kernal/getin.s

@@ -1,4 +1,15 @@
-; Function defined on pp272-273 of C64 Programmers Reference Guide
+
+;;
+;; Official Kernal routine, described in:
+;;
+;; - [RG64] C64 Programmer's Reference Guide   - page 283
+;; - [CM64] Compute's Mapping the Commodore 64 - page 227/228
+;;
+;; CPU registers that has to be preserved (see [RG64]): .X, .Y
+;;
+
+;; XXX currently does not preserve registers, to be fixed!
+
 getin:
 
 	;; Wait for a key

c64/kernal/listen.s

@@ -1,4 +1,14 @@
-; Function defined on pp272-273 of C64 Programmers Reference Guide
+
+;;
+;; Official Kernal routine, described in:
+;;
+;; - [RG64] C64 Programmer's Reference Guide   - page 285
+;; - [CM64] Compute's Mapping the Commodore 64 - page 223
+;;
+;; CPU registers that has to be preserved (see [RG64]): .X, .Y
+;;
+
+;; XXX currently does not preserve registers, to be fixed!
 
 listen:
 

c64/kernal/load.s

@@ -1,7 +1,15 @@
-	; Function defined on pp272-273 of C64 Programmers Reference Guide
-	;; IEC reference at http://www.zimmers.net/anonftp/pub/cbm/programming/serial-bus.pdf
 
-	;; Definition of function from Compute's Mapping the 64 p231
+;;
+;; Official Kernal routine, described in:
+;;
+;; - [RG64] C64 Programmer's Reference Guide   - page 286
+;; - [CM64] Compute's Mapping the Commodore 64 - page 231
+;; - IEC reference at http://www.zimmers.net/anonftp/pub/cbm/programming/serial-bus.pdf
+;;
+;; CPU registers that has to be preserved (see [RG64]): none
+;;
+
+
 	;; Expects that SETLFS and SETNAM are called before hand.
 	;; $YYXX = load address.
 	;; (ignored if SETLFS channel = 1, i.e., like ,8,1)

c64/kernal/membot.s

@@ -1,13 +1,23 @@
-; Function defined on pp272-273 of C64 Programmers Reference Guide
+
+;;
+;; Official Kernal routine, described in:
+;;
+;; - [RG64] C64 Programmer's Reference Guide   - page 287/288
+;; - [CM64] Compute's Mapping the Commodore 64 - page 240
+;;
+;; CPU registers that has to be preserved (see [RG64]): .A
+;;
+
 membot:
-	; p287 C64 Programmers reference guide
-	;;  http://unusedino.de/ec64/technical/project64/mapping_c64.html
+
 	bcc membot_set
 	
-	LDX MEMSTR+0
-	LDY MEMSTR+1
+	ldx MEMSTR+0
+	ldy MEMSTR+1
 	rts
+
 membot_set:
+
 	stx MEMSTR+0
 	stx MEMSTR+1
 	

c64/kernal/memtop.s

@@ -1,14 +1,23 @@
-; Function defined on pp272-273 of C64 Programmers Reference Guide
+
+;;
+;; Official Kernal routine, described in:
+;;
+;; - [RG64] C64 Programmer's Reference Guide   - page 288
+;; - [CM64] Compute's Mapping the Commodore 64 - page 240
+;;
+;; CPU registers that has to be preserved (see [RG64]): .A
+;;
+
 memtop:
-	; p288 C64 Programmer's reference guide
-	; but for now we only support reading it
-	;;  http://unusedino.de/ec64/technical/project64/mapping_c64.html
+
 	bcc memtop_set
 	
-	LDY MEMSIZ+1
-	LDX MEMSIZ+0
+	ldy MEMSIZ+1
+	ldx MEMSIZ+0
 	rts
+
 memtop_set:
+
 	sty MEMSIZ+1
 	stx MEMSIZ+0
 	

c64/kernal/open.s

@@ -1,7 +1,14 @@
-	; Function defined on pp272-273 of C64 Programmers Reference Guide
-	;; See also http://www.zimmers.net/anonftp/pub/cbm/programming/serial-bus.pdf
 
-;; XXX rework this, according to pagetable.com
+;;
+;; Official Kernal routine, described in:
+;;
+;; - [RG64] C64 Programmer's Reference Guide   - page 289
+;; - [CM64] Compute's Mapping the Commodore 64 - page 230/231
+;;
+;; CPU registers that has to be preserved (see [RG64]): none
+;;
+
+;; XXX this is only a test implementation, does not do what the Kernal does!
 
 open:
 

c64/kernal/plot.s

@@ -1,2 +1,12 @@
+
+;;
+;; Official Kernal routine, described in:
+;;
+;; - [RG64] C64 Programmer's Reference Guide   - page 290
+;; - [CM64] Compute's Mapping the Commodore 64 - page 215
+;;
+;; CPU registers that has to be preserved (see [RG64]): none
+;;
+
 plot:
 	rts

c64/kernal/rdtim.s

@@ -1,3 +1,12 @@
-; Function defined on pp272-273 of C64 Programmers Reference Guide
+
+;;
+;; Official Kernal routine, described in:
+;;
+;; - [RG64] C64 Programmer's Reference Guide   - page 291
+;; - [CM64] Compute's Mapping the Commodore 64 - page 232
+;;
+;; CPU registers that has to be preserved (see [RG64]): none
+;;
+
 rdtim:
 	rts

c64/kernal/readst.s

@@ -1,10 +1,18 @@
-; Function defined on pp272-273 of C64 Programmers Reference Guide
+
+;;
+;; Official Kernal routine, described in:
+;;
+;; - [RG64] C64 Programmer's Reference Guide   - page 292
+;; - [CM64] Compute's Mapping the Commodore 64 - page 239
+;;
+;; CPU registers that has to be preserved (see [RG64]): .X, .Y
+;;
 
 readst:
 
 	;; Check the current device number
 
-	lda DFLTN
+	lda current_device_number
 	cmp #$02
 	bne +
 	

c64/kernal/save.s

@@ -1,3 +1,13 @@
-; Function defined on pp272-273 of C64 Programmers Reference Guide
+
+;;
+;; Official Kernal routine, described in:
+;;
+;; - [RG64] C64 Programmer's Reference Guide   - page 293/294
+;; - [CM64] Compute's Mapping the Commodore 64 - page 231/232
+;; - IEC reference at http://www.zimmers.net/anonftp/pub/cbm/programming/serial-bus.pdf
+;;
+;; CPU registers that has to be preserved (see [RG64]): none
+;;
+
 save:
 	rts

c64/kernal/scan_keyboard.s

@@ -1,9 +1,19 @@
-	;; Scan the keyboard..
-	;; Here we don't use the horrible buggy original routine,
-	;; not just because of copyright. Instead, we use the
-	;; nice one with joystick interference removal and
-	;; key roll-over support from
-	;; http://codebase64.org/doku.php?id=base:scanning_the_keyboard_the_correct_and_non_kernal_way
+
+;;
+;; Official Kernal routine, described in:
+;;
+;; - [RG64] C64 Programmer's Reference Guide   - page 295
+;; - [CM64] Compute's Mapping the Commodore 64 - page 220
+;;
+;; CPU registers that has to be preserved (see [RG64]): none
+;;
+
+;; Scan the keyboard..
+;; Here we don't use the horrible buggy original routine,
+;; not just because of copyright. Instead, we use the
+;; nice one with joystick interference removal and
+;; key roll-over support from
+;; http://codebase64.org/doku.php?id=base:scanning_the_keyboard_the_correct_and_non_kernal_way
 
 ;; /*~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 ;;     Keyboard IO Routine

c64/kernal/screen.s

@@ -1,4 +1,12 @@
-; Function defined on p295 of C64 Programmers Reference Guide
+
+;;
+;; Official Kernal routine, described in:
+;;
+;; - [RG64] C64 Programmer's Reference Guide   - page 295
+;; - [CM64] Compute's Mapping the Commodore 64 - page 215
+;;
+;; CPU registers that has to be preserved (see [RG64]): .A
+;;
 
 screen:
 

c64/kernal/second.s

@@ -1,8 +1,19 @@
-; Function defined on pp272-273 of C64 Programmers Reference Guide
+
+;;
+;; Official Kernal routine, described in:
+;;
+;; - [RG64] C64 Programmer's Reference Guide   - page 296
+;; - [CM64] Compute's Mapping the Commodore 64 - page 223/224
+;;
+;; CPU registers that has to be preserved (see [RG64]): .X, .Y
+;;
+
+;; XXX currently does not preserve registers, to be fixed!
+
 second:
 
-	;; This trivial routine is documented in 'C64 Programmer's Reference Guide', page 296 and
-	;; https://www.pagetable.com/?p=1031, , https://github.com/mist64/cbmbus_doc
+	;; see also https://www.pagetable.com/?p=1031, , https://github.com/mist64/cbmbus_doc
+
 	and #$1F ; make sure bits encoding the command are cleared out
 	ora #$60
 	jmp iec_tx_command

c64/kernal/setfls.s

@@ -1,4 +1,12 @@
-; Function defined on pp272-273 of C64 Programmers Reference Guide
+
+;;
+;; Official Kernal routine, described in:
+;;
+;; - [RG64] C64 Programmer's Reference Guide   - page 297
+;; - [CM64] Compute's Mapping the Commodore 64 - page 238
+;;
+;; CPU registers that has to be preserved (see [RG64]): .A, .X, .Y
+;;
 
 setfls:
 

c64/kernal/setmsg.s

@@ -1,4 +1,13 @@
-; Function defined on pp272-273 of C64 Programmers Reference Guide
+
+;;
+;; Official Kernal routine, described in:
+;;
+;; - [RG64] C64 Programmer's Reference Guide   - page 298
+;; - [CM64] Compute's Mapping the Commodore 64 - page 239
+;;
+;; CPU registers that has to be preserved (see [RG64]): .A, .X, .Y
+;;
+
 setmsg:
 	sta MSGFLG
 	rts

c64/kernal/setnam.s

@@ -1,4 +1,12 @@
-; Function defined on pp272-273 of C64 Programmers Reference Guide
+
+;;
+;; Official Kernal routine, described in:
+;;
+;; - [RG64] C64 Programmer's Reference Guide   - page 298/299
+;; - [CM64] Compute's Mapping the Commodore 64 - page 238
+;;
+;; CPU registers that has to be preserved (see [RG64]): .A, .X, .Y
+;;
 
 setnam:
 

c64/kernal/settim.s

@@ -1,3 +1,12 @@
-; Function defined on pp272-273 of C64 Programmers Reference Guide
+
+;;
+;; Official Kernal routine, described in:
+;;
+;; - [RG64] C64 Programmer's Reference Guide   - page 299/300
+;; - [CM64] Compute's Mapping the Commodore 64 - page 232
+;;
+;; CPU registers that has to be preserved (see [RG64]): .A, .X, .Y
+;;
+
 settim:
 	rts

c64/kernal/settmo.s

@@ -1,3 +1,12 @@
-; Function defined on pp272-273 of C64 Programmers Reference Guide
+
+;;
+;; Official Kernal routine, described in:
+;;
+;; - [RG64] C64 Programmer's Reference Guide   - page 300
+;; - [CM64] Compute's Mapping the Commodore 64 - page 239
+;;
+;; CPU registers that has to be preserved (see [RG64]): .A, .X, .Y
+;;
+
 settmo:
 	rts

c64/kernal/stop.s

@@ -1,4 +1,13 @@
-; Function defined on pp272-273 of C64 Programmers Reference Guide
+
+;;
+;; Official Kernal routine, described in:
+;;
+;; - [RG64] C64 Programmer's Reference Guide   - page 301
+;; - [CM64] Compute's Mapping the Commodore 64 - page 232
+;;
+;; CPU registers that has to be preserved (see [RG64]): .Y
+;;
+
 stop:
 	;; Bit 7 of BUCKYSTATUS contains the state of the STOP key
 	;; (Compute's Mapping the 64, p27)
@@ -8,10 +17,10 @@ stop:
 	and #$80
 	beq stop_pressed
 
-	;;  By trial and error, we know that Z + C = BREAK
+	;; By trial and error, we know that Z + C = BREAK
 	;; and that neither should be set otherwise
 	lda #$ff
-	clc	
+	clc
 	rts
 
 stop_pressed:

c64/kernal/talk.s

@@ -1,9 +1,20 @@
-; Function defined on pp272-273 of C64 Programmers Reference Guide
+
+;;
+;; Official Kernal routine, described in:
+;;
+;; - [RG64] C64 Programmer's Reference Guide   - page 301/302
+;; - [CM64] Compute's Mapping the Commodore 64 - page 223
+;;
+;; CPU registers that has to be preserved (see [RG64]): .X, .Y
+;;
+
+;; XXX currently does not preserve registers, to be fixed!
+;; XXX shouldn't this do a turnaround?
 
 talk:
 
-	;; This routine is documented in 'Compute's Mapping the Commodore 64', page 223 and
-	;; https://www.pagetable.com/?p=1031, , https://github.com/mist64/cbmbus_doc
+	;; See also https://www.pagetable.com/?p=1031, https://github.com/mist64/cbmbus_doc
+
 	and #$1F ; make sure bits encoding the command are cleared out
 	ora #$40
 	jmp iec_tx_command

c64/kernal/tksa.s

@@ -1,8 +1,20 @@
-; Function defined on pp272-273 of C64 Programmers Reference Guide
+
+;;
+;; Official Kernal routine, described in:
+;;
+;; - [RG64] C64 Programmer's Reference Guide   - page 302
+;; - [CM64] Compute's Mapping the Commodore 64 - page 224
+;;
+;; CPU registers that has to be preserved (see [RG64]): .X, .Y
+;;
+
+;; XXX currently does not preserve registers, to be fixed!
+;; XXX shouldn't this do a turnaround?
+
 tksa:
 
-	;; This routine is documented in 'C64 Programmer's Reference Guide', page 302 and
-	;; https://www.pagetable.com/?p=1031, , https://github.com/mist64/cbmbus_doc
+	;; See also https://www.pagetable.com/?p=1031, , https://github.com/mist64/cbmbus_doc
+
 	and #$1F ; make sure bits encoding the command are cleared out
 	ora #$F0
 	jmp iec_tx_command

c64/kernal/unlsn.s

@@ -1,4 +1,14 @@
-; Function defined on pp272-273 of C64 Programmers Reference Guide
+
+;;
+;; Official Kernal routine, described in:
+;;
+;; - [RG64] C64 Programmer's Reference Guide   - page 303
+;; - [CM64] Compute's Mapping the Commodore 64 - page 224
+;;
+;; CPU registers that has to be preserved (see [RG64]): .X, .Y
+;;
+
+;; XXX currently does not preserve registers, to be fixed!
 
 unlsn:
 

c64/kernal/untlk.s

@@ -1,4 +1,15 @@
-; Function defined on pp272-273 of C64 Programmers Reference Guide
+
+;;
+;; Official Kernal routine, described in:
+;;
+;; - [RG64] C64 Programmer's Reference Guide   - page 304
+;; - [CM64] Compute's Mapping the Commodore 64 - page 224
+;;
+;; CPU registers that has to be preserved (see [RG64]): .X, .Y
+;;
+
+;; XXX currently does not preserve registers, to be fixed!
+;; XXX shouldn't this do a turnaround?
 
 untlk:
 

c64/kernal/update_jiffy_clock.s

@@ -1,2 +1,12 @@
+
+;;
+;; Official Kernal routine, described in:
+;;
+;; - [RG64] C64 Programmer's Reference Guide   - page 303
+;; - [CM64] Compute's Mapping the Commodore 64 - page 232
+;;
+;; CPU registers that has to be preserved (see [RG64]): .Y
+;;
+
 update_jiffy_clock:
 	rts