CPC Configuration Interfaces

The configuration interfaces allow you to perform tasks such as create an empty set, add requests to a set, and change the preset value of a request. The following are the configuration interfaces:

• cpc_set_create()

• cpc_set_destroy()

• cpc_set_add_request()

• cpc_set_request_preset()

cpc_set_t *cpc_set_create(cpc_t *cpc);
int cpc_set_destroy(cpc_t *cpc, cpc_set_t *set);
int cpc_set_add_request(cpc_t *cpc, cpc_set_t *set, const char *event,
          uint64_t preset, uint_t flags, uint_t nattrs,
          const cpc_attr_t *attrs);
int cpc_set_request_preset(cpc_t *cpc, cpc_set_t *set, int index,
          uint64_t preset);

The opaque data type cpc_set_t represents collections of requests. The collections are called sets. The cpc_set_create() function creates an empty set. The cpc_set_destroy() function destroys a set and frees all the memory used by the set. Destroying a set releases the hardware resources the set uses.

The cpc_set_add_request() function adds requests to a set. A request has the following parameters:

attrs

A pointer to an array of cpc_attr_t structures.

event

A string that specifies the name of the event to count.

flags

The results of the logical OR operation applied to a group of request flags.

nattrs

The number of attributes in the array that attrs points to.

preset

A 64-bit unsigned integer that is used as the initial value of the counter.

The following list describes the valid request flags:

CPC_COUNT_USER

This flag enables counting of events that occur while the CPU is executing in user mode.

CPC_COUNT_SYSTEM

This flag enables counting of events that occur while the CPU is executing in privileged mode.

CPC_OVF_NOTIFY_EMT

This flag requests notification of hardware counter overflow.

The CPC interfaces pass attributes as an array of cpc_attr_t structures.

When the cpc_set_add_request() function returns successfully, it returns an index. The index references the data generated by the request added by the call to the cpc_set_add_request() function.

The cpc_set_request_preset() function changes the preset value of a request. This enables the re-binding of an overflowed set with new presets.

The cpc_walk_requests() function calls a user-provided action() routine on each request in cpc_set_t. The value of the arg parameter is passed to the user routine without interpretation. The cpc_walk_requests() function allows applications to print the configuration of each request in a set. The syntax for the cpc_walk_requests() function is as follows:

void cpc_walk_requests(cpc_t *cpc, cpc_set_t *set, void *arg,
void (*action)(void *arg, int index, const char *event,
uint64_t preset, uint_t flags, int nattrs,
            const cpc_attr_t *attrs));