added new library files and fixed comments in others

git-svn-id: https://svn.code.sf.net/p/acme-crossass/code-0/trunk@324 4df02467-bbd4-4a76-a152-e7ce94205b78

ACME_Lib/6502/rc4.a

@@ -5,24 +5,48 @@ lib_6502_rc4_a = 1
 
 ; this is an implementation of the stream cipher algorithm known as RC4.
 
-; you need to define these symbols in your code:
+; you need to define these addresses in your code:
-;	rc4_length	a single byte to hold key/chunk lengths
+;   single bytes:
-;	rc4_count	a single byte (tmp var for iteration counter)
+;	rc4_length	key/chunk length (only used temporarily)
-;	rc4_ii		a single byte to hold state
+;	rc4_count	iteration count (only used temporarily)
-;	rc4_jj		a single byte to hold state
+;	rc4_ii		holds internal state (do not touch!)
-;	rc4_state	a full page of memory (256 bytes)
+;	rc4_jj		holds internal state (do not touch!)
+;   multi-byte areas:
+;	rc4_state	256 bytes of internal state (do not touch!)
 ;	rc4_key		key buffer
 ;	rc4_in		input buffer
 ;	rc4_out		output buffer
-; the size of the buffers limits how much data you can pass to the functions.
+; the sizes of the buffers limit how much data you can pass to the functions.
 ; all three buffer addresses may be identical, in that case the output will
 ; overwrite the input (and/or the key).
+
 ; functions you can then call:
 ;	rc4_init	initialise state
 ;	rc4_usekey_X	use key (in key buffer, length in X) to change state
 ;	rc4_reset	reset ii and jj (call between keying and processing)
 ;	rc4_process_X	de/encrypt data from input to output buffer (length in X)
 
+; here's some example code:
+!if 0 {
+	!src <6502/rc4.a>	; include this file
+entrypoint
+		jsr rc4_init	; (re-)init rc4 internal state
+	[copy user-supplied key (or its hash) to key buf]
+	[maybe append some salt to keybuf]
+		; do this at least once, but some
+		; algorithms need you to do this N times:
+			ldx #TOTALKEYLENGTH
+			jsr rc4_usekey_X
+		; end of (optional) loop
+		jsr rc4_reset
+	[copy chunk of input data to input buffer]
+		ldx #CHUNKSIZE
+		jsr rc4_process_X
+	[read from output buffer]
+		rts
+	+rc4_code		; place actual code
+}
+
 !macro rc4_code {
 	; create shorter names
 	.length	= rc4_length

ACME_Lib/cbm/c128/keys.a

@@ -0,0 +1,54 @@
+;ACME 0.97
+
+!ifdef lib_cbm_c128_keys_a !eof
+lib_cbm_c128_keys_a = 1
+
+;           bit in $dc01:
+;   7   6   5   4   3   2   1   0
+;(Joy1:       BUT RGHT LFT DWN UP)
+;                                   | c64 keys:
+;                                   | bit in $dc00:
+;                                   |     (Joy2:)
+;  DOWN F5  F3  F1  F7 RGHT CR DEL  |   0 (UP)
+;  LSHF E   S   Z   4   A   W   3   |   1 (DOWN)
+;   X   T   F   C   6   D   R   5   |   2 (LEFT)
+;   V   U   H   B   8   G   Y   7   |   3 (RIGHT)
+;   N   O   K   M   0   J   I   9   |   4 (BUTTON)
+;   ,   @   :   .   -   L   P   +   |   5
+;   /   ^   = RSHF HOME ;   * POUND |   6
+;  STOP Q  CBM SPC  2 CTRL  <-  1   |   7
+;
+;                                   | additional c128 keys:
+;                                   | bit in $d02f:
+;   1   7   4   2  TAB  5   8  HELP |   0
+;   3   9   6 ENTER LF  -   +  ESC  |   1
+;  NS RGHT LFT DWN  UP  .   0  ALT  |   2
+
+; values for "current key number" in C128 zeropage location $d4:
+	!src <cbm/c64/keys.a>	; values 00..63 are compatible to C64
+keynumber_HELP		= 64
+keynumber_KEYPAD8	= 65
+keynumber_KEYPAD5	= 66
+keynumber_TAB		= 67
+keynumber_KEYPAD2	= 68
+keynumber_KEYPAD4	= 69
+keynumber_KEYPAD7	= 70
+keynumber_KEYPAD1	= 71
+keynumber_ESC		= 72
+keynumber_KEYPADPLUS	= 73
+keynumber_KEYPADMINUS	= 74
+keynumber_LINEFEED	= 75
+keynumber_KEYPADENTER	= 76
+keynumber_KEYPAD6	= 77
+keynumber_KEYPAD9	= 78
+keynumber_KEYPAD3	= 79
+keynumber_ALT		= 80
+keynumber_KEYPAD0	= 81
+keynumber_KEYPADPOINT	= 82
+keynumber_CRSR128UP	= 83
+keynumber_CRSR128DOWN	= 84
+keynumber_CRSR128LEFT	= 85
+keynumber_CRSR128RIGHT	= 86
+keynumber_NOSCROLL	= 87
+keynumberC128_NONE	= 88	; no key pressed (C64 uses 64 instead)
+

ACME_Lib/cbm/c128/vdc.a

@@ -149,47 +149,47 @@ vdcstate_VERSIONMASK	= %...#####	; vdc version (0, 1 or 2)
 
 
 ; indirect registers		(default value, see $e179 in C128 kernal)
-vdcr_htotal		= $00	; 126 (127 for PAL, depends on kernal version)	characters per line, minus one
+vdcr_htotal		= 0	; 126 (127 for PAL, depends on kernal version)	characters per line, minus one
-vdcr_columns		= $01	; 80	characters per line, actually displayed
+vdcr_columns		= 1	; 80	characters per line, actually displayed
- vdcr_hdisp		= $01
+ vdcr_hdisp		= 1
-vdcr_hsync_pos		= $02	; 102	character position to send horizontal sync in
+vdcr_hsync_pos		= 2	; 102	character position to send horizontal sync in
-vdcr_syncwidth		= $03	; $49	4b vertical, 4b horizontal
+vdcr_syncwidth		= 3	; $49	4b vertical, 4b horizontal
-vdcr_vtotal		= $04	; 32 (39 or 38 for PAL, depends on kernal version)	character lines per screen, minus one
+vdcr_vtotal		= 4	; 32 (39 or 38 for PAL, depends on kernal version)	character lines per screen, minus one
-vdcr_vadjust		= $05	; 0	additional scan lines per screen (to fix timings)
+vdcr_vadjust		= 5	; 0	additional scan lines per screen (to fix timings)
-vdcr_lines		= $06	; 25	character lines per screen, actually displayed
+vdcr_lines		= 6	; 25	character lines per screen, actually displayed
- vdcr_vdisp		= $06
+ vdcr_vdisp		= 6
-vdcr_vsync_pos		= $07	; 29 (32 for PAL)	character line to send vertical sync in
+vdcr_vsync_pos		= 7	; 29 (32 for PAL)	character line to send vertical sync in
-vdcr_interlace		= $08	; 0	interlace mode (0=2=std, 1=jitter, 3=interlace)
+vdcr_interlace		= 8	; 0	interlace mode (0=2=std, 1=jitter, 3=interlace)
-vdcr_charheight_total	= $09	; 7	5b total, minus one
+vdcr_charheight_total	= 9	; 7	5b total, minus one
-vdcr_crsr_start		= $0a	; $20	2b mode, 5b scanline
+vdcr_crsr_start		= 10	; $20	2b mode, 5b scanline (top line of cursor)
 	vdcr_CRSRSTART_MODE_MASK	= %.##.....
 ;	vdcr_CRSRSTART_MODE_FIXED	= %........	; fixed cursor
 	vdcr_CRSRSTART_MODE_OFF		= %..#.....	; invisible
 	vdcr_CRSRSTART_MODE_FAST	= %.#......	; flashing with 1/16 of refresh freq
 	vdcr_CRSRSTART_MODE_SLOW	= %.##.....	; flashing with 1/32 of refresh freq
-vdcr_crsr_end		= $0b	; 7		5b scanline
+vdcr_crsr_end		= 11	; 7		5b scanline (bottom line of cursor, plus 1, so should be 8 instead of 7!)
-vdcr_display_hi		= $0c	; 0	RAM address of display buffer
+vdcr_display_hi		= 12	; 0	RAM address of display buffer,
-vdcr_display_lo		= $0d	; 0
+vdcr_display_lo		= 13	; 0		see "hardscroll" notes below
-vdcr_crsr_hi		= $0e	; 0	RAM address of cursor
+vdcr_crsr_hi		= 14	; 0	RAM address of cursor
-vdcr_crsr_lo		= $0f	; 0
+vdcr_crsr_lo		= 15	; 0
-vdcr_lp_y		= $10	; --	y position of light pen (lines, plus 1)
+vdcr_lp_y		= 16	; --	y position of light pen (lines, plus 1)
-vdcr_lp_x		= $11	; --	x position of light pen (characters, plus 8)
+vdcr_lp_x		= 17	; --	x position of light pen (characters, plus 8)
-vdcr_ram_hi		= $12	; --	RAM address of register $1f (reading/writing register $1f automatically increments this address)
+vdcr_ram_hi		= 18	; --	RAM address of register 31 (reading/writing r31
-vdcr_ram_lo		= $13	; --
+vdcr_ram_lo		= 19	; --		automatically increments this address)
-vdcr_attr_hi		= $14	; $08	RAM address of attribute buffer
+vdcr_attr_hi		= 20	; $08	RAM address of attribute buffer,
-vdcr_attr_lo		= $15	; $00
+vdcr_attr_lo		= 21	; $00		see "hardscroll" notes below
-vdcr_charwidth		= $16	; $78	4b total minus one, 4b displayed minus one
+vdcr_charwidth		= 22	; $78	4b total minus one, 4b displayed
-vdcr_charheight_disp	= $17	; 8	5b displayed, minus one
+vdcr_charheight_disp	= 23	; 8	5b displayed, minus one (so 7 would suffice)
-vdcr_control_v		= $18	; $20	vertical scroll and much other stuff
+vdcr_control_v		= 24	; $20	vertical scroll and much other stuff
 	vdcr_CONTROLV_BLOCKMODE_MASK	= %#.......
-;	vdcr_CONTROLV_BLOCKMODE_WRITE	= %........	; writing to register $1e starts block write
+;	vdcr_CONTROLV_BLOCKMODE_WRITE	= %........	; writing to register 30 starts block write
-	vdcr_CONTROLV_BLOCKMODE_COPY	= %#.......	; writing to register $1e starts block copy
+	vdcr_CONTROLV_BLOCKMODE_COPY	= %#.......	; writing to register 30 starts block copy
 	vdcr_CONTROLV_REVERSESCREEN	= %.#......
 	vdcr_CONTROLV_FLASHFREQ_MASK	= %..#.....
 ;	vdcr_CONTROLV_FLASHFREQ_FAST	= %........
 	vdcr_CONTROLV_FLASHFREQ_SLOW	= %..#.....
 	vdcr_CONTROLV_UPSCROLL_MASK	= %...#####
-vdcr_control_h		= $19	; $47 ($40 for vdc version 0)	horizontal scroll and much other stuff
+vdcr_control_h		= 25	; $47 ($40 for vdc version 0)	horizontal scroll and much other stuff
 	vdcr_CONTROLH_MODE_MASK		= %#.......
 ;	vdcr_CONTROLH_MODE_TEXT		= %........
 	vdcr_CONTROLH_MODE_BITMAP	= %#.......
@@ -200,25 +200,25 @@ vdcr_control_h		= $19	; $47 ($40 for vdc version 0)	horizontal scroll and much o
 	vdcr_CONTROLH_PIXELWIDTH_MASK	= %...#....
 ;	vdcr_CONTROLH_PIXELWIDTH_NARROW	= %........
 	vdcr_CONTROLH_PIXELWIDTH_WIDE	= %...#....
-	vdcr_CONTROLH_LEFTSCROLL_MASK	= %....####
+	vdcr_CONTROLH_RIGHTSCROLL_MASK	= %....####
-vdcr_color		= $1a	; $f0	4b foreground, 4b background
+vdcr_color		= 26	; $f0	4b foreground, 4b background
-	vdcr_COLOR_FOREGROUND_MASK	= %####....	; only used if attributes are off (see bit 6 of reg $19)
+	vdcr_COLOR_FOREGROUND_MASK	= %####....	; only used if attributes are off (see bit 6 of reg 25)
 	vdcr_COLOR_BACKGROUND_MASK	= %....####
-vdcr_row_inc		= $1b	; 0	address increment per row
+vdcr_row_inc		= 27	; 0	address increment per row
-vdcr_charset		= $1c	; $20	3b charset pointer, 1b RAM type, 4b unused
+vdcr_charset		= 28	; $20	3b charset pointer, 1b RAM type, 4b unused
 	vdcr_CHARSET_ADRESS_MASK	= %###.....
 	vdcr_CHARSET_RAMTYPE_MASK	= %...#....
 ;	vdcr_CHARSET_RAMTYPE_16K	= %........
 	vdcr_CHARSET_RAMTYPE_64K	= %...#....
-vdcr_underline		= $1d	; 7	5b scanline
+vdcr_underline		= 29	; 7	5b scanline
-vdcr_cycles		= $1e	; --	number of write- or copy-cycles. 0 means 256.
+vdcr_cycles		= 30	; --	number of write- or copy-cycles. 0 means 256.
-vdcr_access		= $1f	; --	contents of RAM selected by registers $12/$13
+vdcr_access		= 31	; --	contents of RAM selected by registers 18/19
-vdcr_source_hi		= $20	; --	start address for block copy
+vdcr_source_hi		= 32	; --	start address for block copy (block copying
-vdcr_source_lo		= $21	; --
+vdcr_source_lo		= 33	; --		automatically increments this address)
-vdcr_enable_start	= $22	; 125	column to enable display in
+vdcr_enable_start	= 34	; 125	column to enable display in (6 is left of text)
-vdcr_enable_end		= $23	; 100	column to disable display in
+vdcr_enable_end		= 35	; 100	column to disable display in (86 is right of text)
-vdcr_dram_refresh	= $24	; 5	RAM refresh cycles per line (lower 4 bits)
+vdcr_dram_refresh	= 36	; 5	RAM refresh cycles per line (lower 4 bits)
-vdcr_sync_polarity	= $25	; --	only in VDC 8568
+vdcr_sync_polarity	= 37	; --	only in VDC 8568
 	vdcr_HSYNC_POLARITY	= %#.......
 	vdcr_VSYNC_POLARITY	= %.#......
 
@@ -232,3 +232,9 @@ vdcr_sync_polarity	= $25	; --	only in VDC 8568
 	rom8_vdc_to_vic_color_table	= $81f3 ; 00 0c 06 0e 05 0d 0b 03 02 0a 08 04 09 07 0f 01
 	romc_vic_to_vdc_color_table	= $ce5c ; 00 0f 08 07 0b 04 02 0d 0a 0c 09 06 01 05 03 0e
 }
+
+; "hardscroll" notes:
+; the vdc seems to read the values from registers 12/13/20/21 (screen ram and
+; attribute ram) at the _end_ of the display window, so if you change these
+; registers in the lower border, the next frame will still use the old values.
+; this is important if you want to combine hardscroll and softscroll.

ACME_Lib/cbm/c128/zeropage.a

@@ -381,7 +381,7 @@ lib_cbm_c128_zeropage_a = 1
 	z_vicscn	= $0400
 	z_system	= $0a00
 	z_dejavu	= $0a02
-	z_palnts	= $0a03
+	z_palnts	= $0a03	; bit7 set means PAL
 	z_init_status	= $0a04
 	z_memstr	= $0a05
 	z_memsiz	= $0a07
@@ -402,7 +402,7 @@ lib_cbm_c128_zeropage_a = 1
 	z_rodbs		= $0a1a
 	z_rodbe		= $0a1b
 	z_serial	= $0a1c
-	z_timer		= $0a1d
+	z_timer		= $0a1d	; decrementing counter for SLEEP (low/medium/high)
 	z_xmax		= $0a20
 	z_pause		= $0a21
 	z_rptflg	= $0a22
@@ -426,7 +426,7 @@ lib_cbm_c128_zeropage_a = 1
 	z_curcol	= $0a33
 	z_split		= $0a34
 	z_fnadrx	= $0a35
-	z_palcnt	= $0a36
+	z_palcnt	= $0a36	; countdown timer for TI's PAL adjustment (every fifth PAL irq, have an additional TI tick)
 	z_speed		= $0a37
 	z_sprites	= $0a38
 	z_blanking	= $0a39

ACME_Lib/cbm/c64/keys.a

@@ -0,0 +1,84 @@
+;ACME 0.97
+
+!ifdef lib_cbm_c64_keys_a !eof
+lib_cbm_c64_keys_a = 1
+
+;           bit in $dc01:           | bit in
+;   7   6   5   4   3   2   1   0   | $dc00:
+;(Joy1:       BUT RGHT LFT DWN UP)  |     (Joy2:)
+;-----------------------------------+---------
+;  DOWN F5  F3  F1  F7 RGHT CR DEL  |   0 (UP)
+;  LSHF E   S   Z   4   A   W   3   |   1 (DOWN)
+;   X   T   F   C   6   D   R   5   |   2 (LEFT)
+;   V   U   H   B   8   G   Y   7   |   3 (RIGHT)
+;   N   O   K   M   0   J   I   9   |   4 (BUTTON)
+;   ,   @   :   .   -   L   P   +   |   5
+;   /   ^   = RSHF HOME ;   * POUND |   6
+;  STOP Q  CBM SPC  2 CTRL  <-  1   |   7
+
+; values for "current key number" in C64 zeropage location $cb:
+keynumber_DEL		= 0
+keynumber_RETURN	= 1
+keynumber_CURSORRIGHT	= 2
+keynumber_F7		= 3
+keynumber_F1		= 4
+keynumber_F3		= 5
+keynumber_F5		= 6
+keynumber_CURSORDOWN	= 7
+keynumber_3		= 8
+keynumber_W		= 9
+keynumber_A		= 10
+keynumber_4		= 11
+keynumber_Z		= 12
+keynumber_S		= 13
+keynumber_E		= 14
+keynumber_LEFTSHIFT	= 15
+keynumber_5		= 16
+keynumber_R		= 17
+keynumber_D		= 18
+keynumber_6		= 19
+keynumber_C		= 20
+keynumber_F		= 21
+keynumber_T		= 22
+keynumber_X		= 23
+keynumber_7		= 24
+keynumber_Y		= 25
+keynumber_G		= 26
+keynumber_8		= 27
+keynumber_B		= 28
+keynumber_H		= 29
+keynumber_U		= 30
+keynumber_V		= 31
+keynumber_9		= 32
+keynumber_I		= 33
+keynumber_J		= 34
+keynumber_0		= 35
+keynumber_M		= 36
+keynumber_K		= 37
+keynumber_O		= 38
+keynumber_N		= 39
+keynumber_PLUS		= 40
+keynumber_P		= 41
+keynumber_L		= 42
+keynumber_MINUS		= 43
+keynumber_POINT		= 44
+keynumber_COLON		= 45
+keynumber_AT		= 46
+keynumber_COMMA		= 47
+keynumber_POUND		= 48
+keynumber_ASTERISK	= 49
+keynumber_SEMICOLON	= 50
+keynumber_HOME		= 51
+keynumber_RIGHTSHIFT	= 52
+keynumber_EQUALS	= 53
+keynumber_UPARROW	= 54
+keynumber_SLASH		= 55
+keynumber_1		= 56
+keynumber_LEFTARROW	= 57
+keynumber_CTRL		= 58
+keynumber_2		= 59
+keynumber_SPACE		= 60
+keynumber_CBM		= 61
+keynumber_Q		= 62
+keynumber_STOP		= 63
+keynumberC64_NONE	= 64	; no key pressed (C128 uses 88 instead)

ACME_Lib/cbm/c64/reu.a

@@ -16,16 +16,16 @@ rec_STATUS_IRQ		= %#.......
 rec_STATUS_END		= %.#......
 rec_STATUS_ERROR	= %..#.....	; for verify command
 rec_STATUS_TYPE		= %...#....	; chip type (do not use to determine unit size!)
-rec_STATUS_VERSION	= %....####
+rec_STATUS_VERSION	= %....####	; always zero
 !address {
 	; command register
 	rec_command	= $df01
 }
-rec_COMMAND_EXECUTE	= %#.......
+rec_COMMAND_EXECUTE	= %#.......	; setting this starts the operation
-;reserved		= %.#......
+;reserved		= %.#......	; register bit exists, but does nothing
-rec_COMMAND_RELOAD	= %..#.....
+rec_COMMAND_RELOAD	= %..#.....	; reload address registers when done (do not use in verify mode, because you want the address in case of an error!)
 rec_COMMAND_IMMEDIATELY	= %...#....	; do not wait for $ff00 write
-;reserved		= %....##..
+;reserved		= %....##..	; register bits exist, but do nothing
 rec_COMMAND_MODE_MASK	= %......##	; bit mask for the four modes
 rec_COMMAND_MODE_STASH	= %........	; computer-to-REU
 rec_COMMAND_MODE_FETCH	= %.......#	; REU-to-computer
@@ -40,7 +40,7 @@ rec_COMMAND_FETCH	= %#.#....#	;	starting and then reload values.
 	; external address (expansion RAM)
 	rec_ext_low	= $df04
 	rec_ext_high	= $df05
-	rec_ext_bank	= $df06
+	rec_ext_bank	= $df06	; upper five bits always read as 1
 	; A stock 1700 unit has two banks (128 KiB).
 	; A stock 1764 unit has four banks (256 KiB).
 	; A stock 1750 unit has eight banks (512 KiB).
@@ -50,14 +50,18 @@ rec_COMMAND_FETCH	= %#.#....#	;	starting and then reload values.
 	rec_amount_low	= $df07	; using $0000 results in
 	rec_amount_high	= $df08	;	64 KiB being transferred
 	; when to request interrupts
-	rec_irqctrl	= $df09
+	rec_irqctrl	= $df09	; lower five bits always read as 1
 }
 rec_IRQCTRL_ENABLE	= %#.......
 rec_IRQCTRL_ON_END	= %.#......
 rec_IRQCTRL_ON_ERROR	= %..#.....	; for verify errors
 !address {
 	; address control (set to zero for normal operation)
-	rec_addrctrl	= $df0a
+	rec_addrctrl	= $df0a	; lower six bits always read as 1
 }
 rec_ADDRCTRL_FIX_INT	= %#.......
 rec_ADDRCTRL_FIX_EXT	= %.#......
+
+	; $df0b..$df1f always read as $ff,
+	; at $df20 the registers repeat.
+	; these "32 registers" are visible 8 times in the $df00 page.