This guide provides answers to the following questions:
What is IAS?
What platforms does IAS run on?
What is the user interface provided by IAS?
How do I run IAS?
How do I get help while inside the simulator?
How should I set up my environment to run IAS?
What is the state of the machine at startup?
How do I load a program (.class file) into the simulator?
How does control reach this program?
Are classes loaded dynamically as in the JavaTM virtual machine?
What runtime environment is available to the program?
What debugging features are available?
Can I run multithreaded programs on the simulator?
What are the steps for running through a Hello, world program?
What other tools are available that are specific to the picoJavaTM environment?
How do I write a program in picoJava assembly?
Frequently asked questions
Q. What is IAS?
IAS is a simulator which models the picoJava family of processors. Specifically, the current version of the simulator models picoJava-II accurately. (You may occasionally see IAS being referred to as PJSIM - both are synonyms for the same simulator)
IAS models the following:
*_quick
and other instructions
that the picoJava hardware implements, as well as the on-core
caches, such as the D-Cache, I-Cache, and S-Cache.
Basically, IAS models all functionality in the picoJava-II Programmer's Reference Manual and is a comprehensive and accurate functional model of the picoJava hardware. It does not model precise timing (clock cycle) information since it goes by instruction boundaries only. Its primary purpose is to serve as a golden model for verifying the hardware implementation. However, it is also useful for those who need access to the picoJava functionality via a simulator before they have access to actual picoJava-based hardware.
Q. What platforms does IAS run on?
IAS runs on SPARC platforms running Solaris 2.5.1 and up. For information on running IAS on other platforms, see the document Porting IAS.
Q. What is the user interface provided by IAS?
The simulator is based on a Tcl frontend, which automatically provides a Tcl environment for the user interface and the ability to use the Tcl language to extend the command set. It should be easy to bolt on a Tk-based GUI frontend to it, if someone is interested.
You can use the picoJava simulation backend in other ways without the
Tcl interface, such as gdb
for picoJava which links to the
simulation backend, and provide its own frontend.
Q. How do I run IAS?
Type ias at the command prompt. In the picoJava-II environment, the binary for ias usually resides in the directory $DSVHOME/bin
Q. How do I get help while inside the simulator?
Type usage
for online help, which prints a one-line
summary for each of the commands that are available.
Q. How should I set up my environment to run IAS?
Set the environment variable DSVHOME
to the root of
a decaf system verification (DSV
) tree.
The DSVHOME
environment variable:
$DVSHOME/etc/tcl
.
$DSVHOME/etc/sim/sim.tcl
.
$DSVHOME/class/trap_name.class
. However, if a file called
trap_name.class
already exists in the current
directory, then that file name is used instead for the various
trap-related class files. See the next question.
Q. What is the state of the machine at startup?
At startup, IAS first looks at $DSVHOME/class
and in the current directory (see the previous question)
and loads in the trap handlers it can find from these two locations.
The names of the trap handlers are preassigned and fixed.
IAS loads the following three types of trap handlers:
reset.class
and loads at address 0
invokevirtual
, getstatic
, ldc
,
and so on. The emulation trap handlers implement this functionality
and must be loaded in order to properly run Java programs which have
these instructions in them.
See the picoJava-II Programmer's Reference Manual for details about which of the Java virtual machine instructions take emulation traps.
Note - By default, IAS outputs a warning if it cannot find any of these trap handlers, except for the exception handlers.
All exceptions and traps have an associated trap type (see Table 12-1 in the picoJava-II Programmer's Reference Manual). The trap vector table is initialized to point to the respective trap handlers. In the current picoJava environment, the trap vector is hardcoded to address 0x10000; the trapbase register is initialized to 0x10000.
Next, the machine initializes the registers to the power-on values (see Table 8-1 in the specification). As a debug feature, all uninitialized memory and the stack cache are initialized to the pattern 0xdeadbeef. The machine is now at pc 0, ready to execute instructions.
Finally, IAS reads the file .iasrc
in the current
directory and executes the commands in that file. The simulator is
then ready to accept user commands.
Q. How do I load a program (.class
file) into the
simulator?
Use the loadClass
command, which installs the class file
into the machine's memory and sets up the tables for class structures
and so forth. If any of the superclasses of this class have not been
loaded, IAS loads them as well. The simulator searches for
these classes in the same locations as those for the trap handlers: first
in the current directory, and if it cannot find the classes there,
then under $DSVHOME/class
.
If a class is already loaded,
loadClass
prints an error;
it is illegal for the same class to be loaded twice in the same system.
Q. How does control reach this program?
The reset code (from reset.class) is loaded at address 0.
The default is to pick up reset.class from the $DSVHOME/class directory.
(You can also customize the
initializations and override them with a reset.class
in
the current directory, however. See the
last paragraph.)
The default version of the reset code does the following:
.clinit
methods in classes which
contain these methods.
main
and jumps to it.
After main
has finished executing, IAS returns
an integer value, which the reset code then picks up and emits as the
final status of the run with the following message:
IAS: TEST PASSED
(meaning that the exit code is 0)
or:
IAS: TEST FAILED - Return Code xx
(meaning that the exit code is nonzero)
Note - The signature for the main
method is:
public static int main ()
not:
public static void main (String[] argv)
as in regular Java virtual machines.
The default reset code launches main
in superuser mode
(PSR.SU
= 1). This methodology should not affect high-level
Java code, but may have some bearing on programs that contain low-level
machine details that are written in picoJava assembly.
If you want more control over how the reset code sets things up,
create your own reset.class
in the current directory. You
can either disassemble the default reset.class
, patch it and assemble it back, or write your own.
Q. Are classes loaded dynamically ?
No, we do not support dynamic loading. Unless you load all the
classes that your program needs during execution,
you may see a cryptic TEST FAILED: CLASS NOT LOADED
error later on.
Be sure to find out what classes you may possibly need and load them
all with the loadClass
command. A common gotcha is not
loading the classes for exception objects, which may be created along
the way.
Q. What runtime environment is available to the program?
Very little, since porting of the bulk of the runtime environment to picoJava hasn't happened yet. However, the basic functionality that is required to implement the Java virtual machine instruction set (such as memory allocation) is handled internally by a small kernel embedded into the trap handlers. Beyond that, all API functionality has to be created for the simulator. There is a system call mechanism the simulator supports which should be used as the basis for implementing native code functionality.
Q. What debugging features are available?
Debugging features include: run2
,
dumpStack
, dumpReg
, dis*
, and itrace
.
itrace
level 1 prints out trap and exception entries, as well as exit messages.
itrace
level 2 prints out all method calls and returns, jsr
s, and ret
s in addition to the level 1 output.
itrace
level 3 prints out the disassembly of each
instruction as it is being executed in addition to the level 2 output.
This is probably the most useful level.
itrace
level 4 prints out register contents after
every instruction in addition to the level 3 output.
itrace
level 8 prints out every memory reference as it occurs in addition to the level 4 output. This output is very verbose.
Q. Can I run multithreaded programs on the simulator?
Not unless you provide the software layer for locking, thread creation, scheduling, and other features, which is not yet available. This is part of runtime software functionality, not hardware functionality; ias models only the hardware.
Q. What are the steps for running through a Hello, world
program?
Well, Hello, world
is more difficult since you need to have system
call support in your runtime environment. However, here's a simple example of a Java
program that adds two numbers together.
add.java:
class add {
public static int main () {
int a = 3, b = 4, c = 7;
if (a + b == c)
return (0); // indicates pass
else
return (2); // indicates fail
}}
Follow these steps:
add.class
by typing at the prompt:
javac add.java
.
ias
at the prompt.
this emits a bunch of messages about loading trap handlers, etc, then gives you a prompt and is ready for program execution.
loadClass add
at the prompt.
run
.
IAS then runs and ouputs a message like this at the end:
IAS: Test PASSED, 189 instructions, 0 interrupts taken, 0 total traps
exit
.
Q. What other tools are available that are specific to the picoJava environment?
A picoJava assembler, called jasm
, can assemble picoJava and Java virtual machine instructions. The
corresponding disassembler is called jdis
.
Another tool, called classDump
, provides information about
class files.
Q. How do I write a program in picoJava assembly language?
Presumably, you want to write code that is specific to the picoJava
environment and which uses the picoJava instruction set. To do so, you
can use the jasm
assembler (see the previous question) to write your own assembly.
You write a user program in exactly the same way as mentioned
above for Java programs: The entry point
should be a static method called main
.
Here is a minimalist, complete version of an assembly-level main
program:
nop.jasm:
public class nop {
public static Method main:"()I"
stack 1 locals 0
{
sipush 0; // simply return a 0 exit code
ireturn;
}
}
Type jasm nop.jasm
to create nop.class
, then
run ias
and loadClass nop
, and execute run
and other commands just as you do with a high-level
Java program.
Be sure to use the versions of jasm
and jdis
from the picoJava environment.
More questions....
The Frequently Asked Questions document provides answers to more advanced questions, which are not covered in this document. IAS