documentation update, added STATUS.md document

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