Heading:qjk40(635)
How to Use Midas with Piloty756qjk40\b27B
Page Numbers: Yes  X: 527  Y: 10.5"qjk40
XEROX
PARC
9 June 1983


z18556l3033c\f2 5f0 1b5B
To:	Microcode Developers

From:	Edward Fiala

Subject:	How to Debug Dolphin Microcode With Midas

Filed On:	[Indigo]<D0Docs>DebugWithMidas.Bravo, .Press

z18556l3033(0,65535)(1,4960)\f1 3f0t2 1t0 22f1 5f0t2 1t0 14f1 8f0t2 1t0 42f1 10f0t2 1t0 45f1
This is a short description of how to debug Pilot, Cedar, or AMesa microcode with Midas.  It handles any combination of microswitch/Star keyboards and CSL/LF monitors.  Documentation for Midas can be found on [Indigo]<D0Docs>D0Midas.Press.z18556x4e12j(635)
Midas is a debugging program that runs under the Alto OS on a different machine from the one you are debugging.  You can run it on an Alto or on the Alto partition of a Dolphin.  In either case, you need a special cable to connect the printer interface of the Alto or Dolphin running Midas to the printer interface of the Dolphin being debugged.z18556x4e12j
If you don't already have a Midas disk, you will need to build one:z18556x4e12j
1.  Spin up a clean disk on your Alto.  Boot the NetExec and invoke NewOS. Use the long installation dialog and erase the disk.  If you going to run Midas on a Dolphin, you don't have to do this--just make sure there are 2000 free pages on your Alto partition.z18556l4268x4e12
2.  Obtain the following files from the place where you get Alto subsystems (e.g., [Maxc]):z18556l4268x4e12
Micro.run	(microcode assembler)z18556l5538x4e12(0,11465)(1,65535)
MicroD.run	(microcode loader)z18556l5538x4
Ftp.runz18556l5538x4
Bravo.cm	and execute this command filez18556l5538x4
RunMesa.runz18556l5538x4
Empress.runz18556l5538x4
Find.runz18556l5538x4
Waterlily.runz18556l5538x4
3.  Load D0MidasRun.dm and retrieve the other files below from [Indigo] with Ftp:z18556l4268x4e12(635)
<D0Source>D0Lang.Mcz18556l5538x4e12(0,11465)
<D0>D0MidasRun.dmz18556l5538x4
<D0>Midas.programsz18556l5538x4
<D0>MemErrors.midasz18556l5538x4
<D0>MakeLoaderFile.bcd	(microcode boot file builder)z18556l5538x4
Because of file name conflicts, you can only have one of the following dumps of microcode sources loaded at-a-time (except that Initial can coexist with Pilot microcode if Pilot microcode is loaded last):z18556l4268x4e12(635)
<D0Source>CedarUCode.dm	for Cedar microcodez18556l5538x4(0,11465)
<D0Source>PilotUCode.dm	for Pilot microcodez18556l5538x4
<D0Source>AMesaSources.dm	for AMesa microcodez18556l5538x4
<D0Source>InitialSources.dm	for Initial microcodez18556l5538x4
4.	Call Ed Fiala or send message to Fiala.Pa if you have problems with these procedures.z18556l4268x4e12(635)
There are several important limitations to the ways in which Midas can be used to debug a Dolphin.  The first is that you must BEGIN with Midas.  If instead you attempt to attach to a machine which is in an interesting state, then Midas will boot the machine while activating its Kernel microcode, and all RM registers and the TPC's for the tasks will be reset (possibly storage will survive booting, however).z18591x4e12j
The second limitation is that the various microcode systems that you run must all reserve space for the Midas Kernel and have an appropriate linkage between the fault handler and the Midas Kernel.  Initial has an IMReserve for the Midas Kernel; if you assemble the Pilot microcode with WithMidas=1 in GlobalDefs.Mc, then Pilot also has an IMReserve for the Midas Kernel.  SDD Pilot microcode at the present time is built with WithMidas=1, but the Cedar and Tor variants are not, and the normally released Alto emulator overwrites the Midas Kernel, so you will need to obtain or create special debugging versions of these to debug from Midas.z18591x4e12j
The third limitation is that you cannot activate Pilot directly from Midas by loading and running .Mb files.  Instead, you must install the Pilot germ and microcode on the Dolphin SA4000, and then load the microcode by running the Initial microcode from Midas.  The microcode installed on the SA4000 must be the SAME as that on your Midas debugging disk.  In addition, you must have a Physical Boot Volume set. z18591x4e12j
Using Midas to Boot Pilotz18591e18j(2048)\b25B
Boot the Midas disk and type "Midas/i Pilot".  The Pilot.Midas command file will first load Initial.Mb, insert a breakpoint at RamLoaded, and start Initial at SAPilotStart.  If all goes properly, Initial will read the Pilot microcode and all of its overlays from your SA4000 into storage, and the breakpoint at RamLoaded will be hit after LoadRAM has loaded Pilot1 into the microstore; then Pilot1 symbols are loaded by RunProg and the RamLoaded breakpoint is reinserted in octal (at IMX 316); this is necessary because all previous symbols and breakpoint information (which pertained to Initial) have been flushed by Run-Prog; since the space occupied by the LoadRAM module in Initial has been IMReserved in Pilot, the RamLoaded symbol is no longer available.z18591e12j
The Pilot.Midas command file pauses at this point with a message saying that Pilot1 is loaded, and you may abort the command file or continue it.  If you continue the command file, it will pause again at BootEmulators in Initialize.Mc after comleting all device initialization but before loading the Pilot2 overlay.  If you continue from there, it will pause a final time after loading the Pilot2 overlay; if you continue from there, your physical boot volume will be started.z18591e12j
Assuming that you abort the first time the Pilot.Midas command file pauses, then you have the following options:z18591e12j
a) Kill the IMX 316 breakpoint and proceed, letting Pilot start normally.  After it is running, you can get control with Midas control-C (or by selecting and left-buttoning "Abort") and establish a suitable debugging context as discussed below.z18591e12j
b) Insert any breakpoints in Pilot1 that you wish and continue.  This allows debugging initialization and other Pilot1 microcode.z18591e12j
c) If you want to debug the terminal microcode, then the driver for the LF keyboard system is included in Pilot1, so you can insert breakpoints directly; for a CSL keyboard system (with either a CSL or LF monitor), you must proceed from the RamLoaded breakpoint--the next time you get to that breakpoint, the microcode for that terminal, obtained from the first or second overlay in PilotD0.Eb or CedarD0.Eb, will have been loaded into the microstore.  See below for establishing a debugging context.z18591e12j
To debug Pilot2 microcode, you should continue the command file until it indicates that Pilot2 has been loaded; then abort it. z18591e12j
Using Midas to Debug AMesa microcodez18591e18j\b36B
1.  Obtain a special debugging version of the Alto emulator that contains an IMReserve for the Midas Kernel--normal Alto microcode overwrites the Kernel and cannot be used.  [Indigo]<D0>NewAMesa.Mb with CSL keyboards or [Indigo]<D0>LFAMesa.Mb with LF keyboards are suitable; put one of these on your Midas disk.z18591e12j
2.  Boot the Midas disk and type "NewAMesa;L"; this loads the Alto microcode.  Start the Alto emulator with "EGO;G" "KGO;G" or "KGOP2;G" for ether boot, partition 1 boot, or partition 2 boot, respectively.  The Alto Executive will appear shortly on the screen.z18591e12j
Displaying Appropriate Symbols From Midasz18591e18j\b41B
When appropriate microcode is loaded, you can setup a debugging context by doing Run-Prog on PILOT1SYMBOLS, PILOT2SYMBOLS, CSLSYMBOLS, or CSLFSYMBOLS.  Run-Prog clears all previous symbols and breakpoints and loads symbols from one of the four Pilot overlays--it is impossible to have symbols from more than one overlay concurrently active.  PILOT1SYMBOLS and PILOT2SYMBOLS also setup the middle column of the Midas display with registers generally of interest when debugging Pilot emulator code; CSLSYMBOLS and CSLFSYMBOLS setup the middle column with registers generally interesting when debugging one of the display drivers.z18591e12j
At any time you can change the contents of the Midas display by doing Read-Cmds on a variety of files in the menu with suggestive names.  Among these are the following:z18591e12j
BBREGS	Displays BitBlt registers in middle column.z18591l7056d3704e12j(0,7056)
RDCREGS	Displays RDC registers in middle column.z18591l7056d3704e3j
GCDEBUG	Displays CedarGC registers.z18591l7056d3704e3j
MEMERRORS	Displays memory error registers in right column.z18591l7056d3704e3j
TX*	Various TextBlt registers.z18591l7056d3704e3j
Loading the Eprom Microcodez18591e18j(2048)\b27B
To load the microcode that is normally loaded from the EPROMs, use the EPROM command file:z18591e12j
1. Select Run-Prog on the Midas menu.z18591e12j
2. When the Run-Prog menu appears, select EPROM.z18591e12j
3. When SA4000Boot is loaded and the next menu appears, select continue.  This will cause the D0 to be booted from the Initial Microcode file.z18591e12j
Loading Initialz18591e18j\b15B
To load the Initial microcode, use the Initial command file:z18591e12j
1. Select Run-Prog on the Midas menu.z18591e12j
2. When the Run-Prog menu appears, select INITIAL.z18591e12j
When the command file is finished, the display will show some symbols of interest for the MemInit.Mc module.  The various starting addresses are on pages 1 and 2 of Initial.Mc; they include the following:z18591e12j
SAAltoStart	boots and starts AMesa from the SA4000.z18591l7056d3704e12j(0,7056)
SAPilotStart	boots and starts Pilot from the SA4000.z18591l7056d3704e3j
EtherAltoStart	boots and starts AMesa from the 3 mb Ethernet.z18591l7056d3704e3j
EtherPilotStart	boots and starts Pilot from the 3 mb Ethernet.z18591l7056d3704e3j
Some interesting breakpoints in Initial are the following:z18591e12j(2048)
RamLoaded	(IMX 316) where LoadRAM finishes.z18591l7056d3704e12j(0,7056)
IMap	beginning of the map and storage test.z18591l7056d3704e3j
imRepeatStorageTest	after map test.; here you can change the contents of the SoftQThreshold register to 100b if you want to make the storage test put pages with correctable errors into service.z18591l7056d3704e3j
MemInitDone	end of storage test.z18591l7056d3704e3j
MicrocodeLoaded	after loading microcode into the VM block at 1400b.z18591l7056d3704e3j