Merge pull request #328 from b1ackmai1er/dev

Some driver documentation updates and corrections

Source/HBIOS/ctc.asm

@@ -19,6 +19,12 @@ CTC_TIMCFG	.EQU	%11010111	; CTC TIMER CHANNEL CONFIG
 		;	 |+-------- COUNTER MODE
 		;	 +--------- INTERRUPT ENABLE
 ;
+;==================================================================================================
+; ONLY IM2 IMPLEMENTED BELOW.  I DON'T SEE ANY REASONABLE WAY TO IMPLEMENT AN IM1 TIMER BECAUSE
+; THE CTC PROVIDES NO WAY TO DETERMINE IF IT WAS THE CAUSE OF AN INTERRUPT OR A WAY TO
+; DETERMINE WHICH CHANNEL CAUSED AN INTERRUPT.
+;==================================================================================================
+;
 #IF (INTMODE != 2)
 	.ECHO	"*** WARNING: CTC TIMER DISABLED -- INTMODE 2 REQUIRED!!!\n"
 #ENDIF
@@ -36,11 +42,52 @@ CTC_TIMCFG	.EQU	%11010111	; CTC TIMER CHANNEL CONFIG
 	!!!	; FORCE AN ASSEMBLY ERROR
   #ENDIF
 ;
-; ONLY IM2 IMPLEMENTED BELOW.  I DON'T SEE ANY REASONABLE WAY TO
-; IMPLEMENT AN IM1 TIMER BECAUSE THE CTC PROVIDES NO WAY TO
-; DETERMINE IF IT WAS THE CAUSE OF AN INTERRUPT OR A WAY TO
-; DETERMINE WHICH CHANNEL CAUSED AN INTERRUPT.
-;  
+;==================================================================================================
+; TIMER SETUP
+;
+; A PERIODIC INTERRUPT TIMER CAN BE SETUP USING EITHER THE CPU SYSTEM CLOCK OR AN EXTERNAL
+; OSCILLATOR CONNECTED TO THE CTC. THE DEFACTO PERIOD FOR THIS TIMER IS 50Hz OR 60Hz.
+;
+; THE DESIRED TIMER PERIOD IS SET IN THE CONFIGURATION:
+;	TICKFREQ	.SET	60	; OR
+;	TICKFREQ	.SET	50
+;
+; THIS DRIVER USES TWO CTC CHANNELS TO CREATE A TWO STEP DIVIDER THAT DIVIDES THE CPU SYSTEM 
+; CLOCK OR EXTERNAL OSCILLATOR INTO A PERIODIC TICK THAT GENERATES AN INTERRUPT.
+;
+; THE CPU CLOCK OR CTC EXTERNAL OSCILLATOR NEEDS TO BE LESS THAN 3.932160MHz FOR A 60HZ TIMER
+; TICK OR 3.276800MHz FOR A 50Hz TIMER TICK.
+;
+; THE CHANNELS USED ARE DEFINED BY THE CTCPRECH AND CTCTIMCH DEFINITIONS - TYPICALLY 2 & 3.
+; EXTERNAL HARDWARE MUST BE CONFIGURED TO MATCH THIS CONFIGURATION.
+;
+; EACH CHANNEL SUCCESSIVELY DIVIDES THE CLOCK OR OSCILLATOR FREQUENCY DOWN TO A 50 OR 60Hz TICK.
+; THE FIRST DIVIDER CHANNEL IS THE PRESCALER, THE SECOND IS THE TIMER CHANNEL. 
+;
+; IF CTCMODE IS CTCMODE_CTR THEN THE OSCILLATOR CONNECTED TO CTC PRESCALER CHANNEL IS USED.
+;
+; 	THE CONFIGURATION FILES DEFINE THE OSCILLATOR FREQUENCY THAT IS CONNECTED TO THE PRESCALER
+; 	CHANNEL. I.E. THE EXTERNAL HARDWARE CONNECTED TO THE CTC.
+;
+;	FOR A 60Hz TIMER WITH A 3.579545Mhz OSCILLATOR USE:
+;	CTCMODE		.SET	CTCMODE_CTR
+;	TICKFREQ	.SET	60
+;	CTCOSC		.SET	3579545	
+;	
+; IF CTCMODE IS CTCMODE_TIM16 OR CTCMODE_TIM256 THE CPU SYSTEM CLOCK FREQUENCY IS USED.
+;
+;  	THIS MODE HAS LIMITED VALUE AS MANY SYSTEMS OPERATE ABOVE THE USABLE TOP FREQUENCY.
+;	THE CONFIGURATION FILE MUST BE UPDATED TO MATCH YOUR CPU CLOCK FREQUENCY.
+;
+;	FOR A 60Hz TIMER WITH A 2Mhz OSCILLATOR USE:
+;	CTCMODE		.SET	CTCMODE_TIM256
+;	TICKFREQ	.SET	60
+;	CTCOSC		.SET	2000000
+;
+;	NOTE THAT IF CPU SPEED IS CHANGED IN THIS MODE, THE TIMER SPEED WILL ALSO CHANGE.
+;
+;==================================================================================================
+;
 CTC_PREIO	.EQU	CTCBASE + CTCPRECH
 CTC_SCLIO	.EQU	CTCBASE + CTCTIMCH
 ;
@@ -88,7 +135,16 @@ CTCTIVT		.EQU	INT_CTC0A + CTCTIMCH
 ;
 #ENDIF
 ;
+;==================================================================================================
+; CTC PRE-INITIALIZATION
+;
+; CHECK TO SEE IF A CTC EXISTS. IF IT EXISTS, ALL FOUR CTC CHANNELS ARE PROGRAMMED TO:
+;  INTERRUPTS DISABLED, COUNTER MODE, RISING EDGE TRIGGER, RESET STATE.
 ;
+; IF THE CTCTIMER CONFIGURATION IS SET, THEN A PERIOD INTERRUPT TIMER IS SET UP USING CTC CHANNELS
+; 2 (CTCPRECH) & 3 (CTCTIMCH). THE TIMER WILL BE SETUP TO 50 OR 60HZ DEPENDING ON CONFIGURATION 
+; SETTING TICKFREQ. CHANNEL 3 WILL GENERATE THE TICK INTERRUPT.. 
+;==================================================================================================
 ;
 CTC_PREINIT:
 	CALL	CTC_DETECT		; DO WE HAVE ONE?
@@ -136,7 +192,9 @@ CTC_PREINIT1:
 	XOR	A
 	RET
 ;
-;
+;==================================================================================================
+; DRIVER INITIALIZATION
+;==================================================================================================
 ;
 CTC_INIT:				; MINIMAL INIT
 CTC_PRTCFG:
@@ -199,7 +257,10 @@ CTC_PRTCFG1:
 	XOR	A
 	RET
 ;
-;
+;==================================================================================================
+; DETECT CTC BY CHECKING REGISTER CAN BE WRITTEN AND READ, AND THEN BY SETTING UP ONE CHANNEL IN 
+; TIMER MODE AND CHECKING IT IS COUNTING DOWN.
+;==================================================================================================
 ;
 CTC_DETECT:
 	LD	A,CTC_TIM256CFG

Source/HBIOS/pio.asm

@@ -1,6 +1,6 @@
 ;
 ;==================================================================================================
-; PIO DRIVER (SERIAL PORT)
+; PIO DRIVER (PARALLEL PORT)
 ;==================================================================================================
 ;
 ;  SETUP PARAMETER WORD:
@@ -12,7 +12,7 @@
 ;
 ; THIS DRIVER IS JUST A STUB TO DETECT AND INITIALIZE PIO HARDWARE
 ; IF IT EXISTS.  FOR NOW, IT DOES NOT REGISTER ANY OF THE PIO CHANNELS
-; AS CHARCTER DEVICE UNITS.
+; AS CHARACTER DEVICE UNITS.
 ;
 PIO_NONE	.EQU	0
 PIO_PIO		.EQU	1
@@ -34,7 +34,7 @@ PIO1B_DAT	.EQU	PIO1BASE + $01
 PIO_PREINIT:
 ;
 ; SETUP THE DISPATCH TABLE ENTRIES
-; NOTE: INTS WILL BE DISABLED WHEN PREINIT IS CALLED AND THEY MUST REMIAIN
+; NOTE: INTS WILL BE DISABLED WHEN PREINIT IS CALLED AND THEY MUST REMAIN
 ; DISABLED.
 ;
 	CALL	PIO_PROBE		; PROBE FOR CHIPS