Table of contents
- Installing the application
- Using the application
- Writing a MIPS assembly file
The KOYOTE Project is a computer application capable of simulating a RISC (Reduced Instruction Set Computer) processor's behavior and showing which parts of the processor are used during a clock cycle in a graphical way.
The program reads a MIPS assembly file and shows you what really happens at a very low level when an instruction is executed. The components represented are : the memory, the datapath and its control unit.
The processor we have chosen is a simplified MIPS R2000-like processor whose instruction set is large enough, but still quite simple.
Installing the application
The KOYOTE Project is distributed as a source archive containing all the files needed to compile the program. Unpack the archive to a directory of your choice and follow the instructions detailed in the INSTALL file.
If you encounter problems during the installation, try and check the FAQ section. If your problem does not find an answer there please contact us and we will try and help you as soon as possible.
Using the application
The KOYOTE Project accepts several command-line options:
- -c or --console
- Runs the program in text mode, showing a lot of details. This is useful to people who want to see more details than the graphic interface shows.
- -g or --graphic
- Runs the program in graphic mode, showing a user-friendly GTK+ interface that lets you see what occurs during the clock cycles. This is the default mode, the '--graphic' option is implied if you do not specify any other option.
- -v or --version
- Outputs full version information to the standard output and exits.
- -h or --help
- Outputs a short summary of the available options and exits.
You can only specify one option at a time. If you specify more than one option, a short summary of the option syntax will be displayed.
To start the program in graphic mode, type the following command on the command-line:
% koyote &
The graphic mode launches a GTK+ interface that lets you load a MIPS assembly file, reset the datapath to its initial status, execute an instruction, display the parser error output and get version information.
When the program starts, no file is loaded. Press the 'Load File' button or hit the 'Ctrl+L' keys, the 'Load a MIPS assembly file' window appears.
Choose a file in the list or type its name and press OK. If the file is a valid file a message saying that the file has been successfully loaded will be displayed at the bottom of the window.
Otherwise you will get a message saying that errors were found while loading the file.
In this version of the program, the detailed error list is still outputted to the standard error output. In next versions, the error list will be available by clicking on the '!' button.
Once a file has successfully been loaded, you can press the 'Next Cycle' button or the 'Ctrl+N' keys to start the next clock cycle. The display will then update. The active parts of the datapath are shown in blue, the inactive ones in black and the control lines in green. Active control lines are shown in blue too. Note that a control line is marked as active if and only if it is used during the cycle.
For the moment the instruction name and value are not displayed on screen in the graphic mode. This will come in the next version.
Once you have reached the end of the loaded instructions the program will display a message that there is no more instruction to display and suggest you to load another MIPS assembly file. The program will also stop and display a message if your assembly program attempts to jump outside the allocated instruction memory.
You can reset the datapath at any moment by pressing the 'Reset' button or hitting the 'Ctrl+R' keys. This will reset the instruction and data memory as well as the datapath itself to their initial empty status.
You can get version information by clicking on the 'About' entry in the '?' menu or by hitting the 'Ctrl+A' keys.
To quit the program, press the 'Quit' button or hit the 'Ctrl+Q' keys.
To start the program in console mode, type the following command on the command-line:
% koyote --console &
%koyote -c &
The program will then ask you for the name of the file you want to load. Type the name and press the 'Enter' key.
The program will then display detailed information about the execution of each instruction contained in the file. The program displays the status of the MIPS registers before the execution, the status of the control lines during the clock cycle, the arithmetical and logical results computed during the cycle and the status of the MIPS registers after the execution. Hit the 'Enter' key to execute next instruction.
The application will stop automatically when the end of the assembly program has been reached. If your assembly program runs in an infinite loop, the application will run in an infinite loop as well.
Writing a MIPS assembly file
Whenever you are writing a MIPS assembly file that you intend to use with The KOYOTE Project, you must consider the following limitations:
The following instructions are the only implemented instructions, any other instruction will be ignored.
nop j jal add addu and nor or slt sltu sub subu xor sllv srav srlv sll sra srl beq bne bgez bgezal bgtz blez bltzal bltz jr jalr lw sw addi addiu andi ori xori slti sltiu
Symbolic jump labels are not supported.
This means that whenever you are writing a MIPS assembly program that you intend to use with The KOYOTE Project, you must use the hexadecimal value of the jump address, not a symbolic value.
Symbolic jump label support will be added in the next version.
Assembler directives are ignored.
If your program rely heavily on them, it won't work as expected.
You can learn more about the MIPS architecture and programming language in James Larus' XSPIM documentation available here.
If you want to learn even more about computer architecture read Computer Organization & Design: The Hardware-Software Interface by J.Hennessy and D.Patterson.