<p>[This is Markdown format; README.html is auto-generated from this file.]</p>

<h1>The CSPIM MIPS simulator</h1>

<p>More details about this project can be found

<a href="http://zvrba.net/software/cspim.html">here.</a> Detailed description of CSPIM

internals as well as the motivation and possible use cases can be found in the

following publication:</p>

<p>Vrba, Z.; Halvorsen, P.; Griwodz, C., "Program obfuscation by strong

cryptography" The International Dependability Conference, 2010. ARES

'10. International Conference on, 15-18 February, 2010.

<a href="http://dx.doi.org/10.1109/ARES.2010.47">DOI:10.1109/ARES.2010.47</a></p>

<p>Copies of the paper are available on explicit request by email.</p>

<h1>COPYRIGHT NOTICE</h1>

<p>All files in this distribution, unless otherwise explicitly noted, are</p>

<li>(c) 2008-2012 Zeljko Vrba <a href="&#109;&#97;&#x69;&#108;t&#x6F;:z&#x76;&#x72;&#98;&#97;&#x2E;&#x65;&#120;&#116;&#101;&#114;n&#97;&#x6C;&#64;z&#x76;&#114;&#x62;&#97;&#46;&#x6E;&#101;&#x74;">z&#x76;&#x72;&#98;&#97;&#x2E;&#x65;&#120;&#116;&#101;&#114;n&#97;&#x6C;&#64;z&#x76;&#114;&#x62;&#97;&#46;&#x6E;&#101;&#x74;</a></li>

<p>and are distributed under the following license:</p>

<p>Permission is hereby granted, free of charge, to any person obtaining a copy

of this software and associated documentation files (the "Software"), to

deal in the Software without restriction, including without limitation the

rights to use, copy, modify, merge, publish, distribute, sublicense, and/or

sell copies of the Software, and to permit persons to whom the Software is

furnished to do so, subject to the following conditions:</p>

<p>The above copyright notice and this permission notice shall be included in

all copies or substantial portions of the Software.</p>

<p>THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR

IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,

FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE

AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER

LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING

FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS

IN THE SOFTWARE.</p>

<h1>Project structure</h1>

<p>The top-level directory contains the following subdirectories:</p>

<li>bmips: precompiled programs for MIPS I; directly runnable by CSPIM</li>

<li>hostapps: host utilities [the interpreter itself]</li>

<li>mipsapps: source fof programs runnable by CSPIM; precompiled in <code>bmips</code></li>

<li>vm: core simulator: MIPS instruction set and ELF loader</li>

<h1>How to build</h1>

<p>This package has been developed and tested with Solaris cc, gcc and Visual

Studio 2008. Prerequisites for building:</p>

<li>Working native compiler. Solaris cc, gcc and Visual Studio 2008 have been

tested.</li>

<li>Working cross-compiler which can generate little-endian MIPS I ELF

executables. gcc 4.2.4 and binutils 2.22 have been tested.</li>

<li><a href="http://www.cmake.org">CMake</a></li>

<p>The interpreter is built by executing</p>

<pre><code>cmake .

make

<p>This will build host applicactions in <code>hostapps</code> and MIPS applications in

<code>mipsapps</code>. (Files in <code>bmips</code> directory are for reference only and are not

overwritten.)</p>

<h2>Host applications</h2>

<p>The following applications are built in <code>hostapps</code>:</p>

<li><code>runtorture</code>: use to run the MIPS torture test</li>

<li><code>run</code>: use to run (possibly encrypted) MIPS executables</li>

<li><code>runbench</code>: use to run the MIPS benchmarks</li>

<li><code>elfcrpyt</code>: use to encrypt MIPS ELF executables</li>

<p><code>sstep</code>, <code>hanoi-bench-native</code>, <code>mmult-bench-native</code> are benchmarking

applications; see the above paper for details. The "run" programs

take as parameter a MIPS ELF executable; an example invocation is

./hostapps/run ./mipsapps/hanoi

<code>runtorture</code> should only be used to run the <code>cputorture</code> program.</p>

<h2>MIPS CPU torture test</h2>

<p>Torture test assembly source is generated by preprocessing the <code>*.sm4</code> files

with M4:</p>

<pre><code>m4 cputorture.sm4 &gt; cputorture.s

<p>The pregenerated source is already provided in the distribution. The test

is run by executing</p>

<pre><code>./hostapps/runtorture ./mipsapps/cputorture

<p>If the test is successfully passed, the last lines of the output will be

something like (note the <code>(near SUCCESS)</code> in the last line):</p>

<pre><code>finished: exception=5, code=0x0, last_branch=0x2e74(near t_link)

***MIPS@0xb7c6b008***

BASE=200000@0xb7c6b008 BRK=00003fd0 STKSZ=00004000

R00=00000000 R01=00000000 R02=00000000 R03=0000000c

R04=00000001 R05=00005678 R06=00005678 R07=00001234

R08=00001234 R09=0000e7f8 R10=0000e7f8 R11=0000c5d6

R12=0000c5d6 R13=12345678 R14=12345678 R15=c5d6e7f8

R16=c5d6e7f8 R17=56787800 R18=56787800 R19=12345678

R20=12345678 R21=00001234 R22=ffffe7f8 R23=00000000

R24=90000000 R25=f0000000 R26=00003fc0 R27=00003fc4

R28=00003fc0 R29=00003fc4 R30=00003fc8 R31=00002fa0

HI =12345678 LO =9abcdef0

PC =00002fb0 DS =00000000

(near SUCCESS)

<p>If the execution stops at a label name other than <code>SUCCESS</code> in the last line,

something has gone wrong and the preceding output can be determined to find

out what.</p>

<h2>MIPS applications</h2>

<p>Many of the other example problems are are solved assignments (in C) from

Appendix of the third edition of Hennessy &amp; Patterson, Computer Organization

and Design: The Hardware/Software Interface; available at. This appendix is

also available online <a href="http://pages.cs.wisc.edu/~larus/HP_AppA.pdf">here.</a>

These programs should be executed with <code>./hostapps/run program</code>.</p>

<h2>Encrypted execution</h2>

<p>All LOAD ELF segments of executables can be encrypted with RC-5 encryption

algorithm using 32-bit block size and 128-bit key. The encryption uses ECB

mode, which should <em>not be used for anything but simple demos</em>! Example

session:</p>

<pre><code>./hostapps/elfcrypt mipsapps/hanoi /tmp/hanoi-crypt 0123456789ABCDEF0123456789ABCDEF

./hostapps/run /tmp/hanoi-crypt 0123456789ABCDEF0123456789ABCDEF

<p>Failing to provide the key in the last command will terminate execution with

exception 3 (invalid instruction).</p>

<h2>Self-simulation</h2>

<p>Compile both HOSTED and non-HOSTED build (configure this by using <code>ccmake</code>).

This must be done in two separate build directories; note that cmake supports

builds in directories other than the source directory (so-called

"out-of-source build"). This builds an extra executable,

<code>./mipsapps/run-lvl1</code>, which should be run with <code>./hostapps/load-lvl1</code>.

<code>./run-lvl1</code> can currently only run cputorture, since the nested simulation

does not yet forward system calls to the outer simulation.</p>

<p>NOTE: You need to remove all files previously generated by CMake for

out-of-source build to work.</p>

<p>Suppose that the hosted interpreter has been built in the <code>./HH</code> directory,

and the non-hosted in the <code>./NH</code> directory. Then the CPU torture test can

be run in the nested simulation with the following command:</p>

<pre><code>./HH/hostapps/load-lvl1 ./NH/mipsapps/run-lvl1 ./NH/mipsapps/cputorture

<h2>Building cross-gcc</h2>

<p>Note that gcc 4.2.x is the highest gcc version that doesn't require GMP, MPFR

and MPC libraries, which significantly eases installation.</p>

<li><p>Download and build binutils (tested with version 2.22).

Configure and build as:</p>

<p><code>./configure --prefix=$HOME --disable-debug --disable-nls --target=mipsel-elf</code>

<code>make install</code></p></li>

<li><p>Download and build gcc; it MUST NOT be built in the source dir (hence ../).

Make sure that the installed binutils (mipsel-elf-as etc.) are in PATH.</p>

<p><code>../gcc-4.2.4/configure --prefix=$HOME --disable-debug --disable-nls --target=mipsel-elf --disable-bootstrap --disable-libssp</code></p>

<p><code>make install</code></p></li>