|
CPU Performance Counters Library Functions | cpc_shared_open(3CPC) |
| cpc_shared_open, cpc_shared_bind_event, cpc_shared_take_sample, cpc_shared_rele, cpc_shared_close - use CPU performance
counters on processors |
SYNOPSIS
|
cc [ flag... ] file... -lcpc [ library... ]
#include <libcpc.h> int cpc_shared_open(void); |
| int cpc_shared_bind_event(int fd, cpc_event_t *event, int flags); |
| int cpc_shared_take_sample(int fd, cpc_event_t *event); |
| int cpc_shared_rele(int fd); |
| void cpc_shared_close(int fd); |
|
The cpc_shared_open() function allows the caller
to access the hardware counters in such a way that the performance of the
currently bound CPU can be measured. The function returns a file descriptor
if successful. Only one such open can be active at a time on any CPU.
The cpc_shared_bind_event(), cpc_shared_take_sample(), and cpc_shared_rele() functions are directly
analogous to the corresponding cpc_bind_event(), cpc_take_sample(), and cpc_rele() functions
described on the cpc_bind_event(3CPC)manual
page, except that they operate on the counters of a particular processor.
|
|
If a thread wishes to access the counters using this interface, it must do so using a thread bound to an lwp, (see the THR_BOUND flag to thr_create(3THR)),
that has in turn bound itself to a processor using processor_bind(2).
Unlike the cpc_bind_event(3CPC)
family of functions, no counter context is attached to those lwps, so the
performance counter samples from the processors reflects the system-wide
usage, instead of per-lwp usage.
The first successful invocation of cpc_shared_open()
will immediately invalidate all
existing performance counter context on the system, and prevent all subsequent attempts to bind counter
context to lwps from succeeding anywhere on the system until the last caller
invokes cpc_shared_close().
This is because it is impossible to simultaneously use the counters
to accurately measure per-lwp and system-wide events, so there is an exclusive
interlock between these uses.
Access to the shared counters is mediated by file permissions on a cpc pseudo device. As shipped, only the superuser is allowed
to access the shared device; this is because doing so prevents use of the
counters on a per-lwp basis to any other users.
The CPC_BIND_LWP_INHERIT and CPC_BIND_EMT_OVF flags are invalid for the shared interface.
|
|
On success, the functions (apart from cpc_shared_close())
return 0. On failure, the functions return -1 and set errno, to indicate the reason.
|
|
-
ENXIO
- The current machine either has
no performance counters, or has been configured to disallow access to them
system-wide.
-
EACCES
- The caller does not have appropriate privilege to access the CPU performance
counters system-wide.
-
EAGAIN
- For cpc_shared_open(), this value implies that the counters on the
bound cpu are busy because they are already being used to measure system-wide
events by some other caller.
-
EAGAIN
- Otherwise, this return value implies that the counters are not available
because the thread has been unbound from the processor it was bound to at
open time. Robust programs should be coded to expect this behavior, and
should invoke cpc_shared_close(), before retrying
the operation.
-
EINVAL
- The counters cannot be accessed on the current CPU because the calling thread
is not bound to that CPU using processor_bind(2).
-
EFAULT
- The event argument specifies a bad address.
-
ENOTSUP
- The caller has attempted an operation that is illegal or not supported on
the current platform.
|
|
See attributes(5)
for descriptions of the following attributes:
ATTRIBUTE TYPE | ATTRIBUTE VALUE |
MT-Level | MT-Safe |
Availability | SUNWcpcu (32-bit) |
| SUNWcpcux (64-bit) |
Interface Stability | Evolving |
|
| |