readme.txt for VA/Java Tracing VM
---------------------------------

This file contains the following sections:

1. Description of Directory Contents
2. Installation
3. Tracing VM Overview
4. Description of Image Level API
5. Description of the User Support DLL API
   5a. General Event Description
   5b. Event Structure Description
6. The Support Library


1. Description of Directory Contents
------------------------------------

This directory contains the tracing version of the VA/Java environment.

For Windows and OS/2, this directory contains the following files:

   trace.txt           This file
   api.jar             The VM API to be imported into VA/Java
   ivjvm20.dll         The tracing Virtual Machine (VM) DLL
   ivjijs20.dll        The tracing VM support DLL
   trace.dll           Sample user tracing DLL

For Unix, this directory contains the following files:

   trace.txt           This file
   api.jar             The VM API to be imported into VA/Java
   ide                 The tracing Virtual Machine (VM)
   libivjijs20.so      The tracing VM support shared library
   libtrace.so         Sample user tracing shared library

This directory contains the following subdirectories:

   include             Support include files for building user tracing DLLs
   lib                 Support library files for building user tracing DLLs
   trace               Sample user tracing DLL source code

All references to "dynamic link library" and "DLL" should be assumed to mean
"shared library" for Unix systems, unless otherwise noted.  As well, when
references are made to a DLL of the name "foo.dll", the name should be changed
to meet Unix standards, e.g., "libfoo.so".


2. Installation
---------------

Before installing for Windows or OS/2, it is recommended that the file,

   ivjvm20.dll

be backed up, as the installation overwrites this file.  Since the tracing
VM runs slightly slower in non-tracing mode than the standard VM, development
is typically done with the latter.

For Unix, the file to back up is,

   ide.

To install, recursively copy the current directory up into the program
directory of the VA/Java environment.


3. Tracing VM Overview
----------------------

The tracing VM system consists of three parts; i) The tracing VM, ii) The
VM level API, iii) The user support DLL.

The tracing VM is an extended VM with hooks that call out to a user DLL when
particular events occur.  This is driven by the VM level API, which specifies
what DLL to call (the user DLL), and what events to report.

The image level API is a low level interface to the tracing VM, and provides
the necessary support for more elaborate statistics gathering applications.
The API allows the user to customize what events are reported to the user DLL
automatically by the VM, as well as the ability to manually trigger certain
events.

The user DLL acts as the event handler for the tracing VM.  It contains 
specific functions that are called by the VM when events occur.  The user
DLL allows the application programer to customize how events are monitored,
recorded, etc., by modifying the standard user DLL functions.


4. Description of Image Level API
---------------------------------

The image level API must be used in conjunction with a user tracing DLL 
(described in section 5).

There are two classes used to control the tracing VM,

   com.ibm.uvm.instrumenting.InstrumentVMSupport
   com.ibm.uvm.instrumenting.InstrumentVMException

All methods described are found in,

   com.ibm.uvm.instrumenting.InstrumentVMSupport, 

with any constants declared as "public static final".  The exception class is
used to report errors during any of the tracing calls.

Each of the first four calls have a corresponding function in the user support
DLL, and is derived by capitalizing the leading letter and prepending 
"Instrument". E.g.,

   (Java method) tracingStartup() -> (C function) InstrumentTracingStartup()

   1. tracingStartup(String libraryName);

   Opens the user tracing DLL to allow any necessary pre-tracing initialization
   to occur.  The DLL opened is specified in a platform independent way.  E.g.,
   if the DLL name "trace" is specified, this signifies the DLL "trace.dll" on
   Windows or OS/2, and "libtrace.so" on Unix platforms.  This call must be
   made before the VM can enter tracing mode.

   2. tracingShutdown();

   Closes the user tracing DLL opened by tracingStartup(String libraryName) to
   allow any necessary post-tracing management.

   3. tracingBegin(int flags);

   Turn tracing mode on with event reporting mode set to "flags".  The VM will
   begin reporting tracing events to the user DLL with the types and format of
   the events described by the following flags:

   (Note: In each case, exactly one flag from each group should be chosen.
   Flags should be |'d (binary OR'ed) together before being passed).

	  InsTrcTypeExeOn
	  InsTrcTypeExeOnLight
	  InsTrcTypeExeOff

	  The execution tracing type describes what is reported for method entry
	  and exit events.  "On" reports method entry and exits.  "OnLight" reports
	  method entry.  "Off" reports no method events.

	  InsTrcTypeGCOn
	  InsTrcTypeGCOnLight
	  InsTrcTypeGCOff

	  The GC tracing type describes what is reported for memory management
	  events.  "On" reports when scavenges and global garbage collects start
	  and end, as well as all object movements and deletions that occur.
	  "OnLight" reports when scavenges and global garbage collects start and
	  end.  "Off" reports no memory management events.
 
	  InsTrcTypeAllocOn
	  InsTrcTypeAllocOff

	  The allocation tracing type describes what is reported for object
	  allocation events.  "On" reports all object allocates.  "Off" reports no
	  allocation events.

   4. tracingEnd();

   Turn tracing mode off, but keeps the user DLL active.

   5. reportObjectReferences();

   Report each object ID currently in the image, and any non-null object
   pointer contained in each object.  This is a heavy weight operation, and is
   made from user code at critical places to determine object connection
   graphs.

   6. userEvent(String message);

   Report that a user specified event has occurred with the string "message".
   This call is made from user code to signal points of interest.


5. Description of the User Support DLL API
------------------------------------------

All constants mentioned in this section can be found in:
   .\include\itrccnst.h

All structures mentioned in this section can be found in:
   .\include\itrcstrt.h

A sample version of the user tracing DLL can be found in:
   .\trace\*.*

Each of the following should be exported from the user DLL when it is compiled
and linked.

   1. unsigned long InstrumentTraceStartup(unsigned long vmID)

   Called when tracingStartup(String) is called at the image level.
   Tracing mode is not yet active.

   2. unsigned long InstrumentTraceShutdown()

   Called when tracingShutdown() is called at the image level.
   Tracing mode is not active.

   3. unsigned long InstrumentTraceBegin(
		 unsigned long vmID,
		 unsigned long flags)

   Called when tracingBegin(int) is called at the image level.

   4. unsigned long InstrumentTraceEnd()

   Called when tracingEnd() is called at the image level.

   5. unsigned long InstrumentTraceEvent(struct InsEventInfo *event)

   For any event generated either implicitly (e.g., method entry) or through
   image API, InstrumentTraceEvent() is called.

   Both types of event structures begin with the InsEventHeader structure,
   which contains the event which occurred (listed under InsTrcEvent*), and
   the VM ID code, which is used in the support library (described in section
   6).

   Note that both types of events consist of a union of structures; the event
   code determines what structure describes the data allocated.

5a. General Event Description
-----------------------------

   Each event is described by an event code and its data.  Below are a
   description of the events provided by the tracing VM.

   InsTrcEventMethodEnter
   InsTrcEventMethodLeave

	  The enter/exit events describe invoking and returning from a particular
	  method.

   InsTrcEventScavengeStart
   InsTrcEventScavengeEnd
   InsTrcEventGGCStart
   InsTrcEventGGCEnd

	  The memory management start/stop events describe when the VM has entered
	  a garbage collection phase, and when it is a local garbage collect
	  (Scavenge) or global garbage collect (GGC).

   InsTrcEventOIDRename
   InsTrcEventOIDRangeRename

	  Report the renaming (movement) of an object from one ID to another, or
	  a range of objects from one to other.

   InsTrcEventOIDDelete
   InsTrcEventOIDRangeDelete

	  Report the deletion (collection) of an object ID, or the range of object
	  IDs.  These events occur only during a garbage collection phase.

   InsTrcEventAllocate

	  Report an object ID when the object is allocated.

   InsTrcEventStartFieldReport
   InsTrcEventFieldReport
   InsTrcEventEndFieldReport

	  These events are triggered by reportObjectFields(), and describe the
	  contents of every object in the image.  The start field describes the
	  object being reported, field report describes a non-nil object pointer
	  inside the object being described, and end field signifies the end of
	  field reporting for a particular object.

   InsTrcEventUserEvent

	  This event is triggered by userEvent(String), and contains the message
	  supplied by the user.

5b. Event Structure Description
-------------------------------

   Each structure has its corresponding event codes and members described.

   1. InsEventTypeMethod

   struct InsEventTypeMethod {
	  unsigned long methodEventFlags;
	  unsigned long stackDepth;
	  unsigned long receiver;
	  char *methodName;
	  unsigned long methodNameSize;
	  char *className;
	  unsigned long classNameSize;
   };

   Used by events:
	  InsTrcEventMethodEnter
	  InsTrcEventMethodLeave

   Members:
	  methodEventFlags - Describe method type and string format as follows:
		 InstrumentMethodEventMethodDB
			Method name string is wide character format
		 InstrumentMethodEventClassDB
			Class name string is wide character format
		 InstrumentMethodEventStatic
			Method is static
		 InstrumentMethodEventNative
			Method is native
		 InstrumentMethodEventSync
			Method is synchronized
	  stackDepth - Stack depth of the current method
	  receiver - The object ID of the receiver
	  methodName - Non-NULL terminated method name
	  methodNameSize - Length of the methodName
	  className - Non-NULL terminated class name
	  classNameSize - Length of className

	  Notes:
	   1) For statics, the receiver is the internal VM class object ID, and is
	   affected by object renaming events.

   2. InsEventTypeOIDRename

   struct InsEventTypeOIDRename {
	  unsigned long source;
	  unsigned long destination;
   };

   Used by event:
	  InsTrcEventOIDRename

   Members:
	  source - object ID to be renamed
	  destination - object ID that source is renamed to.

   3. InsEventTypeOIDRangeRename

   struct InsEventTypeOIDRangeRename {
	  unsigned long sourceStart;
	  unsigned long sourceEnd;
	  unsigned long destination;
   };

   Used by event:
	  InsTrcEventOIDRangeRename

   Members:
	  sourceStart - closed lower bound of object ID range to rename
	  sourceEnd - open upper bound of object ID range to rename
	  destination - starting object ID that the range is renamed to

   4. InsEventTypeOIDDelete

   struct InsEventTypeOIDDelete {
	  unsigned long oid;
   };

   Used by event:
	  InsTrcEventOIDDelete

   Members:
	  oid - object ID to delete

   5. InsEventTypeOIDRangeDelete

   struct InsEventTypeOIDRangeDelete {
	  unsigned long start;
	  unsigned long end;
   };

   Used by event:
	  InsTrcEventOIDRangeDelete

   Members:
	  start - closed lower bound of object ID range to delete
	  end - open upper bound of object ID range to delete

   6. InsEventTypeAllocate

   struct InsEventTypeAllocObj { /* Private */
	  unsigned long allocEventFlags;
	  char *className;
	  unsigned long classNameSize;
   };
   struct InsEventTypeAllocArrObj { /* Private */
	  char *className;
	  unsigned long classNameSize;
	  unsigned long arity;
   };
   struct InsEventTypeAllocate {
	  unsigned long oid;
	  unsigned long sizeInLongs;
	  unsigned long arrayFlag;
	  union {
		 struct InsEventTypeAllocObj object;
		 struct InsEventTypeAllocArrObj array;
		 } allocBody;
	  };

   Used by event:
	  InsTrcEventAllocate

   Members (struct InsEventTypeAllocate):
	  oid - object ID being allocated
	  sizeInLongs - the number of 32 bit words the object requires for storage
	  arrayFlag - Determine what union member is used for allocation
		 description as follows:
			0 - struct InsEventTypeAllocObj object;
			1 - struct InsEventTypeAllocArrObj array;

   Members (struct InsEventTypeAllocObj):
	  allocEventFlags - Describe allocate class name format as follows:
		 InstrumentAllocEventClassDB
			Class name string is wide character format
	  className - Non-NULL terminated class name
	  classNameSize - Length of className

   Members (struct InsEventTypeAllocArrObj):
	  className - Name of array type non-null terminated
	  classNameSize - Length of className
	  arity - array is N dimensional, where N > 1.

	  Notes: If the className is NULL, the arity field determines whether the
	  object is an array of objects (arity == 0) or an array of arrays
	  (arity == 1).  At allocation, the exact type of object used for the 
	  array is not detectable.

   7. InsEventTypeStartFieldReport

   struct InsEventTypeStartFieldReport {
	  unsigned long oid;
	  unsigned long type;
	  unsigned long reportEventFlags;
	  char *className;
	  unsigned long classNameSize;
   };

   Used by event:
	  InsTrcEventStartFieldReport

   Members:
	  oid - object ID being reported
	  type - The type of object being described as follows:
		 InstrumentFREventTypeJava
			oid is a Java object
		 InstrumentFREventTypeJavaArray
			oid is a Java Array (className[Size] is not valid)
		 InstrumentFREventTypeJavaClass
			oid is a Java Class
	  reportEventFlags - Describe report object class name format as follows:
		 InstrumentReportEventClassDB
			Class name string is wide character format
	  className - Non-NULL terminated class name of oid
	  classNameSize - Length of className

   8. InsEventTypeFieldReport

   struct InsEventTypeFieldReport {
	  unsigned long oid;
   };

   Used by event:
	  InsTrcEventFieldReport

   Members:
	  oid - object ID contained in the object being reported

   9. InsEventTypeUserEvent

   struct InsEventTypeUserEvent {
	  unsigned long msgEventFlags;
	  char *msg;
	  unsigned long msgSize;
   };

   Used by event:
	  InsTrcEventUserEvent

   Members:
	  msgEventFlags - Describe the msg member format as follows:
		 InstrumentUserEventDB
			message string is wide character format
	  msg - Non-NULL terminated message supplied by the user
	  msgLength - Length of msg


6. The Support Library
----------------------

The library .\lib\ivjitrcs.lib is a support library containing routines that
enhance the information provided by tracing events.  For each function,
"vmID" is found in the event header.  The return value is zero on success, 
non-zero on failure.

unsigned long InstrumentSupportCurrentThreadDetails(
	unsigned long vmID,
	unsigned long *flags,
	char **name,
	unsigned long *nameLength,
	long *priority,
	char **groupName,
	unsigned long *groupNameLength)

   Return the pointer to the thread name as well as its length, the thread
   priority, and the thread group name as well as its length.
   "flags" can be tagged as:
	  InstrumentThreadNameDB
		 "name" is in wide character mode.
	  InstrumentThreadGroupNameDB
		 "groupName" is in wide character mode.

   Notes:
   1) This routine is not to be called during memory management related
   events, i.e., between the start and end of scavenge or global garbage
   collect events.
   2) The thread with the name, priority and group name of "<ide>", -1 and
   "<ide>" should be treated as a special case internal VM thread.

