jKPU Files

                           KPU

Good day and welcome. This is the README for the KPU code distribution.
This is fundamentally a hack of the jMIPS code.  jMIPS is a MIPS
(that's a hardware CPU architecture) model in Java.  Using jMIPS, one
can run MIPS programs on any platform with Java support.

KPU changes the basic jMIPS architecture to work on encrypted data and
data addresses.  In principle, it changes the arithmetic in the ALU
inside the processor and that's about that.  The code is a software
model of a hardware architecture for prototyping purposes.

Current uses of encryption are in

   1) the ALU (alright);
   X) implementing bytewise instructions (OK - plan to eliminate
      bytewise instructions by compiling code that uses arithmetic on
      words instead);                                          XXDONEXX
   3) the Console printout routine (OK - that's just a convenience
      so that one doesn't go cross-eyed looking the output);
   4) debugging routines (OK);
   X) in the Registers unit to set register $0 to the value of
      encrypted zero (OK - the compiler can fill it, and if necessary 
      we can implement a command to lock the register afterwards, since
      it's supposed to be a sink as well as a source);         XXDONEXX
   X) in Memory, to find the right RAM unit to address and to implement
      some bytewise accesses (OK on the bytewise accesses, since we
      should get rid of them at compile time, not OK on the use for
      selecting RAM). That's more or less all gone now, but the solution
      isn't definitive yet, so it might come in and out still. XXDONEXX


MORE ON THE ORIGINAL jMIPS CODE

Primarily for helping undergraduate students to understand their
Computer Systems Architecture courses, which traditionally use a RISC
architecture, usually MIPS, as the basis.  The idea was that this Java
code be (a) simple, (b) understandable, (c) provide a model of a CPU
both in the sense of the runtime and structure that is accessible to
students.  

The jMIPS code provides objects that individually emulate the functional
parts of a CPU - the ALU, registers, memory, I/O bus, etc.  There's a
CPUx.java (for x=1 to 5, representing consecutively more sophisticated
models) which builds the CPU out of those parts, connects them
together, and supplies the run() method.  The main() code calls the
constructor for CPUx, sets its stack pointer and program counter, and
calls the run() method.  Who could fail to understand that!

It works.  It runs MIPS executable files (ELF format).  I implemented
almost all the 32-bit MIPS ISA.

The evidence from those students who looked at the jMIPS code as part of
their undergraduate course is that it was a help to them, and made
things clear that might otherwise have remained clouded.  For example,
it is clear after looking at the code that you CAN both write to a
register and read from it at the same time.  For some reason confused
students tend to think that one can't both read and write to a register
simultaneously.  One CAN.  The read sees the previous value while the
write puts in the next value. The changeover happens on the clock pulse
edge.

The originally five, now seven, different pipeline models were intended
to be each successively faster on the test machine code files.  The
default output from the simulator is instruction by instruction timing
data.  

The jMIPS code came with a pile of HTML documention which makes up a
guided tour through the different CPU model architectures. You will
find it in the doc/html subdirectory.

COPYRIGHT

The primary copyright (C) 2009/2010 author is Peter T. Breuer.

CONTACT

    ptb@cs.bham.ac.uk
    ptb@ieee.org
    ptb@inv.it.uc3m.es

    Peter T. Breuer
    Dept. Comp. Sci.
    University of Birmingham
    Edgbaston B15 2TT
    Birmingham, UK

LICENCE

The program is released under the GPL v3 licence. The appropriate
rubric that I should quote in that respect is:

    This program is free software: you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation, either version 3 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program.  If not, see <http://www.gnu.org/licenses/>.

Indeed, you'll find the GPLv3 in the COPYING file alongside this README
in the same directory. If it isn't there, please follow the URL quoted
above and retrieve it.

My personal executive take on the GPLv3 is that you are free to use
and modify the source or any code compiled or otherwise derived from it
for your own purposes.  You are also permitted to pass on the code or
your derivation by most means including distribution, sale and resale,
but you must pass on this or your derived product under THIS licence.

There are two major implications: firstly, when you pass on a binary,
you must also provide the receiver with a way to get hold of the source
code to the binary.  Secondly, the receiver also becomes bound by this
licence, and that's the well-known "viral" aspect.

What happens if you don't obey? Then you are in breach of the licence to
the code so you lose the licence's protection and you are now likely in
breach of copyright, with the subsequent statutory penalities and
horrible remedies that may be applicable.

You may add extra licence conditions as you pass on the code, provided
you do not contradict the original GPLv3 licence.  That's hard to do,
since GPLv3 opens holes in copyright restrictions for you, and the way
GPLv3 is crafted, you would contradict it by closing those holes.  There
are known compatible licences, however.  See the GPL URL.  About the
only thing you could do to get hold of the code under a really different
licence is to ask me, as original author, to re-release my code to you
under that licence instead, and take it from there.

That's my take.  For the exact words of advice setting out the
understanding you should receive, see the GPLv3 text itself!  You won't
go far wrong if you understand that GPLv3 is about maintaining the
freedom of the receivers of compiled or derived code to change and
modify what they receive as they wish.



COMPILATION

Type "make".

Yes, there's a Makefile. You need a unix-style "make" program.

What it does for you is:

    javac CPU/Cpu1.java
    ...
    javac CPU/Cpu5.java

so if your java bytecode compiler is not called "javac", you may need to
make some changes.

That should build all the CPU/*.class files.

If you have a native code compiler, you may waht to use that instead.



RUN

Run the compiled bytecode in a Java Virtual Machine as follows:

    java CPU/Cpu1  ../misc/hello_mips32

You'll likely want a "-q" as a command line option in order to stop the
extra noise that's emitted by default:

    java CPU/Cpu1 -q ../misc/hello_mips32

CPU5 needs an interrupt handler too:

    java CPU/Cpu5 -q ../misc/hello_mips32 ../misc/handler_mips32

And CPU6 and CPU7 need a TLB fault handler:

    java CPU/Cpu6 -q ../misc/hello_mips32 ../misc/handler_mips32 c/handler



BUGS etc.

If you find something wrong, fix it :0). Or just talk to me about it.

I'll happily take patches and your name will go into the credits.


Peter T. Breuer, April 2010
ptb@cs.bham.ac.uk