Emulator Commands

Starting the emulator

• -e  Automatic Exit: Usually used with -r, the emulator exits after the program terminates, instead of remaining in interactive mode for further commands.
• -o filename  Redirect output (from running program) to a file. Only really useful when used with -r.
• -q  Quiet: informative comments about executable files being loaded and the addresses used are not printed.
• -r  (Run) Automatically start running the loaded program(s) immediately.
• -rf entry  (Run From) The same as -r, but when a program has multiple entry points, allows the start address to be selected. Entry points are defined with the .entry assembler directive.
• -toptions  Various Tracing options are turned on. The options are indicated by a string of lower-case letters immediately following the -t; those letters are the options that would otherwise be typed as options to the trace interactive command. For example, -tvmex has the same effect as the two commands trace vm and trace ex, and causes all major Virtual Memory operations, and the details of every instruction EXecuted, to be displayed on the terminal. Allowed options are any combination of at, ex, ld, and pf.
• -v  Turn virtual memory off. Virtual memory is normally on and properly initialised before the emulator does anything else. With virtual memory off, all addressing is physical, and the address space is a contiguously allocated region from address 0 to some maximum.
• filename  The file filename.exe is loaded automatically. Multiple filenames may appear, they are loaded in order.

Keyboard Input to Running Programs

• Input depends on interrupts. You need to be able to program your own interrupt system. If your program does any interrupt processing of its own, the getchar() function will stop working, and you will have to make your own equivalent function.
• The way non-ascii characters are entered varies from system to system. Under the emulator, when typing input to a running program, you may press the ESC (escape) key, immeidately followed by two hexadecimal digits 0-9, A-F, a-f. The single character whose numeric code you typed is received as input by your program. Example: typing ESC 5 7 is the same as typing W. typing ESC F 3 gives the character whose integer encoding is 243, which is normally untypable. typing ESC 0 A is exactly the same as pressing ENTER.

Interactive Commands

• exit or quit
  Exit from the emulator. Nothing is saved.
• load filename base
  The contents of the file filename.exe are loaded into memory at appropriate locations, ready for execution. The base parameter is optional.
  Special option: load -v filename does the same "verbosely", reporting memory locations used, etc.
  The different segments of each executable file (segments are executable, read-only, read-write, etc.) are loaded into memory, each starting at the next free address that is a multiple of 0x1000 (decimal 4096), except that is a value for base is provided, that is the address the first segment is loaded at. Segments from different files but with the same attributes are NOT combined, but kept separate.
  If any loaded file defines an entry point called MAIN, that address is stored in the PC register.
• version
  Report the current version number and date.
• clear
  All memory is deallocated and the contents lost, all segment and entry point information is discarded.
• trace option or trace -option
  Activates or deactivates tracing options. The options are:
  • LD: Information on memroy usage and entry points, etc is displayed whenever a .EXE file is loaded.
  • EX: Details of every instruction executed and its effects on memory and register contents are displayed. This causes a lot of output. It is the same output as is produced for each instruction when single-stepping through a program under user control.
  • VM: All major virtual memory operations, such as page allocations and translation problems, are reported.
  • AT: All details of every address translation operation are reported. This produces an enormous amount of output, and should only be used as a last resort, or for a very few instructions.
  • PF: All Page Faults are reported.
• show or show reg
  Show the contents of all normal CPU registers.
• show address
  (Where address is a number) Show the entire contents of the page of memory (512 contigous bytes) that contains that virtual address.
• pshow address
  (Where address is a number) Show the entire contents of the page of memory (512 contigous bytes) that contains that physical address.
• show seg
  Show protections and addresses of all segments.
• show ent
  Show names and addresses of all defined entry points.
• show VM
  Shows details of the virtual memory system, includes a summary of performance, the contents of the 8 special virtual memory controlling CPU registers, the page tables for each of the four address spaces, and the contents of the translation cache ("TLB").
• show VMR
  The contents of the eight special virtual memory control registers are displayed.
• show discs
  Shows details of all available emulated discs.
• show block dn bn
  Shows the entire contents of block bn of disc dn. A block is 512 bytes, discs are numbered 0 to 9, and block numbers start at 0.
• makedisc number size
  A new (emulated) disc drive is created. The number must be between 0 and 9, and is the unit number that system function calls accessing that disc must use to identify it. The size is in units of 512 byte blocks. Do not use large sizes, or you will rapidly fill up the real disc. The file created in the external/host operating system is in the current directory, and called discn.dsc.
  You only have to create a disc once. Emulated discs survive from one session with the emulator to the next.
• disced dn bn
  Enter the interactive disc editor (which has its own online help, type "help"). You may view and change the contents of one of the emulated disc drives. dn is the unit number for that disc. The optional second argument bn is the block number that you want to start viewing.
• assert intname detail
  Artificially signals an interrupt with optional detail (which must be a number). For example, when a program is running and a character is typed, the interrupt CHARIN is signalled, and the detail is the character's ascii code. Assert may be used to simulate interrupts when single-stepping through a program.
• infile number filename
  A running program may read data from a number of "real" files in the external/host operating system. The infile command opens such a file and prepares it for use in the program. The number must be between 0 and 9. Inside a running program, the function call fgetchar(n) reads one character from file number n, returning its ascii code. File number 0 represents the keyboard input stream, so "infile 0" affects the getchar function.
• infile close number
  Closes a file previously opened with the other form of the infile command. Not totally necessary, files are automatiucally closed when their last character is read, and when the emulator is finally exitted.
• E reg
  (Examine) reg is the name of a normal CPU register, R0, R1, R2, ..., R11, FP, AP, SP, or PC. Prints the conmtents of the indicated register.
• E addr
  Show the contents of memory at the indicated (virtual) address. If the contents could be interpreted as a valid executable instruction, that instruction is disassembled and shown completely. Otherwise, 16 bytes starting from the given address are shown. Memory contents are listed three times: the first line showing 16 bytes, the second showing 8 short ints, and the third showing four normal integers.
  The output of E can be difficult to read. If you expect the memory examined to contain data rather than executable instructions, it is much better to use DE instead. It behaves the same way, but never disassembles instructions.
• E addr1-addr2
  As above, but shows the contents of all addresses between the two given.
• E addr1:num
  As above, but shows the contents of the indicated number of bytes starting from the indicated address.
• E
  (with no arguments) Continues the last E command from where it left off. If "E 0x1000" dispalyed a five-byte instruction, then "E" will be equivalent to "E 0x1005".
• PE ...
  (Physical Examine) The same as E, except the virtual memory system is bypassed, used to examine the contents of a physical memory location.
• DE ...
  (Data Examine) The same as E, used when it is known that the memory locations being examined do not contain executable instructions, so the contents is not disassembled. This makes the output much clearer.
• PDE ...
  (Physical Data Examine) A combination of DE and PE.
• ES ...
  (Examine String) The same as E, except that it us used only when the memory location in question is believed to contain the first byte of a zero-terminated string. The string is displayed readably.
• PES ...
  (Physical Examine String) The same as ES combined with PE, a string is dispalyed, given its location in physical memory.
• SF
  Displays the contents of the current Stack Frame, with parameters, local variables, return address, saved frame pointer, etc.
• D reg val
  (Deposit) Sets the value of the indicated register (must be R0, R1, R2, ..., FP, AP, SP, or PC) to the indicated value (must be a number in decimal or hexadecimal with 0x prefix).
• D1 addr val
  (Deposit 1 byte) Writes the indicated value (must be a number in decimal or hexadecimal with 0x prefix). into a single byte of memory at the indicated (virtual) address.
• D2 addr val
  (Deposit 2 bytes) Writes the indicated value (must be a number in decimal or hexadecimal with 0x prefix). as a short int into two bytes of memory starting at the indicated (virtual) address.
• D4 addr val
  (Deposit 4 bytes) Writes the indicated value (must be a number in decimal or hexadecimal with 0x prefix). as a normal integer into four bytes of memory starting at the indicated (virtual) address.
• PD1 ...
  (Physical Deposit 1 byte) The same as D1 but also bypassing virtual memory, so a single byte is written to a physical memory address.
• PD2 ...
  (Physical Deposit 2 bytes) The same as D2 but also bypassing virtual memory, so two bytes are written to a physical memory address.
• PD4 ...
  (Physical Deposit 4 bytes) The same as D4 but also bypassing virtual memory, so four bytes are written to a physical memory address.
• x
  (eXecute) One single instruction is executed (the natural "next" instruction addressed by the PC register). The instruction itself plus any effect it has on memory or register contents is reported on the terminal.
• x addr
  (eXecute) The PC register is set to the address provided, then one instruction is executed exactly as for the addressless version of x.
• run
  Execute whatever program is loaded into memory, starting at its offical starting point (loading a properly compiled complete program correctly sets the starting point) which is usually the entry point called MAIN. Execution continues until something stops it. The user may type control-C to halt it before the end. Typing run a second time will not continue a stopped program, but will attempt to restart it from the beginning. This attempt often fails because the program has changed the contents of memory or registers (especially SP and FP) in some critical way. The reset command may be enough to fix the problem, but many programs are just not written to be reentrant.
• run addr
  The same as the argumentless run command, except that execution starts from the indicated address. The address may be numeric or the name of a defined entry point.
• go
  Start continuous execution of the program. Not the same as Run. Run attempts to clear the state of the program and (re)start it from the beginning. Go starts a program from wherever it happened to be stopped. If you are single-stepping through a program (using the X command), Go will make it run continuously. If a normally running program stopped because it hit a break instruction or an error, Go will make it continue.
• go addr
  The same as the argumentless go command, but the PC register is first set to the indicated address, so it means "go from ...".
• rout filename
  Redirect Output: All output normally produced by the running program (through printf, putchar, or sys$putch, is sent to the named file instead, and does not appear on the terminal. The file is a "real" file in the external/host operating system.
• cout filename
  Copy Output: All output normally produced by the running program (through printf, putchar, or sys$putch, is sent to the named file as well as appearing on the terminal. The file is a "real" file in the external/host operating system.
• flag ...
  The flag command without any arguments displays the current settings of the CPU flags. It may also be followed by a sequence of CPU flag names, each preceeded by a + or - sign. The indicated flags are turned on if preceded by +, or turned off if preceded by -. The flag names are Z, N, SYS, and PAG.
• reset
  All CPU regsiters are set to the appropriate values for execution to begin.
• set break addr
  The break-point is set to the given address. If program execution ever fetches an instruction opcode from that address, the program is stopped, non-destructively (go should successfully continue execution).
• set sreg val
  The named special register (P0BR, P0LR, P1BR, P1LR, S0BR, S0LR, S1BR, or S1LR) is set to the given value.
• clear break
  The break-point is disabled.