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 "", -1 and "" should be treated as a special case internal VM thread.