October 27, 2005 PMC_CONTROL 2

### NAME

pmc_control, pmc_get_info - Hardware Performance Monitoring Interface

### LIBRARY

Standard C Library (libc, -lc)

### SYNOPSIS

```int` pmc_control(```int ctr``, int op``, void *argp`)
```int` pmc_get_info(```int ctr``, int op``, void *argp`)

### DESCRIPTION

pmc_get_info(``) returns the number of counters in the system or information on a specified counter ```ctr`. The possible values for ```op` are:

```PMC_INFO_NCOUNTERS`
  When querying the number of counters in the system, ```ctr` is ignored and ```argp` is of type
  ```int``*`. Upon return, the integer pointed to by ```argp` will contain the number of counters that are available in the system.

```PMC_INFO_CPUCTR_TYPE`
  When querying the type of a counter in the system, ```ctr` refers to the counter being queried, and ```argp` is of type
  ```int``*`. Upon return, the integer pointed to by ```argp` will contain the implementation-dependent type of the specified counter.

  If ```ctr` is -1, the integer pointed to by ```argp` will contain the machine-dependent type describing the CPU or counter configuration.

```PMC_INFO_COUNTER_VALUE`
  When querying the value of a counter in the system, ```ctr` refers to the counter being queried, and ```argp` is of type
  ```uint64_t``*`. Upon return, the 64-bit integer pointed to by ```argp` will contain the value of the specified counter.

```PMC_INFO_ACCUMULATED_COUNTER_VALUE`
  When querying the value of a counter in the system, ```ctr` refers to the counter being queried, and ```argp` is of type
  ```uint64_t``*`. Upon return, the 64-bit integer pointed to by ```argp` will contain the sum of the accumulated values of specified counter in all exited subprocesses of the current process.

pmc_control(``) manipulates the specified counter ```ctr` in one of several fashions. The ```op` parameter determines the action taken by the kernel and also the interpretation of the ```argp` parameter. The possible values for ```op` are:

```PMC_OP_START`
  Starts the specified ```ctr` running. It must be preceded by a call with ```PMC_OP_CONFIGURE`. ```argp` is ignored in this case and may be ```NULL`.

```PMC_OP_STOP`
  Stops the specified ```ctr` from running. ```argp` is ignored in this case and may be ```NULL`.

```PMC_OP_CONFIGURE`
  Configures the specified ```ctr` prior to running. ```argp` is a pointer to a
  ```struct` `pmc_counter_cfg`. `

              struct pmc_counter_cfg {
                      pmc_evid_t      event_id;
                      pmc_ctr_t       reset_value;
                      uint32_t        flags;
              };

  `

  ```event_id`
    is the event ID to be counted.

  ```reset_value`
    is a value to which the counter should be reset on overflow (if supported by the implementation). This is most useful when profiling (see ```PMC_OP_PROFSTART`, below). This value is defined to be the number of counter ticks before the next overflow. So, to get a profiling tick on every hundredth data cache miss, set the ```event_id` to the proper value for ``dcache-miss'' and set ```reset_value` to 100.

  ```flags`
    Currently unused.

```PMC_OP_PROFSTART`
  Configures the specified ```ctr` for use in profiling. ```argp` is a pointer to a
  ```struct` `pmc_counter_cfg` as in ```PMC_OP_CONFIGURE`, above. This request allocates a kernel counter, which will fail if any process is using the requested counter. Not all implementations or counters may support this option.

```PMC_OP_PROFSTOP`
  Stops the specified ```ctr` from being used for profiling. ```argp` is ignored in this case and may be ```NULL`.

### RETURN VALUES

A return value of 0 indicates that the call succeeded. Otherwise, -1 is returned and the global variable errno is set to indicate the error.

### ERRORS

Among the possible error codes from pmc_control(``) and pmc_get_info(``) are

[```EFAULT`]
  The address specified for the ```argp` is invalid.

[```ENXIO`]
  Specified counter is not yet configured.

[```EINPROGRESS`]
  ```PMC_OP_START` was passed for a counter that is already running.

[```EINVAL`]
  Specified counter was invalid.

[```EBUSY`]
  If the requested counter is already in use--either by the current process or by the kernel.

[```ENODEV`]
  If and only if the specified counter event is not valid for the specified counter when configuring a counter or starting profiling.

[```ENOMEM`]
  If the kernel is unable to allocate memory.

### SEE ALSO

pmc(1), pmc(9)

### HISTORY

The pmc_control(``) and pmc_get_info(``) system calls appeared in NetBSD2.0.