SetCPU V1.5 Gamma 4
		Copyright 1989 by Dave Haynie 


	     THIS IS A GAMMA TEST DISTRIBUTION OF SETCPU V1.5
	This program may not be distributed in any form, except as 
	specified by the author.  


	SetCPU V1.5 is my third program designed for identification and
modification of system parameters roughly related to different versions of 
the Motorola 68000 family processors.  The program will identify the 
various types of processors and coprocessors in any 680x0 system up to
68030/68882 systems.  It also makes an attempt to correctly identify an
incorrectly designed but still functional 68020 system, several of which
are known to exist as Amiga coprocessor boards.  It contains MMU code to 
locate kernel ROM in write protected 32 bit ROM, with several optional 
patches to that ROM.

	In any case, the syntax of the program is given as follows:

	SetCPU [INST|DATA] [[NO]CACHE|[NO]BURST] [CONFIG n]
	       [KICKROM path|dfN:] [VERBOSE] [CARDROM path]
               [[NO]FASTROM [KEYPATCH n] [NOPATCH]] [TRAP n]
               [CHECK 680x0|68851|6888x|MMU|FPU]

where "[]" indicates an optional parameter, "|" indicates a choice of
parameters.  Typing "SetCPU ?" will retrieve this same syntax diagram.
Typing SetCPU alone will result in the SYSTEM configuration being 
send to the console, my current system returns this:
 
    SYSTEM: 68030 68882 FASTROM (INST: CACHE NOBURST) (DATA: NOCACHE NOBURST)

This indicates I have a 68030/68882 system, I've previously installed the 
FASTROM translation, and my instruction cache is turned on (done by AmigaOS 
V1.2 or V1.3).  Note that any parameters that don't make sense to the real 
system configuration, such as asking to modify the data cache on a 68020 
system or install the FASTROM translation on a 68000 system are just ignored.

[1] CPU IDENTIFICATION

	There are two basic types of functions performed by SetCPU.  The 
first of these is CPU system identification and cache control.  SetCPU will 
tell about the type of CPU setup in your machine, which consists of the CPU
itself and sometimes FPU or MMU coprocessors.  If the CPU supports caches,
SetCPU will let you switch these caches, and associated cache line burst mode,
on and off.  Finally, SetCPU can be used in a Startup-Sequence or other script
to make decisions based on the system that's running.  This is quite useful 
with accelerator cards like the Commodore A2620 that let you boot the machine
with either 68020 or 68000 in charge.  The individual CPU group commands are 
given below in detail:

[NO]CACHE
	This command will switch on or off 68020 and 68030 caches.  If not 
	qualified, it'll act on both instruction and data caches of the 68030.

[NO]BURST
	This command will switch on or off the burst cache line fill request 
	of the 68030.  If not qualified, it'll act on both instruction and 
	data caches.

INST
	This qualifies a CACHE or BURST operation to restrict it's application
	to the instruction cache only.

DATA
	This qualifies a CACHE or BURST operation to restrict it's application
	to the data cache only.

CHECK 
	This option lets you check for the existence of a particular CPU 
	system component in a script.  It works like this:

		SetCPU CHECK 68020
		If WARN
			echo "No 68020 here!"
		Else
			echo "Sho nuff got a 68020 here!"
		Endif

	The arguments to CHECK can be any of:

		68000	Matches the obvious
		68010	"
		68020	"
		68030	"
		68851	"
		68881	"
		68882	"
		FPU	Matches 68881 or 68882
		MMU	Matches 68851 or 68030

If any cache parameter doesn't apply to the system in use, it'll just be
ignored.  Use the data cache and all burst modes with caution.  Some 
68030 systems aren't designed to correctly support the data cache, so
switching it on may cause an instant system crash.  Even on systems that
correctly support the 68030 data cache, some device drivers, especially
those for DMA devices, may not work properly with the data cache enabled.
You may wish to check with your system vendors to make sure before using
the data cache in your standard system setup.


ROM TRANSLATIONS

	The second thing that SetCPU V1.5 manages are ROM translations.  
Using the MMU on systems so equipped, it can locate the Kernel ROM in the
much faster 32 bit wide memory provided on many 32 bit systems.  It can
also boot a ROM based system with an alternate version of KickStart.
Most of the options here relate to MMU translation setup and various 
modifications of the basic translation premise.

[NO]FASTROM
	This activates the FASTROM translation on or off an MMU equipped 
	system.  When switching on, it first allocates 256K of memory for
	the ROM image, then currenly 512 bytes of memory for the MMU table.
	It copies the ROM into the image area, then applies the translation
	by pointing the MMU at the table and activating it.  The NOFASTROM 
	option will switch off the MMU and reclaim the memory used for the 
	ROM image and MMU table.  If any other program set up the MMU
	for something, this could be a very bad thing to do.  In general, 
	until there's some level of OS support for the MMU in Amiga systems, 
	you're really safe using only one MMU tool at a time.  If you have
	an A2620 system, this option will always get 32 bit memory for you,
	if not, you'll have to make sure that your 32 bit memory is the
	first MEMF_FAST memory in the memory list for it to be used for the
	ROM image.  Also, that ROM image will be allocated as far back on
	that memory list as possible (if you're using MemMerge to merge
	together 32 and 16 bit memory boards, you may want to hold off
	MemMerging until you've got your FASTROM installed).  The SetCPU
	"SYSTEM" line will report this setup as a "FASTROM" setup.

Suboptions are:

	KEYPATCH n
		This will patch the keyboard scanning routine for machines 
		that have Cherry keyboards (small function keys).  The "n"
		parameter allows a variable delay between 1 and 1000 to be
		specified; the necessary delay depends entirely on the CPU
		being used.  As of the GAMMA 4 release, this patch has been
		shown not to cause any problems, and to install correctly,
		but I haven't yet tested it with a problem keyboard.  This
		patch is currently only available for 1.3.
	
	NOPATCH
		This prevents the normal ROM patches from being applied.
		Normally the Workbench screen message is patched to say
		"FastBench", as a visual indication that the FastROM 
		routines are installed.  These patches are currently only
		available under the release 1.3 Kernel.

CARDROM path

	When used in conjunction with the FASTROM option, this allows ROMs
	from expansion cards to be located in fast memory as well.  The
	path should reference a file containing lists of expansion cards
	that should be translated if found.  It's necessary to read this
	from a user-defined file, rather than from the expansion environment
	itself, since an expansion device's ROM could be located close to
	that device's registers; there's no way for SetCPU to know it's
	safe to translate a card ROM image unless you tell it.  On my system
	I read a file called CardROMList, which currently contains the single
	line:

		0x202 0x01 0x10000 0x8000 0x4000 CBM_2090A_Disk_Controller

	All the numbers given are in C language hex format.  The parameters
	are, in order, the device's manufacturer code, product code, the
	device's size (in bytes), the ROM's offset from the configured board's
	base address (in bytes), and the size of the ROM area to be
	translated (in bytes).  The final item is text string to identify
	the device; this'll be displayed by the VERBOSE option if the ROM
	translation does in fact take place.  The "_" characters in the
	name will be translated to " " characters.

KICKROM path|dfN:

	The KickROM option allows the system to be restarted with an
	alternate ROM image.  This can be from a KickStart disk in a
	specified floppy drive, or from a given file name.  If the
	ROM image is accessible, this command will cause the system to
	be immediately rebooted into the new OS.  Note that pre-1.3
	versions of the Amiga operating system will probably have some
	trouble with expansion cards, especially autoboot cards.  For
	that reason there's the CONFIG 0 option, which is explained
	later.

	The KICKROM command will reboot the machine with the new OS, but
	that ROM image will be physically located in either memory at
	$00C00000, if it's available, or CHIP memory, otherwise.  Once the
	new OS has started up, issuing either "SetCPU FASTROM ..." or
	"SetCPU KICKROM..." will cause that image to be moved into fast
	memory, and the slow memory will be given back to the system.  The
	SetCPU "SYSTEM" line will report a 16 bit KickROM image as a
	"SLOWKICK", and a 32 bit KickROM image as a "FASTKICK".  A machine
	running from a SLOWKICK kernel can't be re-KICKROMed, but can be
	from a FASTKICK kernel.

CONFIG n
	This option controls if and how expansion devices are recognized on 
	a KICKROM boot.  At the default configuration level, level 2, the
	expansion cards are left alone, allowing the new Kernel to try and
	configure them.  Since some older operating system will choke on 
	autoboot devices, this option will allow suppression of them for the
	rebooting process.  When requesting a KICKROM boot, a CONFIG level
	of 0 or 1 will prevent the devices from being recoginzed.

	Once rebooted in the new OS, moving from a SLOW	to a FAST Kick image,
	as described above, the CONFIG status will be honored.  If the
	devices weren't suppressed, nothinh special happens.  If they were,
	they'll stay suppressed, and you very likely won't have the memory
	to support a FAST Kick image.  Specifying a CONFIG level of 2 at
	this point will attempt to configure the devices without autobooting.
	At level 1, the devices will be made visable to the system again,
	but nothing will be done with them.

	As of the SetCPU V1.5 Gamma 4 release, CONFIG 0 appears to be 
	required with the 1.2 operating system, at least if there's any
	autoboot device, even if you're attempting to move from a slow to
	fast kick image.  The next release will attempt to allow 1.2 to
	configure non-autobooting devices at this point.

TRAP n
	This option controls the level of error trapping handled for 
	you by the SetCPU system.  The numeric parameter is actually 
	optional for compatibility with SetCPU V1.4.  If no TRAP is 
	specified, the default level 2 is enacted.  If the TRAP command is 
	given without a parameter, trap level 0 will be setup.  

	Trap level 0 causes the MMU to look at all 32 bits of address;
	access to any memory outside of the 24 bit space will result
	in an exception, which if unhandled, results in a GURU 2.  Trap
	level 1 will set up the MMU to only look at 24 bits of address space. 
	Trap level 2 works like level 1, but additionally sets up a trap
	handler for the Bus Error exception (which usually surfaces as a
	GURU #2).  For normal operation (eg, running other people's code),
	Trap level 2 is probably what you want.  For final testing of your
	own code, levels 0 or 1 can catch things which would go unnoticed
	on a 68000 machine, such as writing to ROM space or out of the 24
	bit address space.

	The exception handler used for level 2 trapping catches things like
	writes to protected areas of memory.  It just tells the bus machine
	not to complete the write, and signals no error.  There's a slight
	chance that this won't be enough repair for a program doing something
	really outlandish -- at that point, running at level 1 will let the
	GURU happen, which might help if you're debugging your own code.  
	Other that that, there's probably nothing you can do to get such a
	program working with the MMU turned on, other than having it fixed.
	The other thing to consider is that this exception handler could
	conflict with another system-level handler installed by a GOMF-like
	program.  That shouldn't cause a big problem, since you'll the one
	that was installed later, both of which presumably trap the error,
	but it's something to be aware of.

	Under V1.3 and earlier releases, a DOS bug can cause invalid accesses,
	which cause the exception, when running the EndCLI or NewCLI/NewShell 
	programs; running at level 1 or 2 will avoid gurus with these commands.

VERBOSE	
	This option more fully describes the system translations. 


Also note that much of what SetCPU does may be wrong in a future release of
the OS.  Things like identifying the MMU, CPU, or FPU that aren't fully done
in 1.3 may still work in a future OS release, but if that OS is correctly 
identifying the MMU, CPU (eg, 68020 vs. 68030), or FPU (eg, 68881 vs. 68882),
SetCPU should be using the OS's opinion of these items, not testing itself. 
On a more drastic note, if an OS ever starts using the MMU, the FASTROM and
other MMU code will almost certainly break.  It's the job of the OS to
arbitrate the MMU, and if the OS is doing that, no legal program would be
able to come along and muck with the MMU registers without reeking havoc
on the operating system.

			-Dave Haynie
			 PLINK:		D-Dave H
			 bix:		hazy
			 usenet:	{uunet,rutgers}!cbmvax!daveh