IAS:
Source Guide

Note: All paths are relative to tools/dsv/.

• Build Methodology
• Include File Mechanism
• Source File Description

Build Methodology

The source is split across several directories, all of which share the same Makefile and are linked from config/Makefile. Each directory, however, has it's own copy of Makefile.in included by the makefile.

The Makefile.in specifies the source files in the directory, the exported includes, the libraries and the binaries to be built from that directory.

To build the source, type "make" in the following directories:

Directory	Action Taken by Makefile.in
dsv/src	Exports a couple of basic header files
cache/src	Builds libcache.a. Cache module.
ldr/src	Builds libloader.a. Loader module.
iam/src	Builds libiam.a and chk2mem, a utility used for restarting RTL from IAS checkpoints.
sim/src	Builds the IAS binary including the Tcl frontend.

Note: The libloader.a is also linked to the verilog to provide the main memory and the loader code. During cosim, there are two separate instances of the same libloader.a; one linked to RTL, the other to IAS, with their own versions of common memory.

Each source directory contains a .depend file which makedepend automatically generates. This file is included by the Makefile during the build process.

When each module is built, the exported include files that are specified in Makefile.in are put into the directory include (under tools/dsv) so that the rest of the modules can see the include files. In reality, the include/.h file is simply a link to the location of the real include file inside whichever directory exports it. This ensures that .h files used are always the latest copies, and does not require a separate command to export includes. It also enables you to specify a single argument to -I (the include directory) on the cc command line.

Note: Multiple modules should not have include files with the same name, since this will cause confusion.

No source code or definitions should be in .h files. The .h files should contain only prototypes, extern declarations and macros.

All header files should be protected against double inclusion by defining a dummy macro ___H_

Source File Description

This section is a brief overview of what is in each IAS source file:

dsv module

dsv/src/checkpoint_types.h
Types and macros used by checkpoint functions in every module

dsv/src/dsv.h
Only defines DSV_SUCCESS AND DSV_FAIL. This is used inconsistently throughout the code.

Cache module

cache/src/cache.c cache/src/cache.h
Source for all functions to implement the I-Cache and D-Cache.

cache/src/lutil.h cache/src/util.c
Utility functions used by cache module.

iam module

iam/src/array_ops.c iam/src/array_ops.h
Array instructions for picoJava-II.

iam/src/breakpoints.c iam/src/breakpoints.h
IAS code and data breakpoint functionality. This code is not the same as picoJava hardware breakpoint registers.

iam/src/checkpoint.c iam/src/checkpoint.h
IAS code for checkpoint and restart commands, which in turn calls the checkpoint and restart functions inside each module.

iam/src/chk2mem.c iam/src/chk2mem.h
Source for the chk2mem utility - a standalone utility, and a binary built from this directory.

iam/src/commands.c iam/src/commands.h
Implementations of a few cache control commands.

iam/src/display.c
Implementations of a few display commands.

iam/src/dprint.h
Implementations of a debug print mechanism which controls verbosity of various itrace levels.

iam/src/exception.c iam/src/exception.h
Implementation of exception mechanism for picoJava.

iam/src/ext_ops.c iam/src/ext_ops.h
Implementation of picojava specific "extended" bytcodes.

iam/src/gdb_interface.c iam/src/gdb_interface.h
Adapter to the gdb frontend requirements. The gdb interface is not supported, may not have all features and may not be available to all IAS users.

iam/src/global_regs.c iam/src/global_regs.h
Implementation of picojava registers, and some pseudo-registers. Basically, IAS global variables.

iam/src/iam.c iam/src/iam.h
Main IAS loop and control.

iam/src/interrupts.c iam/src/interrupts.h
IAS implementation of scheduling interrupts feature.

iam/src/javamem.c iam/src/javamem.h
Implements the memory interface of the simulator. All memory accesses go through the functions or macros defined in these files.

iam/src/jmath.h iam/src/jmath_md.h
A couple of floating point macros for picoJava drem instruction.

iam/src/jvm_ops.c iam/src/jvm_ops.h
Source for most simple Java Virtual Machine instructions.

iam/src/object_ops.c iam/src/object_ops.h
Source for all the object related Java Virtual Machine instructions.

iam/src/opcode_names.h iam/src/opcodes.h
Opcode values and names.

iam/src/report.c iam/src/report.h
Code to print out final statistics, pass or fail, and any failure message.

iam/src/sample_libtrace.c
A very simple example to demonstrate use of the IAS program tracing feature.

iam/src/scache.c iam/src/scache.h
Implementation of the picoJava stack cache.

iam/src/serial_port.c iam/src/serial_port.h
Code for PJSIM_PORT_HANDLER, the virtual serial port attached to IAS.

iam/src/sim_config.h
A "control" file which control the defines to be used when building the IAM module. Some defines can be removed to reduce IAS functionality, and possibly increase simulation speed. The default configuration has full functionality, except tracing, which is not required for correctness. Leave this file as is, unless you understand all the implications of the #defines.

iam/src/statistics.c iam/src/statistics.h
Code to implement various kinds of statistics objects.

iam/src/test.c
An old test program. No longer used.

iam/src/tracing.c iam/src/tracing.h
Code to implement the tracing functionality.

iam/src/traps.c iam/src/traps.h
Code for picoJava traps.

ldr/src/binit.h
Header file for the binary init feature of IAS.

ldr/src/bool.h
Defines boolean type. Rarely used.

ldr/src/classDump.c
Source for a standalone binary called classDump built from this directory.

ldr/src/cm.c ldr/src/cm.h
The lowest level of the memory. Allocates and owns the memory. Also provides read and write calls on the memory.

ldr/src/copy.c
Routines to copy over the loader data structures from IAS memory into the picoJava memory.

ldr/src/debug.h
Required by oobj.h

ldr/src/decaf.h
Definitive guide to the picoJava class data structures.

ldr/src/dis.c
Disassembly routine.

ldr/src/dump.c
Routines to print out various class data structures.

ldr/src/loader.c ldr/src/loader.h
The class loading functions.

ldr/src/loadtraps.c ldr/src/loadtraps.h
The trap handler loading function.

ldr/src/oobj.h ldr/src/oobj_md.h
Inherited from JDK source code.

ldr/src/opcodes.h
Enum type declarations for opcodes.

ldr/src/res.c ldr/src/res.h
Resolves method names.

ldr/src/rw.c
Verilog PLI routines.

ldr/src/signature.h
Signature characters for various types.

ldr/src/syscall.c ldr/src/syscall.h
Code for system call functionality in the IAS/RTL environment.

ldr/src/test_loader.c
A test program for the loader. Not actively used.

ldr/src/traptypes.h
Definitions of various trap types. Unfortunate duplication with iam/src/traps.h

ldr/src/tree.h
Definitions for class/method/field attributes.

ldr/src/typedefs.h ldr/src/typedefs_md.h
Type definitions.

ldr/src/veriuser.h ldr/src/vmacro.h
Verilog PLI stuff.

sim/src/ack.c
Function to send cosim acknowlegment to RTL.

sim/src/build_info.h
Stub file, to be updated before every build with revison or build information.

sim/src/cache.c
Tcl frontend cache commands.

sim/src/dis.c
Tcl frontend disassembly commands.

sim/src/dump.c
Tcl frontend dump commands.

sim/src/elf.c sim/src/exechdr.h
Tcl frontend elf loader.

sim/src/init.c
Function called at init to set up Tcl commands, link vars between Tcl and C.

sim/src/load.c
Tcl frontend loadclass command.

sim/src/memfile.c
Tcl frontend memfile and bmemfile commands.

sim/src/option.c
Tcl frontend random commands.

sim/src/run.c
Tcl frontend run commands.

sim/src/sim.h
General header file for this directory.

sim/src/sim.tcl
Tcl frontend interpreter. Also receives results from RTL and performs comparisons during cosim

sim/src/tclAppInit.c
Tcl function.

sim/src/trace.c
Tcl frontend itrace command.

sim/src/update-build-info
Script to update the build_info.h file automatically.