supermario/base/SuperMarioProj.1994-02-09/OS/StartMgr/USTMacros.a

;---------------------------------------------------------------------------
;  File:		USTMacros.a
;
;	Contains:	This file contains macros, record definitions and equates that
;				are used by the test software.
;
;	Written by:	Scott Smyers
;
;	Copyright:	© 1990, 1992-1993 by Apple Computer, Inc., all rights reserved.
;
;	Change History (most recent first):
;
;	   <SM3>	12/13/93	PN		Roll in KAOs and Horror changes to support Malcom and AJ
;									machines.
;	   <SM2>	  5/2/92	kc		Roll in Horror. Comments follow:
;		<H2>	  3/6/92	AL		Extended the USTGlobals structure to include all of the data
;									needed to keep track of CTE v2.1 DTM parameters (for the GI
;									routine ExecuteDTM). Also enhanced the USTTests and USTSubtests
;									structure definitions to match the CTE v2.1 Test and Subtest
;									info
;									structures and added support for StandardTestParams. Modified
;									the
;									CopyRamToPRAM and CopyPRAMToRam macros to handle long branches
;									to the routines. When USTStartTest.a outgrew its allocated space
;									in the ROM and some of the USTxxx.a files were
;									moved to the new USTStartTest1.a file, an addressing range
;									problem came up. This solves it (for these routines).
;		 <4>	  4/2/91	CCH		Rolled in changes from Scott Smyers': Changed subtest ID to a
;									word and added a word sized test ID to CPUTestList structure.
;									Added subtest IDs for SONIC tests and 53C96 test. Changed some
;									ambiguous structure element names to be unique between
;									structures.
;		 <3>	 3/13/91	CCH		Rolled in RBI changes from Scott Smyers.
;		 <2>	 1/14/91	CCH		Rolled in Scott Smyer's changes.
;		 <1>	 12/14/90	SS		first checked in
;
;
;---------------------------------------------------------------------------
	TITLE	'USTMacros.a'

	IF 	&TYPE('USTMacros')='UNDEFINED' THEN

USTMacros	EQU	1

UTEChar		EQU		'!'		;Character prefix for CTE command in STM

;
; The following structure is used by the routines in this file.  By convention, each
; routine expects a0 to point to this structure upon entry, except for the initialization
; routine, which creates this structure and points a0 to it.
;
;
;	Aaron Ludtke - 11/4/91
;
;	This structure has been extended to make room for the parameters to the GI_ExecuteDTM
; routine. The ROM-based environments that utilize CTE v2.1 or later will require these
; parameters to be set up and initialized. By adding them to the end of the USTGlobals,
; they will always be available and can be referenced from a5, as the rest of the
; universal diagnostic information is. The stack will be adjusted by the size of this global
; area, and the fields will be filled out to reflect the information necessary for the call.
;
;	The RelocateGlobals routine should not have to change to account for this modification,
; and a new routine will has been added to fill in the info to set up for the GI_ExecuteDTM
; call. That routine name is, oddly enough, SetupForExecuteDTM. It exists in the file
; USTEnvirons.a, where the Serial Test Manager and In House Tester hook reside.
;
;	This is intended to be a "universal" structure that could be used by four of the ROM
; based environments (startup, RBI, IHT, STM - note that the ATrap does not need the
; USTGlobals because the information kept in there [bases valid flags, product info ptr,
; etc.] can be derived from the OS). It should also be able to use the SetupForExecuteDTM
; routine, if I work it right. I'll have to check into that...
;
;	This structure was enhanced (2/2/92) to support a standardTestParams structure, which
; is used by Tests to further refine their performance. The executionOptions field
; testParams will be set to point to this structure after it has been filled out by the
; SetupForExecuteDTM routine.


USTGlobals	RECORD	0, Increment

CmdNumber			ds.l	1		;Current command number
CallFrameSize		ds.l	1		;Size of the call stack frame for CTE command
RunMode				ds.w	1		;the mode flags (i.e., restart, startup, etc.)
USTTestList			ds.l	1		;Pointer to a list of tests to execute
USTSubTestList		ds.l	1		;Pointer to a list of subtests for each test
GlobCPUTestList		ds.l	1		;Pointer to the CPU specific test list in ROM	<2>
CTEGlobals			ds.l	1		;Pointer to the CTE Globals
ErrorHandler		ds.l	1		;Pointer to error handler, if any
WarmStartConst		ds.l	1		;Warm start constant (if =#WmStConst, warm start)
DcdrInfPtr			ds.l	1		;Decoder information pointer
PrdctInfPtr			ds.l	1		;Pointer to the product info record.
BasesValidFlags		ds.l	1		;Bases valid flags, as returned by Get Hardware Info.

; Here's the new GI_ExecuteDTM paramters stuff:

;;	This is the CTEDTMExecutionOptions structure. See the What's New In CTE 2.0 documentation
;	for a more thorough description of what these fields mean:

exOpUserInfo				ds.l	1	; a pointer to user-specific info that CTE knows nothing about
exOpProcessorType			ds.l	1	; the gestalt-enumerated processor (68000 = 1, 68040 = 5, etc.)
exOpExecutionMode			ds.l	1	; the CTE execution mode being used (executeTest, etc.)
exOpTestParams				ds.l	1	; a pointer to the test parameters
exOpTestResultsOverride		ds.l	1
exOpSubtestParamsOverride	ds.l	1
exOpSubtestResultsOverride	ds.l	1
exOpIdleMethod				ds.l	1
exOpIdleMethodArg			ds.l	1

;;	This is the testInfo structure:

tInfoUserInfo		ds.l	1	; a pointer to user-specific info that CTE knows nothing about
tInfoID				ds.l	1	; the ID number of the test (a la CTE)
tInfoFunctionEntry	ds.l	1	; the address of the test
tInfoParamsSize		ds.l	1	; size (in bytes) of the test parameters (can usually be NULL)
tInfoResultsSize	ds.l	1	; ditto for the test results size

;;	This is the subtestInfo structure:

sInfoUserInfo		ds.l	1	; a pointer to user-specific info that CTE knows nothing about
sInfoID				ds.l	1	; the ID number of the subtest (a la CTE)
sInfoFunctionEntry	ds.l	1	; the address of the subtest
sInfoParamsSize		ds.l	1	; size (in bytes) of the subtest parameters (can usually be NULL)
sInfoResultsSize	ds.l	1	; ditto for the subtest results size

;;	This is the executionResults structure:

exResErr			ds.l	1	; the DTM error
exResTestParams		ds.l	1
exResTestResults	ds.l	1
exResSubtestParams	ds.l	1
exResSubtestResults	ds.l	1

;;	This is the StdTestParams structure:

stdModifier			ds.l	1	; the "modifier" field
stdMachineType		ds.l	1	; the box flag (gestalt) machine type


; The Chunk Table should be the last thing in this record, in case it needs to be extended
; in the future:

ChunkTable			ds.l	1		;Chunk table comes after


sizeofUSTGlobals	equ		*		;Size of preceding structure

			ENDR

SizeOfCTEGlobals	equ		54*1024	;give 54K to the CTE globals

;
; The following record defines the bits which determine under what conditions each
; machine specific test can execute.
;

RunBits		RECORD	0,increment

StartupBit	ds.b	1				;System power up		- bit 0
RestartBit	ds.b	1				;System restart			- bit 1
STMBit		ds.b	1				;Serial Test Manager	- bit 2
ATrapBit	ds.b	1				;_TestManager A trap	- bit 3
RBIBit		ds.b	1				;ROM Burnin				- bit 4

; Mask values

Startup		equ		1<<StartupBit	;$0001
Restart		equ		1<<RestartBit	;$0002
STM			equ		1<<STMBit		;$0004
ATrap		equ		1<<ATrapBit		;$0008
RBI			equ		1<<RBIBit		;$0010

			ENDR

;
; USTtest - the structure which defines the data for a single test.
; There is one test in the ROM which knows about all the subtests there.  This test
; has one entry in a test table which has the following structure:
;
	
USTTest		STRUCTURE		0
			DSF.L	TTest_ID			;ID for this test							<T4>
			DSF.L	TEntryPtr			;Pointer to the entry point					<T4>
			DSF.L	TNamePtr			;Pointer to the name of this test (or NULL)	<T4>
			DSF.L	TCodeSize			;Size of the code (in bytes, can be NULL)	<T4>
			DSF.L	TParamSize			; Size of the parameter block
			DSF.L	TResultSize			; Size of the results block
			ENDSTRUCT
		
;
; The following macro creates an entry in the test table
;

	MACRO
	USTTestItem		&items
	STRUCTITEM		USTTest, &items
	ENDM

;
; USTSubtest - the structure which defines the data for a single subtest.
; Each test in the main subtest table has a single entry in the main test table.  Each
; entry has the following structure:
;
	
USTSubtest		STRUCTURE		0
				DSF.L	STSubtest_ID		;ID for this subtest					<T4>
				DSF.L	STEntryPtr			;Pointer to the entry point				<T4>
				DSF.L	STNamePtr			;Pointer to the name of this subtest (or NULL)<T4>
				DSF.L	STCodeSize			;Size of the code (in bytes, can be NULL)<T4>
				DSF.L	STParamSize			;Size of the parameter block			<T4>
				DSF.L	STResultSize		;Size of the results block				<T4>
				ENDSTRUCT

;
; The following macro creates an entry in the main test table:
;

	MACRO
	USTSubtestItem	&items
	STRUCTITEM		USTSubtest, &items
	ENDM

;
; The following defines the test ID for the one test in ROM
;
USTTestIDs	RECORD	1, Increment	;												<T4>

USTMainTest_ID		ds.b	1		;#1 - Test to handle all non-CTE tests in ROM	<T4>
SONIC_Test_ID		ds.b	1		;#2 - Test for the SONIC chip in eclipse/spike	<T4>

MaxTest_ID			equ		*-1		;max test number								<T4>

		ENDR						;												<T4>
;
; Following are the equates which define the subtest ID number for each of the subtests.
;

StartingSubtestID	EQU		$80		;Starting subtest ID number

USTSubtestIDs	RECORD	StartingSubtestID, Increment

MapRamDataTest_ID	ds.b	1		;$80
MapRamUniqTest_ID	ds.b	1		;$81
VramDataTest_ID		ds.b	1		;$82
VramAddrTest_ID		ds.b	1		;$83
SCCRegTest_ID		ds.b	1		;$84
SCCLoopTest_ID		ds.b	1		;$85
SCCTimerTest_ID		ds.b	1		;$86
VIATest_ID			ds.b	1		;$87
TestSCSI_ID			ds.b	1		;$88
TestASC_ID			ds.b	1		;$89
PramTest_ID			ds.b	1		;$8A
TestRBV_ID			ds.b	1		;$8B
TestSWIM_ID			ds.b	1		;$8C
Float_Test_ID		ds.b	1		;$8D
TestPGC_ID			ds.b	1		;$8E
FMCRegTest_ID		ds.b	1		;$8F
FMCCacheTest_ID		ds.b	1		;$90
OSSRegTest_ID		ds.b	1		;$91
OSSIntTest_ID		ds.b	1		;$92
RPUTest_ID			ds.b	1		;$93
EgretTest_ID		ds.b	1		;$94
TestSndInts_ID		ds.b	1		;$95
TestCLUT_ID			ds.b	1		;$96
TestVRAM_ID			ds.b	1		;$97
TestPWM_ID			ds.b	1		;$98 - only in Apollo ROM					<T4>
TimeSoundInts		ds.b	1		;$99 - only in Apollo ROM					<T4>
TestC96_ID			ds.b	1		;$9A										<T4>
SONIC_BitMarch_ID	ds.b	1		;$9B										<T4>
SONIC_CAMDMA_ID		ds.b	1		;$9C										<T4>
SONIC_Loopback_ID	ds.b	1		;$9D										<T4>
TestGSCRegs_ID		ds.b	1		;$9E
PGESelfTest_ID		ds.b	1		;$9F
TestCSCRegs_ID		ds.b	1		;$A0										<H3>

MaxSubtest_ID		equ		*-1		;maximum subtest number

				ENDR

;
; The following structure describes one item in the table of machines for which there
; exists a cpu specific test table.  If a CPU does not have an element in this table,
; there is a default table which contains the tests which previously ran at startup
; on all machines.  By convention, this default table takes up the last position in
; the table.
;
; The macro defines one item in the table.
;

CPUList		STRUCTURE	0
			DSF.W	cpuBoxFlag			;CPU Box flag
			DSF.L	CPUTestListPtr		;Pointer to CPU specific test table
			ENDSTRUCT

	MACRO
	CPUListItem	&items
	STRUCTITEM	CPUList, &items
	ENDM

;
; The following structure describes each element in the cpu specific test table.
;
; The macro defines one item in the table.
;
;	NOTE: The ID entries for the tests and subtests are defined as words in this table
;	because it could potentially save lots of space (given all the tables that are created
;	and all of the entries, this could be quite a few bytes). However, this won't be a
;	problem, even though CTE defines IDs as longs. The reason is this: when tests and
;	subtests are ported over to the ROM, we can assign them any ID values we like. This
;	is possible because we own the headers and everything. So, we will just make sure to
;	keep their IDs within 16 bits. It seems unlikely that we'll use up more than 65,000
;	ID values in the ROM.
;
;	NOTE: This structure was modified to support the inclusion of a standard
;		test params "modifier" field, which can be unique for any number of a given
;		test. To use the modifier, a separate entry must exist in the machine test
;		lists for each "modified" DTM. These entries will differ only in their modifier.

CPUTestList		STRUCTURE	0
				DSF.W	TLTest_ID		;test list Test ID (note that this is a word)	<T4>
				DSF.W	TLSubTest_ID	;test list SubTest ID (note:  this is a word)	<T4>
				DSF.W	TLrunflags		;Flags indicating when to run this test			<T4>
			
				DSF.L	TLModifier		; the testParams structure modifier
				ENDSTRUCT

	MACRO
	CPUTestListItem	&items
	STRUCTITEM	CPUTestList, &items
	ENDM

;------------------------------							to next <T3> below
;
; The following Macro defines the calling convention for the 'copy ram to pram'
; routine.
;
; In order to execute this routine, the following registers must be set up:
;
;	a0 - decoder info pointer
;	a1 - product info pointer
;	a2 - via1 base address
;
;	NOTE: These two macros had to be changed to account for long branches to
;			the Copy... routines. They use a3 but preserve it across the calls.

	MACRO
		_CopyRAMToPRAM		&RAMAddr, &PRAMDest, &NumBytes		;macro to call the Copy To PRAM subroutine
		move.l	a3,-(sp)								; preserve a3 across this call
		pea		&RAMAddr								;push the source RAM address
		move.w	&PRAMDest,-(sp)							;push the PRAM destination value
		move.w	&NumBytes,-(sp)							;push the number of bytes
		lea		@CR2P,a3
		move.l	a3,-(sp)
		BigLea	CopyRAMToPRAM,a3
		jmp		(a3)
@CR2P	lea		8(sp),sp								;and clean up the stack
		movea.l	(sp)+,a3								; restore a3
	ENDM

;
; The following Macro defines the calling convention for the 'copy pram to ram'
; routine.
;
; In order to execute this routine, the following registers must be set up:
;
;	a0 - decoder info pointer
;	a1 - product info pointer
;	a2 - via1 base address
;
;	NOTE: These two macros had to be changed to account for long branches to
;			the Copy... routines. They use a3 but preserve it across the calls.

	MACRO
		_CopyPRAMToRAM		&PRAMSource, &RAMDest, &NumBytes		;macro to call the Copy To PRAM subroutine

		move.l	a3,-(sp)				; preserve a3 across this call
		move.w	&PRAMSource,-(sp)		;push the PRAM source address value
		pea		&RAMDest				;push the destination RAM address
		move.w	&NumBytes,-(sp)			;push the number of bytes
		lea		@CP2R,a3
		move.l	a3,-(sp)
		BigLea	CopyPRAMToRAM,a3
		jmp		(a3)
@CP2R	lea		8(sp),sp				;and clean up the stack
		movea.l	(sp)+,a3				; restore a3
	ENDM

;------------------------------							to next <T3> above

	ENDIF