# HG changeset patch
# User boisy
# Date 1063979872 0
# Node ID 146dfa918a9c1a364b86abae573caa0e920277be
# Parent  2b0af03a79152ac7ac0fc4bec7bc29a769e01aa3
Added comments

diff -r 2b0af03a7915 -r 146dfa918a9c level2/modules/cc3io.asm
--- a/level2/modules/cc3io.asm	Thu Sep 18 12:38:15 2003 +0000
+++ b/level2/modules/cc3io.asm	Fri Sep 19 13:57:52 2003 +0000
@@ -97,13 +97,20 @@
          ldx   ,x		get entry pointer at ,X
          jmp   $03,x		call term routine in sub module
 
-* Device initialization routine
-* Entry: U=Static mem ptr for device to initialize
-*        Y=Path dsc. ptr  
-*        DP=0 (or we're in trouble)
+* Init
+*
+* Entry:
+*    Y  = address of device descriptor
+*    U  = address of device memory area
+*
+* Exit:
+*    CC = carry set on error
+*    B  = error code
+*
 Init     ldx   <D.CCMem		get ptr to CC mem
          ldd   <G.CurDev,x	has CC3IO itself been initialized?
-         lbne  L00EF		yes, don't bother doing it again
+         lbne  PerWinInit	yes, don't bother doing it again
+* CC3IO initialization code - done on the first init of ANY cc3io device
          leax  >CC3Irq,pcr	set up AltIRQ vector in DP
          stx   <D.AltIRQ
          leax  >shftclr,pcr	point to SHIFT-CLEAR subroutine
@@ -164,11 +171,15 @@
          jsr   ,y		call init routine of sub module
          puls  u,y,x,b,a	restore saved regs
          std   <D.Proc		and restore current process
-L00EF    ldd   #$0078		set default SS.Mouse parameters
+
+* This code is executed on init of every window
+* U = device memory area
+PerWinInit
+         ldd   #$0078		set default SS.Mouse parameters
          std   <MS.Smpl,u	(Mouse sample rate & fire button timeout value)
          ldd   <IT.PAR,y	get parity/baud bytes from dev desc
          std   <DevPar,u	save it off in our static
-         lbra  L08AA		go find and init co-module
+         lbra  FindCoMod	go find and init co-module
 
 KeyDrv   fcs   /KeyDrv/
 JoyDrv   fcs   /JoyDrv/
@@ -179,8 +190,22 @@
          ldu   <D.CCMem		get ptr to CC mem
          rts   
 
-* NOTE: This just reads keys from the buffer. The physical reading of keys
-*   is done by the IRQ routine
+
+* Read
+*
+* NOTE:
+* This just reads keys from the buffer. The physical reading 
+* of keys is done by the IRQ routine.
+*
+* Entry:
+*    Y  = address of path descriptor
+*    U  = address of device memory area
+*
+* Exit:
+*    A  = character read
+*    CC = carry set on error
+*    B  = error code
+*
 Read     lda   V.PAUS,u		device paused?
          bpl   read1		no, do normal read (should this be bne?)
 * Device is paused; check for mouse button press
@@ -852,6 +877,18 @@
          clra  
          puls  pc,x		restore and return
 
+
+* Write
+*
+* Entry:
+*    A  = character to write
+*    Y  = address of path descriptor
+*    U  = address of device memory area
+*
+* Exit:
+*    CC = carry set on error
+*    B  = error code
+*
 Write    ldb   <ParmCnt,u	are we in the process of getting parameters?
          lbne  L0600		yes, go process
          sta   <DevPar,u	save off character
@@ -1324,7 +1361,7 @@
          anda  #$80		trying to flip from window to VDG?
          bne   L088F		yes, error
          lda   R$Y,x		no, get requested window type again
-         bsr   L08AA		go make sure co-module for new type exists
+         bsr   FindCoMod	go make sure co-module for new type exists
          lbcc  L07B5		carry it over to co-module
          rts   			return
 
@@ -1334,8 +1371,11 @@
 * Link to proper co-module
 * Try VDGInt first
 *
-L08AA    sta   V.TYPE,u		save new type
-         bmi   L08C3		if hi-bit if A is set, we're a window
+* Entry: A = window type (If bit 7 is set, it's a window, else VDG screen)
+*
+FindCoMod
+         sta   V.TYPE,u		save new type
+         bmi   FindWind		if hi-bit if A is set, we're a window
          pshs  u,y,a		..else VDG
          lda   #$02		get code for VDG type window
          sta   <WinType,u	save it
@@ -1348,7 +1388,7 @@
 *
 * Try WindInt
 *
-L08C3    pshs  u,y		preserve regs
+FindWind pshs  u,y		preserve regs
          clra  			set window type
          sta   <WinType,u
          leax  <WindInt,pcr	point to WindInt name
@@ -1383,7 +1423,6 @@
          puls  y		restore path descriptor pointer
          cmpa  #$02		was it WindInt?
          bgt   L08D2		no, return
-*L0900    ldb   #$00
 L0900    clrb
          lbra  L0590		send it to co-module
 
diff -r 2b0af03a7915 -r 146dfa918a9c level2/modules/keydrv_cc3.asm
--- a/level2/modules/keydrv_cc3.asm	Thu Sep 18 12:38:15 2003 +0000
+++ b/level2/modules/keydrv_cc3.asm	Fri Sep 19 13:57:52 2003 +0000
@@ -41,140 +41,146 @@
          lbra  FuncKeys  
 
 * Read - read keys if pressed
-ReadKys  ldu   <D.CCMem   Get CC3IO global memory into U
-         ldx   #PIA0Base  base address of PIA #0
+* Exit: A = key pressed
+ReadKys  ldu   <D.CCMem		Get CC3IO global memory into U
+         ldx   #PIA0Base	base address of PIA #0
          ldb   #$FF
-         stb   $02,x      clear all row strobes
-         ldb   ,x         read Joystick buttons
-         comb             invert bits so 1=pressed
-         andb  #%00001111 keep only buttons
-         bne   L0059      branch if button pushed; error routine
-         clr   $02,x      enable all strobe lines
-         lda   ,x         read PIA #0
+         stb   $02,x		clear all row strobes
+         ldb   ,x		read Joystick buttons
+         comb			invert bits so 1=pressed
+         andb  #%00001111	keep only buttons
+         bne   L0059		branch if button pushed; error routine
+         clr   $02,x		enable all strobe lines
+         lda   ,x		read PIA #0
          coma            
-         anda  #%01111111 mask only the joystick comparator
-         beq   L0042      branch if no keys pressed
-         pshs  dp        
-         tfr   u,d       
-         tfr   a,dp       set DP to the address in regU
-         bsr   L005C      evaluate the found key matrix
-         puls  dp         return to system DP
-         bpl   L005B      valid key
-L0042    clra             regA    would have been the found key
-         ldb   <G.CapLok,u CapsLock/SysRq key down flag
-         bne   L0056     
-         clr   <G.KTblLC,u Key table entry# last checked (1-3)
+* Check to see if ANY key is down
+         anda  #%01111111	mask only the joystick comparator
+         beq   NoKey		branch if no keys pressed
+* Here, a key is down on the keyboard
+         pshs  dp		save our DP
+         tfr   u,d		move statics ptr to D
+         tfr   a,dp		set DP to the address in regU
+         bsr   EvalMatrix	evaluate the found key matrix
+         puls  dp		return to system DP
+         bpl   L005B		valid key
+NoKey    clra			regA    would have been the found key
+         ldb   <G.CapLok,u	CapsLock/SysRq key down flag
+         bne   L0056		branch if down
+         clr   <G.KTblLC,u	Key table entry# last checked (1-3)
          IFNE  H6309
          comd
          ELSE
          coma
          comb
          ENDC
-         sta   <G.LKeyCd,u last keyboard code
-         sta   <G.2Key1,u 2nd key table storage; $FF=none
-         std   <G.2Key2,u format (Row/Column)
-L0056    clr   <G.CapLok,u see above
+         sta   <G.LKeyCd,u	last keyboard code
+         sta   <G.2Key1,u	2nd key table storage; $FF=none
+         std   <G.2Key2,u	format (Row/Column)
+L0056    clr   <G.CapLok,u	see above
 L0059    ldb   #$FF      
 L005B    rts             
 
-L005C    ldx   #PIA0Base  base value of PIA #0
+
+* Evaluates the keyboard matrix for a key
+EvalMatrix
+         ldx   #PIA0Base	base value of PIA #0
          IFNE  H6309
          clrd            
          ELSE
          clra            
          clrb            
          ENDC
-         std   <G.ShftDn  shift/CTRL flag; 0=NO $FF=YES
-         std   <G.KeyFlg  PIA bits/ALT flag
+         std   <G.ShftDn	shift/CTRL flag; 0=NO $FF=YES
+         std   <G.KeyFlg	PIA bits/ALT flag
 *	%00000111-Column # (Output, 0-7)
 *	%00111000-Row # (Input, 0-6)
          IFNE  H6309     
-         comd             set D to $FFFF
+         comd			set D to $FFFF
          ELSE            
          coma            
-         comb             set primary key table
+         comb			set primary key table
          ENDC            
-         std   <G.Key1    key 1&2 flags $FF=none
-         sta   <G.Key3    key 3      "
-         deca             ie. lda #%11111110
-         sta   $02,x      strobe one column
-L006E    lda   ,x         read PIA #0 row states
-         coma             invert bits so 1=key pressed
-         anda  #$7F       keep only keys, bit 0=off 1=on
-         beq   L0082      no keys pressed, try next column
-         ldb   #$FF       preset counter to -1
+         std   <G.Key1		key 1&2 flags $FF=none
+         sta   <G.Key3		key 3     "
+         deca			ie. lda #%11111110
+         sta   $02,x		strobe one column
+L006E    lda   ,x		read PIA #0 row states
+         coma			invert bits so 1=key pressed
+         anda  #$7F		keep only keys, bit 0=off 1=on
+         beq   L0082		no keys pressed, try next column
+         ldb   #$FF		preset counter to -1
 L0077    incb            
-         lsra             bit test regA
-         bcc   L007E      no key so branch
-         lbsr  L010E      convert column/row to matrix value and store it
-L007E    cmpb  #$06       max counter
-         blo   L0077      loop if more bits to test
-L0082    inc   <G.KeyFlg  counter; used here for column
-         orcc  #Carry     bit marker; disable strobe
-         rol   $02,x      shift to next column
-         bcs   L006E      not finished with columns so loop
-         lbsr  L0166      simultaneous check; recover key matrix value
-         bmi   L00F5      invalid so go
-         cmpa  <G.LKeyCd  last keyboard code	
+         lsra			bit test regA
+         bcc   L007E		no key so branch
+         lbsr  L010E		convert column/row to matrix value and store it
+L007E    cmpb  #$06		max counter
+         blo   L0077		loop if more bits to test
+L0082    inc   <G.KeyFlg	counter; used here for column
+         orcc  #Carry		bit marker; disable strobe
+         rol   $02,x		shift to next column
+         bcs   L006E		not finished with columns so loop
+         lbsr  L0166		simultaneous check; recover key matrix value
+         bmi   L00F5		invalid so go
+         cmpa  <G.LKeyCd	last keyboard code	
          bne   L0095     
-         inc   <G.KySame  same key flag ?counter?
-L0095    sta   <G.LKeyCd  setup for last key pressed
-         beq   L00B5      if @ key, use lookup table
-         suba  #$1A       the key value (matrix) of Z
-         bhi   L00B5      not a letter so go
-         adda  #$1A       restore regA
-         ldb   <G.CntlDn  CTRL flag
-         bne   L00E0      CTRL is down so go
-         adda  #$40       convert to ASCII value; all caps
-         ldb   <G.ShftDn  shift key flag
-         ldy   <G.CurDev  get current device static memory pointer
-         eorb  <ULCase,y  caps lock and keyboard mouse flags
-         andb  #CapsLck   test caps flag
-         bne   L00E0      not shifted so go
-         adda  #$20       convert to ASCII lower case
+         inc   <G.KySame	same key flag ?counter?
+L0095    sta   <G.LKeyCd	setup for last key pressed
+         beq   L00B5		if @ key, use lookup table
+         suba  #$1A		the key value (matrix) of Z
+         bhi   L00B5		not a letter so go
+         adda  #$1A		restore regA
+         ldb   <G.CntlDn	CTRL flag
+         bne   L00E0		CTRL is down so go
+         adda  #$40		convert to ASCII value; all caps
+         ldb   <G.ShftDn	shift key flag
+         ldy   <G.CurDev	get current device static memory pointer
+         eorb  <ULCase,y	caps lock and keyboard mouse flags
+         andb  #CapsLck		test caps flag
+         bne   L00E0		not shifted so go
+         adda  #$20		convert to ASCII lower case
          bra   L00E0     
 * not a letter key, use the special keycode lookup table at L01DC.
 * Entry: regA = table index (matrix scancode-26)
-L00B5    ldb   #$03       three entries per key (normal,shift,ctrl)
-         mul              convert index to table offset
-         lda   <G.ShftDn  shift key flag
-         beq   L00BF      not shifted so go
-         incb             adjust offset for SHIFTed entry
+L00B5    ldb   #$03		three entries per key (normal,shift,ctrl)
+         mul			convert index to table offset
+         lda   <G.ShftDn	shift key flag
+         beq   L00BF		not shifted so go
+         incb			adjust offset for SHIFTed entry
          bra   L00C5     
-L00BF    lda   <G.CntlDn  CTRL flag
-         beq   L00C5      adjust offset for CONTROL entry
+L00BF    lda   <G.CntlDn	CTRL flag
+         beq   L00C5		adjust offset for CONTROL entry
          addb  #$02      
-L00C5    ldx   <G.CurDev  point X to device's static memory
-         lda   <$22,x     key sense flag
-         beq   L00D0      not set so go
-         cmpb  #$11       spacebar
-         ble   L00F3      must be an arrow so go
-L00D0    cmpb  #$4B       ALT key? (was cmpb #$4C)
-         blt   L00D8      not ALT, CTRL, F1, F2, or SHIFT so go
-         inc   <G.AltDwn  flag special keys (ALT,CTRL)
-         subb  #$06       and adjust offset to skip them
-L00D8    leax  >L01DC,pcr decode table
+L00C5    ldx   <G.CurDev	point X to device's static memory
+         lda   <$22,x		key sense flag
+         beq   L00D0		not set so go
+         cmpb  #$11		spacebar
+         ble   L00F3		must be an arrow so go
+L00D0    cmpb  #$4B		ALT key? (was cmpb #$4C)
+         blt   L00D8		not ALT, CTRL, F1, F2, or SHIFT so go
+         inc   <G.AltDwn	flag special keys (ALT,CTRL)
+         subb  #$06		and adjust offset to skip them
+L00D8    leax  >L01DC,pcr	decode table
          lda   b,x       
-         bmi   L00F6      if regA = $81 - $84, special key
+         bmi   L00F6		if regA = $81 - $84, special key
 * several entries to this routine from any key press; regA is already ASCII
-L00E0    ldb   <G.AltDwn  was ALT flagged?
-         beq   L00F0      no so go
-         cmpa  #$3F       ?	
-         bls   L00EE      # or code
-         cmpa  #$5B       [
-         bhs   L00EE      capital letter so go
-         ora   #$20       convert to lower case
-L00EE    ora   #$80       set for ALT characters
-L00F0    andcc  #^Negative not negative
+L00E0    ldb   <G.AltDwn	was ALT flagged?
+         beq   L00F0		no so go
+         cmpa  #$3F		?	
+         bls   L00EE		# or code
+         cmpa  #$5B		[
+         bhs   L00EE		capital letter so go
+         ora   #$20		convert to lower case
+L00EE    ora   #$80		set for ALT characters
+L00F0    andcc  #^Negative	not negative
          rts             
-L00F3    orcc  #Negative  set negative
+L00F3    orcc  #Negative	set negative
 L00F5    rts             
 * Flag that a special key was hit
-L00F6    inc   <G.CapLok  caps lock/SysRq
-         inc   <G.Clear   one shot caps lock/SysRq
+L00F6    inc   <G.CapLok	caps lock/SysRq
+         inc   <G.Clear		one shot caps lock/SysRq
          bra   L00F0     
 * Calculate arrow keys for key sense byte
-L00FC    pshs  b,a        convert column into power of 2
+L00FC    pshs  b,a		convert column into power of 2
          clrb            
          orcc  #Carry    
          inca            
@@ -182,39 +188,39 @@
          deca            
          bne   L0102     
 *         bra   L0108      WHY IS THIS HERE??
-L0108    orb   <G.KySns   previous value of column
+L0108    orb   <G.KySns		previous value of column
          stb   <G.KySns  
          puls  pc,b,a    
 * Check special keys (Shift, Cntrl, Alt)
 L010E    pshs  b,a       
-         cmpb  #$03       is it row 3?
+         cmpb  #$03		is it row 3?
          bne   L011C     
-         lda   <G.KeyFlg  get column #
-         cmpa  #$03       is it column 3?; ie up arrow
-         blt   L011C      if lt must be a letter
-         bsr   L00FC      its a non letter so bsr
-L011C    lslb             B*8  8 keys per row
+         lda   <G.KeyFlg	get column #
+         cmpa  #$03		is it column 3?; ie up arrow
+         blt   L011C		if lt must be a letter
+         bsr   L00FC		its a non letter so bsr
+L011C    lslb			B*8  8 keys per row
          lslb            
          lslb            
-         addb  <G.KeyFlg  add in the column #
-         cmpb  #$33       ALT
+         addb  <G.KeyFlg	add in the column #
+         cmpb  #$33		ALT
          bne   L012B     
-         inc   <G.AltDwn  ALT down flag
+         inc   <G.AltDwn	ALT down flag
          ldb   #$04      
          bra   L0108     
-L012B    cmpb  #$34       CTRL
+L012B    cmpb  #$34		CTRL
          bne   L0135     
-         inc   <G.CntlDn  CTRL down flag
+         inc   <G.CntlDn	CTRL down flag
          ldb   #$02      
          bra   L0108     
-L0135    cmpb  #$37       SHIFT key
+L0135    cmpb  #$37		SHIFT key
          bne   L013F     
-         com   <G.ShftDn  SHIFT down flag
+         com   <G.ShftDn	SHIFT down flag
          ldb   #$01      
          bra   L0108     
 * check how many key (1-3) are currently being pressed
 L013F    pshs  x         
-         leax  <$2D,u     1st key table
+         leax  <$2D,u		1st key table
          bsr   L014A     
          puls  x         
          puls  pc,b,a    
@@ -234,63 +240,63 @@
          puls  pc,a      
 * simultaneous key test
 L0166    pshs  y,x,b     
-         ldb   <G.KTblLC  key table entry #
+         ldb   <G.KTblLC	key table entry #
          beq   L019D     
-         leax  <$2A,u     point to 2nd key table
+         leax  <$2A,u		point to 2nd key table
          pshs  b         
-L0171    leay  <$2D,u     1st key table
+L0171    leay  <$2D,u		1st key table
          ldb   #$03      
-         lda   ,x         get key #1
-         bmi   L018F      go if invalid? (no key)
-L017A    cmpa  ,y         is it a match?
-         bne   L0184      go if not a matched key
+         lda   ,x		get key #1
+         bmi   L018F		go if invalid? (no key)
+L017A    cmpa  ,y		is it a match?
+         bne   L0184		go if not a matched key
          clr   ,y        
-         com   ,y         set value to $FF
+         com   ,y		set value to $FF
          bra   L018F     
 L0184    leay  $01,y     
          decb            
          bne   L017A     
          lda   #$FF      
          sta   ,x        
-         dec   <G.KTblLC  key table entry#
+         dec   <G.KTblLC	key table entry#
 L018F    leax  $01,x     
-         dec   ,s         column counter
+         dec   ,s		column counter
          bne   L0171     
          leas  $01,s     
-         ldb   <G.KTblLC  key table entry (can test for 3 simul keys)
+         ldb   <G.KTblLC	key table entry (can test for 3 simul keys)
          beq   L019D     
          bsr   L01C4     
-L019D    leax  <$2D,u     1st key table
+L019D    leax  <$2D,u		1st key table
          lda   #$03      
 L01A2    ldb   ,x+       
          bpl   L01B5     
          deca            
          bne   L01A2     
-         ldb   <G.KTblLC  key table entry (can test for 3 simul keys)
+         ldb   <G.KTblLC	key table entry (can test for 3 simul keys)
          beq   L01C0     
          decb            
-         leax  <$2A,u     2nd key table
+         leax  <$2A,u		2nd key table
          lda   b,x       
          bra   L01BE     
 L01B5    tfr   b,a       
-         leax  <$2A,u     2nd key table
+         leax  <$2A,u		2nd key table
          bsr   L014A     
          stb   <G.KTblLC 
 L01BE    puls  pc,y,x,b  
-L01C0    orcc  #Negative  flag negative
+L01C0    orcc  #Negative	flag negative
          puls  pc,y,x,b  
 * Sort 3 byte packet @ G.2Key1 according to sign of each byte
 * so that positive #'s are at beginning & negative #'s at end
-L01C4    leax  <$2A,u     2nd key table
-         bsr   L01CF      sort bytes 1 & 2
+L01C4    leax  <$2A,u		2nd key table
+         bsr   L01CF		sort bytes 1 & 2
          leax  $01,x     
-         bsr   L01CF      sort bytes 2 & 3
-         leax  -$01,x     sort 1 & 2 again (fall thru for third pass)
-L01CF    ldb   ,x         get current byte
-         bpl   L01DB      positive - no swap
-         lda   $01,x      get next byte
-         bmi   L01DB      negative - no swap
-         std   ,x         swap the bytes
+         bsr   L01CF		sort bytes 2 & 3
+         leax  -$01,x		sort 1 & 2 again (fall thru for third pass)
+L01CF    ldb   ,x		get current byte
+         bpl   L01DB		positive - no swap
+         lda   $01,x		get next byte
+         bmi   L01DB		negative - no swap
+         std   ,x		swap the bytes
 L01DB    rts             
 
 * Special Key Codes Table : 3 entries per key - Normal, Shift, Control
@@ -339,29 +345,29 @@
 * This entry point tests for the F1/F2 function keys on a CoCo 3
 * keyboard.
 * Exit: A = Function keys pressed (Bit 0 = F1, Bit 2 = F2)
-FuncKeys ldu   <D.CCMem   get CC3IO global mem pointer into U
-         ldx   #PIA0Base  get address of PIA #0
-         clra             clear A
-         ldb   #%11011111 strobe column #6 of PIA #0
+FuncKeys ldu   <D.CCMem		get CC3IO global mem pointer into U
+         ldx   #PIA0Base	get address of PIA #0
+         clra			clear A
+         ldb   #%11011111	strobe column #6 of PIA #0
          stb   $02,x     
          IFNE  H6309
-         tim   #%01000000,0,x F1 down?
+         tim   #%01000000,0,x	F1 down?
          ELSE
-         ldb   ,x         read PIA #0
-         bitb  #%01000000 test for F1 function key
+         ldb   ,x		read PIA #0
+         bitb  #%01000000	test for F1 function key
          ENDC
-         bne   CheckF2    branch if set (key not down)
-         inca             flag F1 as down
-CheckF2  ldb   #%10111111 strobe column #7 PIA #0
+         bne   CheckF2		branch if set (key not down)
+         inca			flag F1 as down
+CheckF2  ldb   #%10111111	strobe column #7 PIA #0
          stb   $02,x     
          IFNE  H6309
-         tim   #%01000000,0,x F2 down?
+         tim   #%01000000,0,x	F2 down?
          ELSE
-         ldb   ,x         read PIA #0
-         bitb  #%01000000 test for F2 function key
+         ldb   ,x		read PIA #0
+         bitb  #%01000000	test for F2 function key
          ENDC
          bne   L024C     
-         ora   #$04       flag F2 as down
+         ora   #$04		flag F2 as down
 L024C    rts             
 
          emod