MIPSim : a simple MIPS simulator written as a school project.

License
-------

The source code is available under BSD license. However, due to the dependency
on other libraries (most notably GNU readline), executables are licensed under
the terms of the GPL.


Build instructions
------------------

You need a C compiler to build MIPSim, preferably GCC but any C99 conformant
compiler should do.

Instead of a handwritten Makefile, a qmake project file is provided.

Building is as simple as :

$ qmake && make

Please note that GNU readline is required to build MIPSim. This library is
available by default on most *Nixes but might be more difficult to obtain
under Windows...


A special Makefile (adapted from qmake-generated one) is provided to build
under telsun. The build command becomes :

$ make -f Makefile.telesun


Usage
-----

simips [options] program

Options :
  -t addr            : specify base address of text section (for relocation)
  -d addr            : specify base address of data section (for relocation)
  -s size            : specify maximum amount of memory available to simulator
  -nss size          : specify maximum amount of GCC/newlib stack space
  --zero-sp          : go against spec and let program set SP (newlib compat)
  --debug            : enable debug output
  --debug-log file   : specify file in which to redirect debug output
  --trace            : enable trace output (can be toggled on off in shell)
  --trace-log file   : specify file in which to redirect trace output
  --version          : display version and exit


Note on name :
  The name simips has been enforced by project specs after the original skeleton
was written and any renaming beyond executable name wasn't considered worth the
effort.

Note on s & nss :
  For practical reasons s and nss are independent, therefore the total amount
of physical adress space available to the simulator is the sum of both. Also
note that the nss parameter is only take into account when loading executables
because, as MIPSim does not perform symbol resolution (i.e linking), relocatable
objects that depend on newlib cannot be run in MIPSim.


Documentation
-------------

You can obtain API docs using Doxygen

$ doxygen


Shell
-----

MIPSim basic interface is a GDB-like shell supporting the command set described
below. Parameters in angle bracket are mandatory, parameters in square brackets
are optional.

MIPSim shell provides advanced command editing (with, e.g. tab completion) and
command history thanks to GNU readline library. Additionaly, most numerical
parameters can be arbitrary mathematical expression with C operators.  Literals
can be either register names, ELF symbols or immediates in base 8, 10 or 16.

IMPORTANT : parameter splitting is strict. If you want to use whitspaces in
mathematical expressions for readability, double-quote the parameter.


* load <filepath> [isa]
--------------------------------------------------------------------------------
 Short-hand : l
 
 Loads an ELF binary (executable or relocatable) and map it into the memory of
 the simulated  machine. PC is moved to the entry point or, if none exists, to
 the start of the .text section.
 
 Note : binaries MAY NOT contain references to external symbols.
 
 The optional isa parameter indicate which version of the MIPS instruction set
 should be allowed in the simulator. Valid values are :
    mips1
    mips2
    mips3
    mips4
    mips5
    mips32
    mips64
    mips32r2
    mips64r2
 
 The "mips" prefix can be ommitted.
 
 Please note that, while all values are accepted, not all ISA are properly
 simulated yet. In particular there is no FPU and 64 bit support at all...


* run [address]
--------------------------------------------------------------------------------
 Short-hand : r
 GDB equiv  : continue/jump
 
 Resume the execution of the simulated machine from the supplied address (from
 the current  value of the PC by default)
 
 
* quit
--------------------------------------------------------------------------------
 Short-hand : q
 Alias      : exit
 GDB equiv  : quit
 
 Quit MIPSim
 
 
* help [command]
--------------------------------------------------------------------------------
 Short-hand : h
 GDB equiv  : help
 
 Display a list of supported commands if no parameter passed. Display command
 specific help  when given a parameter.


* step [count]
--------------------------------------------------------------------------------
 Short-hand : s
 GDB equiv  : nexti
 
 Executes [count] instructions (default is 1). A branch and its delay slot are
 considered as a  single instruction.
 
 A procedure call and all the subsequent instructions until procedure return are
 considered as  a single instruction.
 

* stepi [count]
--------------------------------------------------------------------------------
 Short-hand : si
 GDB equiv  : stepi
 
 Executes [count] instructions (default is 1). A branch and its delay slot are
 considered as a single instruction.
 
 
* dump
--------------------------------------------------------------------------------
 Short-hand : d
 GDB equiv  : info registers
 
 Dump informations about all processor registers.
 
 
* trace [1 | 0]
--------------------------------------------------------------------------------
 Short-hand : t
 
 Toggle trace output.
 
 
* dasm [start] [end]
--------------------------------------------------------------------------------

 Disassemble memory. Non-executable memory will be disassembled as .word
 directives.
 
 If no start parameter is provided the whole .text section will be disasembled.
 If only the start parameter is provided, end will default to start (only one
 instruction will  be shown).
 
 
* dreg [reg]
--------------------------------------------------------------------------------

 Display the content of a register. The parameter can be a register number or a
 mnemonic, with or without a $ prefix. Using mnemonic, one can access the
 contents of PC, HI, LO and coprocessor registers.

 
* sreg <reg> <value>
--------------------------------------------------------------------------------

 Set the content of a register. The parameter can be a register number or a
 mnemonic, with or without a $ prefix. Using mnemonic, one can access the
 contents of PC, HI, LO and coprocessor registers.

 
* dmem <start> [end]
--------------------------------------------------------------------------------

 Display the content of memory region delimited by start and end parameters. If
 not provided, end default to start + 3*16


* smem <address> <value> [bytecount]
--------------------------------------------------------------------------------

 Set the content of a memory cell. If value is larger than a byte, a valid
 bytecount parameter must be provided. Bytecount can be either 1, 2 or 4.

 
* addbp <start> [end] [mask] [type]
--------------------------------------------------------------------------------
 GDB equiv  : break
 
 Create a breakpoint.
 
 Breakpoint is hit when tested value V verifies :
    start <= (V & mask) <= end
    
 Value being tested depends on the breakpoint type :
 
   type |  value tested
 ----------------------
   memr | memory address passed to lb, lh, lw...
   memw | memory address passed to sb, sh, sw...
   memx | memory address of current instruciton (i.e PC)
 opcode | current instruction
 
 Defaults :
   end  = start
   mask = 0xFFFFFFFF
   type = memx
   

* rmbp [id]
--------------------------------------------------------------------------------

 Remove a breakpoint when given a parameter, all breakpoints otherwise
 
 
* dbp [id]
--------------------------------------------------------------------------------

 Display information about a breakpoint when given a parameter, about all
 breakpoints otherwise
 
 
* mmap [start] [size] [flags]
--------------------------------------------------------------------------------
 
 When invoked without parameters, display all memory mappings of the simulated
 machine, Otherwise create a new mapping.
 
 Mappings MAY NOT overlap.
 
 Default size value is the amount of memory needed to reach next page boundary.
 
 Flags is in {w, x, wx}. wx is accepted as an alias to wx but its use is
 discouraged.
 
 Default flags value is w.


* print <expr>+
--------------------------------------------------------------------------------
 
 Evaluate any number of expressions and print the results.


* status
--------------------------------------------------------------------------------
 
 Display target status (i.e last stop reason if any).


* dsym
--------------------------------------------------------------------------------
 
 Display symbols found in the last loaded ELF file.


* drel
--------------------------------------------------------------------------------
 
 Display relocations informations found in the last loaded ELF file.



Limitations
-----------

MIPSim can only run valid ELF32 binaries targeted to the MIPS I-IV architecture.
Additionally binaries must not have any reference to external symbols (i.e, no
shared libs...)

Such binaries can be obtained via a cross-compiler toolchain (e.g GCC build for
mips-elf target)

MIPSim does not emulate a MIPS pipeline and is not very accurate in terms of
instruction / memory timings : it just goes through the opcodes as fast as it
can without any effort to "harmonize" the time spent on each opcode...

MIPSim does not emulate any peripheral. Minimal I/O is supported via a few
syscalls and a hackish emulation of IDT/PMON monitors.


Tests
-----

MIPSim comes with a few test programs. Some are written in assembly, some in C,
some in a mix of both (via GCC inline assembly). The code is in the demos/
subfolder.

MIPSim strives to achieve accurate simulation and to that end an automated test
program has been written. It runs a target executable in both MIPSim and GDB in
parallel and single step through the code, verifying after each instruction that
there is no simulation divergence (by checking register contents). The source
code of this tool lies in the test/ subfolder. It is written in C++ and depends
on the Qt4 toolikt (only the core lib though, no GUI is provided). This tool has
several important limitations :
    * no I/O redirection of subprocesses (so cannot be used with test programs
    waiting for user input)
    * unpredictable behavior with newlib-free binaries (quite surprisingly, the
    issue comes from GDB simulator which somehow fail to load/simulate these...)