The pm_init API initialization routine

Edit online

The pm_init routine returns (in a structure of type pm_info_t pointed to by its second parameter) the processor name, the number of counters available, the list of available events for each counter, and the threshold multipliers supported.

Some processor support two threshold multipliers, others none, meaning that thresholding is not supported at all. You can not use the pm_init routine with processors newer than POWER4. You must use the pm_initialize routine for newer processors.

For each event returned, in addition to the testing status, the pm_init routine also returns the identifier to be used in subsequent API calls, a short name, and a long name. The short name is a mnemonic name in the form PM_MNEMONIC. Events that are the same on different processors will have the same mnemonic name. For instance, PM_CYC and PM_INST_CMPL are respectively the number of processor cycles and instruction completed and should exist on all processors. For each event returned, a thresholdable flag is also returned. This flag indicates whether an event can be used with a threshold. If so, then specifying a threshold defers counting until a number of cycles equal to the threshold multiplied by the processor's selected threshold multiplier has been exceeded.

The Performance Monitoring API enables the specification of event groups instead of individual events. Event groups are predefined sets of events. Rather than each event being individually specified, a single group ID is specified. The interface to the pm_init routine has been enhanced to return the list of supported event groups in a structure of type pm_groups_info_t pointed to by a new optional third parameter. To preserve binary compatibility, the third parameter must be explicitly announced by OR-ing the PM_GET_GROUPS bitflag into the filter. Some events on some platforms can only be used from within a group. This is indicated in the threshold flag associated with each event returned. The following convention is used:

Item	Descriptor
y	A thresholdable event
g	An event that can only be used in a group
G	A thresholdable event that can only be used in a group
n	A non-thresholdable event that is usable individually

On some platforms, use of event groups is required because all the events are marked g or G. Each of the event groups that are returned includes a short name, a long name, and a description similar to those associated with events, as well as a group identifier to be used in subsequent API calls and the events contained in the group (in the form of an array of event identifiers).

The testing status of a group is defined as the lowest common denominator among the testing status of the events that it includes. If at least one event has a testing status of caveat, the group testing status is at best caveat, and if at least one event has a status of unverified, then the group status is unverified. This is not returned as a group characteristic, but it is taken into account by the filter. Like events, only groups with status matching the filter are returned.