PMC_CONTROL(2)

PMC_CONTROL(2) | System Calls Manual | PMC_CONTROL(2)

# NAME

pmc_control, pmc_get_info — Hardware Performance Monitoring Interface

# LIBRARY

Standard C Library (libc, -lc)

# SYNOPSIS

#include <sys/pmc.h>
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 NetBSD 2.0.

October 27, 2005 | NetBSD 8.0