CPU Performance Counters Library Functions cpcstrtoevent(3CPC)
NAME
cpcstrtoevent, cpceventtostr - translate strings to and
from events
SYNOPSIS
cc [ flag... ] file... -lcpc [ library... ]
#include
int cpcstrtoevent(int cpuver, const char *spec, cpceventt *event);
char *cpceventtostr(cpceventt *event);
DESCRIPTION
The cpcstrtoevent() function translates an event specifica-
tion to the appropriate collection of control bits in a
cpceventt 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 funci-
ton returns 0, the cecpuver field and the ISA-dependent
control registers of event are initialized appropriately,
and the rest of the cpceventt structure is initialized to
0.
The cpceventtostr() function takes an event and constructs
a compact canonical string representation for that event.
RETURN VALUES
Upon successful completion, cpcstrtoevent() 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 cpcseterrfn(3CPC)).
Upon successful completion, cpceventtostr() returns a
pointer to a string. The string returned must be freed by
the caller using free(3C). If cpceventtostr() 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 cpcgetusage() function (see cpcgetcpuver(3CPC)), but
is explained in further detail below.
UltraSPARC
SunOS 5.11 Last change: 28 Mar 2005 1
CPU Performance Counters Library Functions cpcstrtoevent(3CPC)
On UltraSPARC processors, the syntax for setting options is
as follows:
pic0=,pic1= [,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=,pic1= [,sys[01] [,nouser[01]
[,noedge[01] [,pc[01]
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 specifica-
tion 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 electr-
ical effect of driving the pin is dependent uptoon how the
motherboard manufacturer has chosen to connect it, if it is
connected at all.
Pentium I
For Pentium I processors, the syntax is substantially more
complex, reflecting the complex configuration options avail-
able:
SunOS 5.11 Last change: 28 Mar 2005 2
CPU Performance Counters Library Functions cpcstrtoevent(3CPC)
pic0=,pic1= [,sys[01]
[,nouser[01] [,noedge[01] [,pc[01] [,inv[01] [,int[01]
[,cmask[01]=] [,umask[01]=]
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.
cpceventt event;
char *setting = "pic0=ECref,pic1=EChit"; /* UltraSPARC-specific */
if (cpcstrtoevent(cpuver, setting, &event) != 0)
/* can't measure 'setting' on this processor */
else
setting = cpceventtostr(&event);
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE VALUE
Interface Stability Obsolete
MT-Level MT-Safe
SEE ALSO
cpc(3CPC), cpcgetcpuver(3CPC), cpcsetaddrequest(3CPC),
cpcseterrfn(3CPC), free(3C), getsubopt(3C), libcpc(3LIB),
attributes(5)
NOTES
The cpcstrtoevent() and cpceventtostr() functions exist
for binary compatibility only. Source containing these func-
tions will not compile. These functions are obsolete and
might be removed in a future release. Applications should
use cpcsetaddrequest(3CPC) instead.
SunOS 5.11 Last change: 28 Mar 2005 3
CPU Performance Counters Library Functions cpcstrtoevent(3CPC)
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.
SunOS 5.11 Last change: 28 Mar 2005 4
|
