ack/util/int/switch/READ_ME

# $Id$

This directory contains two programs:

mkswitch:
	C program, necessary for regenerating the giant switch
	needed for the disassembly function of the interpreter, 
	which (still) works with Operand access method 2
	(Intelligent Routines) as described in "The EM
	interpreter".

mkiswitch:
	C program, necessary for regenerating the giant switch
	needed for finding the correct instruction handling routine 
	for each opcode.  It works with Operand access method 3
	(Intelligent Calls) as described in "The EM interpreter".
	It constructs the operand of the instruction and passes
	it to the appropriate routine with the operand as
	argument.

The first program reads an input file which holds the interpreter
opcode table (as shown in the [IR-81] report appendix B),
and creates an output file which contains an enormous switch
file.  This switch has entries for each possible opcode.  It's
possible to supply a third filename, which is the name of file
where all functions will be stored.  This is necessary if a new
function implementation is needed.

The first argument to mkswitch is the prefix to be used in the
generated function names.  For the interpreter proper this prefix
is  Do.

The input file contains lines in the following format:

	Mnemonic Flags Count First-number

The created switch file will contain a switch, with each case
having one of the following formats (? is the opcode):

	1) case ?: DoAz();
	2) case ?: DoBm(val);
	3) case ?: DoCs(hob, wsize);
	4) case ?: DoDXY(wsize);

Ad 1)	This format shows that the corresponding opcode does not
	have an argument.  Often the operand is popped from the
	stack.

	e.g. DoNOPz(), this performs the NOP instruction.

Ad 2)	This is the format for a mini.  There is one implicit
	argument (I) .

	e.g. DoLOCm(1), this is the LOC 1 instruction.

Ad 3)	This format corresponds with a shortie.  There is an implicit
	argument (high order byte), and a one byte text argument
	(low order byte).  W equals 'wsize' (if a word multiple),
	otherwise it equals '1'.  H is the value of the high
	order byte.

	e.g. DoLOEs(2, wsize), these are all LOE instructions,
	with all addresses in the range:
		(512 * wordsize) . . (767 * wordsize).
	
Ad 4)	This format is used for opcodes with 2 or more text arguments,
	and no implicit arguments.  There are 6 types:

	XY = l2: two byte negative or positive text argument.
	XY = n2: two byte negative text argument.
	XY = p2: two byte positive text argument.
	XY = l4: four byte negative or positive text argument.
	XY = n4: four byte negative text argument.
	XY = p4: four byte positive text argument.

	W equals 'wsize' (if a word multiple), otherwise it equals 1.

	e.g. DoLDLp2(wsize), these are all LDL instructions, with
	negative local offsets, which are word multiples.


When two file arguments are given to mkswitch (input file and output file),
only the switch is generated.  If an additional third file name is
given (another output file), this file is filled with all function
calls in such a manner that mkfuncs will generate new function files.

Mkfuncs expects two arguments, an input file generated by
mkswitch and the name of a directory where the new function
files are stored.  These files (15) each represent one group (as
proposed in [IR-81] sec 11.3) of instructions.  Each file will
contain all functions needed to implement that specific group
of instructions.  The functions will only contain a logging
message, and a call to newPC() which is necessary to skip the
arguments.  The names of the generated files are: do_XXX.c, where
XXX is the name of the corresponding instruction group.

(Note: these remarks about mkfuncs are probably outdated now,
since mkfuncs has disappeared. -rbf)