Functions IPR_STATUS IprAllocate (void) Allocates (declares ownership of) the counters. Only the process that "owns" the counters is allowed to perform certain operations, such as allocation and deallocation of buffers, starting the counters, and changing the data collection characteristics. IPR_STATUS IprDeallocate (void) Relinquishes ownership of the counters. IPR_STATUS IprSetActiveCounters ( IN IPR_CPUMASK cpus, // CPUs affected IN IPR_CTRMASK validmask, //Mask of valid counters IN IPR_CTRMASK *retmask) //Returned mask for starting counters Specifies which counters are to be considered active. Data is collected only for active counters; interrupts from other counters are ignored. The "retmask" argument will contain a counter mask for use in subsequent calls to IprStart. Some counter implementations require that all counters be started or stopped at the same time, while other implementations do not. In the latter case, preventing the interrupts in the first place will reduce overhead. IprSetActiveCounters will check whether the counters must be started at the same time and return the appropriate counter mask. IPR_STATUS IprSetSampleSkip ( IPR_CPUMASK cpus, // CPUs affected IPR_COUNT *skip values, // Array of skip values, one/counter IPR_SIZE arrsize) //Number of elements in the array Sets the number of interrupts to be skipped between samples (either for sampling or histogramming). By default, zero interrupts are skipped between samples, resulting in data being collected every interrupt. Skip values are passed in an array, where element N is the number of interrupts to be skipped for counter N. IPR_STATUS IprCreateSampleBuffers ( IPR_CPUMASK cpus, // Mask of desired CPUs IPR_COUNT bufcnt, // Number of buffers IPR_SIZE bufsiz, // Size of buffer in bytes IPR_DMASK datcol, // Data to be collected IPR_DMASK qdatcol, // Data to be collected int sampleaction, // Action to perform in lieu of sampling int fullaction, // Action to perform when buffer is full int (*pRoutine) (void), // Routine to be called IPR_COUNT rangecnt, // Number of valid PC ranges uint64 *ranges) // Valid PC ranges (start-end pairs) Creates sample buffers as requested. Specify data to be collected in the "datcol" mask, regardless of size. Items specified in the "qdatcol" mask will have 64 bits collected, otherwise they will have 32 bits collected. The "qdatcol" mask must be a subset of "datcol" mask. The "sampleaction" argument is not currently implemented. The "fullaction" argument indicates what to do when a sample buffer is full. The value is one of the following: IPR_FULL_NONE = do nothing IPR_FULL_WAKE = wake up the calling process IPR_FULL_AST = call the routine pointed to by "pRoutine" IPR_FULL_WRITE = automatically write the buffers (may not be available on all platforms) You may restrict sampling by requiring that the interrupted PC be within one of a group of PC ranges. The ranges are passed as an array of addresses, with the starting addresses occupying the even elements and the end addresses occupying the odd elements. The "rangecnt" argument is the number of RANGES, not the number of elements in the array (the number of elements is rangecnt * 2). IPR_STATUS IprAddAddressHistogramBuffers ( IN IPR_CPUMASK cpus, // CPUs affected IN IPR_HISTVALUE BeginAddr, // Histogram Start address IN IPR_HISTVALUE EndAddr, // Histogram end address unsigned int gran, // Granularity (shift value) unsigned int index) // Index number Creates additional address histogram buffers. Requires that histogram buffers be set up in the first place. Use IprCreateHistogramBuffers to create the first address (or other type) histogram buffer. Because address ranges may overlap, the "index" argument is provided. When address histograms are read, the caller specifies an address range, and it is legal to specify a subset or superset of the address range of an existing histogram. Therefore, there is a possibility that a given read range may fall into more than one histogram range. To provide a way of resolving this ambiguity, use a different index number for each address range, or at least for each overlapping one. (Callers specify an index value when reading histograms.) IPR_STATUS IprCreateHistogramBuffers ( IN IPR_CPUMASK cpus, // CPUs affected IN IPR_HMASK histos, // Histograms to be created IN IPR_HISTVALUE BeginAddr, // Start pt. for addr. histogram IN IPR_HISTVALUE EndAddr, // End pt. for addr. histogram IN unsigned int gran, // Granularity of addr. histogram IN unsigned int index) // Index value for these histograms Creates histogram buffers as specified. Specify the types of the histograms in the "histos" argument. The address range and granularity are used only for the address histogram, if one is reguested. The index value is used for all histograms, but should be zero in most cases. See the description of the "index" argument under IprAddAddressHistogramBuffers. IPR_STATUS IprDeleteBuffers (IN IPR_CPUMASK cpus) Deletes all buffers (sampling and histogramming) for the specified CPUs. IPR_STATUS IprSelectEvents ( IN IPR_CPUMASK cpus, // CPUs affected IN IPR_EVENTSET *events, // Set of events to be counted IN IPR_FREQ freq, // Interrupt freguency IN uint64 *MUXvalue) // Returned encoded value (optional) **** Please note: this function is being made obsolete **** Validates and saves selection information for the specified events. A subsequent call to IprSetEvents will cause the event selections to be transmitted to the counter.See further discussion under IprSelectEventsFromArray. IPR_STATUS IprSelectEventsFromArray ( IN IPR_CPUMASK cpus, // CPUs affected IN const IPR_EVENT *events, // Array of event numbers IN const IPR_FREQ *fregs, // Array of interrupt frequencies IN IPR_SIZE asize, // Number of elements in the arrays IN uint64 *MUXvalue) // Returned encoded value (optional) Attempts to make counter assignments for the specified events at the specified interrupt frequencies. The event at element N goes with the frequency at element N. The selections are not actually transmitted to the counters by this function; that is done by IprSetEvents. Frequencies are zero, a power of two, IPR_FREQUENCY_LOWEST, or IPR_FREQUENCY_HIGHEST. Note that specifying one of the latter two options may not get the lowest or highest possible frequency for the event, but rather the lowest or highest frequency available on whatever counter gets assigned the event. The returned encoded value may be used in a subsequent call to IprSetEvents, if you want to make several sets of selections and switch among them freguently. IPR_STATUS IprSetEvents ( IPR_CPUMASK cpus, // CPUs affected IN uint64 *MUXvalue) // Encoded value (optional) Transmits event and freguency selections to the counters. If the "MUXvalue" argument is passed, it is decoded and used as appropriate. Otherwise, the stored information from previous IprSelectEvents or IprSelectEventsFromArray calls is used. IPR_STATUS IprSetModes ( IN IPR_CPUMASK cpus, // CPUs affected IN IPR_MMASK modes) // Operation modes Sets counter state so that counting is restricted to the specified modes. The modes include processor modes (kernel, PAL, and user, plus exec and super on VMS) and "selected processes" mode. IPR_STATUS IprEventCounterMap ( IN IPR_CPUMASK cpus, // CPUs affected IN IPR_EVENT *event arr, // Returned array of events IN IPR_SIZE asize) // Number of elements in return array Returns the list of events to which the counters have been assigned. The index into the array is the counter number; for example, element 3 contains the event assigned to counter 3. The "cpus" argument should be a single CPU mask or IPR_CURRENT_CPU. IPR_STATUS IprFreqCounterMap ( IN IPR_CPUMASK cpus, // CPUs affected IN IPR_FREQ *freq arr, // Returned array of frequencies IN IPR_SIZE asize) // Nurnber of elements in return array Returns the list of interrupt frequencies to which the counters have been assigned. The index into the array is the counter number; for example, element 3 contains the interrupt frequency assigned to counter 3. The frequency value will be the actual frequency, not IPR_FREQUENCY_HIGHEST or IPR_FREQUENCY_LOWEST. The "cpus" argument should be a single CPU mask or IPR_CURRENT_CPU. IPR_STATUS IprCounterNumber ( IN IPR_CPUMASK cpus, // CPUs effected IN IPR_EVENT event, // Desired event number IN IPR_CTRNUMBER *cnum) // Returned counter number Returns the number of the counter that is counting the specified event. The counter number is returned via the "cnum" argument. The "cpus" argument should be a single CPU mask or IPR_CURRENT_CPU. IPR_STATUS IprStart ( IN IPR_CPUMASK cpus, // CPUs affected IN IPR_CTRMASK ctrs) // Counters to be started Starts the specified counters on the specified CPUs. If the "ctrs" argument is zero, all counters are started. If possible, counters are started from zero. IPR_STATUS IprStop ( IN IPR_CPUMASK cpus, // CPUs affected IN IPR_CTRMASK ctrs) // Counters to be stopped Stops the specified counters on the specified CPUs. If the "ctrs" argument is zero, all counters are stopped. IPR_STATUS IprPause ( IN IPR_CPUMASK cpus, // CPUS effected IN IPR_CTRMASK ctrs) // Counters to be paused Pauses the specified counters on the specified CPUs. If the "ctrs" argument is zero, all counters are paused. If the current process has process monitoring enabled, monitoring is disabled. The counters are not reset to zero. This function may be called by processes other than the owner of the counters. IPR_STATUS IprResume ( IN IPR_CPUMASK cpus, // CPUs affected IN IPR_CTRMASK ctrs) // Counters to be resumed Resumes the argument is had process is enabled. and are not specified counters on the specified CPUs. If the "ctrs" zero, all counters are resumed. If the current process monitoring enabled prior to a call to IprPause, monitoring The counters continue counting from where they left off, forced to start from zero. This function may be called by processes other than the owner of the counters. NOTE: CPU context Functions that take a CPU context number may be called multiple times, returning data for a different CPU each time. To use this feature, create an int variable to hold the CPU context and initialize it to -1. Pass a pointer to this variable to the function. After each call, this variable will contain the CPU number corresponding to the data just returned. Stop making calls when the context variable contains a value greater than or equal to IPR_MAX_CPUS. If no CPU context variable is passed, the functions will combine data for the various CPUs; exact behavior depends on the function. The example below collects data for CPUs 2 and 3, if the exist on the system: int cpuctx; IPR_CPUMASK cmask = (1 << 2) + (1 << 3); for (cpuctx = -1, IprFunc (cmask, &cpuctx, &data); cpuctx < IPR_MAX_CPUS; IprFunc (cmask, &cpuctx, &data)) { printf ("CPU %d data %s\n", cpuctx, data); } If the value of "cmask" is changed to IPR_ALL_CPUS, data will be returned for all CPUs on the system. NOTE: Action flags Some functions take an "action flags" argument. These functions all have an array of returned data. The "action flags" argument specifies how to return the data. The argument can have one of the following values: IPR_ACTION_COPY = Replace the data in the array with the new data. IPR_ACTION_SUM = Add all data for all CPUs together, and return that. This flag is useful if the caller does not pass a CPU context value. IPR_ACTION_ADD = Add the new data to the current contents of the array. IPR_STATUS IprRead ( IN IPR_CPUMASK cpus, // CPUs affected IN int *cpuctxptr, // CPU context number (optional) IN IPR_CTRMASK cmask, // Desired counter mask OUT int *retdata, // Returned array of counter values IN IPR_SIZE rsize, // Number of elements in return data array IN int action flags) // Data handling flag Reads the current values for the specified counters on the specified CPUs. See notes on CPU context and action flags earlier. The index into the returned array is the counter number; for example, element 3 will contain the value for counter 3. IPR_STATUS IprReadAll ( IN IPR_CPUMASK cpus, // CPUs affected IN int *cpuctxptr, // CPU context number (optional) OUT int *retdata, // Returned array of counter values IN IPR_SIZE rsize, // Number of elements in return array IN int action flags) // Data handling flag Reads the current values for all counters on the specified CPUs. See notes on CPU context and action flags earlier. The index into the returned array is the counter number; for example, element 3 will contain the value for counter 3. IPR_STATUS IprWrite ( IN IPR_CPUMASK cpus, // CPUs affected IN int *cpuctxptr, // CPU context number (optional) IN IPR_CTRMASK cmask, // Counters to write IN int *srcdata, // Array of counter values IN IPR_SIZE srcsize) // Number of elements in value array Writes values into the specified counters on the specified CPUs. See notes on CPU context and action flags earlier. The index into the returned array is the counter number; for example, element 3 will contain the value to be written to counter 3. IPR_STATUS IprClear ( IN IPR_CPUMASK cpus, // CPUs affected IN IPR_CTRMASK ctrs) // Counters to be cleared Clears the specified counters on the specified CPUs. If the "ctrs" argument is zero, all counters will be cleared. IPR_STATUS IprReadHistogram ( IN IPR_CPUMASK cpus, // CPUs affected IN int *cpuctxptr, // CPU context number (optional) OUT IPR_HISTELEM *retdata, // Returned histogram data IN IPR_SIZE retsize, // Number of elements in return array IN IPR_HISTVALUE retmin, // Minimum value to be returned IN IPR_HMASK htype, // Type of histogram to be returned IN unsigned int index, // Matching histogram index value IN int action flags) // Data return flag Reads the data for a single histogram and returns it in the passed array. See the notes on CPU context and action flags earlier. The histograms on the appropriate CPUs are scanned, and data returned for any matching histogram. A histogram matches if: - The type is the same as the "htype" argument. - The index is the same as the "index" argument. - The data in the histogram would lie somewhere in the return array, based on the minimum value of the histogram, the "retmin" argument, the size of the return array, and the histogram granularity. Note that the IPROBE API prevents there being more than one histogram for types other than addresses. However, inconsistent use of the histogram index could cause strange results when address histograms are to be read. IPR_STATUS IprClearHistograms ( IN IPR_CPUMASK cpus, // CPUs affected IN IPR_HMASK hmask, // Histogram types to be cleared IN unsigned int index) // Matching index value Clears all histograms that match the input criteria. Must match one of the CPU numbers and one of the the histogram types, and must match exactly the index number. IPR_STATUS IprMarkEmptySampleBuffer (OUT IPR_SBUFFER *Sptr) Marks the passed sample buffer as empty. IPR_STATUS IprNextFullSampleBuffer ( IN IPR_CPUMASK cpus, // CPUs to be checked OUT IPR_SBUFFER **bctx, // Returned ptr and previous context OUT IPR_SIZE *bsize, // Returned size of buffer in bytes IN IPR_BOOLEAN part flag) // Shows whether to check for // partial buffers Finds the next full sample buffer according to the input criteria. The "bctx" argument is a pointer to the found sample buffer, and is also used by the function to indicate where it left off. The "part flag" argument indicates whether partially full buffers are to be returned, in addition to buffers actually marked full; partially full buffers are expected to be returned only when the counters have been disabled. All sample buffer lists for matching CPUs are searched, and one CPU list is finished before moving on to the next CPU list. To use the function, initialize the context pointer to NULL and call repeatedly until it returns IPR__NOMOREBUFF. If partial buffers were requested and one was found, it will return IPR__PARTBUFF, otherwise it will return IPR__SUCCESS or an error. IPR_STATUS IprClearContext (IN IPR_CPUMASK cpus) Clears the internal counter context for the specified CPUs. IPR_STATUS IprWriteToSampleFile ( IN void *bptr, // Pointer to data area IN IPR SIZE bsize) // Size of data area in bytes Writes the specified data into the sample file. Used for writing of header information or additional information. The file information for the sample file is hidden from the caller, requiring that all manipulation of the sample file be done through IPROBE API functions. IPR_STATUS IprWriteOneSampleBuffer ( IN IPR_SBUFFER *bptr, // Sample buffer to be written out IN IPR_SIZE bsize) // Size of the sample buffer in bytes Writes the passed sample buffer to the sample file. Writes the number of bytes specified in the "bsize" argument. IPR_STATUS IprWriteSampleBuffers ( IN IPR_CPUMASK cpus, // Valid CPU mask IN int write flag, // Indicates whether to write partial // buffers OUT int *rbufwrites, // Returned number of buffers written // (optional) OUT int *rpartwrites) // Returned number of partial writes // (optional) Writes all valid sample buffers, according to the specified criteria, to the sample file. A sample file matches if it is for one of the specified CPUs, if it is full, or if it is partially full and the "write flag" argument is TRUE (non-zero3. The "write flag" argument should be passed as TRUE only when the counters are disabled. If specified, the variables pointed to by the "rbufwrites" and "rpartwrites" arguments will be modified to show the number of buffer writes and the number of partial buffer writes done in this call. "Partial buffer writes" is a subset of "buffer writes." Partial buffer writes typically returns one or zero per CPU. IPR_STATUS IprTerminateSampling ( OUT int *rbufwrites, // Returned number of buffers written // (optional) OUT int *rpartwrites) // Returned number of partial writes // (optional) Performs all operations necessary to terminate sampling, in the correct order. Provided as a convenience. Stops the counters, writes out all remaining full sample buffers, and deletes the buffers. The "rbufwrites" and "rpartwrites" arguments are passed through to IprWriteSampleBuffers; see description there. IPR_STATUS IprSpecifyOperations ( IN IPR_CPUMASK cpus, // CPUs affected IN IPR_EVENT *selected_event, // Desired events IN IPR_FREQ *selected_freguency, // Desired interrupt freq. IN IPR_COUNT ecount, // No. of elements in event/freq arrays IN IPR_MMASK selected_modes, // Desired modes OUT uint64 *MUXvalue, // Returned encoded value (optional) OUT IPR_CTRMASK *ctrmask) // Returned valid counter mask Perform all necessary functions to specify how the counters should operate. Selects events for the counters, fills in events for uncovered counters if necessary, sets the events and interrupt frequencies for the counters, sets the counting modes, and returns (if requested) the encoded value and the counter mask. Note that this function may NOT be called incrementally; everything must be specified in a single call. The "ctrmask" argument, if passed, will have returned in it the mask of counters assigned. This mask may be subsequently passed to IprSetActiveCounters. IPR_STATUS IprReadMultipleHistograms ( IN IPR_CPUMASK cpus, // CPU mask IN int *cpuctxptr, // CPU context number (optional) OUT IPR_HISTELEM **retdata, // Array of array pointers for // return data OUT IPR_SIZE *retsize, // Array of array sizes (numbers of // elements) OUT IPR_HISTVALUE *retmin, // Array of minimum values OUT IPR_HMASK *htype, // Array of histogram types OUT unsigned int *index, // Array of buffer index values IN int action flags, Indicates how to store data IN IPR_COUNT itemcnt) // Number of arrays Reads multiple histograms in one call. Provides a way to retrieve multiple histograms for a single CPU without having to save and restore CPU context. This function essentially turns into multiple calls to IprReadHistogram. An example is the easiest way to show how to call it. The example below is a bit impractical, but should illustrate the use of IprReadMultipleHistograms clearly. Note that element N of the "retdata", "retsize", "retmin", "htype", and "index" arrays all correspond to each other. IPR_HISTELEM hdata0 [20], hdatal [30], hdata2 [40], *pRData [3]; IPR_SIZE hsize [3]; IPR_HISTVALUE hmin [3]; IPR_HMASK hmask [3]; unsigned int hidx [3]; pRData [0] = hdata0; /* Pt to appropriate return array */ pRData [1] = hdata1; pRData [2] = hdata2; hsize [0] = 20; /* Save return array sizes */ hsize [1] = 30; hsize [2] = 40; hmin [0] = MY_MIN_0; /* Corresponding minimum values */ hmin [1] = MY_MIN_1; hmin [2] = MY_MIN_2; hmask [0] = MY_MASK_0; /* Histogram types */ hmask [1] = MY_MASK_1; hmask [2] = MY_MASK_2; for (cpuctx = -1, status = IprReadMultipleHistograms (IPR_ALL_CPUS, &cpuctx, pRData, hsize, hmin, hmask, hidx, IPR_ACTION_COPY, 3); cpuctx < IPR_MAX_CPUS; status = IprReadMultipleHistograms ( IPR_ALL_CPUS, &cpuctx, pRData, hsize, hmin, hmask. hidx, IPR_ACTION_COPY, 3)) { printf ("Data for CPU %d\n", cpuctx); /* do something with the returned data */ } IPR_STATUS IprCloseSampleFile ( OUT int *buffwrites, // Number of buffers written OUT int *partwrites) // Number of partial buffers written Closes the sample file. If automatic writing out of sample buffers has been selected, this function will return the number of buffers written out automatically (both the total value and the subset that were partially full). Otherwise, the "buffwrites" and "partwrites" arguments will be returned as zero. IPR_STATUS IprOpenSampleFile ( IN char *fname, // File name to be opened IN char *defname) // Default file name information Opens a sample file. All accesses to this file must be done through the IPROBE API. The "fname" argument contains the name of the file to be opened. On systems that support partial file name defaulting, the "defname" argument contains the default name information. IPR_STATUS IprPrintMessage ( IN char *tag, // Additional printed string IN IPR_STATUS errcode, // API error code IN void (*callback) (char *)) // Printing routine Prints an error message based on the error code. If it is an IPROBE API error, it will be decoded, otherwise the number will be printed. The string specified in the "tag" argument will be part of the message, allowing the caller to provide some context for the message. If a printing routine is specified, it is called. Otherwise, a function is used that writes to stderr. const char *IprEventNumberToName (IPR EVENT evt) Returns a pointer to a string that is the full name of the specified event. If the event number is not valid, the string "" is returned. IPR_COUNT IprNumberOfEvents (void) Returns the total number of events known to the IPROBE API. IPR_STATUS IprEventNameToNumber ( IN char *ename, // Name to be translated OUT IPR_EVENT *evtnum, // Returned event number OUT const char **matches) // List of possible matches // (optional) Searches for the specified name in the event list. If it is found and is an unambiguous match, the full name will be returned in the "matches" argument, the found event code will be returned in the "evtnum" argument, and the return code will be IPR SUCCESS. If the match is ambiguous, IPR__AMBIGUOUS will be the return code and the "matches" argument will contain a space-separated list of all possible matches. If no matches are found, the return code will be IPR__INVEVENTNAME. IPR_STATUS IprHbIndex ( IN IPR_HISTVALUE value, // Candidate value IN IPR_CTRNUMBER ctr, // Candidate counter number IN IPR_COUNT numctrs, // Number of counters IN IPR_HISTVALUE minval, // Minimum value in the histogram IN int gran, // Granularity of the histogram OUT int *index) // Returned histogram array index Calculates the array index that corresponds to the specified value-counter combination, given the histogram description. Example: /* Read histogram data */ numctrs = IprNumCounters (); status = IprReadHistogram (IPR_CURRENT_CPU, NULL, mydata, mydatasiz, hist_min, hist_type, 0, IPR_ACTION_COPY); /* Display data for one value, all counters */ for (ctr = 0; ctr < numctrs; ctr++) { status = IprHbIndex (display_value, display_counter, ctr, numctrs, hist_min, hist_gran, &idx); printf ("Number of hits for value %LX counter %d: " "%Ld\n", display_value, ctr, mydata [idx]); } IPR_STATUS IprHbValue ( IN int index, // Candidate array index IN IPR_COUNT numctrs, // Number of counters IN IPR_HISTVALUE minval, // Histogram minimum value IN int gran, // Histogram granularity OUT IPR_HISTVALUE *value) // Returned element value Returns the smallest value that would be placed in the specified array index, given the histogram description. Example: *** to be decided *** IPR_STATUS IprHbElements ( IN IPR_COUNT numctrs, // Number of counters IN IPR_COUNT numval, // No. of values covered by the histogram IN int gran, // Histogram granularity OUT IPR_COUNT *numelem) // Returned number of array elements Determines the number of array elements needed to hold a histogram of the specified description. IPR_COUNT IprNumCounters (void) Returns the number of counters on the system. IPR_STATUS IprAvailableEvents ( const IPR_EVENTSET *reqevents, // Requested events IPR_EVENTSET *additional events) // Additional events that may // be added Returns the set of events that may be specified in addition to the events in the "reqevents" argument. If further events may be assigned, IPR__FURTHER_EVENTS is returned. If no further events may be assigned, IPR__NO_FURTHER EVENTS is returned. If there is an error in the specified event set, an error code is returned. IPR_STATUS IprAvailableFreqs ( const IPR_EVENT evt, // Candidate event IPR_FREQ *freq) // Returned interrupt frequency mask Returns the interrupt frequencies available for the specified event. IPR_STATUS IprAvailableModes (IPR_MMASK *modes) Returns the counting modes available on the current machine. These include the processor modes, PALcode mode, and "selected processes" mode. Note that not all subsets of the mode list may be legal. IPR_STATUS IprAvailableFuncs (IPR_FMASK *funcs) Returns the functions available on the current machine. IPR_STATUS IprCounterEvents ( IPR_CTRNUMBER ctr, // Counter number IPR_EVENTSET *eset) // Returned event set Returns the events that may be counted by the specified counter. IPR_STATUS IprAvailableCounters ( IPR_EVENT evt, // Event number IPR_CTRMASK *ctrs) // Returned counter mask Returns the list of counters that can count the specified event. Event Set manipulation functions The implementation of an "event set" is hidden from the user. These event set manipulation functions provide access to all necessary operations on event sets. IPR_SIZE IprEventSetSize (void) Returns the number of bytes in an event set. To create an event set, call malloc with this number of bytes. IPR_EVENT IprEventToNumber (const IPR_EVENTSET *eset) Returns the event number of the lowest numbered event in the passed event set. If the event set is empty, zero is returned. IPR_COUNT IprNumberEventsInSet (const IPR_EVENTSET *eset) Returns the number of events in the event set. IPR_BOOLEAN ZprVerifyEventInSet ( const IPR_EVENTSET *eset, // Source event set const IPR_EVENT evt) // Candidate event Returns TRUE if the specified event is in the specified set, FALSE otherwise. IPR_STATUS IprClearEventSet (IPR_EVENTSET *eset) Clears all the events in the passed event set, creating an empty set. IPR_STATUS IprInsertEvent ( IPR_EVENTSET *eset, // Destination event set const IPR_EVENT evt) // Event to be inserted Adds the specified event to the passed event set. IPR_STATUS IprDeleteEvent ( IPR_EVENTSET *eset, // Destination event set const IPR_EVENT evt) // Event to be deleted Deletes the specified event from the passed event set. IPR_STATUS ZprMaskEventSet ( IPR_EVENTSET *dst, // Destination event set const IPR_EVENTSET *src) // Source event set Removes all events from the destination set that are NOT present in the source set. IPR_STATUS IprRemoveEventSet ( IPR_EVENTSET *dst, // Destination event set const IPR_EVENTSET *src) // Source event set Remove all events from the destination set that are PRESENT in the source set. IPR_STATUS IprExpandEventSet ( const IPR_EVENTSET *eset, // Source event set IPR_EVENT *retdata, // Returned event array IPR_SIZE retsize) // Number of elements in the return array Converts the passed event set into an array of events. IPR_STATUS IprMergeEventSet ( IPR_EVENTSET *dst, // Destination event set const IPR EVENTSET *src) // Source event set Adds all events in the source set to the destination set. Macros CPU numbers: IPR_ALL_CPUS, IPR_CURRENT_CPU Histogram copy actions: IPR_HACTION_COPY, IPR_HACTION_ADD, IPR_HACTION_SUM Sample buffer write actions: IPR_WRITE_PARTIAL, IPR_NOWRITE_PARTIAL Minimum address histogram granularity: IPR_PCSHIFT Sample buffer "buffer-is-full" actions: IPR_FULL_NONE, IPR_FULL_WAKE, IPR_FULL_AST, IPR_FULL_WRITE Number of IPLs: IPR_IPL_COUNT Number of modes: IPR_MODE_COUNT Index number for the various modes: IPR_MODE_KERNEL IPR_MODE_EXEC (VMS only) IPR_MODE_SUPER (VMS only) IPR_MODE_USER IPR_MODE_INTERRUPT (may be missing on certain systems) IPR_MODE_IDLE Check for success: IPR_SUCCESS (stsvalue) evaluates to TRUE (non-zero) if the argument is a success status, FALSE (zero) otherwise. Bit Manipulation As a convenience, because there are many bit masks used in the IPROBE API, a library of bit manipulation routines is provided. Most of them are macros; those that are not are functions exported by the IPROBE API. Macros: BIprA111(m) Returns a mask, the same size as m, with all bits set to 1 BIprIsSet(m,b) Returns TRUE if bit number b is set in mask m BIprSet(m,c) Returns a mask with bits set that are set in either mask m or mask c BIprBoth(m,c) Returns a mask with bits set that are set in BOTH mask m and mask c BIprClr(m,c) Returns a mask with bits set that are set only in mask m, and not set in mask c BIprSetLo(b) Returns a mask with all bits set from bit number b down to bit number zero BIprSetHi(b) Returns a mask with all bits set from bit number b up to the highest bit in the mask BIprSet1(m,b) Returns a mask the same as m, plus bit number b is set BIprClr1(m,b) Returns a mask the same as m, except bit number b is clear BZprLowest(m) Returns a mask consisting of only the lowest set bit in mask m BIprZsl(m) Returns TRUE if exactly one bit is set in mask m BIprClrLo(m,b) Clears all bits in mask m lower than bit number b BIprClrHi(m,b) Clears all bits in mask m higher than bit number b BIprAll1, BIprLowest and BIprIs1 use an argument more than once, so should not be invoked with arguments that have side effects. Functions: BZprB2M(b) Returns a mask with only bit number b set BIprCnt(m) Returns the number of set bits in mask m BIprWhich(m) Returns the bit number of the lowest set bit in mask m BIprRelPos(m,b) Returns the relative position of bit number b within the set bits of mask m (the first set bit is zero, the second set bit is one, etc.) Some examples where these might be useful: // Get the number of counters in the mask numctrs = BIprCnt (ctrmask); // Print out the counter numbers of all the counters in // the mask tmpctrmask = ctrmask; printf ("Active counters are: "); while (tmpctrmask) { printf ("%d ", BIprWhich (tmpctrmask)); tmpctrmask = BIprClr (tmpctrmask, BIprLowest(tmpctrmask)); } printf( "\n"); // Use relative bit numbers to map a spare mask into a // dense one so we don't have to keep data for unused bit // values tmpcpumask = cpumask; while (tmpcpumask) { // Get absolute bit number cpunum = BIprXhich (tmpcpumask); // Get relative bit number cpuidx = BIprRelPos (cpumask, cpunum); print_cpu_data(cpunum, sparse_cpu_array[cpuidx]); // Done, clear bit tmpcpumask = BIprClrl(tmpcpumask, cpunum); } // Set all bits in a histogram mask a.ipr_hmask_l_bits = BIprAll1(a.ipr_mask_l_bits); // Pass a histogram mask with all bits set IprSomeFunc (arg0, argl, BIprA111(a.ipr_hmask_l_bits), arg3);