Home
PerfUtil Java API: PerfCounter class
OpenPerfCounterFacilityExclusive
//
// Opens the hardware performance counters facility provided by PerfUtil
// for exclusive control of the performance counters by the calling process.
//
// Input:
// - None.
//
// Returns:
// - 0: Success. Calling process has exclusive control of the
// performance counters.
// - non-zero: Error or performance counters already opened for
// exclusive access.
//
// Notes:
// - Access is exclusive only if using the PerfUtil counter access APIs.
// - Caller can use either the event or counter APIs.
// - No other process can change the performance counter controls, nor
// write to an MSR while the facility is being held exclusively. Reads to
// perf counters and MSRs *ARE* allowed by any process.
// - It is not necessary to open the performance counter facility in order
// to use it, and most of the time you do not want to use it exclusive.
//
static native int OpenPerfCounterFacilityExclusive();
ClosePerfCounterFacility
//
// Closes the hardware performance counters facility provided by PerfUtil
// and relinquish exclusive control of the performance counters.
//
// Input:
// - None.
//
// Returns:
// - 0: Success. Calling process no longer has exclusive control
// of the performance counters.
// - non-zero: Error(s).
//
// Notes:
// - Access is exclusive only if using the PerfUtil counter access APIs.
// - It is good practice to always close the facility after using it.
// Just in case, the facility is closed implicitly when the process
// that holds it exclusively terminates.
//
static native int ClosePerfCounterFacility();
GetNumberOfPerfCounterEventsSupported
//
// Returns the number of performance counter events supported.
//
// Input:
// - None.
//
// Returns:
// - 0: Error or no performance counter events supported.
// - non-zero: Number of performance counter events supported.
//
// Notes:
// - The number of performance counter events supported is only valid
// on the current system and on the current configuration.
// - The returned value (if non-zero) should be used to allocate the
// arrays passed to GetPerfCounterEventIdList() and GetPerfCounterEventNameList().
//
static native int GetNumberOfPerfCounterEventsSupported();
GetNumberOfSimultaneousPerfCounterEventsSupported
//
// Returns the number of performance counter events that can be counted
// simultaneously.
//
// Input:
// - None.
//
// Returns:
// - 0: Error or no performance counter events supported.
// - non-zero: Number of performance counter events that can be counted together.
//
static native int GetNumberOfSimultaneousPerfCounterEventsSupported();
IsPerfCounterEventSupported
//
// Returns whether or not the given performance counter event id or name
// is supported on this system.
//
// Input:
// - event_id: Event id of desired event.
// - event_name: Event name of desired event.
//
// Returns:
// - true: Performance counter event is supported.
// - false: Performance counter event is not supported.
//
static native boolean IsPerfCounterEventSupported(int event_id);
static native boolean IsPerfCounterEventSupported(String event_name);
IsPerfCounterEventActive
//
// Returns whether or not the given performance counter event id or name
// is active (currently being counted).
//
// Input:
// - event_id: Event id of desired event.
// - event_name: Event name of desired event.
//
// Returns:
// - true: Performance counter event is active.
// - false: Performance counter event is not active.
//
static native boolean IsPerfCounterEventActive(int event_id);
static native boolean IsPerfCounterEventActive(String event_name);
AnyPerfCounterEventActive
//
// Returns whether or not *ANY* performance counter event id or name is
// is active (currently being counted).
//
// Returns:
// - true: At least one performance counter event is active.
// - false: No performance counter event is active.
//
static native boolean AnyPerfCounterEventActive();
GetPerfCounterEventList
//
// Returns a list of supported performance counter event ids or event names.
//
// Input:
// - id_list: Array which will contain event id list.
// - name_list: Array which will contain event name list.
// - Dimension should be at least the value returned
// by GetNumberOfPerfCounterEventsSupported().
// Sets:
// - id_list[] and/or name_list[]
//
// Returns:
// - 0: Error.
// - No supported performance counter events.
// - id_list[]/name_list[] array dimension too small.
// - non-zero: Number of elements set in id_list[] or name_list[] array.
//
static native int GetPerfCounterEventList(int[] id_list);
static native int GetPerfCounterEventList(String[] name_list);
GetPerfCounterEventInfo
//
// Returns information about given performance counter event.
//
// Input:
// - event_id: Event id of event whose information is needed.
// - event_name: Event name of event whose information is needed.
//
// Returns:
// - 0: Success. Instance of PerfCounterEventInfo class
// containing performance counter event information.
// - non-zero: Error getting event information.
//
static native int GetPerfCounterEventInfo(int event_id, PerfCounterEventInfo event_info);
static native int GetPerfCounterEventInfo(String event_name, PerfCounterEventInfo event_info);
InitEventCounter
//
// Starts counting a specific event.
//
// Input:
// - event: Event id of event to be started
// - priv_level: Privilege level at which event will be counted
//
// Returns:
// - 0: success
// - non-zero: error starting event
//
// Notes:
// - Valid event ids and privilege levels are listed under "Performance Counter
// Events" in JPerfBase.java.
// - Starting an event will reset any previously started events.
// - Fails if required resources are busy.
// - There is no guarantee that the event will be started in all
// processors at the same time.
//
static native int InitEventCounter(int event, int priv_level);
TerminateEventCounter
//
// Stops counting a specific event and releases all resources associated with it.
//
// Input:
// - event: Event id of event to be terminated
// If ALL_EVENTS then all current events are terminated
//
// Returns:
// - 0: success
// - non-zero: error terminating event
//
// Notes:
// - Valid event ids are listed under "Performance Counter Events"
// in JPerfBase.java.
// - Fails if requested events are not currently initialized.
// - There is no guarantee that the event will be terminated in all
// processors at the same time.
//
static native int TerminateEventCounter(int event);
StopEventCounter
//
// Stops counting a specific event.
//
// Input:
// - event: Event id of event to be stopped
//
// Returns:
// - 0: success
// - non-zero: error stopping event
//
// Notes:
// - Stopping the event merely stops it from counting. The current
// value of the counter is not reset. The event is still initialized
// and can resume counting by invoking the ResumeEventCounter() method.
// - There is no guarantee that the event will be stopped in all
// processors at the same time.
//
static native int StopEventCounter(int event);
ResumeEventCounter
//
// Resumes counting a specific event.
//
// Input:
// - event: Event id of event to be resumed
//
// Returns:
// - 0: success
// - non-zero: error resuming event
//
// Notes:
// - Resuming the event continues counting from the current value.
// This method is usually invoked sometime after invoking the
// StopEventCounter() method.
// - There is no guarantee that the event will be resumed in all
// processors at the same time.
//
static native int ResumeEventCounter(int event);
ResetEventCounter
//
// Resets counter associated with specified event.
//
// Input:
// - event: Event id of event to be reset
//
// Returns:
// - 0: success
// - non-zero: error resetting event
//
// Notes:
// - Resetting the event merely resets the value of the counter. The event
// continues counting.
// - There is no guarantee that the event will be reset in all
// processors at the same time.
//
static native int ResetEventCounter(int event);
GetEventCounter
//
// Get (read) counter values associated with specified event.
//
// Input:
// - event: Event id of event whose value are to be read
// - evt_ctrs: Array that will contain the value of the event
// counters, one counter per processor.
// - evt_cycles: Array that will contain the value of the Time Stamp
// Counter (TSC) at the time the counter was read, one
// per processor.
// Sets:
// - evt_ctrs[]
// - evt_cycles[]
//
// Returns:
// - 0: success
// - non-zero: error getting event counters
//
// Notes:
// - There is no guarantee that the events will be read
// from all processors at the same time.
// - evt_ctrs[] and evt_cycles[] are indexed by CPU number.
// Element i contains the value of the requested counter for
// the ith processor.
// - The largest valid index for evt_ctrs[] and evt_cycles[] is (CpuCnt - 1).
//
static native int GetEventCounter(int event, long[] evt_ctrs, long[] evt_cycles);
GetNumberOfPerfCounters
//
// Returns the number of performance counters supported.
//
// Input:
// - None.
//
// Returns:
// - 0: Error or no performance counters supported.
// - non-zero: Number of performance counters supported on this system.
//
// Notes:
// - The number of performance counters supported is only valid on the current
// system and on the current configuration.
//
static native int GetNumberOfPerfCounters();
GetMaxPerfCounterNumber
//
// Returns the number of highest numbered performance counter supported.
//
// Input:
// - None.
//
// Returns:
// - 0: Error or no performance counters supported.
// - non-zero: Highest valid performance counter number supported on this system.
//
// Notes:
// - The number of performance counters supported is only valid on the current
// system.
//
static native int GetMaxPerfCounterNumber();
IsPerfCounterSupported
//
// Returns whether or not the given performance counter number or name
// is supported on this system.
//
// Input:
// - number: Counter number.
// - name: Counter name.
//
// Returns:
// - true: Performance counter is supported.
// - false: Performance counter is not supported.
//
static native boolean IsPerfCounterSupported(int number);
static native boolean IsPerfCounterSupported(String name);
IsPerfCounterMsrValid
//
// Returns whether or not the given performance counter MSR is valid.
//
// Input:
// - number: Counter number.
// - name: Counter name.
//
// Returns:
// - true: Performance counter MSR is valid.
// - false: Performance counter MSR is not valid.
//
// Notes:
// - Even though a performance counter MSR may be valid, it is considered
// invalid if the associated performance counter is not supported on
// this system.
//
static native boolean IsPerfCounterMsrValid(int msr);
GetPerfCounterList
//
// Returns a list of supported performance counter ids (numbers) or names.
//
// Input:
// - num_list: Array which will contain counter numbers list.
// - name_list: Array which will contain counter names list.
// - Dimension should be at least the value returned
// by GetNumberOfPerfCounters().
// Sets:
// - num_list and/or name_list[]
//
// Returns:
// - 0: Error.
// - No supported performance counter events.
// - num_list[]/name_list[] array dimension too small.
// - non-zero: Number of elements set in num_list[] or name_list[] array.
//
static native int GetPerfCounterList(int[] number_list);
static native int GetPerfCounterList(String[] name_list);
GetPerfCounterNumberFromName
//
// Returns a performance counter number given a performance counter name.
//
// Input:
// - name: Performance counter name.
//
// Returns:
// - CTR_INVALID_ID: Invalid name.
// - other: Performance counter number.
//
static native int GetPerfCounterNumberFromName(String name);
GetPerfCounterNameFromNumber
//
// Returns a performance counter name given a performance counter number.
//
// Input:
// - number: Performance counter number.
//
// Returns:
// - null: Invalid number.
// - other: Performance counter name.
//
static native String GetPerfCounterNameFromNumber(int number);
GetPerfCounterMsr
//
// Returns the MSR number associated with a performance counter number or name.
//
// Input:
// - number: Performance counter number.
// - name: Performance counter name.
//
// Returns:
// - CTR_INVALID_ID: Invalid counter number/name.
// - other: Performance counter MSR.
//
static native int GetPerfCounterMsr(int number);
static native int GetPerfCounterMsr(String name);
StartP4Counter
//
// Set and start counting on the given counter in given processor(s).
// Initializes counter to 'value' and starts it.
//
// ***** Pentium 4 ONLY *****
//
// Input:
// - cpu: Processor on which counters should be started or:
// - ALL_CPUS
// - LP0_CPUS (If HTT enabled)
// - LP1_CPUS (If HTT enabled)
// - value: Value to which counters should be initialized
// - ctr_num: Counter number (0 - 17)
// - CCCRValue: Value to set up CCCR
// - ESCRAddr: ESCR MSR address (0x3A0 - 0x3EF)
// - ESCRValue: Value to set up ESCR
// - XMSRAddr: Other required MSR address or zero
// - XMSRValue: Value to set up other MSR or zero
//
// Returns:
// - 0: success
// - non-zero: error starting counter
//
// Notes:
// - If starting the counter in more than one processor, the start *WILL NOT*
// be atomic: there is no guarantee that the counter will be started in all
// processors at the same time.
// - CCCRValue, ESCRAddr and ESCRValue are required.
// - XMSRAddr and XMSRValue are optional and should be 0 if not used.
// - Can only start one counter at a time, so must be invoked once
// per counter to be started.
// - To start on all processors specify cpu as ALL_CPUS
//
static native int StartP4Counter(int cpu, int value,
int ctr_num, int CCCRValue,
int ESCRAddr, int ESCRValue,
int XMSRAddr, int XMSRValue);
StartP6Counter
//
// Set and start counting on the given counter in given processor(s).
// Initializes counter to 'value' and starts it.
//
// ***** P6 (Pentium Pro/II/III/Celeron) ONLY *****
//
// Input:
// - cpu: Processor on which counters should be started, or ALL_CPUS
// - value: Value to which counters should be initialized
// - PerfEvtSel0: Value of PerfEvtSel0 register
// - PerfEvtSel1: Value of PerfEvtSel1 register
//
// Returns:
// - 0: success
// - non-zero: error starting counter
//
// Notes:
// - If starting the counter in more than one processor, the start *WILL NOT*
// be atomic: there is no guarantee that the counter will be started in all
// processors at the same time.
// - Both counters are started at the same time.
// - To start on all processors specify cpu as ALL_CPUS
//
static native int StartP6Counter(int cpu, int value,
int PerfEvtSel0,
int PerfEvtSel1);
StartAmdCounter
//
// Set and start counting on the given counter in given processor(s).
// Initializes counter to 'value' and starts it.
//
// ***** AMD (Opteron/Athlon/Phenom) ONLY *****
//
// Input:
// - cpu: Processor on which counters should be started, or ALL_CPUS
// - value: Value to which counters should be initialized
// - ctr_num: Counter number (0 - 3)
// - PerfEvtSel: Value of PerfEvtSel register controlling counter
//
// Returns:
// - 0: success
// - non-zero: error starting counter
//
// Notes:
// - If starting the counter in more than one processor, the start *WILL NOT*
// be atomic: there is no guarantee that the counter will be started in all
// processors at the same time.
// - To start on all processors specify cpu as ALL_CPUS
//
static native int StartAmdCounter(int cpu, int value,
int ctr_num,
int PerfEvtSel);
StopCounter
//
// Stop counting on given counter in given processors(s).
//
// Input:
// - cpu: Processor on which counters should be started or:
// - ALL_CPUS
// - LP0_CPUS (If HTT enabled)
// - LP1_CPUS (If HTT enabled)
// - ctr: Number of counter to stop, or ALL_COUNTERS
//
// Returns:
// - 0: success
// - non-zero: error stopping counter
//
// Notes:
// - If stopping the counter in more than one processor, the stop *WILL NOT*
// be atomic: there is no guarantee that the counter will be stopped in all
// processors at the same time.
// - To stop counters on all processors specify cpu as ALL_CPUS
// - To stop all counters specify ctr as ALL_COUNTERS
//
static native int StopCounter(int cpu, int ctr);
ResumeCounter
//
// Resumes counter in given processors(s).
//
// Input:
// - cpu: Processor on which counters should be started or:
// - ALL_CPUS
// - LP0_CPUS (If HTT enabled)
// - LP1_CPUS (If HTT enabled)
// - ctr: Number of counter to resume, or ALL_COUNTERS
//
// Returns:
// - 0: success
// - non-zero: error resuming counter
//
// Notes:
// - If resuming the counter in more than one processor, the resume *WILL NOT*
// be atomic: there is no guarantee that the counter will be resumed in all
// processors at the same time.
// - To resume counters on all processors specify cpu as ALL_CPUS
// - To resume all counters specify ctr as ALL_COUNTERS
//
static native int ResumeCounter(int cpu, int ctr);
SetCounter
//
// Sets counter to 'value' in given processors(s).
//
// Input:
// - cpu: Processor on which counters should be started or:
// - ALL_CPUS
// - LP0_CPUS (If HTT enabled)
// - LP1_CPUS (If HTT enabled)
// - ctr: Number of counter to set, or ALL_COUNTERS
// - value: Value to which the counter should be set
//
// Returns:
// - 0: success
// - non-zero: error resetting counter
//
// Notes:
// - If setting the counter in more than one processor, the set *WILL NOT*
// be atomic: there is no guarantee that the counter will be set in all
// processors at the same time.
// - To set counters on all processors specify cpu as ALL_CPUS
// - To set all counters specify ctr as ALL_COUNTERS
// - To reset counters specify value = 0
//
static native int SetCounter(int cpu, int ctr, long value);
GetCounter
//
// Returns the current value of the given counter from given processors(s).
//
// Input:
// - cpu: Processor on which counters should be started or:
// - ALL_CPUS
// - LP0_CPUS (If HTT enabled)
// - LP1_CPUS (If HTT enabled)
// - ctr: Number of counter to read
//
// Sets:
// - raw_ctrs[]
// - raw_cycles[]
//
// Returns:
// - 0: success
// - non-zero: error getting counter
//
// Notes:
// - If getting counter values from more than one processor, the values *WILL NOT*
// be obtained atomically: there is no guarantee that the counter will be read
// from all processors at the same time.
// - To read counter on all processors specify cpu as ALL_CPUS
// - ctr *MUST* be a valid counter number. It *CANNOT* be ALL_COUNTERS
// - raw_ctrs[] and raw_cycles[] are indexed by CPU number.
// Element i contains the value of the requested counter for
// the ith processor.
// - The largest valid index for raw_ctrs[] and raw_cycles[] is (CpuCnt - 1).
//
static native int GetCounter(int cpu, int ctr, long[] raw_ctrs, long[] raw_cycles);