Inter-Office MemorandumToDistributionDateOctober 26, 1980FromRoy Levin, Richard JohnssonLocationPalo AltoSubjectOn the Harmonious Cooperation ofOrganizationPARC/CSL, OPD/SDDMesa and User MicrocodeXEROX Filed on: Doc>Microcode.bravo, .pressThis document describes an interface that permits users to load their own microcode into the RAMof an Alto II XM and execute it without interfering with the Mesa emulator. These facilities areavailable only on Alto II XM's with XMesa PROMs or with 3K RAM boards. When running on anAlto with the 3K RAM option, the following substitutions should be made in the remainder of thismemo: RAM1 replaces ROM1. RAM0 replaces RAM.Loading User MicrocodeThe Mesa emulator occupies all of ROM1 and about 143 words of RAM. The remainder of the RAMis available for use by client programs. To simplify loading of user microcode, a file containing theoverflow (RAM) portion of the Mesa emulator is included in the user's assembly, producing a singleoutput file that can be loaded in its entirety. Addressing requirements are specified in the file.The microcode normally loaded in the RAM by RunMesa includes some optional extensions so thatmany clients who loaded private microcode in the past may no longer need to do so. The includedfunctions are: Pup Checksum, IEEE floating point, and HBLT (used by Griffin). These microcodepackages use up all of the remaining RAM so that clients desiring additional microcode will have toeliminate one or more of these extensions.Assembly ProcedureUsers should carefully follow the steps below in constructing RAM images to be loaded under Mesa.1)Obtain XMesaOverflow.mu, XMesaRAM.mu, and Mesab.mu from the dump fileSystem>MesaMu.dm. (The dump file contains other files which should beignored.) The first two files are the actual microcode, the third contains the definitions forall registers and other symbols used by the Mesa emulator. If you want to retain any ofthe standard extensions you must get them from the dump file as well. The file names areFloat.mu, HBlt.mu and Checksum.mu.2)Rename XMesaOverflow.mu to be Driver.mu and add to the end a line of the form:#UserMicrocode.mu;user microcode source3)Delete one or more of the optional included files. If you delete Float.mu you must eitheruncomment the line ahead of it or provide your own implementation of the MISCinstruction.Н]Оg║pТiНІОc8qН]rН-єqН7BrТXНІО]ШqН]rН-єqН7BrНІОYqН]rН-єqН7BrН]ОW│НЭОSЛsrНЇОN#qТFП+НЇОG╗rТ≤П]tНЇОFrТ╘ Т╙trПQНЇОDZТ≥tr trТ trНЇОB╡Т√trТ≈П@НЇОAТtr trtr trНЇО<ИuНЇО9 rТ┴П!Т┼trtrtНЇО7СrТ┬Т┴ПVНЇО6KТ▄ trП8Т█НЇО4єТцП%ТдП=НЇО1UТ░Т▒trП5НЇО/ўТ┬П0Т┴П0НЇО.Т▐П@Т░НЇО,_Т▐П%trП.Т░НЇО*╦ТП*НЇО'ivНЇО$rТ┤Т┬П2trНюО лН─Т,wrxТ-w rwrН─О%wrТТП3ТУН─О}Т│П_Н─ОжТ≤П'Т≥П1Н─О/Т─ПUТ│Н─О┤ТП"НюО9Н─Т╪wrwrТҐНЮОЙwН,@ТНюО⌡rН─Т┬ПSТ┴Н─ОТТУПAТЖqН─ОMrЪ LЭ=Г]Э8On the Harmonious Cooperation of Mesa and User Microcode24)Assemble Driver.mu with MU, obtaining Driver.mb.5)Use the PackMU subsystem to convert Driver.mb to Driver.br.Driver.mu contains dummy instructions which occupy the first 20B locations of the RAM. If theuser microcode includes the code to control a non-standard I/O device (e.g., a Trident disk), at leastone of these instructions will be replaced by 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 locationscorresponding to tasks that are not intended to execute in the RAM befilled in with dummyinstructions of the formTaski:TASK, :Taski;Thus, if Driver.mu contains no device control microcode, Task0-Task17 should all have this form.If there is a space crunch, locations 0-17B may be used for ordinary microcode, though this is usually unnecessary. Loading ProcedureDriver.br can now be loaded using the (Mesa) RamLoad package. The facilities of this package aredefined in RamDefs.bcd, and are exported by the module RamLoad.bcd. These files may all befound on Utilities>. RamDefs.mesa contains adequate documentation for the use of thispackage; the following Mesa code illustrates a typical use.BEGIN OPEN RamDefs;driver: MuImage _ ReadPackedMuFile["Driver.br"];IF LoadRamAndBoot[driver,FALSE] # 0 THEN SIGNAL BogusMicrocode;ReleaseMuImage[driver];END;The second parameter to LoadRamAndBoot controls whether a silent boot is performed andshould be FALSE unless it is necessary to alter the set of running tasks (as is required whenadditional device control microcode is initialized). LoadRamAndBoot returns the number ofmismatches between the constants specified in the microcode file and those present in the Alto'sconstants ROM. If this number is non-zero, the microcode cannot execute properly on this machine.Note to the nervous: Since RamLoad is a Mesa program, it must exercise caution to avoid smashing the emulator onwhich it is running. As long as the procedure above is meticulously followed in constructing Driver.br, RamLoad will beable to load the RAM without committing suicide.There and Back AgainThis section describes mechanisms for transferring control between the Mesa emulator and user-supplied microcode. It assumes that this microcode is, in effect, implementing "extendedinstructions", and the linkage mechanisms described are suitable for this purpose. Device drivermicrocode (e.g., for a Trident disk) executes in a different hardware task and therefore does notrequire these linkages.The hardware-defined linkage mechanism between control memory banks is somewhat precarious.Opportunities for errors arise because of the way the "next address" field of the microinstruction isinterpreted when SWMODE has been invoked (see section 8.4 of the Alto Hardware Manual). Thething to remember is that whether you are in ROM1 or RAM, to get to the other memory you mustspecify an address with the 400 bit on (i.e., BITAND[address,400B] = 400B). If you preservethis invariant, your Alto will probably avoid most black holes. Additional address restrictions are ineffect on 3K RAM Altos; see Alto Hardware Manual section 8.4.ЪНЇОfЯuТП8НGОНюОbrН─wrwrwrНюО^оН─wrwrwrНЇО[─wrТ╠П6trtrТ╡НЇОYыТ┐Т└ПFНЇОX2Т▐ПIТ░НЇОV┼ТлТмПVНЇОTЦТАП>ТБtrНЇОS<ТН ЮОOМwН НЇОL·rТ▓wrТ⌠П'wrНЇОJВtТЁТЄПfrТНЇОG╗vНЇОDZwrТ┐П$wrП-НЇОB╡Т≈ w rТ≤w rНЇОAТ╙wrwrП/Т╚НЇО?dТП;Н ЮО<y zyН ЮО:nzyzyzyz yН ЮО8фzyzy zy zyН ЮО7z yzyН ЮО5xНЇО2)rТгz rТхНЇО0┌Тж yrТвП.НЇО.зТйП4Ткz rНЇО-3Т╟ПDТ╠НЇО+▄Т┘ trТ├ПTНЇО(`tТ∙qtТ√П3НЇО'Т─П^qtqtТ│НЇО%÷ТП0НЇО!═uНЇОQrТ╦П%Т╧П9НЇО╙ТП$ТП5НЇОТ╡ТЁПOНЇО[Т╡ vrТЁП1НЇОЄТНЇОeТ╗Т╘ПGНЇОЎТ▐ПDТ░П!НЇОТ▀wrПEНЇОoТ⌠П-trtrТ■НЇО хТ┘Т├vrzrНЇО Т┘П`Т├НЇО yТtrvrЪ░Ї 2>Г]ы{On the Harmonious Cooperation of Mesa and User Microcode3The Mesa MISC InstructionMesa has a bytecode, MISC, that is used to extend the Mesa bytecode set with special purposeinstructions. MISC takes an a-byte which specifies the operation to be performed. Some a valuesalready have defined meaning. These are recorded in System>MiscAlpha.mesa. To avoidconflict with "standard" extensions, e.g. floating point, users implementing strictly private functionsshould use a values larger than 200B. The a value 11B is filtered out by ROM1 and returns the AltoReal Time Clock. All other values are passed to microcode in the RAM. The MISC instruction operatesthis way only on version 41 microcode. In version 39 (released with Mesa 5.0) the MISC instruction always reads theclock regardless of the a value.The normal RAM microcode for MISC simply zeros the stack pointer and returns. The instructionlabeled MISC: in Driver.mu may be replaced by code to decode the a value. When control reachesMISC, the a value is in T. Control is returned to ROM1 by the sequenceSWMODE;sigh...SWMODE and TASK are both F1s:romnext;(... and we can't TASK here)romnext is defined in Mesab.mu, as are all the registers and other symbols used by the Mesaemulator.Setting Up a MISC in MesaThe easiest way to access microcode in the RAM is by declaring a procedure to invoke it as follows:alphaValue: CARDINAL = 100B;MyCode: PROCEDURE[arg1: AType, arg2: AnotherType]RETURNS [result: AThirdType] =MACHINE CODE BEGINMopcodes.zMISC, alphaValueEND;When MyCode is invoked, the arguments are pushed on the evaluation stack. Control will thenwind up at the location MISC in the RAM with alphaValue in T. The microcode is responsible forcomputing result and placing it on the stack (details appear below). The return sequencedescribed above will then cause execution to resume immediately after the invocation of MyCode.The Mesa JRAM InstructionNote: The MISC bytecode provides the function for which JRAM was originally intended. While JRAM isretained for compatibility, its use is discouraged.Mesa also has a bytecode, JRAM, that is a straightforward mapping of the Alto JMPRAM instruction.JRAM takes the top element off the stack and dispatches on it, doing a SWMODE in the sameinstruction. The microcode therefore looks approximately like this:JRAM: IR_sr17, :Pop;pops stack into L, T; returns to JRAMrJRAMr:SINK_M, BUS, SWMODE;L_0, :zero;Thus, at entry to whatever microcode JRAM jumps to, L=0 and T has the target address of thejump.ЪНЇОfЯuТП8НGОНЇОbv{vНЇО^оrТеqrТфП:НЇО](Т qr |rТ⌡П&|rНЇО[─Т▄Т█П!wr НЇОYыТ√П%vrТ≈П.НЇОX2Т│ Т┌|rtr|rtrtrНЇОV┼Т░П"Т▒trtqtНЇОUТ П'Т⌡П,qtНЇОS┌Т|tНЇОP4rТі tr ТїqrП=НЇОN▄Т▌qrwrТ▐|rНЇОLЕqrТ|rП(trН ОI√wН)ЮП#Н ОGОН)ЮНЇОD═rТЎ Т©wrП=НЇОBЫНЇО?╙vТ{vНЇО<\rТ┼Т▀trП5Н ЮО9 z yТFzТXyН ЮО5ЎzyТFzyzТXyzyzyН0О4zyzyzyТFН0О2pН0О0хz yzТX Н0О/!yНЇО+рrТ║zrТ╒ПAНЇО*+Т∙Т√qrtrw rwrП#НЇО(└ТЛ zrП9ТМНЇО&эТ▓ПXzrНЇО#▌vТ{vНЇО ?Т└ {vП*{vТ┘{vНЇО≤ТП3НЇОIrТ√Т≈qrП0qrНЇО╒qrТюП@ТаwrНЇОЗТПDН ЮО╛wТ─Н Н)ЮТП"Н ЮОН Н О] НЇОrТ╣П%qrТІНЇОg эЇ >Г[К{On the Harmonious Cooperation of Mesa and User Microcode4Getting back to ROM1 is equally straightforward. User microcode should terminate with:SWMODE;sigh...SWMODE and TASK are both F1s:romnextA;(... and we can't TASK here)romnextA is defined in MesabROM.mu, as are all the registers and other symbols used by theMesa emulator.The safest way to force a microinstruction to a specific address in the RAM is to use MU's '%' pre-definition facility. For example,%1,1777,540,MyCode;MyCode:. . . ;start of user-written microcodewould enable the Mesa procedure MyCode (defined just below) to transfer control to themicrocode at MyCode.Setting Up a JRAM in MesaThe easiest way to access microcode in the RAM is by declaring a procedure to invoke it as follows:locationInRAM: CARDINAL = 540B;MyCode: PROCEDURE[arg1: AType, arg2: AnotherType]RETURNS [result: AThirdType] =MACHINE CODE BEGINMopcodes.zLIW, locationInRAM/256, locationInRAM MOD 256;Mopcodes.zJRAMEND;When MyCode is invoked, the arguments are pushed on the evaluation stack, then a transfer tolocation 540B in the RAM occurs. The microcode is responsible for computing result and placing iton the stack (details appear below). The return sequence described above will then cause executionto resume immediately after the invocation of MyCode.Note: A few locations in the RAM are already used as entry points from the emulator microcode in ROM1. Althoughno firm convention has been established, user microcode that avoids RAM addresses in the ranges 400B-477B and 600B-677B is unlikely to experience compatibility problems in the future.The Mesa StackThe Mesa stack is implemented by 8 S-registers named stk0, stk1, ..., stk7, with stk0 being thebase of the stack. An R-register, stkp, indicates the number of words on the stack and is thus inthe range [0..8]. To obtain values from the stack in the general case, therefore, requires a dispatchon 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 forarg1 and arg2, which will therefore appear in stk0 and stk1, respectively. In this case stkpwill be 2 at entry, and the microcode should set it to 1 before returning to ROM1. result shouldalso be stored in stk0. It is frequently useful to restrict the use of MyCode to statement contextsso that the microcode can take advantage of the known stack depth. Note: this assumes that values oftype AType, AnotherType, and AThirdType are each represented in a single word. Multi-word quantities are stored inadjacent stack words, with consecutive memory cells being pushed in increasing address order.НЇОfЯuТП8НGОНЇОbrtrПCН О^оwН)ЮП#Н О]( Н)ЮНЇОYыrТ╧Т╨w rП8НЇОX2Т НЇОTЦТ√ПHtr wrТ≈НЇОS<ТП"Н ЮОOМwН ЮОL·Н Т─Н)ЮТНЇОIPrТЗТШzrП0НЇОG╗ТwrНЇОDZv{vНЇОArТ┼Т▀trП5Н ЮО=╪zyТFzТXyН ЮО:nzyТFzyzТXyzyzyН0О8фzyzyzyТFН0О7Н0О5xzyzТXyzyzyН0О3пz Н0О2)yНЇО.зrТ╗zrП>Т╘НЇО-3Т│trtrТ┌П,zrНЇО+▄Т┬ПYТ┴ НЇО)ДТП.zrНЇО&╧tТ┬Т┴П[НЇО%XТ▄П=Н+ О%ЧЩО%XП0НЇО#тТПDНЇО ├v НЇО7rТ╛П5wrТґwr НЇО░Т°П#wrТ²П:НЇОХТ■П#Т∙ПCНЇОAТ▄wrП.zr Т█vrНЇО Т┼Т▀ПUНЇОРzТ·rzrП!xrxrТ÷xНЇОKrТ░П3Т▒П!zrНЇОєТ⌠wrП2zrНЇОЭТ≥ПBtП!Т НЇОxТ²}t} t} tПLНЇОТТП] ░Їґ=Г[^kOn the Harmonious Cooperation of Mesa and User Microcode5An argument or return record may not exceed 5 words in length. If you need more arguments youshould pass a pointer. We believe that it is relatively easy to allow arguments up to 6 words. It may be possible toallow up to 8 words in the future.Other Emulator StateThe Mesa emulator has a number of temporary registers that may be freely used by code enteredvia MISC or JRAM. The following list identifies all registers used by the Mesa emulator, theirintended function, and whether they may be used as destroyable temporaries by user-supplied RAMmicrocode:RegisterTypeDestroyableFunctionby RAM codempcRNoprogram counterstkpRNostack pointerXTSregRNoXfer trap statusibRNoinstruction bytebrkbyteRNoXfer state variable; overlaps AC3clockregRNohigh resolution clock bitsmxRYestemporary during Xfer; overlaps AC2saveretRYesholds return dispatch values; overlaps AC1newfieldRYesused by field instructions; overlaps AC0countRYestemporary for countingtaskholeRYestemporary for holding things across TASKstempRYesgeneral temporarytemp2RYesgeneral temporarylpSNolocal frame pointer (+6)gpSNoglobal frame pointer (+4)cpSNocode segment pointerstk0-7SNo8 evaluation stack registerswdcSNowakeup disable counter (interrupt control)ATPregSYesalloc trap parameterXTPregSYesxfer trap parameterOTPregSYesother trap parametermaskSYesused by field instructions; smashed by BITBLTindexSYesused by field instructions; smashed by BITBLTalphaSYestemporary for alpha byte; smashed by BITBLTentrySYesXfer and field temporary; smashed by BITBLTframeSYesALLOC/FREE temporary; smashed by BITBLTmySYesXfer temporary; smashed by BITBLTunused1SYessmashed by BITBLTunused2SYessmashed by BITBLTunused3SYessmashed by BITBLTUser microcode should endeavor to TASK within 5 microcycles of entry. It should also TASK asclose to the end as possible. Ideally, the penultimate instruction before returning to the emulator would TASK, butunfortunately SWMODE must appear in the same instruction and both are F1s. The Mesa emulator tries toTASK at least every 12 microcycles; user microcode should observe the same guideline.The Mesa emulator does not check for pending interrupts on every instruction. It does so onlywhen it must fetch a new instruction word from memory. Therefore, user microcode that sets apending interrupt condition must not expect that the interrupt will be noticed by the emulatorЪНЇОfЯuТП8НGОНЇОbrТ┬П^НЇО`vТ─tТ│ПLНЇО^оТП"НЇО[─vНЇОX2rТ·П:Т÷П#НЇОV┼ТоqrqrТпПNНЇОTЦТ░П[Т▒tНЇОSЗwН═rН!@Н)─П*Н@О=vwН═rН!@Н)─П(Н@О;РwН═rН!@Н)─Н@О:nwН═rН!@Н)─П)Н@О8ЙwН═rН!@Н)─Н@О7fwН═rН!@Н)─Н@О4^wН═rН!@Н)─Н@О2зwН═rН!@Н)─Н@О1UwН═rН!@Н)─Н@О/яwН═rН!@Н)─Н@О.MwН═rН!@Н)─П*Н@О+EwН═rН!@Н)─Н@О)аwН═rН!@Н)─Н@О(=wН═rН!@Н)─Н@О&╧wН═rН!@Н)─П-Н@О%5wН═rН!@Н)─П-Н@О#╠wН═rН!@Н)─П+Н@О"-wН═rН!@Н)─П+Н@О ╘wН═rН!@Н)─П'Н@О%wН═rН!@Н)─П!Н@О║wН═rН!@Н)─Н@ОwН═rН!@Н)─Н@О≥wН═rН!@Н)─НЇОфТ÷П"wrП*Т═wrНЇОТ┌tТ┐П4qtНЇОwТ╨ qtП$Т╩rНЇОпwrТПQНЇО │Т╡П:ТЁП$НЇОзТ╛ТґПVНЇО 3ТеП0ТфП.Ъ xЇ Л=Г^чOn the Harmonious Cooperation of Mesa and User Microcode6immediately upon return to ROM1.Distribution:Mesa UsersCedar GroupMesa GroupЪНЇОfЯuТП8НGОНЇОbrtrНІО[─Н хОYыТX Н хОX2 Н хОV┼ Ъ├ІVC)Ох* TIMESROMAN HELVETICA TIMESROMAN LOGO TIMESROMAN TIMESROMAN TIMESROMAN HELVETICA GACHA HELVETICA HELVETICA HELVETICAHIPPO TIMESROMANх ┘┘∙"&ж(ЪЪj/+)√#yыЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪMicrocode.bravoJohnssonOctober 26, 1980 4:29 PM