====== Spimmy ======

**Note** Bugs, feature requests, etc have moved to the discussion page for the project.

===== License =====

  * **License**: [[http://www.opensource.org/licenses/gpl-license.php|GNU GPL v2]].

It's not required, but please consider linking to [[spimmy|this page]] or the main page from your site if you like this product.

===== Download =====
Before downloading or using this product, make sure you __**understand and accept**__ the terms of the [[#license]].

After downloading, you can find compilation instructions below.

  * Only the latest version is actively supported:
    * Latest Version: {{:projects:spimmy-07132006.zip|Spimmy - July 13, 2006}}

===== About =====

Spimmy is a mini MIPS **simulator**, written in C. It emulates the **datapath** (indirectly emulating the instruction set) of a stripped down MIPS device. This is different from what is typically called an **emulator**, which directly emulates the instruction set.

By doing things in this fashion though, we sacrifice speed for simplicity (relatively speaking) and gain (theoretically) some implicit accuracy through creative code reuse.

Spimmy is partially built off of the [[http://www.cs.wisc.edu/~larus/spim.html|SPIM]] mips simulator, albeit spimmy is much less complicated and simulates a lot less. 

===== Notes =====

==== Supported Instructions ====
The following are the instructions currently supported:

^ Type ^ Instruction Pneumonic ^ Meaning ^
| R | ''add $rd, $rs, $rt'' | %%$rd = $rs + $rt;%% |
| R | ''and $rd, $rs, $rt'' | %%$rd = $rs & $rt;%% |
| R | ''or $rd, $rs, $rt'' | %%$rd = $rs | $rt;%% |
| R | ''slt $rd, $rs, $rt'' | %%$rd = ($rs < $rt) ? 1 : 0;%% |
| R | ''sltu $rd, $rs, $rt'' | %%$rd = ((unsigned)$rs < (unsigned)$rt) ? 1 : 0;%% |
| R | ''sub $rd, $rs, $rt'' | %%$rd = $rs - $rt;%% |
| J | ''jump imm'' | %%goto imm << 2;%% |
| I | ''beq $rt, $rs, imm'' | %%if ($rt == $rs) goto (PC + 4) + (imm << 2);%% |
| I | ''addi $rt, $rs, imm'' | %%$rt = $rs + imm;%% |
| I | ''slti $rt, $rs, imm'' | %%$rt = ($rs < imm) ? 1 : 0;%% |
| I | ''sltiu $rt, $rs, imm'' | %%$rt = ((unsigned)$rs < (unsigned)imm) ? 1 : 0;%% |
| I | ''lui $rt, imm'' | %%$rt = imm << 16;%% |
| I | ''lw $rt, imm($rs)'' | %%$rt = ((int*)*$rs)[imm];%% |
| I | ''sw $rt, imm($rs)'' | %%((int*)*$rs)[imm] = $rt;%% |

To be continued...

==== File format ====

The file format for input is as follows:
<code php>
00000000 #comment
</code>

Where 00000000 is an instruction in 8-byte hex character format. Comments are **not** parsed nor interpreted by the simulator.

Here is small example of an input file:

<code php>
012a602b  #sltu $12, $9, $10               ; 29: sltu $t4, $t1, $t2;
200d0002  #addi $13, $0, 2                 ; 30: addi $t5, $zero, 2;
012d4822  #sub $9, $9, $13                 ; 31: sub  $t1, $t1, $t5;
</code>

To be continued...

==== Compiling and Running ====

Spimmy compiles correctly using Microsoft Visual Studio 2005 under Windows, as well as gcc under Solaris, and compiles correctly on both big and little endian systems with no changes necessary. It should compile and run on any system that supports gcc.

To be continued...

==== Known Issues ====

These are issues that will eventually be fixed in some fashion:

  * BEQ acts as if it implements branch delay slot, but in reality branch delay is not implemented. Thus if you wish to conditionally jump to instruction at memory address A, instead of using %%A >> 2%%, you will need to use %%(A + 4) >> 2%% or alternatively %%(A >> 2) + 1%%.
  * Data Memory is in big endian format, and...
  * Instruction Memory is in little endian format.
    * But this is actually very unrealistic.

===== What's new =====

  * 07/13/2006 - Initial release