SourceForge.net Logo
Home

PerfUtil Java API: Trace class




SwtraceInit

     //
     // Initializes the Software Tracing (SWTRACE) Facility.
     //
     // Input:
     // - size:    Per-processor trace buffer size, in bytes.
     //            Set to 3MB per processor if value is invalid or zero.
     //
     // Returns:
     // - 0:        Success - trace facility initialized
     // - non-zero: Error.
     //
     // Notes:
     // - Init() allocates trace buffers and initializes the trace facility
     //   so it's ready to begin tracing.
     //
     static native int SwtraceInit(int size);




SwtraceTerminate

     //
     // Terminate the Software Tracing (SWTRACE) Facility.
     //
     // Returns:
     // - 0:        Success - trace facility terminated and no longer usable
     // - non-zero: Error.
     //
     // Notes:
     // - Terminate() deallocates trace buffers and resets the trace facility.
     //   You must re initialized the facility in order to use it again.
     //
     static native int SwtraceTerminate();




SwtraceDiscard

     //
     // Discard contents of tracing buffer and continue tracing.
     //
     // Returns:
     // - 0:        Success - trace facility reset
     // - non-zero: Error.
     //
     // Notes:
     // - Discard() discards the contents of the trace buffers and
     //   continues tracing. The state of the trace facility is not changed.
     //
     static native int SwtraceDiscard();




SwtraceEnable

     //
     // Enables major event codes to be traced.
     //
     // Input:
     // - major:    Major code to enable.
     //             Specify ALL_MAJORS to enable all major codes.
     //
     // Returns:
     // - 0:        Success - selected major code enabled
     // - non-zero: Error.
     //
     // Notes:
     // - Major codes are in the range 2 thru 255.  All others are invalid.
     // - Enable() must be called once per major code to be enabled.
     //
     static native int SwtraceEnable(int major);




SwtraceDisable

     //
     // Disables major event codes to be traced.
     //
     // Input:
     // - major:    Major code to disable
     //             Specify ALL_MAJORS to disable all major codes.
     //
     // Returns:
     // - 0:        Success - selected major code disabled
     // - non-zero: Error.
     //
     // Notes:
     // - Major codes are in the range 2 thru 255.  All others are invalid.
     // - Disable() must be called once per major code to be disabled.
     //
     static native int SwtraceDisable(int major);




SwtraceOn

     //
     // Turns Software Tracing (SWTRACE) Facility on.
     //
     // Returns:
     // - 0:        Success - tracing started
     // - non-zero: Error.
     //
     // Notes:
     // - Tracing will be started if trace is currently off.
     //
     static native int SwtraceOn();




SwtraceOff

     //
     // Turns Software Tracing (SWTRACE) Facility off.
     //
     // Returns:
     // - 0:        Success - tracing stopped
     // - non-zero: Error.
     //
     // Notes:
     // - Tracing will be stopped if trace is currently on.
     //
     static native int SwtraceOff();




SwtraceSuspend

     //
     // Suspend Software Tracing (SWTRACE) facility.
     //
     // Returns:
     // - 0:        Success - tracing suspended
     // - non-zero: Error.
     //
     // Notes:
     // - Tracing needs to be on.
     // - Suspend means to stop writing trace hooks into the trace
     //   buffers, assuming any trace major codes are enabled and
     //   tracing is on.
     //
     static native int SwtraceSuspend();




SwtraceResume

     //
     // Resume Software Tracing (SWTRACE) facility.
     //
     // Returns:
     // - 0:        Success - tracing resumed
     // - non-zero: Error.
     //
     // Notes:
     // - Tracing needs to be on.
     // - Resume means to start writing trace hooks into the trace
     //   buffers, assuming any trace major codes are enabled and
     //   tracing is on.
     //
     static native int SwtraceResume();




IsSwtraceOn

     //
     // Returns whether or not tracing is currently on.
     //
     // Returns:
     // - TRUE:  Tracing is on
     // - FALSE: Tracing is off
     //
     static native boolean IsSwtraceOn();




IsSwtraceActive

     //
     // Returns whether or not tracing is currently active (not paused).
     //
     // Returns:
     // - TRUE:  Tracing is active (not paused).
     // - FALSE: Tracing is not active (it is paused or off).
     //
     static native boolean IsSwtraceActive();




SwtraceQueryMajor

     //
     // Query whether or not a major code is enabled.
     //
     // Input:
     // - major:  Major code to check
     //
     // Returns:
     // - MAJOR_NOT_ENABLED:  Given major code is disabled or invalid
     // - MAJOR_ENABLED_NOMM: Given major code enabled, no multi-metric (i.e., cycles only)
     // - MAJOR_ENABLED_MM:   Given major code enabled, multi-metric
     //
     // Notes:
     // - Tracing will be stopped if trace is currently on.
     //
     static native int SwtraceQueryMajor(int major);




SwtraceSetProfilerRate

     //
     // Sets the TPROF tick rate.
     //
     // Input:
     // - rate:   TPROF tick rate (in ticks per second)
     //
     // Returns:
     // - 0:        TPROF tick rate set
     // - non-zero: Error.
     //
     static native int SwtraceSetProfilerRate(int rate);




SwtraceWriteBufferToFile

     //
     // Get copy of SWTRACE buffer and write to disk.
     //
     // Returns:
     // - 0:        Success - trace buffer written to given file.
     // - non-zero: Error.
     //
     // Notes:
     // - Trace data is written to file "swtrace.nrm2" in the
     //   current directory.
     //
     static native int SwtraceWriteBufferToFile();




SwtraceTraceHookInt

     //
     // Writes a trace hook with a 32-bit user-supplied 'value'.
     //
     // Input:
     // - major:  User supplied major code
     // - minor:  User supplied minor code
     // - value:  User supplied value written
     //
     // Returns:
     // - 0:        Success - trace hook written
     // - non-zero: Error.
     //
     // Notes:
     // - The hook is written only if the designated major code is enabled.
     //
     static native int SwtraceTraceHookInt(int major, int minor, int value);




SwtraceTraceHookBuf

     //
     // Writes a trace hook with a variable length user-supplied buffer.
     //
     // Input:
     // - major:  User supplied major code
     // - minor:  User supplied minor code
     // - len:    Length of (number of elements in) buffer
     // - buffer: User buffer (array of bytes)
     //
     // Returns:
     // - 0:        Success - trace hook written
     // - non-zero: Error.
     //
     // Notes:
     // - The hook is written only if the designated major code is enabled.
     //
     static native int SwtraceTraceHookBuf(int major, int minor, int len, byte[] buffer);




ItraceInit

     //
     // Initializes the Instruction Tracing (ITRACE) Facility.
     //
     // Returns:
     // - 0:        Success - instruction trace facility initialized
     // - non-zero: Error.
     //
     // Notes:
     // - ItraceInit() installs required support for instruction tracing.
     // - Caller must allocate a trace buffer via SwtraceInit() method prior
     //   to invoking ItraceInit().
     //
     static native int ItraceInit();




ItraceTerminate

     //
     // Terminate the Instruction Tracing (ITRACE) Facility.
     //
     // Returns:
     // - 0:        Success - trace facility terminated and no longer usable
     // - non-zero: Error.
     //
     // Notes:
     // - ItraceTerminate() removes support for instruction tracing.
     //   You must re-initialized the facility in order to use it again.
     // - Caller must deallocate the trace buffer via SwtraceTerminate() method.
     //
     static native int ItraceTerminate();




ItraceEnableAll

     //
     // Enables tracing for *ALL* processes.
     //
     // Returns:
     // - 0:        Success - tracing for all PIDs enabled
     // - non-zero: Error.
     //
     // Notes:
     // - Tracing does not start until you issue ItraceOn(). At that time
     //   tracing will begin for all PIDs that have been enabled.
     // - You should enable all the required PIDs before turning on ITrace.
     // - You should not invoke any ItraceEnable*() method once you are tracing.
     //
     static native int ItraceEnableAll();




ItraceEnableCurrent

     //
     // Enables tracing for the *CURRENT* process only.
     //
     // Returns:
     // - 0:        Success - tracing for the current PID enabled
     // - non-zero: Error.
     //
     // Notes:
     // - Tracing does not start until you issue ItraceOn(). At that time
     //   tracing will begin for all PIDs that have been enabled.
     // - You should enable all the required PIDs before turning on ITrace.
     // - You should not invoke any ItraceEnable*() method once you are tracing.
     //
     static native int ItraceEnableCurrent(); 




ItraceEnablePid

     //
     // Enables tracing for the *SELECTED* process only.
     //
     // Input:
     // - pid       Process ID of process for which tracing will be enabled
     //
     // Returns:
     // - 0:        Success - tracing for selected PID enabled
     // - non-zero: Error.
     //
     // Notes:
     // - You can invoke the method as many times as needed. Alternatively, you
     //   can use the ItraceEnableList() method.
     // - Tracing does not start until you issue ItraceOn(). At that time
     //   tracing will begin for all PIDs that have been enabled.
     // - You should enable all the required PIDs before turning on ITrace.
     // - You should not invoke any ItraceEnable*() method once you are tracing.
     //
     static native int ItraceEnablePid(int pid);




ItraceEnableGreater

     //
     // Enables tracing for processes whose PID is numerically equal to or greater
     // than the *GIVEN* starting PID.
     //
     // Input:
     // - startpid  PID marking the beginning of the range of PIDs to
     //             be enabled. Only PIDs numerically equal to or greater than
     //             startpid will be enabled.
     // Returns:
     // - 0:        Success - tracing for selected PID enabled
     // - non-zero: Error.
     //
     // Notes:
     // - Tracing does not start until you issue ItraceOn(). At that time
     //   tracing will begin for all PIDs that have been enabled.
     // - You should enable all the required PIDs before turning on ITrace.
     // - You should not invoke any ItraceEnable*() method once you are tracing.
     //
     static native int ItraceEnableGreater(int startpid);




ItraceEnableRange

     //
     // Enables tracing for processes whose PID is numerically greater than
     // or equal the starting PID and less than or equal to the ending PID.
     //
     // Input:
     // - startpid  PID marking the beginning of the range of PIDs to be enabled.
     // - endpid    PID marking the end of the range of PIDs to be enabled.
     //
     // Returns:
     // - 0:        Success - tracing for selected PID enabled
     // - non-zero: Error.
     //
     // Notes:
     // - Tracing does not start until you issue ItraceOn(). At that time
     //   tracing will begin for all PIDs that have been enabled.
     // - You should enable all the required PIDs before turning on ITrace.
     // - You should not invoke any ItraceEnable*() method once you are tracing.
     //
     static native int ItraceEnableRange(int startpid, int endpid);




ItraceEnableList

     //
     // Enables tracing for the selected *LIST* of processes.
     //
     // Input:
     // - pidlist:  Array of PIDs for which tracing will be enabled.
     // - pidcnt:   Number of elements in pidlist array.
     //
     // Returns:
     // - 0:        Success - tracing for selected PID enabled
     // - non-zero: Error.
     //
     // Notes:
     // - Tracing does not start until you issue ItraceOn(). At that time
     //   tracing will begin for all PIDs that have been enabled.
     // - You should enable all the required PIDs before turning on ITrace.
     // - You should not invoke any ItraceEnable*() method once you are tracing.
     //
     static native int ItraceEnableList(int[] pidlist, int pidcnt);




ItraceDisable

     //
     // Disables tracing all enabled processes.
     //
     // - 0:        Success - tracing disabled
     // - non-zero: Error.
     //
     // Notes:
     // - Tracing for all enabled PIDs is disabled.
     // - Typically there is no need to invoke ItraceDisable(). When done
     //   tracing you should just invoke ItraceOff().
     //
     static native int ItraceDisable();




ItraceOn

     //
     // Turns Instruction Tracing (ITrace) Facility on.
     //
     // Returns:
     // - 0:        Success - already tracing
     // - non-zero: Error.
     //
     // Notes:
     // - Tracing is started for all PIDs currently enabled (if any).
     // - You must invoke one of the ItraceEnableXxxx() methods to indicate
     //   which PIDs are to be traced.
     //
     static native int ItraceOn();




ItraceOff

     //
     // Turns Instruction Tracing (ITrace) Facility off.
     //
     // Returns:
     // - 0:        Success - tracing stopped
     // - non-zero: Error.
     //
     // Notes:
     // - Tracing will be stopped.
     // - You can invoke ItraceOn() to continue tracing.
     //
     static native int ItraceOff();




ItraceSetSkipCount

     //
     // Sets number of Timer interrupts to skip while tracing.
     //
     // Input:
     // - skipcount: Number of timer ticks to skip before allowing one to
     //              be processed normally.
     //
     // Returns:
     // - 0:        Success - trace hook written
     // - non-zero: Error.
     //
     // Notes:
     // - "skipcount" is the number of timer interrupts that will be handled
     //   by ITRACE before allowing one to be handled by the OS.
     // - The default is 50 (the OS handles every 50th timer tick). You should
     //   not need to change this.
     //
     static native int ItraceSetSkipCount(int skipcount);