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);