November 10, 2001 I386_PMC_INFO 2 i386

### NAME

i386_pmc_info, i386_pmc_startstop, i386_pmc_read - interface to CPU performance counters

### LIBRARY

i386 Architecture Library (libi386, -li386)

### SYNOPSIS

```int` i386_pmc_info(```struct i386_pmc_info_args *ia`)
```int` i386_pmc_startstop(```struct i386_pmc_startstop_args *ssa`)
```int` i386_pmc_read(```struct i386_pmc_read_args *ra`)

### DESCRIPTION

These functions provide an interface to the CPU performance counters on the 586-class and 686-class processors.

i386_pmc_info(``) will return information about the available CPU counters. The information is returned in ```ia` having the following structure: ``

    struct i386_pmc_info_args {
            int     type;
            int     flags;
    };

The type member describes the class of performance counters available. Valid values are:

PMC_TYPE_NONE
  No PMC support
PMC_TYPE_I586
  586-class CPUs
PMC_TYPE_I686
  686-class Intel CPUs
PMC_TYPE_K7
  686-class AMD CPUs

The flags member describes additional capabilities of the processor. Valid values are:

PMC_INFO_HASTSC
  CPU has time-stamp counter

i386_pmc_startstop(``) is used to start and stop the measurement of the CPU performance counters. The argument ```ssa` has the following structure: ``

    struct i386_pmc_startstop_args {
            int counter;
            uint64_t val;
            uint8_t event;
            uint8_t unit;
            uint8_t compare;
            uint8_t flags;
    };

The counter specified by the member counter is started if the member flags has PMC_SETUP_KERNEL or PMC_SETUP_USER set, otherwise the counter is stopped. The initial value of the counter is set to val. Additional values for the flags member are PMC_SETUP_EDGE and PMC_SETUP_INV. The event member specifies some event written to the control register. The unit member specifies the measurement units. The compare member is a mask for the counter.

i386_pmc_read(``) will return information about a specific CPU counter measured during the last measurement period determined by the calling of i386_pmc_startstop(``). The information is returned in ```ra` having the following structure: ``

    struct i386_pmc_read_args {
            int counter;
            uint64_t val;
            uint64_t time;
    };

The counter to read should be specified by the counter member. Counters are numbered from 0 to ```PMC_NCOUNTERS`. The value of the counter is returned in the val member. The time since epoch, measured in CPU clock cycles, is returned in the time member.

### RETURN VALUES

Upon successful completion zero is returned, otherwise -1 is returned on failure.