Tribblix: manual page: cpc

CPC_STRTOEVENT(3CPC) CPU Performance Counters Library Functions

NAME

cpc_strtoevent, cpc_eventtostr - translate strings to and from events

SYNOPSIS

cc [ flag... ] file... -lcpc [ library... ]
#include <libcpc.h>

int cpc_strtoevent(int cpuver, const char *spec, cpc_event_t *event);

char *cpc_eventtostr(cpc_event_t *event);

DESCRIPTION

The cpc_strtoevent() function translates an event specification to
the appropriate collection of control bits in a cpc_event_t structure
pointed to by the event argument. The event specification is a
getsubopt(3C)-style string that describes the event and any
attributes that the processor can apply to the event or events. If
successful, the function returns 0, the ce_cpuver field and the ISA-
dependent control registers of event are initialized appropriately,
and the rest of the cpc_event_t structure is initialized to 0.

The cpc_eventtostr() function takes an event and constructs a compact
canonical string representation for that event.

RETURN VALUES

Upon successful completion, cpc_strtoevent() returns 0. If the string
cannot be decoded, a non-zero value is returned and a message is
printed using the library's error-reporting mechanism (see
cpc_seterrfn(3CPC)).

Upon successful completion, cpc_eventtostr() returns a pointer to a
string. The string returned must be freed by the caller using
free(3C). If cpc_eventtostr() fails, a null pointer is returned.

USAGE

The event selection syntax used is processor architecture-dependent.
The supported processor families allow variations on how events are
counted as well as what events can be counted. This information is
available in compact form from the cpc_getusage() function (see
cpc_getcpuver(3CPC)), but is explained in further detail below.

UltraSPARC

On UltraSPARC processors, the syntax for setting options is as
follows:

pic0=<eventspec>,pic1=<eventspec> [,sys] [,nouser]

This syntax, which reflects the simplicity of the options available
using the %pcr register, forces both counter events to be selected.
By default only user events are counted; however, the sys keyword
allows system (kernel) events to be counted as well. User event
counting can be disabled by specifying the nouser keyword.

The keywords pic0 and pic1 may be omitted; they can be used to
resolve ambiguities if they exist.

Pentium I

On Pentium processors, the syntax for setting counter options is as
follows:

pic0=<eventspec>,pic1=<eventspec> [,sys[[0|1]]] [,nouser[[0|1]]]
[,noedge[[0|1]]] [,pc[[0|1]]]

The syntax and semantics are the same as UltraSPARC, except that is
possible to specify whether a particular counter counts user or
system events. If unspecified, the specification is presumed to apply
to both counters.

There are some additional keywords. The noedge keyword specifies that
the counter should count clocks (duration) instead of events. The pc
keyword allows the external pin control pins to be set high (defaults
to low). When the pin control register is set high, the external pin
will be asserted when the associated register overflows. When the pin
control register is set low, the external pin will be asserted when
the counter has been incremented. The electrical effect of driving
the pin is dependent upon how the motherboard manufacturer has chosen
to connect it, if it is connected at all.

Pentium II

For Pentium II processors, the syntax is substantially more complex,
reflecting the complex configuration options available:

pic0=<eventspec>,pic1=<eventspec> [,sys[[0|1]]]
[,nouser[[0|1]]] [,noedge[[0|1]]] [,pc[[0|1]]] [,inv[[0|1]]] [,int[[0|1]]]
[,cmask[0|1]=<maskspec>] [,umask[0|1]=<maskspec>]

This syntax is a straightforward extension of the earlier syntax. The
additional inv, int, cmask0, cmask1, umask0, and umask1 keywords
allow extended counting semantics. The mask specification is a number
between 0 and 255, expressed in hexadecimal, octal or decimal
notation.

EXAMPLES

SPARC

Example 1: SPARC Example.

cpc_event_t event;
char *setting = "pic0=EC_ref,pic1=EC_hit"; /* UltraSPARC-specific */

if (cpc_strtoevent(cpuver, setting, &event) != 0)
/* can't measure 'setting' on this processor */
else
setting = cpc_eventtostr(&event);

ATTRIBUTES

NOTES

The cpc_strtoevent() and cpc_eventtostr() functions exist for binary
compatibility only. Source containing these functions will not
compile. These functions are obsolete and might be removed in a
future release. Applications should use cpc_set_add_request(3CPC)
instead.

These functions are provided as a convenience only. As new processors
are usually released asynchronously with software, the library allows
the pic0 and pic1 keywords to interpret numeric values specified
directly in hexadecimal, octal, or decimal.

March 10, 2023 CPC_STRTOEVENT(3CPC)