Inter-Office MemorandumToDistributionDateApril 16, 1979FromRoy LevinLocationPalo AltoSubjectOn the Harmonious Cooperation ofOrganizationPARC/CSLXMesa and User Microcode (version 3)XEROX Filed on: [Ivy]Doc>Microcode.bravo (and .press)This 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 under XMesa. Higher-level facilities of XMesa are described in a separate documentfiled on [Ivy]Doc>XMesa.press (and .bravo).Loading User MicrocodeThe XMesa emulator occupies all of ROM1 and about 105 words of RAM. The remainder of theRAM is available for use by client programs. To simplify loading of user microcode, a filecontaining 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 arespecified in the file; no locations are reserved "by convention" alone. Assembly ProcedureUsers should carefully follow the steps below in constructing RAM images to be loaded underXMesa.1)Obtain MesaXRAM.mu, MesaBLTLreal.mu, and MesabROM.mu from the dump file[Ivy]System>XMesaMu.dm. The first tow files are the actual microcode, thethird contains the definitions for all registers and other symbols used by the Mesaemulator.2)Prepare a source file, Driver.mu, of the following form:#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 source3)Assemble Driver.mu with MU, obtaining Driver.mb .Н]Оg║pТiНІОc8qН]rН-єqН7BrТX НІО]ЭqН]rН-єqН7BrНІОYqН]rН-єqН7BrН]ОW│П$НЭОSЛsrНЇОN"qТFП6НЇОG╗rТ▄П?Т█П!НЇОFТ╒ТёПQНЇОDXТ▀П=Т▄П%НЇОB╟ТП2НЇО>█tНЇО;>rТ■П1Т∙П(НЇО9√ТшТэП@НЇО7НТЩП8ТЧП!НЇО6FТьП*ТыП4НЇО4·ТПHНЇО1OuНЇО.rТдТеП>НЇО,XНюО) Н─Тъv rvrТЮv rН─О'avrТ⌠Т■Н─О%╧ТМП&ТНП-Н─О$НюО бН─ТvrНЮОsvН,@НЮО#П5НЮО{П#НЮО+Н,@НЮО┐Н,@НЮОшН,@НюО▄rН─vrvrЪХЭE=ГZҐПOn the Harmonious Cooperation of XMesa and User Microcode24)Use the PackMU subsystem to convert Driver.mb to Driver.br .The code in MesaXRAM.mu must be assembled to begin at RAM location 20. The user must assurethis condition by including a predefinition (with no omitted labels) at the indicated place inDriver.mu; e.g.,%17,1777,0,L0,L1,L2,L3,L4,L5,L6,L7,L10,L11,L12,L13,L14,L15,L16,L17;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 silentboot sequence (see Alto Hardware Manual, sections 2.4, 8.4, and 9.2.2). Prudence suggests that thelocations corresponding to tasks that are not intended to execute in the RAM be filled in withdummy instructions of the formLi:TASK, :Li;Thus, if Driver.mu contains no device control microcode, L0-L17 should all have this form. Ifthere is a space crunch, however, locations 0-17 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 packageare defined in RamDefs.bcd, and are exported by the module RamLoad.bcd. These files may allbe found on [Ivy]Utilities. RamDefs.mesa contains adequate documentation for the useof this package; 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 thismachine.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.Obtaining More RAM SpaceThe implementation of BLTL in microcode can be removed to recover approximately 26 words ofRAM space, as described below. Clients should weigh this option carefully, since BLTL is normallyused by the XMesa swapper to move blocks of words (particularly code segments) between memorybanks. The swapper can survive without BLTL, but its performance is degraded.To eliminate BLTL from the RAM, retrieve the file MesaBLTLfake.mu from[Ivy]System>XMesaMu.dm and include it in Driver.mu in the place ofMesaBLTLreal.mu. Nothing else in Driver.mu should be changed.НЇОfПtТП9НGОНюОbrН─П$vrvrНЇО^оТ─v rТ│П'НЇО]'ТБП+ТЦП3НЇО[vrТН ЮОX0vПCНЇОTАrТ▒П2Т▓П2НЇОS9Т ПRТ⌡НЇОQ▒Т▌Т▐ПQНЇОOИТЎПYТ©НЇОNAТН ЮОJРН НЇОGёТ╗vrПHТ╘wНЇОEШТ▄Т█П`rТНЇОB╛uНЇО?]vrТ▄П#Т█П1НЇО=╣Т─v rТ│v rНЇО< Т П$vrП,НЇО:eТПCНЇО7xТF yТXxНЇО5nyxyxyxy xНЇО3фyxyxТF yТXxТFyТXxНЇО2y xyxНЇО0vНЇО-'rТгy rТхНЇО+Тж xrТвП.НЇО)вТйП4Ткy rНЇО(/Т╟ПDТ╠НЇО&┤ТДП@ТЕНЇО$ъНЇО!ЁwТ≈Т≤ПjНЇО RТ┐П]Т└НЇОЯТП0НЇОфuНЇОwrТ⌡ПRТ°НЇОоТ┌ Т┐ПXНЇО'Т┤П(Т┬П5НЇОТПNНЇО0ТнП,ТоvrНЇО┬vrТxvrТyНЇОЮvrТvrЪPЇ≥>Г[qROn the Harmonious Cooperation of XMesa and User Microcode3There 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 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 youmust specify 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.The Mesa JRAM InstructionMesa 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 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.Getting 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,440,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 = 440B;НЇОfПtТП9НGОНЇОbНЇО^оrТ╦П%Т╧П9НЇО]'ТП$ТП5НЇО[Т╡ТЁПOНЇОYвТ╡ urТЁП1НЇОX/ТНЇОTЮТ╗Т╘ПGНЇОS8Т╩П@Т╪П!НЇОQ░Т├П5Т┤П'НЇОOХТ╞ПTТ╟НЇОN@Т▀П$Т▄urП/НЇОL≤ТП?НЇОIIuНЇОEЗrТ■Т∙П=НЇОDRТўПDТ╞НЇОB╙ТПDН ЮО?[vТ─Н Н)ЮТ╛ТґН ЮО=ЁН ТН О< НЇО8╪rТїПEТ╗НЇО7НЇО3еТПWН О0vvН)ЮП#Н О.н Н)ЮНЇО+rТ╨v rТ╩НЇО)вТ НЇО&┬Т┬ Т┴ПUНЇО$ЮТП"Н ЮО!▒vН ЮОAН Т─Н)ЮТНЇОРrТЗТШyrП0НЇОJТvrНЇОШuНЇО╛rТ│ПMТ┌НЇО]yxТFyТXxЪ≤Ї>ГXТ On the Harmonious Cooperation of XMesa and User Microcode4MyCode: 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 440 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 400-477 and 600-677 isunlikely 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.An argument or return record exceeding 5 words in length requires special handling that is beyondthe scope of this document. See Roy Levin for details.Other Emulator StateThe Mesa emulator has a number of temporary registers that may be freely used by code enteredvia JRAM. The following list identifies all registers used by the Mesa emulator, their intendedfunction, 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 temporaryНЇОfПtТП9НGОНЇОbyxТFyxyТXxyxyxТFyТXxyxyxТFН`О`vН`О^нyxyТXxyxyxН`О]&y Н`О[~xНЇОX/rТ╗yrП>Т╘НЇОV┤Т┌ПAТ┐ yrНЇОTъТ┬ПYТ┴ НЇОS7ТП.yrНЇОPwТ┬Т┴П[НЇОN╙Т│ПTТ┌П"НЇОM&ТП<НЇОIвu НЇОF┬rТ│П5vrvrvrТ┌vr НЇОDЮТ⌠П#vrП&Т■НЇОC8Т∙ПfНЇОA░Т┌vrП.yrТ┐П$urНЇО?ХТ┼Т▀ПUНЇО>@yТ·ryrП!vrvrТ÷vНЇО<≤rТ░П3Т▒П!yrНЇО:ПТ┬vrТ┴yrНЇО9HТ≥ПBwП!Т НЇО7цТ²zwz wz wПLНЇО6?ТП]НЇО2ПrТ▐ПAТ░НЇО1HТП7НЇО-ЫuНЇО*╙rТ·П:Т÷П#НЇО)Т╧ПGТ╨НЇО'ZТЭП&ТЩП0НЇО%╡ Н@О"cНюН Н)─НО ╩ТX Н@О▐Н═Н!@Н)─Н@О Н═Н!@Н)─Н@О┘Н═Н!@Н)─Н@ОН═Н!@Н)─Н@О{Н═Н!@Н)─П!Н@ОЖН═Н!@Н)─Н@ОЛН═Н!@Н)─П#Н@ОgН═Н!@Н)─П*Н@ОБН═Н!@Н)─П(Н@О]Н═Н!@Н)─Н@ОьН═Н!@Н)─П)Н@ОSН═Н!@Н)─LЇ=Г\ЧїOn the Harmonious Cooperation of XMesa and User Microcode5temp2RYesgeneral 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 emulatorimmediately upon return to ROM1.Distribution:XMesa UsersCedar GroupMesa GroupНЇОfПtТП9НGОН@ОbrН═Н!@Н)─ТXН@О_Н═Н!@Н)─Н@О]▐Н═Н!@Н)─Н@О\ Н═Н!@Н)─Н@ОZ┘Н═Н!@Н)─Н@ОYН═Н!@Н)─П*Н@ОUЖН═Н!@Н)─Н@ОTqН═Н!@Н)─Н@ОRЛН═Н!@Н)─Н@ОQgН═Н!@Н)─П-Н@ОOБН═Н!@Н)─П-Н@ОN]Н═Н!@Н)─П+Н@ОLьН═Н!@Н)─П+Н@ОKSН═Н!@Н)─П'Н@ОIнН═Н!@Н)─П!Н@ОHIН═Н!@Н)─Н@ОFдН═Н!@Н)─Н@ОE?Н═Н!@Н)─НЇО@kТ≥П>Т НЇО>цТ─wТ│П=НЇО=ТЇПEТ╦rНЇО;sТПUНЇО8$Т╡П:ТЁП$НЇО6|Т╛ТґПVНЇО4тТеП0ТфП.НЇО3,ТНІО,▌Н хО*ФТX Н хО)> Н хО'√ ЪфІ'O=Г@╩ TIMESROMAN HELVETICA TIMESROMAN LOGO TIMESROMAN TIMESROMAN GACHA TIMESROMAN HELVETICA HELVETICA TIMESROMANў СYЯ!ЪЪj/$"⌠BцщЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪЪMicrocode.bravoLevinApril 16, 1979 9:04 PM