How to use MIXemu ================= This is a short tutorial on using MIXemu, the MIX computer emulator. MIXemu is still in its early development stage, and one of the things it lacks is documentation. This text gives only basic information on using mixemu and mixasm, but that should be enough to get you started. I assume, considering your interest in MIXemu, that you're familiar with Knuth's "The Art of Computer Programming". You should, at least, know a little bit about the MIX computer and MIXAL assembly language. Basic mixemu usage ------------------ The "mixemu" program is a very simple command line interface for the MIX emulator. It can also be used to debug MIX programs, since it has some debugging capabilities. When you run mixemu, it displays its prompt (a ">") and waits for commands. $ mixemu > You can now type a command, followed by pressing Return. Let's start by displaying the state of MIX registers with the "regs" command. > regs A = (+00 00 00 00 00) X = (+00 00 00 00 00) I1 = (+00 00) I2 = (+00 00) I3 = (+00 00) I4 = (+00 00) I5 = (+00 00) I6 = (+00 00) J = (+00 00) Cmp = EQUAL Overflow = NO > The output shows the well-known MIX registers: rA, rX, index registers rI1 through rI6, jump register rJ, and the compare and overflow flags. Apparently, all registers have been initially set to zero. You can change any register's value using the "set" command. In the following example, the value of rA is set to 10: > set rA +00 00 00 00 10 > regs A = (+00 00 00 00 10) X = (+00 00 00 00 00) I1 = (+00 00) I2 = (+00 00) I3 = (+00 00) I4 = (+00 00) I5 = (+00 00) I6 = (+00 00) J = (+00 00) Cmp = EQUAL Overflow = NO > (NOTE: Numbers are written using the notation presented in "TAOCP": a sign, followed by five (or two, for short numbers) byte values.) Now, let's take a look at MIX's memory. To examine a single memory word, use the "mem" command, followed by the address of a word. Suppose you want to see the contents of the word located at 1234: > mem 1234 1234 +00 00 00 00 00 > It is also possible to examine a range of words, by specifying the starting and ending addresses: > mem 1234 1240 1234 +00 00 00 00 00 1235 +00 00 00 00 00 1236 +00 00 00 00 00 1237 +00 00 00 00 00 1238 +00 00 00 00 00 1239 +00 00 00 00 00 1240 +00 00 00 00 00 > You can modify the value of a single memory word with the "set" command. The example below changes the value of the word located at 1234 to +01 02 03 04 05: > set mem 1234 +01 02 03 04 05 > After you've played a little with the registers and memory, you'd probably like to see the emulator actually doing something, eg. executing a program. The example program below puts 3 into the rA register, then halts: ENTA 3 HLT To run this program, you need to translate it to MIX machine code and put it in the emulator's memory. Assuming the code will start at the address 1000, you would type: > set mem 1000 +00 03 00 02 48 > set mem 1001 +00 00 00 02 05 > To execute this code, the emulator must know where it starts. To tell mixemu that the starting address of the program is 1000, you use the "go" command: > go 1000 > Now you can start the program by typing the "run" command. > run Program finished normally at 1001. > The emulator claims that the program finished normally at 1001 - sounds fair, since that's where you put the HLT instruction. To see if the program actually did what it was supposed to do (put 3 in rA), take a look at the registers: > regs A = (+00 00 00 00 03) X = (+00 00 00 00 00) I1 = (+00 00) I2 = (+00 00) I3 = (+00 00) I4 = (+00 00) I5 = (+00 00) I6 = (+00 00) J = (+00 00) Cmp = EQUAL Overflow = NO > Hey, it worked! Nevertheless, you probably think that executing MIX programs this way isn't very convenient. You are right, and that's where mixasm comes into play. But first, leave mixemu using the "quit" command. Assembling MIXAL programs with mixasm ------------------------------------- The "mixasm" program is a MIXAL assembler. It takes a MIXAL source file and produces corresponding MIX machine code that can be loaded and executed by mixemu. Suppose you want to make sure that 2+2 is 4. You could use the following MIXAL program: START ENTA 2 ADD =2= HLT END START Start your favorite text editor, type in the program and save it as "add.mas". Then assemble it with mixasm using this command: $ mixasm add.mas As a result, you get a file named "add.mp" (MP stands for MIX Program), which contains the machine code ready to be executed with mixemu. Running assembled programs in mixemu ------------------------------------ To execute a program, first load it into memory. Use the "load" command, followed by a file name: > load add.mp Start address: 0000 > As you can see, mixemu loaded the program and informed you that it starts at 0000. You can now run the program. > run Program finished normally at 0002. > To see the result, examine the rA register: > regs A = (+00 00 00 00 04) X = (+00 00 00 00 00) I1 = (+00 00) I2 = (+00 00) I3 = (+00 00) I4 = (+00 00) I5 = (+00 00) I6 = (+00 00) J = (+00 00) Cmp = EQUAL Overflow = NO > So 2+2 is, in fact, 4. Hooray :-) Programs can be also stepped through, one instruction at a time. The "step" command executes the current instruction, and displays the next one to be executed. If you stepped through the last program, your session with mixemu might look like this: > load add.mp Start address: 0000 > step 0001 +0003 00 05 01 ADD =2= > step 0002 +0000 00 02 05 HLT > step Program finished normally at 0002. > As you can see, the "step" command displays the memory location of the next instruction, as well as the corresponding assembler code. Another useful feature of mixemu are the breakpoints. You can set a breakpoint on a specified memory location, and upon reaching that location, mixemu will stop executing the program. Breakpoints are set with the "break" command. Using the "2+2" program as an example again: > load add.mp Start address: 0000 > break 0001 Set breakpoint #1 at 0001. > run Breakpoint #1 at 0001. > step 0002 +0000 00 02 05 HLT > step Program finished normally at 0002. > You can see that the emulator executed the instruction at 0000, then stopped. Clearing breakpoints that are no longer needed is very simple - you use the "clear" command. You can clear a specific breakpoint (using its number as an argument): > clear #1 Cleared breakpoint #1. > ...or clear them all: > clear Cleared all breakpoints. >