Heading:qjk40(635)
On the Harmonious Cooperation of XMesa and User Microcodey756qjk40\b
Page Numbers: Yes  X: 527  Y: 10.5"qjk40
Inter-Office Memorandumz18592l4445y762\f5b
To	Distribution	Date	April 16, 1979z18592l4445d2998e21(0,65535)(1,4445)(5,11684)(6,14146)\f7 2f0t2 1t0 12t6 1f7t0 4f0t7 1t0
From	Roy Levin	Location	Palo Altoz18592l4445d2998y716e25\f7 4f0t2 1t0 9t6 1f7t0 8f0t7 1t0
Subject	On the Harmonious Cooperation of	Organization	PARC/CSL
XMesa and User Microcode (version 3)z18592l4445d2998e25\f7 7f0t2 1t0 33f7 12f0t7 1t0
XEROX       z18592l508y644e14(2116)\f2 5f0
Filed on: [Ivy]<XMesa>Doc>Microcode.bravo (and .press)e30(0,16510)(1,65535)(5,65535)(6,65535)\f7 54f1
x2e12(2116)
This document describes an interface that permits users to load their own microcode into the RAM of an Alto II XM and execute it without interfering with the Mesa emulator.  These facilities are available only under XMesa.  Higher-level facilities of XMesa are described in a separate document filed on [Ivy]<XMesa>Doc>XMesa.press (and .bravo).x2e12jk40(1799)
Loading User Microcodex2e18jk80\b22B
The XMesa emulator occupies all of ROM1 and about 105 words of RAM.  The remainder of the RAM is available for use by client programs.  To simplify loading of user microcode, a file containing the overflow portion of the XMesa emulator is included in the user's assembly, producing a single output file that can be loaded in its entirety. Addressing requirements are specified in the file; no locations are reserved "by convention" alone. x2e12jk40
Assembly Procedurex2e12jk80\i
Users should carefully follow the steps below in constructing RAM images to be loaded under XMesa.x2e12jk40
1)	Obtain MesaXRAM.mu, MesaBLTLreal.mu, and MesabROM.mu from the dump file [Ivy]<XMesa>System>XMesaMu.dm.  The first tow files are the actual microcode, the third contains the definitions for all registers and other symbols used by the Mesa emulator.l4480d3776x2e12jk40(0,4480)\10f8 11f0 1f8 16f0 6f8 11f0 20f8 29f0
2)	Prepare a source file, Driver.mu, of the following form:l4480d3776x2e12jk40\26f8 9f0
#AltoConsts23.mu;	standard Alto definitions

; Sufficient pre-definitions must be inserted here to
; reserve locations 0-17 inclusive.

#MesaXRAM.mu;	includes MesabROM internally
#MesaBLTLreal.mu;	full implementation of BLTL
#UserMicrocode.mu;	user microcode sourcel4832x2e12jk40(0,11328)\f8
3)	Assemble Driver.mu with MU, obtaining Driver.mb .l4480d3776x2e12jk40(0,4480)\12f8 9f0 20f8 9f0
4)	Use the PackMU subsystem to convert Driver.mb to Driver.br .l4480d3776x2e12jk40\39f8 9f0 4f8 9f0
The code in MesaXRAM.mu must be assembled to begin at RAM location 20.  The user must assure this condition by including a predefinition (with no omitted labels) at the indicated place in Driver.mu; e.g.,x2e12jk40(1799)\12f8 11f0 165f8 9f0
%17,1777,0,L0,L1,L2,L3,L4,L5,L6,L7,L10,L11,L12,L13,L14,L15,L16,L17;l3552x2e12jk40\f8
If the user microcode includes the code to control a non-standard I/O device (e.g., a Trident disk), at least one of the labels in this predefinition will refer to an instruction used as part of the silent boot sequence (see Alto Hardware Manual, sections 2.4, 8.4, and 9.2.2).  Prudence suggests that the locations corresponding to tasks that are not intended to execute in the RAM be filled in with dummy instructions of the formx2e12jk40
Li:	TASK, :Li;l3552x2e12jk40(0,5664)(1,10720)
Thus, if Driver.mu contains no device control microcode, L0-L17 should all have this form.  If there is a space crunch, however, locations 0-17 may be used for ordinary microcode, though this is usually unnecessary.  x2e12jk40(1799)\9f8 9f0 74f1 123f0
Loading Procedurex2e12jk80\i
Driver.br can now be loaded using the (Mesa) RamLoad package.  The facilities of this package are defined in RamDefs.bcd, and are exported by the module RamLoad.bcd.  These files may all be found on [Ivy]<XMesa>Utilities.  RamDefs.mesa contains adequate documentation for the use of this package; the following Mesa code illustrates a typical use.x2e12jk40\f8 9f0 100f8 11f0 33f8 11f0 59f8 12f0
BEGIN OPEN RamDefs;
driver: MuImage _ ReadPackedMuFile["Driver.br"];
IF LoadRamAndBoot[driver,FALSE] ~= 0 THEN SIGNAL BogusMicrocode;
ReleaseMuImage[driver];
END;x2e12k40(0,4704)(1,65535)\f7b10f6 8f7 1f6 7f7 1f6 9f7 1f6 17f7 1f6 11f7 2f6 1f7 2f6 15f7 1f6 6f7 11f6 2f7 11f6 15f7 1f6 15f7 1f6 6f7 7f6
The second parameter to LoadRamAndBoot controls whether a silent boot is performed and should be FALSE unless it is necessary to alter the set of running tasks (as is required when additional device control microcode is initialized).  LoadRamAndBoot returns the number of mismatches between the constants specified in the microcode file and those present in the Alto's constants ROM.  If this number is non-zero, the microcode cannot execute properly on this machine.x2e12jk40(1799)\24f6b14f0B59f7b5f0B133f6b14f0B
Note to the nervous:  Since RamLoad is a Mesa program, it must exercise caution to avoid smashing the emulator on which it is running.  As long as the procedure above is meticulously followed in constructing Driver.br, RamLoad will be able to load the RAM without committing suicide.x2e12jk40\f1
Obtaining More RAM Spacex2e12jk80\i
The implementation of BLTL in microcode can be removed to recover approximately 26 words of RAM space, as described below.  Clients should weigh this option carefully, since BLTL is normally used by the XMesa swapper to move blocks of words (particularly code segments) between memory banks.  The swapper can survive without BLTL, but its performance is degraded.x2e12jk40
To eliminate BLTL from the RAM, retrieve the file MesaBLTLfake.mu from [Ivy]<XMesa>System>XMesaMu.dm and include it in Driver.mu in the place of MesaBLTLreal.mu.  Nothing else in Driver.mu should be changed.x2e12jk40\50f8 15f0 6f8 29f0 19f8 9f0 17f8 15f0 19f8 9f0
There and Back Againx2e18jk80\b20B
This section describes mechanisms for transferring control between the Mesa emulator and user-supplied microcode.  It assumes that this microcode is, in effect, implementing "extended instructions", and the linkage mechanisms described are suitable for this purpose.  Device driver microcode (e.g., for a Trident disk) executes in a different hardware task and therefore does not require these linkages.x2e12jk40\293i5I
The hardware-defined linkage mechanism between control memory banks is somewhat precarious.  Opportunities for errors arise because of way the "next address" field of the microinstruction is interpreted when SWMODE has been invoked (see section 8.4 of the Alto Hardware Manual).  The thing to remember is that whether you are in ROM1 or RAM, to get to the other memory you must specify an address with the 400 bit on (i.e., BITAND[address,400B] = 400B).  If you preserve this invariant, your Alto will probably avoid most black holes.x2e12jk40\418i5I
The Mesa JRAM Instructionx2e12jk80\i
Mesa has a bytecode, JRAM, that is a straightforward mapping of the Nova JMPRAM instruction.  JRAM takes the top element off the stack and dispatches on it, doing a SWMODE in the same instruction.  The microcode therefore looks approximately like this:x2e12jk40
JRAM: 	IR_sr17, :Pop;	pops stack into L, T; returns to JRAMr
JRAMr:	SINK_M, BUS, SWMODE;
	L_0, :zero;l3552x2e12jk40(0,5664)(1,10720)\f8
Thus, at entry to whatever microcode JRAM jumps to, L=0 and T has the target address of the jump.x2e12jk40(1799)
Getting back to ROM1 is equally straightforward.  User microcode should terminate with:x2e12jk40
	SWMODE;	sigh...SWMODE and TASK are both F1s
	:romnextA;	(... and we can't TASK here)l4032x2e12jk40(0,5664)\f8
romnextA is defined in MesabROM.mu, as are all the registers and other symbols used by the Mesa emulator.x2e12jk40(1799)\f8 8f0 15f8 11f0
The safest way to force a microinstruction to a specific address in the RAM is to use MU's '%' pre-definition facility.  For example,x2e12jk40
%1,1777,440,MyCode;

MyCode:	. . . ;	start of user-written microcodel3552x2e12jk40(0,5664)\f8
would enable the Mesa procedure MyCode (defined just below) to transfer control to the microcode at MyCode.x2e12jk40(1799)\32f6b6f0B62f8 6f0
Setting Up a JRAM in Mesax2e12jk80\i
The easiest way to access microcode in the RAM is by declaring a procedure to invoke it as follows:x2e12jk40
locationInRAM: CARDINAL = 440B;x2e12k40(0,4704)(1,65535)\f6b13f7 12f6 5f7 1f6
MyCode: PROCEDURE[arg1: AType, arg2: AnotherType] RETURNS [result: AThirdType] =
MACHINE CODE BEGIN
Mopcodes.zLIW, locationInRAM/256, locationInRAM MOD 256;
Mopcodes.zJRAM
END;l4704d2999x2e12k40\f6b6f7 12f6 4f7 1f6 6f7 1f6 5f7 1f6 12f7 9f6 1f7 1f6 6f7 1f6 12f7 2f6 1f7 18f6 14f7 1f6 18f7 1f6 15f7 3f6 4f7 1f6 16f7 4f6
When MyCode is invoked, the arguments are pushed on the evaluation stack, then a transfer to location 440 in the RAM occurs.  The microcode is responsible for computing result and placing it on the stack (details appear below).  The return sequence described above will then cause execution to resume immediately after the invocation of MyCode.x2e12jk40(1799)\5f6b6f0B158f6b6f0B162f6b6f0B
Note:  A few locations in the RAM are already used as entry points from the emulator microcode in ROM1.  Although no firm convention has been established, user microcode that avoids RAM addresses in the ranges 400-477 and 600-677 is unlikely to experience compatibility problems in the future.x2e12jk40\f1 293f0
The Mesa Stackx2e12jk80\i
The Mesa stack is implemented by 8 S-registers named stk0, stk1, ..., stk7, with stk0 being the base of the stack.  An R-register, stkp, indicates the number of words on the stack and is thus in the range [0..8].  To obtain values from the stack in the general case, therefore, requires a dispatch on stkp, but there is an important special case.  If MyCode is invoked in a statement context (i.e., one in which it stands alone and is not a term of an expression), the stack will be empty except for arg1 and arg2, which will therefore appear in stk0 and stk1, respectively.  In this case stkp will be 2 at entry, and the microcode should set it to 1 before returning to ROM1.  result should also be stored in stk0.  It is frequently useful to restrict the use of MyCode to statement contexts so that the microcode can take advantage of the known stack depth.  Note:  this assumes that values of type AType, AnotherType, and AThirdType are each represented in a single word.  Multi-word quantities are stored in adjacent stack words, with consecutive memory cells being pushed in increasing address order.x2e12jk40\53f8 4f0 2f8 4f0 7f8 4f0 7f8 4f0 46f8 4f0 166f8 4f0 46f6b6f0B36i4I103f6b5f0B4f6b4f0B33f8 4f0 5f8 4f0 30f8 4f0 85f6b6f0B26f8 4f0 50f6b6f0B89f1 42b5B2b11B6b10B170f0
An argument or return record exceeding 5 words in length requires special handling that is beyond the scope of this document.  See Roy Levin for details.x2e12jk40
Other Emulator Statex2e12jk80\i
The Mesa emulator has a number of temporary registers that may be freely used by code entered via JRAM.  The following list identifies all registers used by the Mesa emulator, their intended function, and whether they may be used as destroyable temporaries by user-supplied RAM microcode:x2e12jk40
Register	Type	Destroyable	Function
		by RAM codel4928x2e12k40(0,6592)(1,7936)(2,10624)
mpc	R	No	program counter
stkp	R	No	stack pointer
XTSreg	R	No	Xfer trap status
ib	R	No	instruction byte
brkbyte	R	No	Xfer state variable; overlaps AC3
clockreg	R	No	high resolution clock bits

mx	R	Yes	temporary during Xfer; overlaps AC2
saveret	R	Yes	holds return dispatch values; overlaps AC1
newfield	R	Yes	used by field instructions; overlaps AC0
count	R	Yes	temporary for counting
taskhole	R	Yes	temporary for holding things across TASKs
temp	R	Yes	general temporary
temp2	R	Yes	general temporary

lp	S	No	local frame pointer (+6)
gp	S	No	global frame pointer (+4)
cp	S	No	code segment pointer
stk0-7	S	No	8 evaluation stack registers
wdc	S	No	wakeup disable counter (interrupt control)

ATPreg	S	Yes	alloc trap parameter
XTPreg	S	Yes	xfer trap parameter
OTPreg	S	Yes	other trap parameter
mask	S	Yes	used by field instructions; smashed by BITBLT
index	S	Yes	used by field instructions; smashed by BITBLT
alpha	S	Yes	temporary for alpha byte; smashed by BITBLT
entry	S	Yes	Xfer and field temporary; smashed by BITBLT
frame	S	Yes	ALLOC/FREE temporary; smashed by BITBLT
my	S	Yes	Xfer temporary; smashed by BITBLT
unused1	S	Yes	smashed by BITBLT
unused2	S	Yes	smashed by BITBLT
unused3	S	Yes	smashed by BITBLT
l4928e12k40(0,6816)(1,8512)
User microcode should endeavor to TASK within 5 microcycles of entry.  It should also TASK as close to the end as possible.  Ideally, the penultimate instruction before returning to the emulator would TASK, but unfortunately SWMODE must appear in the same instruction and both are F1s.  The Mesa emulator tries to TASK at least every 12 microcycles; user microcode should observe the same guideline.x2e12jk40(1799)\125f1 162f0
The Mesa emulator does not check for pending interrupts on every instruction.  It does so only when it must fetch a new instruction word from memory.  Therefore, user microcode that sets a pending interrupt condition must not expect that the interrupt will be noticed by the emulator immediately upon return to ROM1.x2e12jk40
x2e12jk40(2116)
Distribution:
XMesa Users
Cedar Group
Mesa Groupl3528d2998x2e12k80