Cpi

     //
     // Constructs Cpi object
     //
     // - Initializes public data members
     // - Create CPI measurement instance
     //
     public Cpi();

Cpi Public Data Members

     //
     // Data members set by:
     // - get()
     // - getAndStart()
     // - getAndTrace()
     // - getTraceAndStart()
     //
     long[]  cpu_instr;           // [MEASURED] Intructions executed by processor
     long[]  cpu_cycles;          // [MEASURED] Elapsed cycles by processor
     long[]  cpu_cycles_scaled;   // [CALCULATED] Scaled (to busy) cycles by processor
     long[]  cpu_busy_cycles;     // [MEASURED] AI busy counter by processor
     long[]  cpu_elapsed_cycles;  // [MEASURED] AI elapsed time by processor
     float[] cpu_busy_pc;         // [CALCULATED] %time each processor is busy
     float[] cpu_cpi;             // [CALCULATED] Raw CPI by processor
     float[] cpu_cpi_scaled;      // [CALCULATED] Raw CPI by processor scaled to while busy

     long    sys_instr;           // [CALCULATED] Sum of intructions executed by all processors
     long    sys_cycles;          // [CALCULATED] Sum of elapsed cycles on all processor
     long    sys_cycles_scaled;   // [CALCULATED] Sum of scaled cycles on all processor
     float   sys_busy_pc;         // [CALCULATED] %time system is busy
     float   sys_cpi;             // [CALCULATED] Raw system CPI
     float   sys_cpi_scaled;      // [CALCULATED] Raw system CPI scaled to while busy

     long    thread_instr;        // [MEASURED] Instructions executed on current thread
     long    thread_cycles;       // [MEASURED] Cycles on current thread
     float   thread_cpi;          // Thread CPI (scaled by default)

     long    elapsed_cycles;      // Elapsed interval cycles

     int     num_cpus;            // Number of CPUs
     int     tid;                 // Thread Id of thread doing init/start

init()

     //
     // Initialize CPI Measurement facility to measure:
     // - Raw CPI
     // - Scaled (while busy) CPI
     // - On-thread CPI
     //
     // Returns:
     // - 0:        Success
     // - non-zero: Error initializing. CPI Measurement facility not usable.
     //             * PU_ERROR_INVALID_PARAMETER:
     //               - Invalid mode
     //             * PU_ERROR_DRIVER_NOT_LOADED:
     //               - PERFDD device driver not loaded
     //             * PU_ERROR_ACCESS_DENIED:
     //               - ITrace active or not fully removed
     //             * PU_ERROR_NOT_SUPPORTED:
     //               - Performance counter event INSTR not supported
     //             * PU_ERROR_NOT_ENOUGH_MEMORY:
     //               - Unable to allocate CPI internal structures
     //             * PU_ERROR_INCONSISTENT_PTT_STATE:
     //               - PTT facility in an inconsistent state
     //             * Other:
     //               - Errors starting INSTR performance counter event
     //               - Errors starting AI
     //               - Errors starting PTT
     //
     // Notes:
     // - Enables measuring Raw, Scaled and Onthread CPI.
     // - init() implies the beginning of a CPI measurement interval.
     // - Initialized in the default mode, you must invoke the get*()
     //   method that best suits your needs:
     //   * get()
     //   * getAndTrace()
     //   * getAndTraceDetailed()
     //   * getAndTraceDetailed()
     //   * getAndTraceSummary()
     //   * getAndTraceSummary()
     // - You should always invoke init() and terminate() as a pair.
     //
     native int init();

init(int)

     //
     // Initialize CPI Measurement facility to measure requested modes.
     //
     // Input:
     // - mode:     Desired measurement types. Valid values (can be ORed):
     //             * JPerf.CPI_TYPE_RAW
     //               - Enable raw CPI measurements.
     //               - Always enabled. Does not need to be specified.
     //             * JPerf.CPI_TYPE_SCALED
     //               - Enable AI so scaled CPI can be measured.
     //             * JPerf.CPI_TYPE_ONTHREAD
     //               - Enable PTT so on-thread CPI can be measured.
     //             * JPerf.CPI_TYPE_TRACE_ON_GET:
     //               - Causes measurement interval data to be written
     //                 to the trace buffer after any get().
     //             * JPerf.CPI_TYPE_TRACE_ONLY_ON_GET:
     //               - Causes measurement interval data to *ONLY* be written
     //                 to the trace buffer after any get(). No Cpi object
     //                 instance variables are set.
     //             * JPerf.CPI_TYPE_TRACE_SUMMARY:
     //               - If either JPerf.CPI_TYPE_TRACE_ON_GET or
     //                 JPerf.CPI_TYPE_TRACE_ONLY_ON_GET are set, causes minimal
     //                 amount of data to be written to the trace buffer after
     //                 any get().
     //             * JPerf.CPI_TYPE_TRACE_DETAILED:
     //               - If either JPerf.CPI_TYPE_TRACE_ON_GET or
     //                 JPerf.CPI_TYPE_TRACE_ONLY_ON_GET are set, causes all
     //                 Cpi object public instance variables to be written to the
     //                 trace buffer after any get().
     //
     // Returns:
     // - See init() above.
     //
     // Notes:
     // - Enables measuring the requested mode(s).
     // - init() implies the beginning of a CPI measurement interval.
     // - JPerf.CPI_TYPE_TRACE_ON_GET/.CPI_TYPE_TRACE_ONLY_ON_GET only affect
     //   the get() method.
     // - If you intend to do your own get*() method invocations then you
     //   *SHOULD NOT* set any of the *_ON_GET modes.
     // - If you always want a specific trace action on get() then you *SHOULD*
     //   specify the appropriate *_ON_GET mode(s) and only invoke the get() method.
     // - If either JPerf.CPI_TYPE_TRACE_ON_GET or JPerf.CPI_TYPE_TRACE_ONLY_ON_GET
     //   is specified and neither JPerf.CPI_TYPE_TRACE_SUMMARY nor
     //   JPerf.CPI_TYPE_TRACE_DETAILED is specified then the default becomes
     //   JPerf.CPI_TYPE_TRACE_SUMMARY.
     // - You should always invoke init() and terminate() as a pair.
     //
     public native int init(int mode);

terminate

     //
     // Terminate CPI Measurement facility
     //
     // Returns:
     // - 0:        Success
     // - non-zero: Error terminating. CPI Measurement facility state unchanged.
     //             * PU_ERROR_INVALID_PARAMETER:
     //               - Facility never initialized (i.e., Cpi.init() not done)
     //             * PU_ERROR_DRIVER_NOT_LOADED:
     //               - PERFDD device driver not loaded
     //
     // Notes:
     // - You should always invoke init() and terminate() as a pair.
     // - You must re-initialized (Cpi.init()) in order to continue measuring CPI.
     //
     native void terminate();

start

     //
     // Marks the beginning of a CPI measurement interval.
     //
     // Returns:
     // - 0:        Success
     // - non-zero: Errors attempting to begin measurement interval.
     //             * PU_ERROR_INVALID_PARAMETER/PU_ERROR_INVALID_SIGNATURE:
     //               - Facility never initialized (i.e., Cpi.init() not done)
     //             * Other:
     //               - Errors reading INSTR performance counter event data
     //               - Errors reading AI data
     //               - Errors reading PTT data
     //
     // Notes:
     // - This method records initial values/counters necessary to calculate
     //   CPI at the end of the measurement interval.
     // - You must invoke start() everytime you want to start a new interval.
     //
     native int start();

get

     //
     // Calculates CPI since the start of the measurement interval.
     //
     // Returns:
     // - 0:        Success
     // - non-zero: Errors
     //
     // Sets public members as follows
     // - Raw CPI data (always available)
     //   * elapsed_cycles
     //   * cpu_instr[]
     //   * cpu_cycles[]
     //   * cpu_cpi[]
     //   * sys_instr
     //   * sys_cycles
     //   * sys_cpi
     //
     // - Scaled CPI data (available if isScaledCpiAvailable() returns true)
     //   * cpu_busy_cycles[]
     //   * cpu_elapsed_cycles[]
     //   * cpu_busy_pc[]
     //   * cpu_cycles_scaled[]
     //   * cpu_cpi_scaled[]
     //   * sys_cycles_scaled
     //   * sys_busy_pc
     //   * sys_cpi_scaled
     //
     // - Scaled CPI data (available if isOnThreadCpiAvailable() returns true)
     //   * thread_instr
     //   * thread_cycles
     //   * thread_cpi
     //
     // Returns:
     // - 0:        Success
     // - non-zero: Errors attempting to get measurement interval data.
     //             * PU_ERROR_INVALID_PARAMETER/PU_ERROR_INVALID_SIGNATURE:
     //               - Facility never initialized (i.e., Cpi.init() not done)
     //             * Other:
     //               - Errors reading INSTR performance counter event data
     //               - Errors reading AI data
     //               - Errors reading PTT data
     //
     // Notes:
     // - This method records final values/counters necessary to calculate
     //   CPI and calculates CPI for the interval.
     // - CPI is calculated since the last start().
     // - On-thread CPI is calculated for the thread on which get() is invoked.
     //   That means you must make sure to invoke start()/get() on the same
     //   thread when getting on-thread CPI.
     // - If JPerf.CPI_TYPE_TRACE_ON_GET was specified on the init() call
     //   then get() will write the results of the measurement interval to
     //   the trace buffer.
     // - If JPerf.CPI_TYPE_TRACE_ONLY_ON_GET was specified on the init() call
     //   then get() will *ONLY* write the results of the measurement interval
     //   to the trace buffer. No object instance variables will be set.
     // - The amount of data traced is controlled by modes
     //   JPerf.CPI_TYPE_TRACE_SUMMARY and/or JPerf.CPI_TYPE_TRACE_DETAILED.
     // - If either of the *_ON_GET trace modes is specified, you can select
     //   the minor code and the trace label of each get() by invoking the
     //   setTraceHookId() method before invoking the get() method.
     //
     native int get();

getAndTrace
getAndTraceDetailed
getAndTraceSummary

     //
     // Same as get() with the addition of writing the results to the trace buffer.
     //
     // Returns:
     // - 0:        Success
     // - non-zero: Errors attempting to get measurement interval data.
     //             * See return codes for get() method.
     //
     // Notes:
     // - See notes for get() method.
     // - It is the caller's responsibility to initialize tracing and to enable
     //   the CPI major code (0xC1).
     // - No data is written to the trace buffer if tracing is off or if the
     //   CPI major code (0xC1) is not enabled. No error indication given.
     // - This method is intended for use when the init() mode does not
     //   contain any of the implied *_ON_GET trace actions:
     //   * JPerf.CPI_TYPE_TRACE_ON_GET
     //   * JPerf.CPI_TYPE_TRACE_ONLY_ON_GET
     //
     native int getAndTrace(int minor_code, int trace_flags);
     native int getAndTrace(int minor_code, int trace_flags, String label);
     native int getAndTraceDetailed(int minor_code);
     native int getAndTraceDetailed(int minor_code, String label);
     native int getAndTraceSummary(int minor_code);
     native int getAndTraceSummary(int minor_code, String label);

setTraceHookId

     //
     // Sets individual trace hook id when *ON_GET trace modes in effect.
     //
     // Input:
     // - minor_code:  Desired hook minor code.
     // - label:       Desired hook group label.
     //
     // Returns:
     // - 0:        Success
     // - non-zero: Errors
     //
     // Notes:
     // - This method sets the hook minor code and, optionally, a hook label
     //   for all trace hooks written from now on as a result of automatic
     //   ON_GET tracing.
     // - If you want to identify each hook then you must invoke this method
     //   before invoking the get() method.
     // - If neither *_ON_GET trace mode is on this method does nothing.
     //
     public native int setTraceHookId(int minor_code);
     public native int setTraceHookId(int minor_code, String label);

isSupported

     //
     // Check whether or not the CPI Measurement facility is supported.
     //
     // Returns:
     // - true:        CPI facility is supported.
     // - false:       CPI facility is not supported.
     //
     public native boolean isSupported();

isActive

     //
     // Check whether or not the CPI Measurement facility is active.
     //
     // Returns:
     // - true:        CPI facility active and at least Raw CPI measurements available.
     // - false:       CPI facility is not active.
     //
     public boolean isActive();