The DLion version of Burdock has two windows. One is for debugging/controlling the CP and one for working on the IOP. Unfortunately, the old Logic Analyzer lashup from Alto Burdock to the Tektronix logic analyzer plugin for a scope has never been revived.

I haven't worked with DLion burdock for a long time, so you should be extra suspicious about parts of this memo the talk about DLions, especially parts that talk about the IOP.

The Dicentra version of Burdock also has two windows. Again, the first one is for debugging/controlling the CP. The second one is the History Buffer. It's a logic analyzer for tracing execution of CP microcode. (Dicentras don't have an IOP, so there isn't any need for an IOP Window.)

There is probably a Burdock subdirectory on your favorite AMesa/APilot archive directory. Mesa 12.0 is archived on [Ramrod:OSBU North:Xerox]<AMesa>12.0>. The DLion version is BurdockDLion.bcd. The Dicentra version is BurdockDicentra.bcd. They are on the Burdock>Friends subdirectory. (You don't need anything else to get Burdock off the ground. The CP Kernel microcode and things like that are TableCompiled and Bound into the config.)

Burdock thinks in HEX! Except for a few places like messages that printout bits/second, ALL numbers in Burdock default to HEX. When typing in numbers, you have to use a leading 0 if it would start with a letter. If you want to specify a decimal number, append a 'd. If you want to specify an octal number, append a 'b. For uniformity, you can append a 'x, but that's the default.

Burdock uses the normal Tools Window routines. At startup time, they scan your user.cm to determine where to place the windows. I suggest you add the following to your user.cm.

Burdock keeps track of the State of the CP. Many operations require that CP to be in a reasonable state. CP/IOP Dead means that the CP has crashed, the IOP has crashed, or the CP hasn't been Booted yet. Halted means that the CP has been initialized (Booted) and is now stopped. It could have run some already. If so it has been manually stopped. Running means that the CP is running user code. (It's running the CP Kernel when it's in the Halted or CPBreak states.) CPBreak means that the CP has hit a breakpoint. IOPStopped means that the IOP is stopped or at a breakpoint. The CP must be Stopped before it can be manipulated. The CP could be stopped automatically when the IOP stops, but refreshing the CP Panel usually takes several seconds, and that's a waste of time if you are chasing an IOP bug.

Burdock polls the state of the CP. When it changes a message is printed in the log window. If it changes to Halted or CPBreak, the CP Panel is refreshed.

The CP symbol manipulation routines contain a large collection of built-in symbols.

.CR n is location n of Real Control Store. .CV n is location n of Virtual Control Store. (The nth instruction in the microcode listing.) Pass 2 of Mass determines the mapping between CR and CV.

.MR n is location n of Main Real memory. .MV n is location n of Main Virtual memory.

.MAP n is the nth word of the map.

.RH n, .R n, .U n, .TPC n, .LINK n, Q, and L0 through L7 are the obvious things. So are .IB, .PC16, .STACKP, .IBPTR, .MINT, .EKERR.

A number is normally interpreted as a location in main memory.

If an expression for an R register in the left side of a tile in the CP Panel is prefixed with a $, the RH/R pair will be displayed as a 24 bit number.

The CP Kernel currently (11.1) uses locations 0F6F, 0F77 and 0F7F through 0FFF. (Except for a typing error, the appropriate reserves are in InitDLion.mc.) I think the Dicentra version is actually a few words smaller, but I haven't gotten interested enough to check. For Diagnostics and such where space isn't critical, I reserve 0F5F through 0FFF.

The DLion CP can have up to 16 breakpoints. The Dicentra can have up to 256.

While the CP is stopped, the breakpoints are temporarily removed so they will be invisible if you examine Control Store. When the CP is started, the instruction at each breakpoint is replaced with a jump to the CP Kernel.

Breaks at c2 and c3 are risky. If a memory operation was started, the results will be lost. You can't set a break at a c* instruction because Burdock needs the cycle info to build the right breakpoint instruction. If you hit a breakpoint on the wrong cycle, Burdock will probably declare the CP to be dead. (This whole mess is asking to be cleaned up. It might not be too hard.)

Boot! goes through various steps to initialize the CP and the CP Panel so you can start debugging. It forgets all the current CP symbols and break points. It then does a low level boot on the CP. On the DLion, this will automatically boot the IOP unless it is already talking to Burdock. Then the CP Kernel is loaded into Control Store, and the CP Kernel task is started up running the Kernel. Dicentras don't have tasking, but the innards of Burdock save and restore the CP's PC to fake the kernel and emulator tasks. After the CP Kernel is loaded, Burdock looks around for extra banks of Control Store, and if it finds any, it loads a copy of the Kernel into each extra bank. Finally, Burdock reinitializes the CP Panel.

All of the various Load commands use the current selection to specify a filename. For loading microcode, the default extension is .fb. For loading symbols, the extension is .st.

Load! is used to load microcode into Control Store. First it resets the CP symbols, CP breakpoints, and CP Panel. Then it loads the microcode. Then the CP Panel is reset.

LoadMore! loads microcode and symbols without resetting anything. This is useful if you have more than one bank of Control Store. (The symbol tables probably get confused if you load two hunks of microcode into the same bank, even if they don't smash each other. This could be fixed.)

Start! evaluates the current expression as a CP symbol. The answer contains a task number, a cycle number, and a control store address. If the cycle number is c1, then the TPC for the specified task is set to the control store address. Then the CP is Continue!ed.

Continue! just lets the CP start running again. On a DLion, the IOP will be continued too if that makes sense.

Stop! stops the CP. The CP Panel will be automatically refreshed.

Run! runs a Burdock command file. The filename is in the File: slot. If that is empty, the current selection is used. The default extension is .burdock.

LoadRaw! is a hack for loading a diagnostic or scope loop when the CP is too sick to run Burdock's Kernel. It resets everything, loads the microcode and symbols, and then starts running the CP's Kernel task. Thus your microcode should specify a StartAddress for task 7.

LoadNoSyms! is like Load! except that loading the symbols is skipped. This saves time if you don't need them.

LoadSymbols! is used to load symbols when you change your mind after using LoadNoSyms.

LoadGerm! is used to load a germ into memory. It assumes that the initial microcode has already initialized the map. The default extension is .germ.

LoadReal! is leftover from the old Alto days before LoadGerm and LoadBoot existed. The default extension is .cpr. It loads a file into CP main memory. This was also used to dump fancy pictures into DLion display memory.

Using LoadReal to load a germ is a krock. Unfortunately, nobody has taken the time to cleanup the mess in this corner of the DLion world. Most of the space in the germRM files is taken up by blank map entrys, and thus most of the time spent loading the germ is wasted. On top of that, you need a separate file for each size machine.

LoadBoot! loads a boot file. Like LoadGerm, it assumes that the initial microcode has already set up the map. The default file extension is .boot.

Refresh! refreshes the CP Panel. This involves reading all of the specified locations and updating the display. A * will appear next to each slot that changes. The display is automatically refreshed each time the CP is stopped or hits a breakpoint. Manual refresh can be used to see if the hardware has changed it's mind, or to catch the sneaky case when you have two slots pointing at the same register and you changed one of them since the display was last refreshed.

What! evaluates the current selection as a CP symbol and prints the answer out in hex, decimal, and octal. If the selection is just a number, this can be used to convert from one base to another.

ListBreaks! lists the current CP breakpoints.

ClearAllBreaks! forgets all of the current CP breakpoints.

UnBreak! evaluates the current selection as a CP symbol, and if there is a breakpoint at that location, it is cleared.

Break! evaluates the current selection as a CP symbol, and sets a CP breakpoint there.

Compare! uses the current selection to read a microcode file. Each word is compared with the contents of Control Store. If they are different, an error message is printed. (On a Dicentra, this can be used to check Control Store PROMs. See the Dicentra documentation.)

CrossJump! is a hack to help microcoders locate instructions that might be easy to bum out.

Burdock keeps track of the State of the IOP. Many operations require that IOP to be in a reasonable state. Dead means that the IOP has crashed, or it hasn't been Booted yet. Booted means that the IOP has been initialized (Booted) but the PC hasn't been initialized yet. Halted means that the IOP has been running and is now stopped. Running means that the IOP is running user code. (It's running the IOP Kernel when it's in the Booted, Halted or Break states.) Break means that the IOP has hit a breakpoint. CP Halt/Break means that the IOP is in limbo because it noticed that the CP encountered a breakpoint or it was halted (by Burdock) to halt the CP.

Burdock polls the state of the IOP. When it changes a message is printed in the log window. If it changes to Halted or Break, the IOP Panel is refreshed.

IOP Breakpoints use an RST 2 instruction. You can assemble one into your code to "Call Burdock".

There is no limit to the number of IOP breakpoints that can be active at the same time.

The IOP symbol manipulation routines contain several built-in symbols.

B, C, D, E, H, L, M, A, PCH, PCL, SPH, SPL, Flags, and RIM are symbols for the obvious registers. BC, DE, HL, SP, PSW, and PC are symbols for the obvious register pairs.

A raw number is an address in IOP memory.

If an expression for an address in IOP memory is prefixed with a $, that location will be displayed in word mode. If an expression for an address in IOP memory is prefixed with %, that location will be displayed as an instruction.

Stack! displays clumpSize words from the stack.

Instructions! evaluates the current selection as an IOP symbol, and then starting there, displays clumpSize instructions.

Boot! goes through various steps to initialize the IOP and the IOP Panel so you can start debugging. It forgets all the current IOP symbols and break points. It then does a low level boot on the IOP and establishes contact with the IOP Kernel. Finally, Burdock reinitializes the IOP Panel and preloads it with a default collection of tiles. This operation leaves the CP in the Dead state.

All of the various Load commands use the current selection to specify a filename. For loading IOP code, the default extension is .bin.

Load! is used to load microcode into IOP RAM. First it resets the IOP symbols, IOP breakpoints. Then it loads the IOP code. Then the IOP Panel is reset.

Start! evaluates the current expression as an IOP symbol, sets the PC to that location, and Continue!s the IOP. The CP will be automatically continued first if that makes sense.

Step! lets the IOP execute one instruction and then refreshes the IOP Panel. This is implemented by automatically inserting a breakpoint at the next location, so that interrupt routines may get to run. If the instruction to be executed is a conditional jump, two breakpoints are inserted.

Continue! just lets the IOP start running again. Again, the CP will be automatically continued first if that makes sense.

Stop! stops the IOP. The IOP Panel will be automatically refreshed.

Run! runs a Burdock command file. The filename is in the File: slot. If that is empty, the current selection is used. The default extension is .burdock.

LoadNoSyms! is like Load! except that the symbols are not loaded into the symbol table. This saves time if you don't need them.

LoadSymbols! is used to load symbols when you change your mind after using LoadNoSyms.

LoadModSymbols! loads the symbols for the module specified by the current selection.

Refresh! refreshes the IOP Panel. This involves reading all of the specified locations and updating the display. A * will appear next to each slot that changes. The display is automatically refreshed each time the IOP is stopped or hits a breakpoint. Manual refresh can be used to see if the hardware has changed its mind, or to catch the sneaky case when you have two slots pointing at the same register and you changed one of them since the display was last refreshed.

What! evaluates the current selection as an IOP symbol and prints the answer out in hex, decimal, and octal. If the selection is just a number, this can be used to convert from one base to another.

ListBreaks! lists the current IOP breakpoints.

ClearAllBreaks! forgets all of the current IOP breakpoints.

UnBreak! evaluates the current selection as a IOP symbol, and if there is a breakpoint at that location, it is cleared.

Break! evaluates the current selection as a IOP symbol, and sets a IOP breakpoint there.

Arm! evaluates the string in Target as a CP symbol, and sets up the HB matcher to trigger on that address.

Display! displays the data in the history buffer using the current values of Before and After.

ManualTrigger! kicks the hardware so that it acts like the address matcher has seen the target. Again, Burdock will automatically display things. This is handy if you don't know what your microcode is doing. You need to Arm the HB before ManualTrigger will do anything. If you can't think of any symbol to type into Target so you can Arm things, use .CR 0.

LoadArmAndGo! does a LoadRaw of the file specified in File, Arms the history buffer at the location specified at Target, and then Continues the CP. This is a convenient way to start a low level CP diagnostic.

BB! (Boot Button) flaps INIT/ on the Multibus backplane.

There are several commands on the History Buffer Window that are mostly left over from hardware debugging.

UseROM is a boolean used to switch the debugger board into working with the Control Store ROM on the CP board. This can be used to Compare microcode on the disk with the contents of PROMs. UseROM doesn't do anything until the next time you interact with the debugger board, so poke BB! or something to make sure it gets noticed.

Text enclosed with matching |s is ignored.

Most of the commands available in the CP or IOP windows are also available as functions within Burdock command files. They use Mesa procedure call syntax. If the names would clash, the names for the IOP commands are suffixed with "IOP". For example, "Boot[];" will boot the CP, "BootIOP[];" will boot the IOP, and "Break[Foo];" will set a CP breakpoint at location Foo.

Arguments to commands should be quoted if they might confuse the scanner.

Commands that start execution take an additional parameter: the number of milliseconds to wait for the CP or IOP to stop running. (The normal reason for stopping is a breakpoint.) An omitted parameter means don't wait at all. (Of course, you can't do much while it's still running.) A value of 0 means wait forever. Remember, numbers used to specify wait times are interpreted as hex.

Here is a checklist of CP commands:

Here is a checklist of IOP commands:

Here is a checklist of HB commands:

Command files can also initialize tiles in the Panel areas. "CP[3,0]! Foo" stores "Foo" into the left side of the tile in the third row of the first column in the CP Panel. "CP[3,0]! Foo ← 13" sets it up and then stores 13 (hex) into Foo. "IOP[..]" is used to setup IOP tiles.

Tiles can be named (for use with conditionals and WriteLoc) by preceding the CP with tileName=. It's a good idea to use the name of the register in the tile as the name of the tile.

SetMP[tileName] puts the right side of a tile into the MP. (This number won't be in hex.)

Tag: defines tag at the current position in the command file.

GOTO[tag] resumes execution of the command file at the position corresponding to tag. Forward and backward jumps are both legal.

IF operand relation operand {...};. Each operand is either a tileName or a hex constant. The relations include >, >=, <, <=, =, and #. Conditionals can be nested.

Close[]; closes the current log file if there is one open.

OpenToAppend[filename]; opens a log file in append mode.

OpenToWrite[filename]; opens a log file in write mode.

Write[quoted string]; writes its argument into the log file. (Write[] is legal, and doesn't do anything.)

WriteLine[quoted string]; writes its argument into the log file, and then writes a CR. WriteLine[] just writes a CR.

WriteLoc[tileName(, width)]; writes the right side of the designated tile into the log file in hex. If width is specified, leading blanks will be added to make the string written at least that wide.

WriteTime[]; writes the current time into the log file.

Look at the code. It's CommandFiler.mesa.

TestUmbilical is a program for checking out DLion-DLion Burdock Boxes. I assume it works with Song boards too, but I've never tried it. TestUmbilical is pretty simple minded, but I have forgotten all the details. It probably includes several scope loops. Look at the source code if you have any questions.

TestDebuggerBoard and TestHistoryBuffer are used to debug the Dicentra debugger board. See the Dicentra Manual for more information.

CSBankTester is used to test extra banks of CP Control Store. It is packaged with Burdock as an inactive tool because the DLion uses the CP Kernel to set the bank register.

CPKernelTester is leftover from when I was trying to understand how the CP Kernel worked. It might be handy if you are chasing obscure problems. It too is packaged with Burdock as an inactive tool.

When bringing up the first member of a new family of machines, there is a time when it mostly runs, but the Emulator or Germ doesn't work well enough to be TeleDebugged. At this stage, you end up doing a lot of pointer chasing to follow stacks and such. Machines are good at that sort of thing. I'm lazy.

CPMesa is a tool that is included with Burdock. Normally it's inactive. It has two commands. DispStack displays the current stack in HEX. Each frame is a separate line. ListProc displays the current list of processes.

CPSymbolsDebug is another normally inactive tool that comes packaged with Burdock. It's leftover from when I was debugging the symbol table machinery. It will dump the symbol tables into a log file. If you are trying to understand all the uses for all of the registers, this might be handy. (Use the What command if you are just interested in a few registers.)