Basic pmapi library calls
Each of the following sections describes a system-wide API call that has variations for first- and third-party kernel thread or group counting. Variations are indicated by suffixes to the function call names, such as pm_set_program, pm_set_program_mythread, and pm_set_program_group.
- pm_set_program
- Sets the counting configuration. Use this call to specify the
events (as a list of event identifiers, one per counter, or as a single
event-group identifier) to be counted, and a mode in which to count.
The list of events to choose from is returned by the pm_init routine.
If the list includes a thresholdable event, you can also use this
call to specify a threshold, and a threshold multiplier.
The mode in which to count can include user-mode and kernel-mode counting, and whether to start counting immediately. For the system-wide API call, the mode also includes whether to turn counting on only for a process and its descendants or for the whole system. For counting group API calls, the mode includes the type of counting group to create, that is, a group containing the initial thread and its future descendants, or a process-level group, which includes all the threads in a process.
By default, the time spent during interrupts handling is counted. It is possible to override this default behavior by modifying the counting mode.
- pm_get_program
- Retrieves the current Performance Monitor settings. This includes mode information and the list of events (or the event group) being counted. If the list includes a thresholdable event, this call also returns a threshold and the multiplier used.
- pm_delete_program
- Deletes the Performance Monitor configuration. Use this call to undo pm_set_program.
- pm_start, pm_tstart
- Starts Performance Monitor counting. pm_tstart returns a timestamp associated with the time the Performance Monitoring counters started counting. This is a timebase value that can be converted to time using time_base_to_time.
- pm_stop, pm_tstop
- Stops Performance Monitor counting. pm_tstop returns a timestamp associated with the time the Performance Monitoring counters stopped counting. This is a timebase value that can be converted to time using time_base_to_time.
- pm_get_data, pm_get_tdata, pm_get_Tdata
- Returns Performance Monitor counting data. The data is a set of
64-bit values, one per hardware counter. For the counting group API
calls, the group information is also returned. (See Thread counting-group information.)
pm_get_tdata is similar to pm_get_data, but includes a timestamp that indicates the last time that the hardware Performance Monitoring counters were read. This is a timebase value that can be converted to time by using time_base_to_time.
pm_get_Tdata is also similar to pm_get_data but includes accumulated times corresponding to the interval during which the hardware Performance Monitoring counters were active. The interval is measured in real time, PURR and SPURR (on processors supporting those) values, and returned in timebase units convertable to time using time_base_to_time.
The pm_get_data_cpu, pm_get_tdata_cpu and pm_get_Tdata_cpu interfaces return the Performance Monitor counting data for a single processor. The specified processor number represents a contiguous number going from 0 to _system_configuration.ncpus. This number can represent a different processor from call to call if dynamic reconfiguration operations have occurred.
The pm_get_data_lcpu, pm_get_tdata_lcpu and pm_get_Tdata_lcpu interfaces return the Performance Monitor counting data for a single logical processor. The logical processor numbering is not contiguous, and the call to these interfaces returns an error if the specified logical processor has not been on line since the last call to pm_set_program. A logical processor number always designates the same processor even if dynamic reconfiguration operations have occurred. To get data for all processors, these interfaces must be called in a loop from 0 to _system_configuration.max_ncpus.
- pm_reset_data
- Resets Performance Monitor counting data. All values are set to 0.