Page Numbers: Yes X: 530 Y: 10.5" First Page: 1 Not-on-first-page
Margins: Top: 1.3" Bottom: 1"
Heading: Not-on-first-page

Dorado Midas ManualEdward R. Fiala24 June 1983

DORADO

MIDAS MANUAL

24 June 1983

by

Edward R. Fiala

Xerox Palo Alto Research Center
3333 Coyote Hill Rd.
Palo Alto, CA. 94304

Filed on: [Indigo]<DoradoDocs>DoradoMidas.press
Sources on: [Indigo]<DoradoSource>DoradoMidasManual.dm

This manual describes a largely machine-independent loader/debugger for microprocessors originally developed for the Maxc2 computer and since used for the Dorado, Dolphin, and M68 microprocessors. This manual is specialized for the Dorado version of Midas.

This manual is the property of Xerox Corporation and is to be used solely for evaluative purposes. No part thereof may be reproduced, stored in a retrieval system, transmited, disseminated, or disclosed to others in any form or by any means without prior written permission of Xerox.


TABLE OF CONTENTS

l.Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

2.Storage Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

3.Starting and Exiting from Midas . . . . . . . . . . . . . . . . . . . . 5

4.Midas Display and the Mouse . . . . . . . . . . . . . . . . . . . . . . 6

5.Name-Value Menus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

6.Command Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

7.Keyboard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11

8.Command Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12

9.Syntax of Command-file Actions . . . . . . . . . . . . . . . . . . . .16

10.Registers and Memories Known to Midas . . . . . . . . . . . . . .19

11.The IM Memory and Virtual Addresses . . . . . . . . . . . . . . .21

12.Registers and Memories that Contain Microinstructions . . . .21

13.Task-Specific Registers . . . . . . . . . . . . . . . . . . . . . . . . . . .24

14.BR Addressing Kludge . . . . . . . . . . . . . . . . . . . . . . . . . . .24

15.STKX Kludge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .24

16.Memory System Registers and Memories . . . . . . . . . . . . . .24

17.Memories and Registers Associated With the DMux . . . . . . .26

18.Interface Registers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .27

19.Config . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .27

20.SetClk . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .27

21.Reset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .28

22.Loading Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .30

23.Dump and Cmpr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .31

24.Brk and Unbrk . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .31

25.Go, SS, Proceed, OS, and Call . . . . . . . . . . . . . . . . . . . . .32

26.When Registers are Read/Written
Restrictions on Continuing . . . . . . . . . . . . . . . . . . . . . . . . .33

27.Hardware Failure Reporting . . . . . . . . . . . . . . . . . . . . . . . .35

28.Hardware Checkout Facilities . . . . . . . . . . . . . . . . . . . . . . .36

29.Parity-Error Scanning . . . . . . . . . . . . . . . . . . . . . . . . . . . .36

30.Testing Directly From Midas . . . . . . . . . . . . . . . . . . . . . . .36

31.LDRtest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .39

32.Scope Loop Actions: Fields, RepGo, RepSS, RepT2 . . . . . .40

33.HWChk . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .40

34.DMux Consistency Checker . . . . . . . . . . . . . . . . . . . . . . . .41

35.Poking: T1, T2, and T3 . . . . . . . . . . . . . . . . . . . . . . . . . .43

36.Passive Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .43

37.MIRdebug Feature . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .45

38.Failure Diagnosis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .45

39.Baseboard Microcomputer Stuff . . . . . . . . . . . . . . . . . . . . .45

40.Command Files Used With "RdCmds" . . . . . . . . . . . . . . . .49

41.DMux Signal Assignments . . . . . . . . . . . . . . . . . . . . . . . . .50

42.Hardware Read/Write Methods . . . . . . . . . . . . . . . . . . . . .70


LIST OF TABLES

Table l:Command Menu Actions . . . . . . . . . . . . . . . . . . . . .10

Table 2:Command File Name-Value Actions . . . . . . . . . . . . .15

Table 3:Command File Command Actions . . . . . . . . . . . . . . .16

Table 4:Memories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .19

Table 5:Registers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .20

Table 6:Test Data Pattern Actions . . . . . . . . . . . . . . . . . . . . .37

Table 7:Test Items in the Name-Value Display . . . . . . . . . . . .38

Table 8:Other Test Actions . . . . . . . . . . . . . . . . . . . . . . . . . .39

Table 9:Command Files . . . . . . . . . . . . . . . . . . . . . . . . . . . .49

Table 10:Control Section DMux Signals . . . . . . . . . . . . . . . . . .50

Table 11:BaseBoard DMux Signals . . . . . . . . . . . . . . . . . . . . .52

Table 12:Processor DMux Signals . . . . . . . . . . . . . . . . . . . . . .53

Table 13:MemC DMux Signals . . . . . . . . . . . . . . . . . . . . . . . .56

Table 14:MemD DMux Signals . . . . . . . . . . . . . . . . . . . . . . . .58

Table 15:MemX DMux Signals . . . . . . . . . . . . . . . . . . . . . . . .60

Table 16:Disk Controller DMux Signals . . . . . . . . . . . . . . . . . .64

Table 17:Ethernet Controller DMux Signals . . . . . . . . . . . . . . .65

Table 18:IFU DMux Signals . . . . . . . . . . . . . . . . . . . . . . . . . .66

Table 19:Display Controller DMux Signals . . . . . . . . . . . . . . . .68

Table 20:Other DMux Stuff . . . . . . . . . . . . . . . . . . . . . . . . . .69

Figure l:Midas Display


l. Introduction

Midas is a loader/debugger that runs on an Alto and controls its target machine remotely. It can load/dump microprograms assembled by Micro, examine and modify storage, and test hardware in an assortment of ways. Versions exist for Maxc2, Dorado, Dolphin, and M68 microprocessors.

Midas is coded about 95% in Bcpl and 5% in assembly language. The Maxc2 version was implemented by E. R. Fiala and H. E. Sturgis. The Dorado, Dolphin, and M68 versions consist of machine-independent modules implemented by E. Fiala (Overlay and LoadRAM packages implemented by L. Deutsch and Alto microcode by E. Taft are also used) and machine-dependent sections implemented by E. Fiala for Dorado; D. Swinehart and P. Baudelaire for M68; and D. Charnley, C. Thacker, B. Rosen, C. Hankins, and E. Fiala for Dolphin.

An internal description of Midas is available to anyone interested in adapting Midas to a new hardware system (see [Indigo]<DoradoDocs>MidasInternal.Press).

2 Storage Requirements

Midas requires about 500 Alto disk pages, using the following files:

Midas.Run~350 pages
Midas.Syms ~40 pages
Midas.Errors ~8 pagesError message strings for Midas swat calls
Midas.Programs ~2 pages(Discussed below)
Midas.UserPrograms ~2 pages(Discussed below)
*.Midas ~2 pages eachCommand files for "RunProg" and "RdCmds" actions
*.mbAssorted micro-binary files loaded by command files
Midas.RunProg ~31 pagesBuilt by Midas/I
Midas.Dtach ~31 pagesBuilt by Midas/I
Midas.FixUps ~2 pagesCreated by Midas/I (used when loading .MB files)
Midas.Compare ~2 pagesCreated by Midas/I, written when "Cmpr" action fails

Dorado Midas can be obtained by loading [Indigo]<Dorado>DoradoMidasRun.Dm and retrieving <Dorado>Midas.Programs with Ftp. You must do Midas/I to initialize Midas on your disk after retrieving these. Subsequently, new versions of Midas can be retrieved by executing the D1NewMidas.cm command file from the Alto Executive. Midas runs only under Alto OS versions 17 or later.

To setup an Alto disk for use in Dorado microcode development or hardware debugging, you can install the Alto OS on a blank disk using the long installation dialog and erase the disk. When this finishes, fetch [Indigo]<Dorado>DoradoUnbugDisk.cm and execute this command file from the Alto Executive; it will retrieve Midas and a number of other files that are needed when using an Alto to control Dorado.

3. Starting and Exiting from Midas

Midas may be started from the Alto Executive in the following ways:

midasstart Midas.

midas/iinitialize and fire up Midas. This is about 8 seconds slower than a normal start. /i must be used after any Midas files move or change because Midas keeps the FP’s (File pointers) in its saved state. Changing any files named in Midas.Programs or Midas.UserPrograms, changing the Alto OS, and changing files named Midas.* all require /i.);

midas debugstarts Midas and immediately reads commands from the "Debug.Midas" command file

Dorado Midas may attach to any of up to 20 machines accessible through its Diablo Printer interface. If only one machine is accessible, it immediately connects to it; if more than one machine is there, it first puts up a menu of accessible serial numbers, and then connects to the one selected by the user. After connection, subsequent actions affect only the connected machine.

Although Midas itself can deal with up to 20 machines, the hardware is presently limited to less. It was observed that ringing on the communication cable introduced extra clocks when too many machines were connected, so Midas couldn’t communicate reliably with target machines. The PARC technicians presently observe a limit of about 6 machines, which seems to work. No hardware fix is likely to be made for this problem.

Midas will seize the hardware only if the connected machine is halted; if running, Midas waits for the machine to halt or for you to execute "Abort" or "Dtach" actions. "Dtach", equivalent to exiting to the Executive and restarting Midas, also appears in the main command menu and in the submenu put up by "Go", so you can start a microprogram running with "Go" on one Dorado, then "Dtach", connect Midas to another machine, and do something else (However, if you Dtach and later reattach to a machine, you will have lost the display configuration and address symbols, which might be inconvenient).

Note that there are two different arrangements for the initial Midas display. For both arrangements the left-hand display column shows the principal Dorado registers, and the middle column shows several other items. When you initially attach to a machine, the right-hand column will show voltage, temperature, and current readings collected by the baseboard microcomputer; after a "RunProg" action, the right-hand column will show items used by Midas hardware testing actions.

To exit from Midas type SHIFT-SWAT (i.e., simultaneously depress the left-hand shift key and the right-most, lowest unmarked key); this will close any open output files prior to exit and disconnect the Alto from the Dorado it was controlling. Note that on "Dtach" or exit, if the Dorado was running, it will not be disturbed, but if halted, Midas first restores the hardware state as though it were about to continue, so it will be possible later to reattach and continue a program that was stopped at a breakpoint.

4. Midas Display and the Mouse

The Midas display is arranged as follows:

Blank area at the top (unused);

20 lines x 3 columns of name-value menus;

Blank line;

Program and elapsed time line;

Blank line;

Two command comment lines;

Blank line;

Three lines of command menu;

Blank line;

Input text line;

Blank area a the bottom (unused).

The program line will show the Midas release date or the name of the last program loaded. The right-most part of this line will show elapsed time during long-running actions such as "Go" or "Test"; it shows the execution time of Midas initialization, the last command file, or the last action at other times.

Midas uses the two comment lines to report results of actions that it executes.

When you move the mouse over a name-value menu or the command menu, the selected item (if any) inverts black and white. Mouse actions execute when you RELEASE all mouse buttons, so you can move the mouse with buttons depressed without causing damage. If the mouse has moved off of the menu that was selected when the first button went down, nothing will happen when the buttons are released.

Some menus have additional actions "underneath" the ones normally displayed which will appear when you depress appropriate button combinations, as discused below. In other words, when you DEPRESS buttons, the menu may change; when you RELEASE ALL BUTTONS the selected action will get executed. On Dorado Midas, only name-value menus have actions underneath the ones normally displayed.

Since you can neither depress a button combination simultaneously nor release the buttons simultaneously, Midas accumulates the union of all buttons that go down. This button-union governs the "underneath" menu displayed, if any, and is the argument passed to the action procedure when all buttons are finally released.

5. Name-Value Menus

A name-value menu may contain a register or memory address in the name area and its contents in the value area. A memory address may be specified as the memory name and word number, or as the name of an address symbol defined in a microprogram you have loaded. The address symbol may be followed by +/- displacement. If a number (default radix 8) is examined, the memory name is defaulted to "VM," so examining "1234" will cause "VM 1234" to be displayed.

Name-value areas are of different sizes. Smaller menus on the left are already filled in when you fire-up Midas; others are empty. Any item can be put in any menu, but larger menus on the right are better for items with long names or values. If an item overflows its menu, the right-most characters of its name get truncated, then the left-most characters of its value.

To display a new item, type its name (which will appear on the input text line), move the mouse over the name field in a name-value menu, and push-and-release the left (top) mouse button. Memory addresses in your microprogram may optionally be followed by a displacement "+n" or "-n"; " n" is the same as "+n". Midas will obtain the value of the item from the hardware and display it.

If the command line is empty, the selected menu will be cleared when the button is released.

The address and data items in a name-value menu are affected by the radix and display mode for the item, initially defaulted from a table indexed by the register or memory number. The address offset and value radices are always identical--Midas does not allow these to be independently specified. On Dorado, octal radix is the default for everything except the microcomputer memories ($ABSOLUTE and $ABS), where hexadecimal is used. The user may change the radix with the actions discussed below.

The display mode for a value may be either numeric, search, or symbolic.

Numeric mode shows the value as a sequence of numbers (in the chosen radix) separated by blanks; this is the default for almost all items.

Search mode shows the value as an address symbol plus offset; this is illegal except for registers or memories that normally contain pointers into some other memory (e.g., on Dorado, search mode for TPC, TLINK, etc. shows the nearest IM address symbol less-than-or-equal to the value plus an offset; for MEMBASE, BR address symbols are shown; for TIOA, DEVICE address symbols are shown.). Search mode is not the default for any memory or register because it is slightly slower than numeric mode due to symbol table access and because more screen area is required to accommodate long address symbols; however, you may find search mode convenient for some of the items mentioned above.

Symbolic mode results in a special procedure being called to print the value for the item. Symbolic mode is illegal except for the MSTAT memory and the UPTIME and TGLITCH registers on Dorado; for these it is the default; special procedures do not exist for any other items.

When Midas thinks that the value in a register may have changed, it reads its value from the hardware and updates the display; the times when Midas does this are discussed later. Names are sometimes preceded by *, indicating that the value has changed, or by ~, indicating that Midas was unable to read the value for some reason (e.g., the machine was running). For an item marked with ~, the old value, which might be wrong, is displayed.

Once some register or memory address has been put into a name-value menu, various mouse button combinations over the name or value may be used to modify the way it is displayed, sequence through words in a memory, pretty-print the value on the comment lines, or show address equivalences. These are summarized in the table below:

ButtonsName-fieldValue-field

LeftExamineChange value

MiddleAlternate printoutPretty-print value on comment lines

RightA+1, A-1 menuAppend value to input line

Left+MiddleRadix menuRadix menu

Middle+RightFill column menuDisplay mode menu

When a button combination selects an alternate menu, the alternate menu will replace the standard menu while the mouse buttons are depressed; if you release the buttons over an alternate menu item, it will be executed; if you are outside the menu when the buttons are released, the standard menu will be restored and nothing will happen.

The "A+1", "A-1" menu appears for memory addresses, but not for registers; these increment or decrement the memory address in the menu, displaying the successor or predecessor. The "FillC" menu allows you to examine successors (A+1, A+2, etc.) in the menus below the selected one; the whole column is filled with successors, if the input text line is blank; otherwise, the input text line is evaluated to a number N, and N lines are filled in with successors. The last address examined is left on the input text line, so you can iterate the examine and fill column actions to achieve scrolling.

Releasing the left button over a value stores the value of the input text (or 0 if no text typed) in the selected register. For memories and registers whose values are displayed as several fields, the input text must also be divided into fields; omitted fields are zeroed. Each field may consist of numbers or memory addresses separated by +/-; expressions are evaluated using the radix for the item.

Note: On Dolphin and Dorado, IM memory words show an absolute address with each value; it is impossible to modify this address from Midas--the correspondence between virtual and absolute addresses can only be established by loading a microprogram. Several other items also have read-only fields that cannot be written, as discussed later.

Provision is made for special input evaluation based upon the register or memory; whenever the input text cannot be evaluated as a sequence of fields, the special input procedure (if any) is called. At the present time, special input procedures are implemented for registers and memories that contain microinstructions (MIR, IM, IMX, IMBD, and LDR on Dorado) and for 16-bit registers. These are discussed later.

Releasing the middle button over a value pretty-prints the value on the command comment lines. The alternate for registers that normally hold IM addresses is the nearest IM address tag less-equal to the value+offset. Registers and memories that contain microinstructions may also be printed symbolically. Other pretty-print information is detailed later.

Releasing the right button over a value item appends the text of the value to the input text line. This is primarily used in command files to move values from one register to another or to display a memory address that is pointed to by the value in some other register.

6. Command Menu

The command menu holds a list of actions that Midas can execute. The basic menu is modified under some conditions. For example, the "Dump" menu item only appears after you have done a "Ld". During execution, some actions show alternate menus.

For almost all actions in the command menu, mouse buttons are equivalent. On Dorado, the "Go" and "SS" actions are an exception; executing one of these with the right button is interpreted as "proceed," left button as "new go." The "DMux" action is also an exception.

Many common actions may alternatively be initated by keyboard command characters, as given in the action table below.

Table 1: Command Menu Actions

InputCharMenu ItemComments

Actions (potentially) available on all implementations of Midas

[File]RunProgReset symbol table and display, then do RdCmds.

[File]RdCmdsExecutes command file (def. ext. ".Midas") on input text line or from submenu.

ShowCmdsShows command file text for selected menu items.

FileWrtCmdsWrite subsequent commands on File.

Files;LLdLoads .MB files (names separated by ",").

FilesLdSymsLoads only addresses from .MB files.

[File];DDump# Dumps compacted .MB file using the .MB file(s) of the previous load to control what’s dumped.

[File];CCmpr# Compares hardware data to that in .MB file.

Addr=Prints value of an address (illegal in com-file)

IMaddr;BBrkInserts break point.

[IMaddr];KUnBrkRemoves breakpoint (default address = last break).

[IMaddr];GGo* Start at address (continue if nothing typed).

[IMaddr];PProceed* Start at address without IOReset or control section reset (continue from break if nothing typed).

[IMaddr]:SSSingle-step at address (continue-step if nothing typed).

IMaddr)--Call subroutine with args (e.g., "FOO(A1,A2)").

ResetReset the machine; assorted options from a submenu.

TestTest register, memory, or other test with data pattern and item selected from submenus.

TestAllTest everything.

IMaddr;RRepGo* Go at address, repeatedly restart after halts.

IMaddr;SRepSS* Repeatedly SS at address.

PEscanScan local memories for parity errors (IMX, IFUM, RM, STK, CACHEA, and CACHED on Dorado).

FieldsFor scoping.

LDRaddrLDRtest* Manually-constructed test sequences.

VirtChanges IM address interpretation to be virtual.

AbsChanges IM address interpretation to be absolute.

Actions peculiar to Dorado Midas

SetClkSet the clock speed from a submenu.

T1Clocks MIR through t1, reads the DMux, then clocks through t2 and restores MIR (so display shows DMux values read after t1).

T2Clocks MIR through t2, reads the DMux, and restores MIR (so display shows DMux values read after t2).

T3Clocks MIR through t3, reads the DMux, then clocks through t4 and restores MIR (so display shows DMux values read after t3).

RepT2* Repeatedly does t2 (for scope loops).

DtachDisconnects Midas and repeats the connection procedure.

ConfigModify board configuration, cache, map, storage, and IM parameters from submenus and adapt Midas to these.

DMuxModify display of DMux items as discussed later.

[IMaddr]OS* "Opcode step" = SS program until a halt condition occurs or an IFUJump has been executed.

[IMaddr]SimGo* Like "Go" invoking the DMux checker after each step.

SimTest* Random instruction test using MIR and the DMux checker.

HWChkDisplays submenu of tests and scope loops for hardware checkout.

ActiveActive, PrePassive, and Passive modes discussed later.

UpdateRead registers and display new values (used while passive)

* = requires preceding "TimeOut" action in command file
# = requires confirmation with <cr>, "Y", or "." (or by preceding "Confirm" command in com-file)
[...] = optional input text

Some actions in the preceding table are replaced with complementary actions after execution; these are ShowCmds by StopShow, WrtCmds by StopWrt, Virt by Abs. The Active, PrePassive, and Passive actions are in a "ring"; the current hardware mode is shown in the menu; bugging it will change to the next mode. The DMux action will be displayed as "DMux", "OldDMux", "DWrong", or "DChk" according to which DMux table is currently displayed. All of these actions are discussed later.

General philosophy on mixing keyboard and mouse button control is that, when possible, a command involving some typing is carried out completely at the keyboard, whereas commands involving mouse buttons are carried out completely with the mouse.

For example, to start a microprogram at some address, you normally type an address; then you could bug "Go" in the command menu, but probably "address;G" is more convenient because you won’t have to lift your hand from the keyboard; ";G" are the command characters equivalent to bugging "Go".

Many commands are executed in overlays. When these get executed, the register display will turn off (The code for overlays resides where the display bit buffers would otherwise be.). During loading or execution of command files, the display is turned off to make the machine run faster.

Long-running commands normally display an "Abort" menu item. When this is bugged or when control-C is typed, the action terminates.

7. Keyboard

"=", "+", "-", "#", and "!" are legal symbol constituents in microprograms but will cause trouble for Midas if they appear in address symbols. "=" is an action character that will prettyprint the memory name and offset and the nearest address symbol less-than-or-equal to the value of the string on the input text line. "+" and "-" have their usual sum and difference meanings in evaluating input expressions. "#" (octal), "!" (decimal), and "%" (hexadecimal) may be inserted anywhere in a number to overrule the default radix; e.g., "#123" or "123#" will force the evaluation of the number "123" to be in octal. The default input/output radix for almost everything on Dorado Midas is 8 (octal).

Exceptions are UPTIME and TGLITCH, which show hr:min:sec in decimal and the $ABS and $ABSOLUTE memories, which use hexadecimal for both the address and value.

Lower case typein is converted to upper case by Midas, so avoid lower case characters in microprogram address symbols. You should either write microprograms with the shift-lock key depressed or assemble them with the convert-to-upper-case assembly switch.

Typing ahead is legal until the character you type would cause execution of an action. After that, Midas will flush input and blink at you until the current action finishes.

At the end of an action, input text typed for that action is displayed on the input text line. This text remains valid and can be used as the arg for another mouse action. However, if you type any character (except control-A or backspace), the old input will be flushed before inserting the new character.

Keyboard editing characters are as follows:

control-Adelete last character
backspacedelete last character
control-Qclear text line
delclear text line

Other special keyboard characters are as follows:

control-Cabort the current action--equivalent to bugging the "Abort" command (only defined for actions that display "Abort")

control-Zabort all command files in progress

escaperepeat previous action (special for "Test" and "TestAll")

returnspecial following "Test" or "TestAll"

control-Dturns on the display (used during command files)

control-Oturns off the display (used during command files)

shift-swatexit cleanly from Midas

The interrupt characters above are ineffective during loading, dumping, or comparing, which typically take between 2 and 20 seconds. Indefinite duration commands, such as "Go", "Test", etc. always monitor the keyboard, so control-C can be used to terminate them.

Control-Z, control-D, and control-O are intended for use during command files. However, these characters do not take effect until the command file executes a command such as "Go" which monitors the keyboard. There is no way to abort a command file and give control back to Midas safely except during a "Go" or other long-running command. This is not expected to be a problem because commands are executed quickly.

After interrupting a "Go" with control-C or control-Z, proceeding with ";P" or ";G" will succeed except when you have smashed the machine state by writing a register or in some other way or have interrupted an instruction from which continuation is impossible.

Although command menu items "SS", "Go", "Brk", "UnBrk", "RepSS", and "RepGo" are provided, the keyboard characters equivalent to these are usually more convenient.

8. Command Files

Command files (default extension ".Midas") are normally executed either by typing "Midas filename" to the Executive or by bugging a file name in the subsidiary menus put up by "RunProg" or "RdCmds". Alternatively, you may type a file name first, then bug one of these actions (If you type a file name after the subsidiary menu is put up and then bug "Abort", the command file will also be executed; it is not clear whether this is a bug or a feature.).

File names in these sub-menus are contained in the files Midas.Programs and Midas.UserPrograms, each of which has a list of file names separated by blanks, commas, or carriage-returns. Midas.Programs is part of the standard Midas release; Midas.UserPrograms is an optional file that a user of Midas can prepare with his own stuff. The names must be UPPER-CASE. These lists serve two purposes: building file FP’s to speed OpenFile, and preparing the menu items for "RunProg" and "RdCmds".

If the file name contains no extension, then hint FP’s will be built for both name.MB and name.MIDAS and name will be put in the "RunProg" menu. (However, the hint FP’s are not built unless the file exists, and the file name will not be put in the "RunProg" menu unless name.MIDAS exists).

If the name ends in "*", a quick OpenFile table entry is made for name.midas and the name will appear in the "RdCmds" menu.

If the file name contains an extension, then it will be put in the quick OpenFile table, but won’t appear in the "RunProg" or "RdCmds" menus.

Since Midas builds a table of file FP’s during initialization, when you edit a command file or modify a .MB file, you should reinitialize Midas by typing "Midas/I". When you add new command files or .MB files you should update the "Midas.UserPrograms" file appropriately and do "Midas/I".

"RdCmds" executes the actions stored in the command file; it is frequently used to modify the display in various ways by executing command files that show collections of items that are of interest.

"RunProg" first clears the symbol table and restores the display to its initial arrangement; then it executes the actions in the selected command file; "RunProg" is used to completely change contexts--to run a new microprogram, for example.

Generally, there is one "RunProg" command file for each hardware diagnostic, with the same name as the diagnostic, e.g.:

dgbasic.mbthe diagnostic;
dgbasic.midasthe command file.

A command file following this convention loads the diagnostic into the microprocessor and displays various registers of interest when the microprogram is in use.

The command-file facility is actually a (awkward and limited) programming language. The collection of actions discussed below is being developed so that command files can monitor diagnostic microprograms, collect and report error information on an output file, or direct the sequence of diagnostic microprograms according to hardware failures that are observed.

For system microcode, command-files can be used to control auto-restart and failure diagnosis.

Command files can be nested with "RunProg" and "RdCmds" subject to the following RESTRICTIONS:

(1) [Maxc2 only] "AltIO" terminates command files (i.e., upon return to Midas from AltIO the command file will not be continued).

(2) Nesting is limited to 8 levels (a parameter that could be increased if more levels are needed).

(3) Command file names appearing in the "RdCmds" or "RunProg" menus must not duplicate any other action names used by Midas. If this happens inadvertently, command file interpretation will be substituted for the intended action whenever that action is executed from a command file. Fortunately, interactive execution of the duplicated action is unaffected. Midas does not detect this.

(4) Midas is tight on storage when running the simulator (SimGo and SimTest actions), and available space might become exhausted. Three separate storage resources are husbanded by Midas: stack, sysZone, and other. Some sysZone is consumed by each open file, and the simulator puts one overlay there. If command, output, and WrtCmds files are simultaneously open when SimTest or SimGo is executed from a command file, I think sysZone will overflow, but there should be enough sysZone storage for two open files plus the overlay.

Note that even when command files are nested to several levels, Midas only keeps open the current command file, so nesting command files does not affect the storage requirement.

The simulator also steals space from the stack for one overlay, and it is conceivable that running SimGo from a command file and then aborting from the keyboard will exhaust the stack. However, if Midas is properly checked out, then this should not happen.

Finally, unused storage and the name-value menu bit buffers are used for the rest of the simulator. Since this storage is consumed by file handles and name strings which you add to Midas.Programs and Midas.UserPrograms, this storage might become too small for the simulator. If this happens, you will fall into Swat with an "Out of storage" message when you try to run the simulator.

(5) There are other size limits you must observe. First, the number of RdCmds and RunProg actions you may add to the ones already in Midas.Programs is limited to about 25 (on 24 June 1983). This limit is imposed by the table storage reserved for these actions when Midas is built. If you exceed this limit, the submenu for the "Test" action cannot be shown, and Midas will fall into Swat during Midas/i initialization with a message indicating the number of excess actions. The limit applies not to the number of names in Midas.Programs and Midas.UserPrograms, but rather to the number of these names which exist on your disk. So to recover from this overflow, you can either prune the number of names in Midas.Programs or Midas.UserPrograms, or you can delete some of the *.Midas files from your disk.

Secondly, the list of names in the RdCmds or in the RunProg menu must not overflow command menu space. If one of these lists overflows, Midas will fall into Swat during its Midas/i initialization with a message telling you by how many characters you have exceeded the limit. Here again, you recover from the overflow by either pruning names or deleting *.Midas files. Or you can continue from the Swat call; if you continue, Midas will simply truncate the names which won’t fit when it displays the menu.

(6) Some actions occur in command overlays where a sequence of menu items must be bugged before the action is specified. For example, on "Test", you must specify the data pattern (e.g., "Random"), then a "TimeOut", and finally the register or memory to be tested (e.g., "RM"). It is illegal to start a nested command file before the subsidiary actions are specified; if you try to do this, Midas will give an error message.

(7) Some actions require a preceding "TimeOut" action. The command file must have two actions after the "TimeOut" before terminating.

A number of actions, some of which cannot be given interactively, are useful in command files. These, not given in the table earlier, are shown below. The first table is for actions that operate on name-value menus (A0 ... C19); the second table for command menu (X) actions.

Table 2: Command File Name-Value Actions

Text ArgActionComments

AddressAddrButton actions as discussed earlier.

ValueValButton actions as discussed earlier.

A+1Increment memory address, as discussed earlier.

A-1Decrement memory address, as discussed earlier.

NColsFillCFill name-value menus beneath the one selected with consecutive addresses starting at the address contained in the selected menu.

OctDisplay address offset and value in octal.

DecDisplay address offset and value in decimal.

HexDisplay address offset and value in hexadecimal.

NumDisplay value numerically.

SymDisplay value symbolically.

SearchDisplay value as an address symbol plus offset in the appropriate memory.

ValueSkipESkip the next command if the input text evaluates equal to the contents of the register or memory word displayed. The input text is evaluated exactly as though it were to be stored into the register displayed in that name-value menu, so if the value displayed has several fields, the input text must also have several fields. The command file must have at least one more action after the SkipE.

ValueSkipGSkip if input text greater than the contents of the item in the name-value menu (unsigned compare).

ValueSkipLSkip if input text less than name-value item.

ValueSkipNESkip if input text unequal to name-value item.

ValueSkipLESkip if input text less than or equal name-value item.

ValueSkipGESkip if input text greater than or equal to name-value item.

Table 3: Command File Command Actions

Text ArgActionComments

Octal no.SkipSkip N following actions, where N is the value of the input text. An error occurs if the command file does not specify at least N more actions after the Skip.

.TagSkipSkip following actions until one is encountered with the label ".Tag". An error occurs if ".Tag" is not found.

Octal no.BackSkip

.TagBackSkipReset to byte 1 of the command file, then skip.

Octal no.ReturnReturn out of current command file, then skip (".Tag" form is illegal for Return.).

DisplayOnTurn on the display, so that effects of subsequent commands can be observed. The display is initially off for a command file. This can also be done with control-D.

DisplayOffTurn off the display. This can also be done with control-O.

Octal no.TimeOutInput text is evaluated to a 32-bit octal number of msec at which to abort the immediately following command, if it has not finished by then. This is intended for use before "Go" and other commands which might hang indefinitely. If the timeout occurs, Midas will skip the command after the "Go". TimeOut also turns on the display, necessary because the machinery which checks for timeout is only active with the display on. Note that TimeOut is required before the actions *’ed in the table on page 4 and is illegal before other commands; Midas will complain if you do not use TimeOut appropriately. The command file should include at least two more actions after the TimeOut. Command files written by WrtCmds will include necessary TimeOuts with a default of 30000 (~12 seconds); you will generally have to replace this default value with something more appropriate.

ConfirmSupplies confirmation for the command which follows (which should be one of the commands requiring confirmation). If you omit a confirm in a command file, the user is queried for confirmation.

File nameOpenOutputOpens an output file (default extension ".Report") on which text can be written.

File nameAppendOutputAppend to an output file (default extension ".Report")

CloseOutputCloses the output file.

[text]WriteMessageWrites the contents of the input text buffer on the output file. Note that if any text follows the WriteMessage, that text up to but not including the <cr> is what gets written. However, if <cr> immediately follows WriteMessage, then the contents of the input text buffer left by the previous command get written. "~" is translated into <cr> and "\" into a blank.

WriteDTAppends the current date and time to the output file.

textShowErrorDisplays the text arg on the command line, turns on the display if it was off, and queries with "Abort" and "Continue" menu items. Aborting will terminate all nested command files back to the top level.

--DumpDisplayWrites the current display image on the output file.

textPrettyPrintEvaluates text to a memory address, register name, or memory name; writes this name on the output file; then pretty-prints the value on the output file exactly as it would be pretty-printed on the comment lines if the item were displayed in one of the name-value menus and middle-buttoned.

File nameWriteStateUsed by Midas initialization to create the Midas.Dtach and Midas.RunProg files--users shouldn’t use this action.

9. Syntax of Command-file Actions

The syntax of a command-file action is as follows:

[["."<tag>]$" "]<buttons>$" "<menu>$" "<action>[$" "<text>][";"<comment>]<cr>

where the "[]" denote that the ".tag", input text, and ";comment" are optional. $" " denotes a sequence of one or more blanks or tabs (any characters with Ascii codes less than 408 except carriage return are equivalent to blanks). The sequence of characters excluding the comment must not exceed 99 characters.

If the first character on the line is a ".", then the characters after that are a label or tag which may be used as the argument for the "Skip" or "BackSkip" actions given in the table earlier.

<buttons> may be any combination of the letters "L" (left-button), "M" (middle-button), and "R" (right-button); these are the buttons released to execute the action. These may appear in any order.

<menu> is the menu name in which the action is executed ("X" for the command menu, "A0"..."A19", "B0"..."B19", and "C0"..."C19" for name-value menus).

<action> is the text name for one of the actions (upper/lower case must match the definition).

<text> is the text typed on the command line, which may be anything except a ";".

Note that if a single blank terminates <action> and if no input text argument is given, then input text left-over from the preceding action will be used. This allows text from a right-button action over a value to be used in a following action (e.g., in WriteMessage or to store the value into another reigster). However, one or more extra blanks will reset the input text, so the action is executed with null input text.

";" begins a comment, which may be omitted.

<cr> (carriage-return) terminates the action.

I think Midas will report all command file syntax errors intelligibly. Error handling works approximately as follows: Whenever Midas is watching the keyboard (which only happens during long-running actions such as "Go" or "Test"), control-Z will abort the current and all nested command files; the ShowError action in a command file also aborts all command files. If Midas detects an error while executing an action and queries, then "Continue" will abort the action in progress and continue with the next command file action. "Abort" will terminate the current command file, but not higher command files. However, a syntax error in the command file itself always aborts the current command file.

To find out what text should be put in command files, you can bug "ShowCmds" in the command menu. This will cause the command file text for each command to be displayed on the command comment line as the mouse selects it (You don’t have to execute the command to see the equivalent text.). This text is complete except that the mouse button which executes the command isn’t shown unless you depress the mouse button. To terminate "ShowCmds", bug "StopShow" (which appears only when "ShowCmds" is in progress.).

You can prepare a command file (default extension ".Midas") by typing a file name and bugging "WrtCmds". This causes text for subsequent commands to be put on the file. When you are done with this, bug "StopWrt" to close the file. ("StopWrt" is in the command menu only when a command file is being written.). Exiting from Midas also closes the output file.

You will probably want to edit out your goofs with Bravo after the command file is written.

In addition, you will have to insert "Confirm" before actions which require confirmation and modify the "TimeOut" stuff which Midas uses to surround actions which might hang indefinitely (See the table given earlier for the actions that require this.).

Here is a sample command file:

L X Ld dg1;Equivalent to typing "dg1" and bugging "Ld" in the command menu
L A0 Addr TASK;Examine the "TASK" register in name-value menu A0
L A0 Val 0;Change the value in TASK to 0
L A1 Addr RTEMP;Examine the address "RTEMP" in menu A1
L A1 SkipE FOO+3;Skip the next command if RTEMP contains the value FOO+3
L X ShowError RTEMP not loaded correctly
L A2 TLINK 0;Examine the Link register for task 0 in menu A2
L X TimeOut 2000;Abort the following command if it hasn’t finished in 1.024 sec.
L X Go START;Begin microprogram execution at address "START"
L X Skip 1;Skip the next command if "Go" halts before timeout
L X ShowError START;G failed;Show an error message