---
name: "pfm_get_cycle_event"
section: "3"
platform: "linux"
package: "libpfm3-3.2-dev"
version: "3.2.070507-1.1"
release: "Debian 6.0 (Squeeze)"
platforms: ["linux"]
url: "https://new.carta.tech/pfm_get_cycle_event"
---

# pfm\_get\_cycle\_event(3)

get basic event descriptors

## NAME

pfm\_get\_cycle\_event, pfm\_get\_inst\_retired\_event - get basic event descriptors

## SYNOPSIS

```
#include <perfmon/pfmlib.h>

int pfm_get_cycle_event(pfmlib_event_t *ev);
int pfm_get_inst_retired_event(pfmlib_event_t *ev);

```

## DESCRIPTION

In order to build very simple geenric examples that work across all PMU models, the library provides a way to retrieve information about two basic events that are present in most PMU models: cycles  and instruction retired. The first event, cycles, counts the number of elapsed cycles. The second event, instruction retired, counts the number of instructions that have executed and retired from the processor pipeline. Depending on the PMU model, there may be variations in the exact definition of those events. The library provides this information on a best effort basis. User must refer to PMU model specific documentation to validate the event definition.

The **pfm\_get\_cycle\_event** function returns in **ev** the event and optional unit mask descriptors for the event that counts elapsed  cycles. Depending on the PMU model, there may be unit mask(s) necessary to count cycles. Application must check the value returned in **ev-\>num\_masks**.

The **pfm\_get\_inst\_retired\_event** function returns in **ev** the event and optional unit mask descriptors for the event that counts the number of retured instruction. Depending on the PMU model, there may be unit mask(s) necessary to count retired instructions. Application must check the value returned in **ev-\>num\_masks**.

## RETURN

All functions return whether or not the call was successful. A return value of **PFMLIB\_SUCCESS** indicates success,  otherwise the value is the error code.

## ERRORS

**PFMLIB\_ERR\_NOINIT** the library has not been initialized properly.

- **PFMLIB\_ERR\_INVAL**

  the **ev** parameter is NULL.

- **PFMLIB\_ERR\_NOTSUPP**

  the host PMU does not define an event to count cycles or instructions retired.

- Stephane Eranian \<eranian@hpl.hp.com\>

  ## AUTHOR