Beginner's Guide To Using IAS

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:

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:

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:

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:

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.

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:

  1. Create add.class by typing at the prompt: javac add.java.

  2. Type: 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.

  3. Type loadClass add at the prompt.

  4. Type run.

    IAS then runs and ouputs a message like this at the end:
    IAS: Test PASSED, 189 instructions, 0 interrupts taken, 0 total traps

  5. Type 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


Copyright © 1999 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, CA 94303-4900 USA. All rights reserved.

Last modified 24-March-1999