diff options
Diffstat (limited to 'usr/src/man/man3cpc')
23 files changed, 5613 insertions, 0 deletions
diff --git a/usr/src/man/man3cpc/Makefile b/usr/src/man/man3cpc/Makefile new file mode 100644 index 0000000000..53b008570f --- /dev/null +++ b/usr/src/man/man3cpc/Makefile @@ -0,0 +1,160 @@ +# +# This file and its contents are supplied under the terms of the +# Common Development and Distribution License ("CDDL"), version 1.0. +# You may only use this file in accordance with the terms of version +# 1.0 of the CDDL. +# +# A full copy of the text of the CDDL should have accompanied this +# source. A copy of the CDDL is also available via the Internet +# at http://www.illumos.org/license/CDDL. +# + +# Copyright 2011, Richard Lowe + +include ../../Makefile.master + +MANSECT = 3cpc + +MANFILES = cpc.3cpc \ + cpc_access.3cpc \ + cpc_bind_curlwp.3cpc \ + cpc_bind_event.3cpc \ + cpc_buf_create.3cpc \ + cpc_count_usr_events.3cpc \ + cpc_enable.3cpc \ + cpc_event.3cpc \ + cpc_event_diff.3cpc \ + cpc_getcpuver.3cpc \ + cpc_npic.3cpc \ + cpc_open.3cpc \ + cpc_pctx_bind_event.3cpc \ + cpc_set_create.3cpc \ + cpc_seterrfn.3cpc \ + cpc_seterrhndlr.3cpc \ + cpc_shared_open.3cpc \ + cpc_strtoevent.3cpc \ + cpc_version.3cpc \ + generic_events.3cpc \ + pctx_capture.3cpc \ + pctx_set_events.3cpc + +MANSOFILES = cpc_bind_cpu.3cpc \ + cpc_bind_pctx.3cpc \ + cpc_buf_add.3cpc \ + cpc_buf_copy.3cpc \ + cpc_buf_destroy.3cpc \ + cpc_buf_get.3cpc \ + cpc_buf_hrtime.3cpc \ + cpc_buf_set.3cpc \ + cpc_buf_sub.3cpc \ + cpc_buf_tick.3cpc \ + cpc_buf_zero.3cpc \ + cpc_caps.3cpc \ + cpc_cciname.3cpc \ + cpc_close.3cpc \ + cpc_count_sys_events.3cpc \ + cpc_cpuref.3cpc \ + cpc_disable.3cpc \ + cpc_event_accum.3cpc \ + cpc_eventtostr.3cpc \ + cpc_getcciname.3cpc \ + cpc_getcpuref.3cpc \ + cpc_getnpic.3cpc \ + cpc_getusage.3cpc \ + cpc_pctx_invalidate.3cpc \ + cpc_pctx_rele.3cpc \ + cpc_pctx_take_sample.3cpc \ + cpc_rele.3cpc \ + cpc_request_preset.3cpc \ + cpc_set_add_request.3cpc \ + cpc_set_destroy.3cpc \ + cpc_set_restart.3cpc \ + cpc_set_sample.3cpc \ + cpc_shared_bind_event.3cpc \ + cpc_shared_close.3cpc \ + cpc_shared_rele.3cpc \ + cpc_shared_take_sample.3cpc \ + cpc_take_sample.3cpc \ + cpc_unbind.3cpc \ + cpc_walk_attrs.3cpc \ + cpc_walk_events_all.3cpc \ + cpc_walk_events_pic.3cpc \ + cpc_walk_generic_events_all.3cpc \ + cpc_walk_generic_events_pic.3cpc \ + cpc_walk_names.3cpc \ + cpc_walk_requests.3cpc \ + pctx_create.3cpc \ + pctx_release.3cpc \ + pctx_run.3cpc + +MANFILES += $(MANSOFILES) + +cpc_bind_cpu.3cpc := SOSRC = man3cpc/cpc_bind_curlwp.3cpc +cpc_bind_pctx.3cpc := SOSRC = man3cpc/cpc_bind_curlwp.3cpc +cpc_request_preset.3cpc := SOSRC = man3cpc/cpc_bind_curlwp.3cpc +cpc_set_restart.3cpc := SOSRC = man3cpc/cpc_bind_curlwp.3cpc +cpc_unbind.3cpc := SOSRC = man3cpc/cpc_bind_curlwp.3cpc + +cpc_rele.3cpc := SOSRC = man3cpc/cpc_bind_event.3cpc +cpc_take_sample.3cpc := SOSRC = man3cpc/cpc_bind_event.3cpc + +cpc_buf_add.3cpc := SOSRC = man3cpc/cpc_buf_create.3cpc +cpc_buf_copy.3cpc := SOSRC = man3cpc/cpc_buf_create.3cpc +cpc_buf_destroy.3cpc := SOSRC = man3cpc/cpc_buf_create.3cpc +cpc_buf_get.3cpc := SOSRC = man3cpc/cpc_buf_create.3cpc +cpc_buf_hrtime.3cpc := SOSRC = man3cpc/cpc_buf_create.3cpc +cpc_buf_set.3cpc := SOSRC = man3cpc/cpc_buf_create.3cpc +cpc_buf_sub.3cpc := SOSRC = man3cpc/cpc_buf_create.3cpc +cpc_buf_tick.3cpc := SOSRC = man3cpc/cpc_buf_create.3cpc +cpc_buf_zero.3cpc := SOSRC = man3cpc/cpc_buf_create.3cpc +cpc_set_sample.3cpc := SOSRC = man3cpc/cpc_buf_create.3cpc + +cpc_count_sys_events.3cpc := SOSRC = man3cpc/cpc_count_usr_events.3cpc + +cpc_disable.3cpc := SOSRC = man3cpc/cpc_enable.3cpc + +cpc_event_accum.3cpc := SOSRC = man3cpc/cpc_event_diff.3cpc + +cpc_getcciname.3cpc := SOSRC = man3cpc/cpc_getcpuver.3cpc +cpc_getcpuref.3cpc := SOSRC = man3cpc/cpc_getcpuver.3cpc +cpc_getnpic.3cpc := SOSRC = man3cpc/cpc_getcpuver.3cpc +cpc_getusage.3cpc := SOSRC = man3cpc/cpc_getcpuver.3cpc +cpc_walk_names.3cpc := SOSRC = man3cpc/cpc_getcpuver.3cpc + +cpc_caps.3cpc := SOSRC = man3cpc/cpc_npic.3cpc +cpc_cciname.3cpc := SOSRC = man3cpc/cpc_npic.3cpc +cpc_cpuref.3cpc := SOSRC = man3cpc/cpc_npic.3cpc +cpc_walk_attrs.3cpc := SOSRC = man3cpc/cpc_npic.3cpc +cpc_walk_events_all.3cpc := SOSRC = man3cpc/cpc_npic.3cpc +cpc_walk_events_pic.3cpc := SOSRC = man3cpc/cpc_npic.3cpc +cpc_walk_generic_events_all.3cpc := SOSRC = man3cpc/cpc_npic.3cpc +cpc_walk_generic_events_pic.3cpc := SOSRC = man3cpc/cpc_npic.3cpc + +cpc_close.3cpc := SOSRC = man3cpc/cpc_open.3cpc + +cpc_pctx_invalidate.3cpc := SOSRC = man3cpc/cpc_pctx_bind_event.3cpc +cpc_pctx_rele.3cpc := SOSRC = man3cpc/cpc_pctx_bind_event.3cpc +cpc_pctx_take_sample.3cpc := SOSRC = man3cpc/cpc_pctx_bind_event.3cpc + +cpc_set_add_request.3cpc := SOSRC = man3cpc/cpc_set_create.3cpc +cpc_set_destroy.3cpc := SOSRC = man3cpc/cpc_set_create.3cpc +cpc_walk_requests.3cpc := SOSRC = man3cpc/cpc_set_create.3cpc + +cpc_shared_bind_event.3cpc := SOSRC = man3cpc/cpc_shared_open.3cpc +cpc_shared_close.3cpc := SOSRC = man3cpc/cpc_shared_open.3cpc +cpc_shared_rele.3cpc := SOSRC = man3cpc/cpc_shared_open.3cpc +cpc_shared_take_sample.3cpc := SOSRC = man3cpc/cpc_shared_open.3cpc + +cpc_eventtostr.3cpc := SOSRC = man3cpc/cpc_strtoevent.3cpc + +pctx_create.3cpc := SOSRC = man3cpc/pctx_capture.3cpc +pctx_release.3cpc := SOSRC = man3cpc/pctx_capture.3cpc +pctx_run.3cpc := SOSRC = man3cpc/pctx_capture.3cpc + +.KEEP_STATE: + +include ../Makefile.man + +install: $(ROOTMANFILES) + + diff --git a/usr/src/man/man3cpc/cpc.3cpc b/usr/src/man/man3cpc/cpc.3cpc new file mode 100644 index 0000000000..c254e5a960 --- /dev/null +++ b/usr/src/man/man3cpc/cpc.3cpc @@ -0,0 +1,160 @@ +'\" te +.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH cpc 3CPC "8 Oct 2008" "SunOS 5.11" "CPU Performance Counters Library Functions" +.SH NAME +cpc \- hardware performance counters +.SH DESCRIPTION +.sp +.LP +Modern microprocessors contain \fIhardware performance counters\fR that allow +the measurement of many different hardware events related to CPU behavior, +including instruction and data cache misses as well as various internal states +of the processor. The counters can be configured to count user events, system +events, or both. Data from the performance counters can be used to analyze and +tune the behavior of software on a particular type of processor. +.sp +.LP +Most processors are able to generate an interrupt on counter overflow, allowing +the counters to be used for various forms of profiling. +.sp +.LP +This manual page describes a set of APIs that allow Solaris applications to use +these counters. Applications can measure their own behavior, the behavior of +other applications, or the behavior of the whole system. +.SS "Shared Counters or Private Counters" +.sp +.LP +There are two principal models for using these performance counters. Some users +of these statistics want to observe system-wide behavior. Other users want to +view the performance counters as part of the register set exported by each +\fBLWP\fR. On a machine performing more than one activity, these two models are +in conflict because the counters represent a critical hardware resource that +cannot simultaneously be both shared and private. +.SS "Configuration Interfaces" +.sp +.LP +The following configuration interfaces are provided: +.sp +.ne 2 +.mk +.na +\fB\fBcpc_open\fR(3CPC)\fR +.ad +.RS 21n +.rt +Check the version the application was compiled with against the version of the +library. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBcpc_cciname\fR(3CPC)\fR +.ad +.RS 21n +.rt +Return a printable string to describe the performance counters of the +processor. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBcpc_npic\fR(3CPC)\fR +.ad +.RS 21n +.rt +Return the number of performance counters on the processor. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBcpc_cpuref\fR(3CPC)\fR +.ad +.RS 21n +.rt +Return a reference to documentation that should be consulted to understand how +to use and interpret data from the performance counters. +.RE + +.SS "Performance Counter Access" +.sp +.LP +Performance counters can be present in hardware but not acccessible because +either some of the necessary system software components are not available or +not installed, or the counters might be in use by other processes. The +\fBcpc_open\fR(3CPC) function determines the accessibility of the counters and +must be invoked before any attempt to program the counters. +.SS "Finding Events" +.sp +.LP +Each different type of processor has its own set of events available for +measurement. The \fBcpc_walk_events_all\fR(3CPC) and +\fBcpc_walk_events_pic\fR(3CPC) functions allow an application to determine the +names of events supported by the underlying processor. A collection of generic, +platform independent event names are defined by \fBgeneric_events\fR(3CPC). +Each generic event maps to an underlying hardware event specific to the +underlying processor and any optional attributes. The +\fBcpc_walk_generic_events_all\fR(3CPC) and +\fBcpc_walk_generic_events_pic\fR(3CPC) functions allow an application to +determine the generic events supported on the underlying platform. +.SS "Using Attributes" +.sp +.LP +Some processors have advanced performance counter capabilities that are +configured with attributes. The \fBcpc_walk_attrs\fR(3CPC) function can be used +to determine the names of attributes supported by the underlying processor. The +documentation referenced by \fBcpc_cpuref\fR(3CPC) should be consulted to +understand the meaning of a processor's performance counter attributes. +.SS "Performance Counter Context" +.sp +.LP +Each processor on the system possesses its own set of performance counter +registers. For a single process, it is often desirable to maintain the illusion +that the counters are an intrinsic part of that process (whichever processors +it runs on), since this allows the events to be directly attributed to the +process without having to make passive all other activity on the system. +.sp +.LP +To achieve this behavior, the library associates \fIperformance counter +context\fR with each \fBLWP\fR in the process. The context consists of a small +amount of kernel memory to hold the counter values when the \fBLWP\fR is not +running, and some simple kernel functions to save and restore those counter +values from and to the hardware registers when the \fBLWP\fR performs a normal +context switch. A process can only observe and manipulate its own copy of the +performance counter control and data registers. +.SS "Performance Counters In Other Processes" +.sp +.LP +Though applications can be modified to instrument themselves as demonstrated +above, it is frequently useful to be able to examine the behavior of an +existing application without changing the source code. A separate library, +\fBlibpctx\fR, provides a simple set of interfaces that use the facilities of +\fBproc\fR(4) to control a target process, and together with functions in +\fBlibcpc\fR, allow \fBtruss\fR-like tools to be constructed to measure the +performance counters in other applications. An example of one such application +is \fBcputrack\fR(1). +.sp +.LP +The functions in \fBlibpctx\fR are independent of those in \fBlibcpc\fR. These +functions manage a process using an event-loop paradigm \(em that is, the +execution of certain system calls by the controlled process cause the library +to stop the controlled process and execute callback functions in the context of +the controlling process. These handlers can perform various operations on the +target process using APIs in \fBlibpctx\fR and \fBlibcpc\fR that consume +\fBpctx_t\fR handles. +.SH SEE ALSO +.sp +.LP +\fBcputrack\fR(1), \fBcpustat\fR(1M), \fBcpc_bind_curlwp\fR(3CPC), +\fBcpc_buf_create\fR(3CPC), \fBcpc_enable\fR(3CPC), \fBcpc_npic\fR(3CPC), +\fBcpc_open\fR(3CPC), \fBcpc_set_create\fR(3CPC), \fBcpc_seterrhndlr\fR(3CPC), +\fBgeneric_events\fR(3CPC), \fBlibcpc\fR(3LIB), \fBpctx_capture\fR(3CPC), +\fBpctx_set_events\fR(3CPC), \fBproc\fR(4) diff --git a/usr/src/man/man3cpc/cpc_access.3cpc b/usr/src/man/man3cpc/cpc_access.3cpc new file mode 100644 index 0000000000..86fe014b64 --- /dev/null +++ b/usr/src/man/man3cpc/cpc_access.3cpc @@ -0,0 +1,102 @@ +'\" te +.\" Copyright (c) 2005, Sun Microsystems, Inc. +.\" All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH cpc_access 3CPC "28 Mar 2005" "SunOS 5.11" "CPU Performance Counters Library Functions" +.SH NAME +cpc_access \- test access CPU performance counters +.SH SYNOPSIS +.LP +.nf +cc [ \fIflag\fR... ] \fIfile\fR... \(milcpc [ \fIlibrary\fR... ] +#include <libcpc.h> + +\fBint\fR \fBcpc_access\fR(\fBvoid\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +Access to CPU performance counters is possible only on systems where the +appropriate hardware exists and is correctly configured. The \fBcpc_access()\fR +function \fBmust\fR be used to determine if the hardware exists and is +accessible on the platform before any of the interfaces that use the counters +are invoked. +.sp +.LP +When the hardware is available, access to the per-process counters is always +allowed to the process itself, and allowed to other processes mediated using +the existing security mechanisms of \fB/proc\fR. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBcpc_access()\fR returns \fB0\fR. Otherwise, it +returns \fB\(mi1\fR and sets \fBerrno\fR to indicate the error. +.sp +.LP +By default, two common \fBerrno\fR values are decoded and cause the library to +print an error message using its reporting mechanism. See +\fBcpc_seterrfn\fR(3CPC) for a description of how this behavior can be +modified. +.SH ERRORS +.sp +.LP +The \fBcpc_access()\fR function will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEAGAIN\fR\fR +.ad +.RS 10n +.rt +Another process may be sampling system-wide CPU statistics. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOSYS\fR\fR +.ad +.RS 10n +.rt +CPU performance counters are inaccessible on this machine. This error can occur +when the machine supports CPU performance counters, but some software +components are missing. Check to see that all CPU Performance Counter packages +have been correctly installed. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +lw(2.75i) |lw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelMT-Safe +_ +Interface StabilityObsolete +.TE + +.SH SEE ALSO +.sp +.LP +\fBcpc\fR(3CPC), \fBcpc_open\fR(3CPC), \fBcpc_seterrfn\fR(3CPC), +\fBlibcpc\fR(3LIB), \fBproc\fR(4), \fBattributes\fR(5) +.SH NOTES +.sp +.LP +The \fBcpc_access()\fR function exists for binary compatibility only. Source +containing this function will not compile. This function is obsolete and might +be removed in a future release. Applications should use \fBcpc_open\fR(3CPC) +instead. diff --git a/usr/src/man/man3cpc/cpc_bind_curlwp.3cpc b/usr/src/man/man3cpc/cpc_bind_curlwp.3cpc new file mode 100644 index 0000000000..66c7ab91e4 --- /dev/null +++ b/usr/src/man/man3cpc/cpc_bind_curlwp.3cpc @@ -0,0 +1,563 @@ +'\" te +.\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH cpc_bind_curlwp 3CPC "05 Mar 2007" "SunOS 5.11" "CPU Performance Counters Library Functions" +.SH NAME +cpc_bind_curlwp, cpc_bind_pctx, cpc_bind_cpu, cpc_unbind, cpc_request_preset, +cpc_set_restart \- bind request sets to hardware counters +.SH SYNOPSIS +.LP +.nf +cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-lcpc\fR [ \fIlibrary\fR\&.\|.\|. ] +#include <libcpc.h> + +\fBint\fR \fBcpc_bind_curlwp\fR(\fBcpc_t *\fR\fIcpc\fR, \fBcpc_set_t *\fR\fIset\fR, \fBuint_t\fR \fIflags\fR); +.fi + +.LP +.nf +\fBint\fR \fBcpc_bind_pctx\fR(\fBcpc_t *\fR\fIcpc\fR, \fBpctx_t *\fR\fIpctx\fR, \fBid_t\fR \fIid\fR, \fBcpc_set_t *\fR\fIset\fR, + \fBuint_t\fR \fIflags\fR); +.fi + +.LP +.nf +\fBint\fR \fBcpc_bind_cpu\fR(\fBcpc_t *\fR\fIcpc\fR, \fBprocessorid_t\fR \fIid\fR, \fBcpc_set_t *\fR\fIset\fR, + \fBuint_t\fR \fIflags\fR); +.fi + +.LP +.nf +\fBint\fR \fBcpc_unbind\fR(\fBcpc_t *\fR\fIcpc\fR, \fBcpc_set_t *\fR\fIset\fR); +.fi + +.LP +.nf +\fBint\fR \fBcpc_request_preset\fR(\fBcpc_t *\fR\fIcpc\fR, \fBint\fR \fIindex\fR, \fBuint64_t\fR \fIpreset\fR); +.fi + +.LP +.nf +\fBint\fR \fBcpc_set_restart\fR(\fBcpc_t *\fR\fIcpc\fR, \fBcpc_set_t *\fR\fIset\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +These functions program the processor's hardware counters according to the +requests contained in the \fIset\fR argument. If these functions are +successful, then upon return the physical counters will have been assigned to +count events on behalf of each request in the set, and each counter will be +enabled as configured. +.sp +.LP +The \fBcpc_bind_curlwp()\fR function binds the set to the calling \fBLWP\fR. If +successful, a performance counter context is associated with the \fBLWP\fR that +allows the system to virtualize the hardware counters to that specific +\fBLWP\fR. +.sp +.LP +By default, the system binds the set to the current \fBLWP\fR only. If the +\fBCPC_BIND_LWP_INHERIT\fR flag is present in the \fIflags\fR argument, +however, any subsequent \fBLWP\fRs created by the current \fBLWP\fR will +inherit a copy of the request set. The newly created \fBLWP\fR will have its +virtualized 64-bit counters initialized to the preset values specified in +\fIset\fR, and the counters will be enabled and begin counting events on behalf +of the new \fBLWP\fR. This automatic inheritance behavior can be useful when +dealing with multithreaded programs to determine aggregate statistics for the +program as a whole. +.sp +.LP +If the \fBCPC_BIND_LWP_INHERIT\fR flag is specified and any of the requests in +the set have the \fBCPC_OVF_NOTIFY_EMT\fR flag set, the process will +immediately dispatch a \fBSIGEMT\fR signal to the freshly created \fBLWP\fR so +that it can preset its counters appropriately on the new \fBLWP\fR. This +initialization condition can be detected using \fBcpc_set_sample\fR(3CPC) and +looking at the counter value for any requests with \fBCPC_OVF_NOTIFY_EMT\fR +set. The value of any such counters will be \fBUINT64_MAX\fR. +.sp +.LP +The \fBcpc_bind_pctx()\fR function binds the set to the \fBLWP\fR specified by +the \fIpctx\fR-\fIid\fR pair, where \fIpctx\fR refers to a handle returned from +\fBlibpctx\fR and \fIid\fR is the ID of the desired \fBLWP\fR in the target +process. If successful, a performance counter context is associated with the +specified \fBLWP\fR and the system virtualizes the hardware counters to that +specific \fBLWP\fR. The \fIflags\fR argument is reserved for future use and +must always be \fB0\fR. +.sp +.LP +The \fBcpc_bind_cpu()\fR function binds the set to the specified CPU and +measures events occurring on that CPU regardless of which \fBLWP\fR is running. +Only one such binding can be active on the specified CPU at a time. As long as +any application has bound a set to a CPU, per-\fBLWP\fR counters are +unavailable and any attempt to use either \fBcpc_bind_curlwp()\fR or +\fBcpc_bind_pctx()\fR returns \fBEAGAIN\fR. The first invocation of +\fBcpc_bind_cpu()\fR invalidates all currently bound per-\fBLWP\fR counter +sets, and any attempt to sample an invalidated set returns \fBEAGAIN\fR. To +bind to a CPU, the library binds the calling \fBLWP\fR to the measured CPU with +\fBprocessor_bind\fR(2). The application must not change its processor binding +until after it has unbound the set with \fBcpc_unbind()\fR. The \fIflags\fR +argument is reserved for future use and must always be \fB0\fR. +.sp +.LP +The \fBcpc_request_preset()\fR function updates the preset and current value +stored in the indexed request within the currently bound set, thereby changing +the starting value for the specified request for the calling \fBLWP\fR only, +which takes effect at the next call to \fBcpc_set_restart()\fR. +.sp +.LP +When a performance counter counting on behalf of a request with the +\fBCPC_OVF_NOTIFY_EMT\fR flag set overflows, the performance counters are +frozen and the \fBLWP\fR to which the set is bound receives a \fBSIGEMT\fR +signal. The \fBcpc_set_restart()\fR function can be called from a \fBSIGEMT\fR +signal handler function to quickly restart the hardware counters. Counting +begins from each request's original preset (see +\fBcpc_set_add_request\fR(3CPC)), or from the preset specified in a prior call +to \fBcpc_request_preset()\fR. Applications performing performance counter +overflow profiling should use the \fBcpc_set_restart()\fR function to quickly +restart counting after receiving a \fBSIGEMT\fR overflow signal and recording +any relevant program state. +.sp +.LP +The \fBcpc_unbind()\fR function unbinds the set from the resource to which it +is bound. All hardware resources associated with the bound set are freed and if +the set was bound to a CPU, the calling \fBLWP\fR is unbound from the +corresponding CPU. See \fBprocessor_bind\fR(2). +.SH RETURN VALUES +.sp +.LP +Upon successful completion these functions return 0. Otherwise, -1 is returned +and \fBerrno\fR is set to indicate the error. +.SH ERRORS +.sp +.LP +Applications wanting to get detailed error values should register an error +handler with \fBcpc_seterrhndlr\fR(3CPC). Otherwise, the library will output a +specific error description to \fBstderr\fR. +.sp +.LP +These functions will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEACCES\fR\fR +.ad +.RS 11n +.rt +For \fBcpc_bind_curlwp()\fR, the system has Pentium 4 processors with +HyperThreading and at least one physical processor has more than one hardware +thread online. See NOTES. +.sp +For \fBcpc_bind_cpu()\fR, the process does not have the \fIcpc_cpu\fR privilege +to access the CPU's counters. +.sp +For \fBcpc_bind_curlwp()\fR, \fBcpc_bind_cpc()\fR, and \fBcpc_bind_pctx()\fR, +access to the requested hypervisor event was denied. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEAGAIN\fR\fR +.ad +.RS 11n +.rt +For \fBcpc_bind_curlwp()\fR and \fBcpc_bind_pctx()\fR, the performance counters +are not available for use by the application. +.sp +For \fBcpc_bind_cpu()\fR, another process has already bound to this CPU. Only +one process is allowed to bind to a CPU at a time and only one set can be bound +to a CPU at a time. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 11n +.rt +The set does not contain any requests or \fBcpc_set_add_request()\fR was not +called. +.sp +The value given for an attribute of a request is out of range. +.sp +The system could not assign a physical counter to each request in the system. +See NOTES. +.sp +One or more requests in the set conflict and might not be programmed +simultaneously. +.sp +The \fIset\fR was not created with the same \fIcpc\fR handle. +.sp +For \fBcpc_bind_cpu()\fR, the specified processor does not exist. +.sp +For \fBcpc_unbind()\fR, the set is not bound. +.sp +For \fBcpc_request_preset()\fR and \fBcpc_set_restart()\fR, the calling +\fBLWP\fR does not have a bound set. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOSYS\fR\fR +.ad +.RS 11n +.rt +For \fBcpc_bind_cpu()\fR, the specified processor is not online. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOTSUP\fR\fR +.ad +.RS 11n +.rt +The \fBcpc_bind_curlwp()\fR function was called with the +\fBCPC_OVF_NOTIFY_EMT\fR flag, but the underlying processor is not capable of +detecting counter overflow. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBESRCH\fR\fR +.ad +.RS 11n +.rt +For \fBcpc_bind_pctx()\fR, the specified \fBLWP\fR in the target process does +not exist. +.RE + +.SH EXAMPLES +.LP +\fBExample 1 \fRUse hardware performance counters to measure events in a +process. +.sp +.LP +The following example demonstrates how a standalone application can be +instrumented with the \fBlibcpc\fR(3LIB) functions to use hardware performance +counters to measure events in a process. The application performs 20 iterations +of a computation, measuring the counter values for each iteration. By default, +the example makes use of two counters to measure external cache references and +external cache hits. These options are only appropriate for UltraSPARC +processors. By setting the EVENT0 and EVENT1 environment variables to other +strings (a list of which can be obtained from the \fB-h\fR option of the +\fBcpustat\fR(1M) or \fBcputrack\fR(1) utilities), other events can be counted. +The \fBerror()\fR routine is assumed to be a user-provided routine analogous to +the familiar \fBprintf\fR(3C) function from the C library that also performs an +\fBexit\fR(2) after printing the message. + +.sp +.in +2 +.nf +#include <inttypes.h> +#include <stdlib.h> +#include <stdio.h> +#include <unistd.h> +#include <libcpc.h> +#include <errno.h> + +int +main(int argc, char *argv[]) +{ +int iter; +char *event0 = NULL, *event1 = NULL; +cpc_t *cpc; +cpc_set_t *set; +cpc_buf_t *diff, *after, *before; +int ind0, ind1; +uint64_t val0, val1; + +if ((cpc = cpc_open(CPC_VER_CURRENT)) == NULL) + error("perf counters unavailable: %s", strerror(errno)); + +if ((event0 = getenv("EVENT0")) == NULL) + event0 = "EC_ref"; +if ((event1 = getenv("EVENT1")) == NULL) + event1 = "EC_hit"; + +if ((set = cpc_set_create(cpc)) == NULL) + error("could not create set: %s", strerror(errno)); + +if ((ind0 = cpc_set_add_request(cpc, set, event0, 0, CPC_COUNT_USER, 0, + NULL)) == -1) + error("could not add first request: %s", strerror(errno)); + +if ((ind1 = cpc_set_add_request(cpc, set, event1, 0, CPC_COUNT_USER, 0, + NULL)) == -1) + error("could not add first request: %s", strerror(errno)); + +if ((diff = cpc_buf_create(cpc, set)) == NULL) + error("could not create buffer: %s", strerror(errno)); +if ((after = cpc_buf_create(cpc, set)) == NULL) + error("could not create buffer: %s", strerror(errno)); +if ((before = cpc_buf_create(cpc, set)) == NULL) + error("could not create buffer: %s", strerror(errno)); + +if (cpc_bind_curlwp(cpc, set, 0) == -1) + error("cannot bind lwp%d: %s", _lwp_self(), strerror(errno)); + +for (iter = 1; iter <= 20; iter++) { + + if (cpc_set_sample(cpc, set, before) == -1) + break; + + /* ==> Computation to be measured goes here <== */ + + if (cpc_set_sample(cpc, set, after) == -1) + break; + + cpc_buf_sub(cpc, diff, after, before); + cpc_buf_get(cpc, diff, ind0, &val0); + cpc_buf_get(cpc, diff, ind1, &val1); + + (void) printf("%3d: %" PRId64 " %" PRId64 "\en", iter, + val0, val1); +} + + if (iter != 21) + error("cannot sample set: %s", strerror(errno)); + +cpc_close(cpc); + +return (0); +} +.fi +.in -2 + +.LP +\fBExample 2 \fRWrite a signal handler to catch overflow signals. +.sp +.LP +The following example builds on Example 1 and demonstrates how to write the +signal handler to catch overflow signals. A counter is preset so that it is +1000 counts short of overflowing. After 1000 counts the signal handler is +invoked. + +.sp +.LP +The signal handler: + +.sp +.in +2 +.nf +cpc_t *cpc; +cpc_set_t *set; +cpc_buf_t *buf; +int index; + +void +emt_handler(int sig, siginfo_t *sip, void *arg) +{ + ucontext_t *uap = arg; + uint64_t val; + + if (sig != SIGEMT || sip->si_code != EMT_CPCOVF) { + psignal(sig, "example"); + psiginfo(sip, "example"); + return; + } + + (void) printf("lwp%d - si_addr %p ucontext: %%pc %p %%sp %p\en", + _lwp_self(), (void *)sip->si_addr, + (void *)uap->uc_mcontext.gregs[PC], + (void *)uap->uc_mcontext.gregs[SP]); + + if (cpc_set_sample(cpc, set, buf) != 0) + error("cannot sample: %s", strerror(errno)); + + cpc_buf_get(cpc, buf, index, &val); + + (void) printf("0x%" PRIx64"\en", val); + (void) fflush(stdout); + + /* + * Update a request's preset and restart the counters. Counters which + * have not been preset with cpc_request_preset() will resume counting + * from their current value. + */ + (cpc_request_preset(cpc, ind1, val1) != 0) + error("cannot set preset for request %d: %s", ind1, + strerror(errno)); + if (cpc_set_restart(cpc, set) != 0) + error("cannot restart lwp%d: %s", _lwp_self(), strerror(errno)); +} +.fi +.in -2 + +.sp +.LP +The setup code, which can be positioned after the code that opens the CPC +library and creates a set: + +.sp +.in +2 +.nf +#define PRESET (UINT64_MAX - 999ull) + + struct sigaction act; + ... + act.sa_sigaction = emt_handler; + bzero(&act.sa_mask, sizeof (act.sa_mask)); + act.sa_flags = SA_RESTART|SA_SIGINFO; + if (sigaction(SIGEMT, &act, NULL) == -1) + error("sigaction: %s", strerror(errno)); + + if ((index = cpc_set_add_request(cpc, set, event, PRESET, + CPC_COUNT_USER | CPC_OVF_NOTIFY_EMT, 0, NULL)) != 0) + error("cannot add request to set: %s", strerror(errno)); + + if ((buf = cpc_buf_create(cpc, set)) == NULL) + error("cannot create buffer: %s", strerror(errno)); + + if (cpc_bind_curlwp(cpc, set, 0) == -1) + error("cannot bind lwp%d: %s", _lwp_self(), strerror(errno)); + + for (iter = 1; iter <= 20; iter++) { + /* ==> Computation to be measured goes here <== */ + } + + cpc_unbind(cpc, set); /* done */ +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityEvolving +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBcpustat\fR(1M), \fBcputrack\fR(1), \fBpsrinfo\fR(1M), +\fBprocessor_bind\fR(2), \fBcpc_seterrhndlr\fR(3CPC), +\fBcpc_set_sample\fR(3CPC), \fBlibcpc\fR(3LIB), \fBattributes\fR(5) +.SH NOTES +.sp +.LP +When a set is bound, the system assigns a physical hardware counter to count on +behalf of each request in the set. If such an assignment is not possible for +all requests in the set, the bind function returns -1 and sets \fBerrno\fR to +\fBEINVAL\fR. The assignment of requests to counters depends on the +capabilities of the available counters. Some processors (such as Pentium 4) +have a complicated counter control mechanism that requires the reservation of +limited hardware resources beyond the actual counters. It could occur that two +requests for different events might be impossible to count at the same time due +to these limited hardware resources. See the processor manual as referenced by +\fBcpc_cpuref\fR(3CPC) for details about the underlying processor's +capabilities and limitations. +.sp +.LP +Some processors can be configured to dispatch an interrupt when a physical +counter overflows. The most obvious use for this facility is to ensure that the +full 64-bit counter values are maintained without repeated sampling. Certain +hardware, such as the UltraSPARC processor, does not record which counter +overflowed. A more subtle use for this facility is to preset the counter to a +value slightly less than the maximum value, then use the resulting interrupt to +catch the counter overflow associated with that event. The overflow can then be +used as an indication of the frequency of the occurrence of that event. +.sp +.LP +The interrupt generated by the processor might not be particularly precise. +That is, the particular instruction that caused the counter overflow might be +earlier in the instruction stream than is indicated by the program counter +value in the ucontext. +.sp +.LP +When a request is added to a set with the \fBCPC_OVF_NOTIFY_EMT\fR flag set, +then as before, the control registers and counter are preset from the 64-bit +preset value given. When the flag is set, however, the kernel arranges to send +the calling process a \fBSIGEMT\fR signal when the overflow occurs. The +\fBsi_code\fR member of the corresponding \fBsiginfo\fR structure is set to +\fBEMT_CPCOVF\fR and the \fBsi_addr\fR member takes the program counter value +at the time the overflow interrupt was delivered. Counting is disabled until +the set is bound again. +.sp +.LP +If the \fBCPC_CAP_OVERFLOW_PRECISE\fR bit is set in the value returned by +\fBcpc_caps\fR(3CPC), the processor is able to determine precisely which +counter has overflowed after receiving the overflow interrupt. On such +processors, the \fBSIGEMT\fR signal is sent only if a counter overflows and the +request that the counter is counting has the \fBCPC_OVF_NOTIFY_EMT\fR flag set. +If the capability is not present on the processor, the system sends a +\fBSIGEMT\fR signal to the process if any of its requests have the +\fBCPC_OVF_NOTIFY_EMT\fR flag set and any counter in its set overflows. +.sp +.LP +Different processors have different counter ranges available, though all +processors supported by Solaris allow at least 31 bits to be specified as a +counter preset value. Portable preset values lie in the range \fBUINT64_MAX\fR +to \fBUINT64_MAX\fR-\fBINT32_MAX\fR. +.sp +.LP +The appropriate preset value will often need to be determined experimentally. +Typically, this value will depend on the event being measured as well as the +desire to minimize the impact of the act of measurement on the event being +measured. Less frequent interrupts and samples lead to less perturbation of the +system. +.sp +.LP +If the processor cannot detect counter overflow, bind will fail and return +\fBENOTSUP\fR. Only user events can be measured using this technique. See +Example 2. +.SS "Pentium 4" +.sp +.LP +Most Pentium 4 events require the specification of an event mask for counting. +The event mask is specified with the \fIemask\fR attribute. +.sp +.LP +Pentium 4 processors with HyperThreading Technology have only one set of +hardware counters per physical processor. To use \fBcpc_bind_curlwp()\fR or +\fBcpc_bind_pctx()\fR to measure per-\fBLWP\fR events on a system with Pentium +4 HT processors, a system administrator must first take processors in the +system offline until each physical processor has only one hardware thread +online (See the \fB-p\fR option to \fBpsrinfo\fR(1M)). If a second hardware +thread is brought online, all per-\fBLWP\fR bound contexts will be invalidated +and any attempt to sample or bind a CPC set will return \fBEAGAIN\fR. +.sp +.LP +Only one CPC set at a time can be bound to a physical processor with +\fBcpc_bind_cpu()\fR. Any call to \fBcpc_bind_cpu()\fR that attempts to bind a +set to a processor that shares a physical processor with a processor that +already has a CPU-bound set returns an error. +.sp +.LP +To measure the shared state on a Pentium 4 processor with HyperThreading, the +\fIcount_sibling_usr\fR and \fIcount_sibling_sys\fR attributes are provided for +use with \fBcpc_bind_cpu()\fR. These attributes behave exactly as the +\fBCPC_COUNT_USER\fR and \fBCPC_COUNT_SYSTEM\fR request flags, except that they +act on the sibling hardware thread sharing the physical processor with the CPU +measured by \fBcpc_bind_cpu()\fR. Some CPC sets will fail to bind due to +resource constraints. The most common type of resource constraint is an ESCR +conflict among one or more requests in the set. For example, the branch_retired +event cannot be measured on counters 12 and 13 simultaneously because both +counters require the \fBCRU_ESCR2\fR ESCR to measure this event. To measure +\fIbranch_retired\fR events simultaneously on more than one counter, use +counters such that one counter uses \fBCRU_ESCR2\fR and the other counter uses +CRU_ESCR3. See the processor documentation for details. diff --git a/usr/src/man/man3cpc/cpc_bind_event.3cpc b/usr/src/man/man3cpc/cpc_bind_event.3cpc new file mode 100644 index 0000000000..5030257344 --- /dev/null +++ b/usr/src/man/man3cpc/cpc_bind_event.3cpc @@ -0,0 +1,444 @@ +'\" te +.\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH cpc_bind_event 3CPC "02 Mar 2007" "SunOS 5.11" "CPU Performance Counters Library Functions" +.SH NAME +cpc_bind_event, cpc_take_sample, cpc_rele \- use CPU performance counters on +lwps +.SH SYNOPSIS +.LP +.nf +cc [ \fIflag\fR... ] \fIfile\fR... \(milcpc [ \fIlibrary\fR... ] +#include <libcpc.h> + +\fBint\fR \fBcpc_bind_event\fR(\fBcpc_event_t *\fR\fIevent\fR, \fBint\fR \fIflags\fR); +.fi + +.LP +.nf +\fBint\fR \fBcpc_take_sample\fR(\fBcpc_event_t *\fR\fIevent\fR); +.fi + +.LP +.nf +\fBint\fR \fBcpc_rele\fR(\fBvoid\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +Once the events to be sampled have been selected using, for example, +\fBcpc_strtoevent\fR(3CPC), the event selections can be bound to the calling +\fBLWP\fR using \fBcpc_bind_event()\fR. If \fBcpc_bind_event()\fR returns +successfully, the system has associated performance counter context with the +calling \fBLWP\fR. The context allows the system to virtualize the hardware +counters to that specific \fBLWP\fR, and the counters are enabled. +.sp +.LP +Two flags are defined that can be passed into the routine to allow the behavior +of the interface to be modified, as described below. +.sp +.LP +Counter values can be sampled at any time by calling \fBcpc_take_sample()\fR, +and dereferencing the fields of the \fBce_pic\fR\fB[]\fR array returned. The +\fBce_hrt\fR field contains the timestamp at which the kernel last sampled the +counters. +.sp +.LP +To immediately remove the performance counter context on an \fBLWP\fR, the +\fBcpc_rele()\fR interface should be used. Otherwise, the context will be +destroyed after the \fBLWP\fR or process exits. +.sp +.LP +The caller should take steps to ensure that the counters are sampled often +enough to avoid the 32-bit counters wrapping. The events most prone to wrap are +those that count processor clock cycles. If such an event is of interest, +sampling should occur frequently so that less than 4 billion clock cycles can +occur between samples. Practically speaking, this is only likely to be a +problem for otherwise idle systems, or when processes are bound to processors, +since normal context switching behavior will otherwise hide this problem. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBcpc_bind_event()\fR and \fBcpc_take_sample()\fR +return \fB0\fR. Otherwise, these functions return \fB\(mi1\fR, and set +\fBerrno\fR to indicate the error. +.SH ERRORS +.sp +.LP +The \fBcpc_bind_event()\fR and \fBcpc_take_sample()\fR functions will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEACCES\fR\fR +.ad +.RS 11n +.rt +For \fBcpc_bind_event()\fR, access to the requested hypervisor event was +denied. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEAGAIN\fR\fR +.ad +.RS 11n +.rt +Another process may be sampling system-wide CPU statistics. For +\fBcpc_bind_event()\fR, this implies that no new contexts can be created. For +\fBcpc_take_sample()\fR, this implies that the performance counter context has +been invalidated and must be released with \fBcpc_rele()\fR. Robust programs +should be coded to expect this behavior and recover from it by releasing the +now invalid context by calling \fBcpc_rele()\fR sleeping for a while, then +attempting to bind and sample the event once more. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 11n +.rt +The \fBcpc_take_sample()\fR function has been invoked before the context is +bound. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOTSUP\fR\fR +.ad +.RS 11n +.rt +The caller has attempted an operation that is illegal or not supported on the +current platform, such as attempting to specify signal delivery on counter +overflow on a CPU that doesn't generate an interrupt on counter overflow. +.RE + +.SH USAGE +.sp +.LP +Prior to calling \fBcpc_bind_event()\fR, applications should call +\fBcpc_access\fR(3CPC) to determine if the counters are accessible on the +system. +.SH EXAMPLES +.LP +\fBExample 1 \fRUse hardware performance counters to measure events in a +process. +.sp +.LP +The example below shows how a standalone program can be instrumented with the +\fBlibcpc\fR routines to use hardware performance counters to measure events in +a process. The program performs 20 iterations of a computation, measuring the +counter values for each iteration. By default, the example makes the counters +measure external cache references and external cache hits; these options are +only appropriate for UltraSPARC processors. By setting the \fBPERFEVENTS\fR +environment variable to other strings (a list of which can be gleaned from the +\fB-h\fR flag of the \fBcpustat\fR or \fBcputrack\fR utilities), other events +can be counted. The \fBerror()\fR routine below is assumed to be a +user-provided routine analogous to the familiar \fBprintf\fR(3C) routine from +the C library but which also performs an \fBexit\fR(2) after printing the +message. + +.sp +.in +2 +.nf +\fB#include <inttypes.h> +#include <stdlib.h> +#include <stdio.h> +#include <unistd.h> +#include <libcpc.h> +int +main(int argc, char *argv[]) +{ +int cpuver, iter; +char *setting = NULL; +cpc_event_t event; + +if (cpc_version(CPC_VER_CURRENT) != CPC_VER_CURRENT) + error("application:library cpc version mismatch!"); + +if ((cpuver = cpc_getcpuver()) == -1) + error("no performance counter hardware!"); + +if ((setting = getenv("PERFEVENTS")) == NULL) + setting = "pic0=EC_ref,pic1=EC_hit"; + +if (cpc_strtoevent(cpuver, setting, &event) != 0) + error("can't measure '%s' on this processor", setting); +setting = cpc_eventtostr(&event); + +if (cpc_access() == -1) + error("can't access perf counters: %s", strerror(errno)); + +if (cpc_bind_event(&event, 0) == -1) + error("can't bind lwp%d: %s", _lwp_self(), strerror(errno)); + +for (iter = 1; iter <= 20; iter++) { + cpc_event_t before, after; + + if (cpc_take_sample(&before) == -1) + break; + + /* ==> Computation to be measured goes here <== */ + + if (cpc_take_sample(&after) == -1) + break; + (void) printf("%3d: %" PRId64 " %" PRId64 "\n", iter, + after.ce_pic[0] - before.ce_pic[0], + after.ce_pic[1] - before.ce_pic[1]); +} + +if (iter != 20) + error("can't sample '%s': %s", setting, strerror(errno)); + +free(setting); +return (0); +}\fR +.fi +.in -2 + +.LP +\fBExample 2 \fRWrite a signal handler to catch overflow signals. +.sp +.LP +This example builds on Example 1, but demonstrates how to write the signal +handler to catch overflow signals. The counters are preset so that counter zero +is 1000 counts short of overflowing, while counter one is set to zero. After +1000 counts on counter zero, the signal handler will be invoked. + +.sp +.LP +First the signal handler: + +.sp +.in +2 +.nf +#define PRESET0 (UINT64_MAX - UINT64_C(999)) +#define PRESET1 0 + +void +emt_handler(int sig, siginfo_t *sip, void *arg) +{ +ucontext_t *uap = arg; +cpc_event_t sample; + +if (sig != SIGEMT || sip->si_code != EMT_CPCOVF) { + psignal(sig, "example"); + psiginfo(sip, "example"); + return; +} + +(void) printf("lwp%d - si_addr %p ucontext: %%pc %p %%sp %p\n", + _lwp_self(), (void *)sip->si_addr, + (void *)uap->uc_mcontext.gregs[PC], + (void *)uap->uc_mcontext.gregs[USP]); + +if (cpc_take_sample(&sample) == -1) + error("can't sample: %s", strerror(errno)); + +(void) printf("0x%" PRIx64 " 0x%" PRIx64 "\n", + sample.ce_pic[0], sample.ce_pic[1]); +(void) fflush(stdout); + +sample.ce_pic[0] = PRESET0; +sample.ce_pic[1] = PRESET1; +if (cpc_bind_event(&sample, CPC_BIND_EMT_OVF) == -1) + error("cannot bind lwp%d: %s", _lwp_self(), strerror(errno)); +} +.fi +.in -2 + +.sp +.LP +and second the setup code (this can be placed after the code that selects the +event to be measured): + +.sp +.in +2 +.nf +\fBstruct sigaction act; +cpc_event_t event; +\&... +act.sa_sigaction = emt_handler; +bzero(&act.sa_mask, sizeof (act.sa_mask)); +act.sa_flags = SA_RESTART|SA_SIGINFO; +if (sigaction(SIGEMT, &act, NULL) == -1) + error("sigaction: %s", strerror(errno)); +event.ce_pic[0] = PRESET0; +event.ce_pic[1] = PRESET1; +if (cpc_bind_event(&event, CPC_BIND_EMT_OVF) == -1) + error("cannot bind lwp%d: %s", _lwp_self(), strerror(errno)); + +for (iter = 1; iter <= 20; iter++) { + /* ==> Computation to be measured goes here <== */ +} + +cpc_bind_event(NULL, 0); /* done */\fR +.fi +.in -2 + +.sp +.LP +Note that a more general version of the signal handler would use \fBwrite\fR(2) +directly instead of depending on the signal-unsafe semantics of \fBstderr\fR +and \fBstdout\fR. Most real signal handlers will probably do more with the +samples than just print them out. + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelMT-Safe +_ +Interface StabilityObsolete +.TE + +.SH SEE ALSO +.sp +.LP +\fBcpustat\fR(1M), \fBcputrack\fR(1), \fBwrite\fR(2). \fBcpc\fR(3CPC), +\fBcpc_access\fR(3CPC), \fBcpc_bind_curlwp\fR(3CPC), +\fBcpc_set_sample\fR(3CPC), \fBcpc_strtoevent\fR(3CPC), \fBcpc_unbind\fR(3CPC), +\fBlibcpc\fR(3LIB), \fBattributes\fR(5) +.SH NOTES +.sp +.LP +The \fBcpc_bind_event()\fR, \fBcpc_take_sample()\fR, and \fBcpc_rele()\fR +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 \fBcpc_bind_curlwp\fR(3CPC), +\fBcpc_set_sample\fR(3CPC), and \fBcpc_unbind\fR(3CPC) instead. +.sp +.LP +Sometimes, even the overhead of performing a system call will be too disruptive +to the events being measured. Once a call to \fBcpc_bind_event()\fR has been +issued, it is possible to directly access the performance hardware registers +from within the application. If the performance counter context is active, then +the counters will count on behalf of the current \fBLWP\fR. +.SS "SPARC" +.sp +.in +2 +.nf +rd %pic, %r\fBN\fR ! All UltraSPARC +wr %r\fIN\fR, %pic ! (ditto, but see text) +.fi +.in -2 + +.SS "x86" +.sp +.in +2 +.nf +rdpmc ! Pentium II only +.fi +.in -2 + +.sp +.LP +If the counter context is not active or has been invalidated, the \fB%pic\fR +register (SPARC), and the \fBrdpmc\fR instruction (Pentium) will become +unavailable. +.sp +.LP +Note that the two 32-bit UltraSPARC performance counters are kept in the single +64-bit \fB%pic\fR register so a couple of additional instructions are required +to separate the values. Also note that when the \fB%pcr\fR register bit has +been set that configures the \fB%pic\fR register as readable by an application, +it is also writable. Any values written will be preserved by the context +switching mechanism. +.sp +.LP +Pentium II processors support the non-privileged \fBrdpmc\fR instruction which +requires [5] that the counter of interest be specified in \fB%ecx\fR, and +returns a 40-bit value in the \fB%edx:%eax\fR register pair. There is no +non-privileged access mechanism for Pentium I processors. +.SS "Handling counter overflow" +.sp +.LP +As described above, when counting events, some processors allow their counter +registers to silently overflow. More recent CPUs such as UltraSPARC III and +Pentium II, however, are capable of generating an interrupt when the hardware +counter overflows. Some processors offer more control over when interrupts will +actually be generated. For example, they might allow the interrupt to be +programmed to occur when only one of the counters overflows. See +\fBcpc_strtoevent\fR(3CPC) for the syntax. +.sp +.LP +The most obvious use for this facility is to ensure that the full 64-bit +counter values are maintained without repeated sampling. However, current +hardware does not record which counter overflowed. A more subtle use for this +facility is to preset the counter to a value to a little less than the maximum +value, then use the resulting interrupt to catch the counter overflow +associated with that event. The overflow can then be used as an indication of +the frequency of the occurrence of that event. +.sp +.LP +Note that the interrupt generated by the processor may not be particularly +precise. That is, the particular instruction that caused the counter overflow +may be earlier in the instruction stream than is indicated by the program +counter value in the ucontext. +.sp +.LP +When \fBcpc_bind_event()\fR is called with the \fBCPC_BIND_EMT_OVF\fR flag +set, then as before, the control registers and counters are preset from the +64-bit values contained in \fBevent\fR. However, when the flag is set, the +kernel arranges to send the calling process a \fBSIGEMT\fR signal when the +overflow occurs, with the \fBsi_code\fR field of the corresponding +\fBsiginfo\fR structure set to \fBEMT_CPCOVF\fR, and the \fBsi_addr\fR field is +the program counter value at the time the overflow interrupt was delivered. +Counting is disabled until the next call to \fBcpc_bind_event()\fR. Even in a +multithreaded process, during execution of the signal handler, the thread +behaves as if it is temporarily bound to the running \fBLWP\fR. +.sp +.LP +Different processors have different counter ranges available, though all +processors supported by Solaris allow at least 31 bits to be specified as a +counter preset value; thus portable preset values lie in the range +\fBUINT64_MAX\fR to \fBUINT64_MAX\fR\(mi\fBINT32_MAX\fR. +.sp +.LP +The appropriate preset value will often need to be determined experimentally. +Typically, it will depend on the event being measured, as well as the desire to +minimize the impact of the act of measurement on the event being measured; less +frequent interrupts and samples lead to less perturbation of the system. +.sp +.LP +If the processor cannot detect counter overflow, this call will fail +(\fBENOTSUP\fR). Specifying a null event unbinds the context from the +underlying \fBLWP\fR and disables signal delivery. Currently, only user events +can be measured using this technique. See Example 2, above. +.SS "Inheriting events onto multiple \fBLWP\fRs" +.sp +.LP +By default, the library binds the performance counter context to the current +\fBLWP\fR only. If the \fBCPC_BIND_LWP_INHERIT\fR flag is set, then any +subsequent \fBLWP\fRs created by that \fBLWP\fR will automatically inherit the +same performance counter context. The counters will be initialized to 0 as if +a \fBcpc_bind_event()\fR had just been issued. This automatic inheritance +behavior can be useful when dealing with multithreaded programs to determine +aggregate statistics for the program as a whole. +.sp +.LP +If the \fBCPC_BIND_EMT_OVF\fR flag is also set, the process will immediately +dispatch a \fBSIGEMT\fR signal to the freshly created \fBLWP\fR so that it can +preset its counters appropriately on the new \fBLWP\fR. This initialization +condition can be detected using \fBcpc_take_sample()\fR to check that both +\fBce_pic\fR[] values are set to \fBUINT64_MAX\fR. diff --git a/usr/src/man/man3cpc/cpc_buf_create.3cpc b/usr/src/man/man3cpc/cpc_buf_create.3cpc new file mode 100644 index 0000000000..74400c8cf8 --- /dev/null +++ b/usr/src/man/man3cpc/cpc_buf_create.3cpc @@ -0,0 +1,278 @@ +'\" te +.\" Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH cpc_buf_create 3CPC "30 Jan 2004" "SunOS 5.11" "CPU Performance Counters Library Functions" +.SH NAME +cpc_buf_create, cpc_buf_destroy, cpc_set_sample, cpc_buf_get, cpc_buf_set, +cpc_buf_hrtime, cpc_buf_tick, cpc_buf_sub, cpc_buf_add, cpc_buf_copy, +cpc_buf_zero \- sample and manipulate CPC data +.SH SYNOPSIS +.LP +.nf +cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-lcpc\fR [ \fIlibrary\fR\&.\|.\|. ] +#include <libcpc.h> + +\fBcpc_buf_t *\fR\fBcpc_buf_create\fR(\fBcpc_t *\fR\fIcpc\fR, \fBcpc_set_t *\fR\fIset\fR); +.fi + +.LP +.nf +\fBint\fR \fBcpc_buf_destroy\fR(\fBcpc_t *\fR\fIcpc\fR, \fBcpc_buf_t *\fR\fIbuf\fR); +.fi + +.LP +.nf +\fBint\fR \fBcpc_set_sample\fR(\fBcpc_t *\fR\fIcpc\fR, \fBcpc_set_t *\fR\fIset\fR, \fBcpc_buf_t *\fR\fIbuf\fR); +.fi + +.LP +.nf +\fBint\fR \fBcpc_buf_get\fR(\fBcpc_t *\fR\fIcpc\fR, \fBcpc_buf_t *\fR\fIbuf\fR, \fBint\fR \fIindex\fR, \fBuint64_t *\fR\fIval\fR); +.fi + +.LP +.nf +\fBint\fR \fBcpc_buf_set\fR(\fBcpc_t *\fR\fIcpc\fR, \fBcpc_buf_t *\fR\fIbuf\fR, \fBint\fR \fIindex\fR, \fBuint64_t\fR \fIval\fR); +.fi + +.LP +.nf +\fBhrtime_t\fR \fBcpc_buf_hrtime\fR(\fBcpc_t *\fR\fIcpc\fR, \fBcpc_buf_t *\fR\fIbuf\fR); +.fi + +.LP +.nf +\fBuint64_t\fR \fBcpc_buf_tick\fR(\fBcpc_t *\fR\fIcpc\fR, \fBcpc_buf_t *\fR\fIbuf\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBcpc_buf_sub\fR(\fBcpc_t *\fR\fIcpc\fR, \fBcpc_buf_t *\fR\fIds\fR, \fBcpc_buf_t *\fR\fIa\fR, \fBcpc_buf_t *\fR\fIb\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBcpc_buf_add\fR(\fBcpc_t *\fR\fIcpc\fR, \fBcpc_buf_t *\fR\fIds\fR, \fBcpc_buf_t *\fR\fIa\fR, \fBcpc_buf_t *\fR\fIb\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBcpc_buf_copy\fR(\fBcpc_t *\fR\fIcpc\fR, \fBcpc_buf_t *\fR\fIds\fR, \fBcpc_buf_t *\fR\fIsrc\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBcpc_buf_zero\fR(\fBcpc_t *\fR\fIcpc\fR, \fBcpc_buf_t *\fR\fIbuf\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +Counter data is sampled into CPC buffers, which are represented by the opaque +data type \fBcpc_buf_t\fR. A CPC buffer is created with \fBcpc_buf_create()\fR +to hold the data for a specific CPC set. Once a CPC buffer has been created, it +can only be used to store and manipulate the data of the CPC set for which it +was created. +.sp +.LP +Once a set has been successfully bound, the counter values are sampled using +\fBcpc_set_sample()\fR. The \fBcpc_set_sample()\fR function takes a snapshot of +the hardware performance counters counting on behalf of the requests in +\fIset\fR and stores the 64-bit virtualized software representations of the +counters in the supplied CPC buffer. If a set was bound with +\fBcpc_bind_curlwp\fR(3CPC) or \fBcpc_bind_curlwp\fR(3CPC), the set can only be +sampled by the LWP that bound it. +.sp +.LP +The kernel maintains 64-bit virtual software counters to hold the counts +accumulated for each request in the set, thereby allowing applications to count +past the limits of the underlying physical counter, which can be significantly +smaller than 64 bits. The kernel attempts to maintain the full 64-bit counter +values even in the face of physical counter overflow on architectures and +processors that can automatically detect overflow. If the processor is not +capable of overflow detection, the caller must ensure that the counters are +sampled often enough to avoid the physical counters wrapping. The events most +prone to wrap are those that count processor clock cycles. If such an event is +of interest, sampling should occur frequently so that the counter does not wrap +between samples. +.sp +.LP +The \fBcpc_buf_get()\fR function retrieves the last sampled value of a +particular request in \fIbuf\fR. The \fIindex\fR argument specifies which +request value in the set to retrieve. The index for each request is returned +during set configuration by \fBcpc_set_add_request\fR(3CPC). The 64-bit +virtualized software counter value is stored in the location pointed to by the +\fIval\fR argument. +.sp +.LP +The \fBcpc_buf_set()\fR function stores a 64-bit value to a specific request in +the supplied buffer. This operation can be useful for performing calculations +with CPC buffers, but it does not affect the value of the hardware counter (and +thus will not affect the next sample). +.sp +.LP +The \fBcpc_buf_hrtime()\fR function returns a high-resolution timestamp +indicating exactly when the set was last sampled by the kernel. +.sp +.LP +The\fB cpc_buf_tick()\fR function returns a 64-bit virtualized cycle counter +indicating how long the set has been programmed into the counter since it was +bound. The units of the values returned by \fBcpc_buf_tick()\fR are CPU clock +cycles. +.sp +.LP +The \fBcpc_buf_sub()\fR function calculates the difference between each request +in sets \fIa\fR and \fIb\fR, storing the result in the corresponding request +within set \fIds\fR. More specifically, for each request index \fIn\fR, this +function performs \fIds\fR[\fIn\fR] = \fIa\fR[\fIn\fR] - \fIb\fR[n]. Similarly, +\fBcpc_buf_add()\fR adds each request in sets \fIa\fR and \fIb\fR and stores +the result in the corresponding request within set \fIds\fR. +.sp +.LP +The \fBcpc_buf_copy()\fR function copies each value from buffer \fIsrc\fR into +buffer \fIds\fR. Both buffers must have been created from the same +\fBcpc_set_t\fR. +.sp +.LP +The \fBcpc_buf_zero()\fR function sets each request's value in the buffer to +zero. +.sp +.LP +The \fBcpc_buf_destroy()\fR function frees all resources associated with the +CPC buffer. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBcpc_buf_create()\fR returns a pointer to a CPC +buffer which can be used to hold data for the set argument. Otherwise, this +function returns \fINULL\fR and sets \fBerrno\fR to indicate the error. +.sp +.LP +Upon successful completion, \fBcpc_set_sample()\fR, \fBcpc_buf_get()\fR, and +\fBcpc_buf_set()\fR return 0. Otherwise, they return -1 and set \fBerrno\fR to +indicate the error. +.SH ERRORS +.sp +.LP +These functions will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +For \fBcpc_set_sample()\fR, the set is not bound, the set and/or CPC buffer +were not created with the given \fIcpc\fR handle, or the CPC buffer was not +created with the supplied set. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEAGAIN\fR\fR +.ad +.RS 10n +.rt +When using \fBcpc_set_sample()\fR to sample a CPU-bound set, the LWP has been +unbound from the processor it is measuring. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOMEM\fR\fR +.ad +.RS 10n +.rt +The library could not allocate enough memory for its internal data structures. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityEvolving +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBcpc_bind_curlwp\fR(3CPC), \fBcpc_set_add_request\fR(3CPC), +\fBlibcpc\fR(3LIB), \fBattributes\fR(5) +.SH NOTES +.sp +.LP +Often the overhead of performing a system call can be too disruptive to the +events being measured. Once a \fBcpc_bind_curlwp\fR(3CPC) call has been issued, +it is possible to access directly the performance hardware registers from +within the application. If the performance counter context is active, the +counters will count on behalf of the current LWP. +.sp +.LP +Not all processors support this type of access. On processors where direct +access is not possible, \fBcpc_set_sample()\fR must be used to read the +counters. +.sp +.ne 2 +.mk +.na +\fBSPARC\fR +.ad +.RS 9n +.rt +.sp +.in +2 +.nf +rd %pic, %rN ! All UltraSPARC +wr %rN, %pic ! (All UltraSPARC, but see text) +.fi +.in -2 + +.RE + +.sp +.ne 2 +.mk +.na +\fBx86\fR +.ad +.RS 9n +.rt +.sp +.in +2 +.nf +rdpmc ! Pentium II, III, and 4 only +.fi +.in -2 + +.RE + +.sp +.LP +If the counter context is not active or has been invalidated, the \fB%pic\fR +register (SPARC), and the \fBrdpmc\fR instruction (Pentium) becomes +unavailable. +.sp +.LP +Pentium II and III processors support the non-privileged rdpmc instruction that +requires that the counter of interest be specified in \fB%ecx\fR and return a +40-bit value in the \fB%edx\fR:\fB%eax\fR register pair. There is no +non-privileged access mechanism for Pentium I processors. diff --git a/usr/src/man/man3cpc/cpc_count_usr_events.3cpc b/usr/src/man/man3cpc/cpc_count_usr_events.3cpc new file mode 100644 index 0000000000..c369311f1c --- /dev/null +++ b/usr/src/man/man3cpc/cpc_count_usr_events.3cpc @@ -0,0 +1,148 @@ +'\" te +.\" Copyright (c) 2005, Sun Microsystems, Inc. +.\" All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH cpc_count_usr_events 3CPC "28 Mar 2005" "SunOS 5.11" "CPU Performance Counters Library Functions" +.SH NAME +cpc_count_usr_events, cpc_count_sys_events \- enable and disable performance +counters +.SH SYNOPSIS +.LP +.nf +cc [ \fIflag\fR... ] \fIfile\fR... \(milcpc [ \fIlibrary\fR... ] +#include <libcpc.h> + +\fBint\fR \fBcpc_count_usr_events\fR(\fBint\fR \fIenable\fR); +.fi + +.LP +.nf +\fBint\fR \fBcpc_count_sys_events\fR(\fBint\fR \fIenable\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +In certain applications, it can be useful to explicitly enable and disable +performance counters at different times so that the performance of a critical +algorithm can be examined. The \fBcpc_count_usr_events()\fR function can be +used to control whether events are counted on behalf of the application running +in user mode, while \fBcpc_count_sys_events()\fR can be used to control whether +events are counted on behalf of the application while it is running in the +kernel, without otherwise disturbing the binding of events to the invoking LWP. +If the \fIenable\fR argument is non-zero, counting of events is enabled, +otherwise they are disabled. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBcpc_count_usr_events()\fR and +\fBcpc_count_sys_events()\fR return \fB0\fR. Otherwise, the functions return +\fB\(mi1\fR and set \fBerrno\fR to indicate the error. +.SH ERRORS +.sp +.LP +The \fBcpc_count_usr_events()\fR and \fBcpc_count_sys_events()\fR functions +will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEAGAIN\fR \fR +.ad +.RS 11n +.rt +The associated performance counter context has been invalidated by another +process. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR \fR +.ad +.RS 11n +.rt +No performance counter context has been created, or an attempt was made to +enable system events while delivering counter overflow signals. +.RE + +.SH EXAMPLES +.LP +\fBExample 1 \fRUse \fBcpc_count_usr_events()\fR to minimize code needed by +application. +.sp +.LP +In this example, the routine \fBcpc_count_usr_events()\fR is used to minimize +the amount of code that needs to be added to the application. The +\fBcputrack\fR(1) command can be used in conjunction with these interfaces to +provide event programming, sampling, and reporting facilities. + +.sp +.LP +If the application is instrumented in this way and then started by +\fBcputrack\fR with the \fBnouser\fR flag set in the event specification, +counting of user events will only be enabled around the critical code section +of interest. If the program is run normally, no harm will ensue. + +.sp +.in +2 +.nf +int have_counters = 0; +int +main(int argc, char *argv[]) +{ + if (cpc_version(CPC_VER_CURRENT) == CPC_VER_CURRENT && + cpc_getcpuver() != -1 && cpc_access() == 0) + have_counters = 1; + + /* ... other application code */ + + if (have_counters) + (void) cpc_count_usr_events(1); + + /* ==> Code to be measured goes here <== */ + + if (have_counters) + (void) cpc_count_usr_events(0); + + /* ... other application code */ +} +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelMT-Safe +_ +Interface StabilityObsolete +.TE + +.SH SEE ALSO +.sp +.LP +\fBcputrack\fR(1), \fBcpc\fR(3CPC), \fBcpc_access\fR(3CPC), +\fBcpc_bind_event\fR(3CPC), \fBcpc_enable\fR(3CPC), \fBcpc_getcpuver\fR(3CPC), +\fBcpc_pctx_bind_event\fR(3CPC), \fBcpc_version\fR(3CPC), \fBlibcpc\fR(3LIB), +\fBattributes\fR(5) +.SH NOTES +.sp +.LP +The \fBcpc_count_usr_events()\fR and \fBcpc_count_sys_events()\fR 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 \fBcpc_enable\fR(3CPC) instead. diff --git a/usr/src/man/man3cpc/cpc_enable.3cpc b/usr/src/man/man3cpc/cpc_enable.3cpc new file mode 100644 index 0000000000..eebbd23911 --- /dev/null +++ b/usr/src/man/man3cpc/cpc_enable.3cpc @@ -0,0 +1,127 @@ +'\" te +.\" Copyright (c) 2005, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH cpc_enable 3CPC "31 Jan 2005" "SunOS 5.11" "CPU Performance Counters Library Functions" +.SH NAME +cpc_enable, cpc_disable \- enable and disable performance counters +.SH SYNOPSIS +.LP +.nf +cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-lcpc\fR [ \fIlibrary\fR\&.\|.\|. ] +#include <libcpc.h> + +\fBint\fR \fBcpc_enable\fR(\fBcpc_t *\fR\fIcpc\fR); +.fi + +.LP +.nf +\fBint\fR \fBcpc_disable\fR(\fBcpc_t *\fR\fIcpc\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +In certain applications, it can be useful to explicitly enable and disable +performance counters at different times so that the performance of a critical +algorithm can be examined. The \fBcpc_enable()\fR and \fBcpc_disable()\fR +functions can be used to enable and disable the performance counters without +otherwise disturbing the invoking LWP's performance hardware configuration. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBcpc_enable()\fR and \fBcpc_disable()\fR return +0. Otherwise, they return -1 and set \fBerrno\fR to indicate the error. +.SH ERRORS +.sp +.LP +These functions will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEAGAIN\fR\fR +.ad +.RS 10n +.rt +The associated performance counter context has been invalidated by another +process. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +No performance counter context has been created for the calling LWP. +.RE + +.SH EXAMPLES +.LP +\fBExample 1 \fRUse cpc_enable and cpc_disable to minimize code needed by +application. +.sp +.LP +In the following example, the \fBcpc_enable()\fR and \fBcpc_disable()\fR +functions are used to minimize the amount of code that needs to be added to the +application. The \fBcputrack\fR(1) command can be used in conjunction with +these functions to provide event programming, sampling, and reporting +facilities. + +.sp +.LP +If the application is instrumented in this way and then started by +\fBcputrack\fR with the \fBnouser\fR flag set in the event specification, +counting of user events will only be enabled around the critical code section +of interest. If the program is run normally, no harm will ensue. + +.sp +.in +2 +.nf +int +main(int argc, char *argv[]) +{ + cpc_t *cpc = cpc_open(CPC_VER_CURRENT); + /* ... application code ... */ + + if (cpc != NULL) + (void) cpc_enable(cpc); + + /* ==> Code to be measured goes here <== */ + + if (cpc != NULL) + (void) cpc_disable(cpc); + + /* ... other application code */ +} +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityEvolving +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBcputrack\fR(1), \fBcpc\fR(3CPC), \fBcpc_open\fR(3CPC), \fBlibcpc\fR(3LIB), +\fBattributes\fR(5) diff --git a/usr/src/man/man3cpc/cpc_event.3cpc b/usr/src/man/man3cpc/cpc_event.3cpc new file mode 100644 index 0000000000..ad33e69146 --- /dev/null +++ b/usr/src/man/man3cpc/cpc_event.3cpc @@ -0,0 +1,102 @@ +'\" te +.\" Copyright (c) 2003, Sun Microsystems, Inc. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH cpc_event 3CPC "12 May 2003" "SunOS 5.11" "CPU Performance Counters Library Functions" +.SH NAME +cpc_event \- data structure to describe CPU performance counters +.SH SYNOPSIS +.LP +.nf +#include <libcpc.h> +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBlibcpc\fR interfaces manipulate CPU performance counters using the +\fBcpc_event_t\fR data structure. This structure contains several fields that +are common to all processors, and some that are processor-dependent. These +structures can be declared by a consumer of the API, thus the size and offsets +of the fields and the entire data structure are fixed per processor for any +particular version of the library. See \fBcpc_version\fR(3CPC) for details of +library versioning. +.SS "SPARC" +.sp +.LP +For UltraSPARC, the structure contains the following members: +.sp +.in +2 +.nf +typedef struct { + int ce_cpuver; + hrtime_t ce_hrt; + uint64_t ce_tick; + uint64_t ce_pic[2]; + uint64_t ce_pcr; +} cpc_event_t; +.fi +.in -2 + +.SS "x86" +.sp +.LP +For Pentium, the structure contains the following members: +.sp +.in +2 +.nf +\fBtypedef struct { + int ce_cpuver; + hrtime_t ce_hrt; + uint64_t ce_tsc; + uint64_t ce_pic[2]; + uint32_t ce_pes[2]; +#define ce_cesr ce_pes[0] +} cpc_event_t;\fR +.fi +.in -2 + +.sp +.LP +The APIs are used to manipulate the highly processor-dependent control +registers (the \fBce_pcr\fR, \fBce_cesr\fR, and \fBce_pes\fR fields); the +programmer is strongly advised not to reference those fields directly in +portable code. The \fBce_pic\fR array elements contain 64-bit accumulated +counter values. The hardware registers are virtualized to 64-bit quantities +even though the underlying hardware only supports 32-bits (UltraSPARC) or +40-bits (Pentium) before overflow. +.sp +.LP +The \fBce_hrt\fR field is a high resolution timestamp taken at the time the +counters were sampled by the kernel. This uses the same timebase as +\fBgethrtime\fR(3C). +.sp +.LP +On SPARC V9 machines, the number of cycles spent running on the processor is +computed from samples of the processor-dependent \fB%tick\fR register, and +placed in the \fBce_tick\fR field. On Pentium processors, the +processor-dependent time-stamp counter register is similarly sampled and placed +in the \fBce_tsc\fR field. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityEvolving +.TE + +.SH SEE ALSO +.sp +.LP +\fBgethrtime\fR(3C), \fBcpc\fR(3CPC), \fBcpc_version\fR(3CPC), +\fBlibcpc\fR(3LIB), \fBattributes\fR(5) diff --git a/usr/src/man/man3cpc/cpc_event_diff.3cpc b/usr/src/man/man3cpc/cpc_event_diff.3cpc new file mode 100644 index 0000000000..61525f7627 --- /dev/null +++ b/usr/src/man/man3cpc/cpc_event_diff.3cpc @@ -0,0 +1,98 @@ +'\" te +.\" Copyright (c) 2005, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH cpc_event_diff 3CPC "28 Mar 2005" "SunOS 5.11" "CPU Performance Counters Library Functions" +.SH NAME +cpc_event_diff, cpc_event_accum \- simple difference and accumulate operations +.SH SYNOPSIS +.LP +.nf +cc [ \fIflag\fR... ] \fIfile\fR... \(milcpc [ \fIlibrary\fR... ] +#include <libcpc.h> + +\fBvoid\fR \fBcpc_event_accum\fR(\fBcpc_event_t *\fR\fIaccum\fR, \fBcpc_event_t *\fR\fIevent\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBcpc_event_diff\fR(\fBcpc_event_t *\fR\fIdiff\fR, \fBcpc_event_t *\fR\fIafter\fR, + \fBcpc_event_t *\fR\fIbefore\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBcpc_event_accum()\fR and \fBcpc_event_diff()\fR functions perform +common accumulate and difference operations on \fBcpc_event\fR(3CPC) data +structures. Use of these functions increases program portability, since +structure members are not referenced directly . +.SS "\fBcpc_event_accum()\fR" +.sp +.LP +The \fBcpc_event_accum()\fR function adds the \fBce_pic\fR fields of +\fIevent\fR into the corresponding fields of \fIaccum\fR. The \fBce_hrt\fR +field of \fIaccum\fR is set to the later of the times in \fIevent\fR and +\fIaccum\fR. +.SS "SPARC:" +.sp +.LP +The function adds the contents of the \fBce_tick\fR field of \fIevent\fR into +the corresponding field of \fIaccum\fR. +.SS "x86:" +.sp +.LP +The function adds the contents of the \fBce_tsc\fR field of \fIevent\fR into +the corresponding field of \fIaccum\fR. +.SS "\fBcpc_event_diff()\fR" +.sp +.LP +The \fBcpc_event_diff()\fR function places the difference between the +\fBce_pic\fR fields of \fIafter\fR and \fIbefore\fR and places them in the +corresponding field of \fIdiff\fR. The \fBce_hrt\fR field of \fIdiff\fR is set +to the \fBce_hrt\fR field of \fIafter\fR. +.SS "SPARC:" +.sp +.LP +Additionally, the function computes the difference between the \fBce_tick\fR +fields of \fIafter\fR and \fIbefore\fR, and places it in the corresponding +field of \fBdiff\fR. +.SS "x86:" +.sp +.LP +Additionally, the function computes the difference between the \fBce_tsc\fR +fields of \fIafter\fR and \fIbefore\fR, and places it in the corresponding +field of \fIdiff\fR. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityObsolete +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBcpc\fR(3CPC), \fBcpc_buf_add\fR(3CPC), \fBcpc_buf_sub\fR(3CPC), +\fBcpc_event\fR(3CPC), \fBlibcpc\fR(3LIB), \fBattributes\fR(5) +.SH NOTES +.sp +.LP +The \fBcpc_event_accum()\fR and \fBcpc_event_diff()\fR 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 \fBcpc_buf_add\fR(3CPC) and \fBcpc_buf_sub\fR(3CPC) +instead. diff --git a/usr/src/man/man3cpc/cpc_getcpuver.3cpc b/usr/src/man/man3cpc/cpc_getcpuver.3cpc new file mode 100644 index 0000000000..4275d1ad4a --- /dev/null +++ b/usr/src/man/man3cpc/cpc_getcpuver.3cpc @@ -0,0 +1,147 @@ +'\" te +.\" Copyright (c) 2005, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH cpc_getcpuver 3CPC "28 Mar 2005" "SunOS 5.11" "CPU Performance Counters Library Functions" +.SH NAME +cpc_getcpuver, cpc_getcciname, cpc_getcpuref, cpc_getusage, cpc_getnpic, +cpc_walk_names \- determine CPU performance counter configuration +.SH SYNOPSIS +.LP +.nf +cc [ \fIflag\fR... ] \fIfile\fR... \(milcpc [ \fIlibrary\fR... ] +#include <libcpc.h> + +\fBint\fR \fBcpc_getcpuver\fR(\fBvoid\fR); +.fi + +.LP +.nf +\fBconst char *\fR\fBcpc_getcciname\fR(\fBint\fR \fIcpuver\fR); +.fi + +.LP +.nf +\fBconst char *\fR\fBcpc_getcpuref\fR(\fBint\fR \fIcpuver\fR); +.fi + +.LP +.nf +\fBconst char *\fR\fBcpc_getusage\fR(\fBint\fR \fIcpuver\fR); +.fi + +.LP +.nf +\fBuint_t\fR \fBcpc_getnpic\fR(\fBint\fR \fIcpuver\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBcpc_walk_names\fR(\fBint\fR \fIcpuver\fR, \fBint\fR \fIregno\fR, \fBvoid *\fR\fIarg\fR, + \fBvoid (*\fR\fIaction\fR)(void *\fIarg\fR, int \fIregno\fR, const char *\fIname\fR, + uint8_t \fIbits\fR)); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBcpc_getcpuver()\fR function returns an abstract integer that corresponds +to the distinguished version of the underlying processor. The library +distinguishes between processors solely on the basis of their support for +performance counters, so the version returned should not be interpreted in any +other way. The set of values returned by the library is unique across all +processor implementations. +.sp +.LP +The \fBcpc_getcpuver()\fR function returns \(mi1 if the library cannot support +CPU performance counters on the current architecture. This may be because the +processor has no such counter hardware, or because the library is unable to +recognize it. Either way, such a return value indicates that the configuration +functions described on this manual page cannot be used. +.sp +.LP +The \fBcpc_getcciname()\fR function returns a printable description of the +processor performance counter interfaces-for example, the string \fIUltraSPARC +I&II\fR. Note that this name should not be assumed to be the same as the name +the manufacturer might otherwise ascribe to the processor. It simply names the +performance counter interfaces as understood by the library, and thus names the +set of performance counter events that can be described by that interface. If +the \fIcpuver\fR argument is unrecognized, the function returns \fINULL\fR. +.sp +.LP +The \fBcpc_getcpuref()\fR function returns a string that describes a reference +work that should be consulted to (allow a human to) understand the semantics of +the performance counter events that are known to the library. If the +\fIcpuver\fR argument is unrecognized, the function returns \fINULL\fR. The +string returned might be substantially longer than 80 characters. Callers +printing to a terminal might want to insert line breaks as appropriate. +.sp +.LP +The \fBcpc_getusage()\fR function returns a compact description of the +\fBgetsubopt()\fR-oriented syntax that is consumed by +\fBcpc_strtoevent\fR(3CPC). It is returned as a space-separated set of tokens +to allow the caller to wrap lines at convenient boundaries. If the \fIcpuver\fR +argument is unrecognized, the function returns \fINULL\fR. +.sp +.LP +The \fBcpc_getnpic()\fR function returns the number of valid fields in the +\fBce_pic\fR[] array of a \fBcpc_event_t\fR data structure. +.sp +.LP +The library maintains a list of events that it believes the processor capable +of measuring, along with the bit patterns that must be set in the corresponding +control register, and which counter the result will appear in. The +\fBcpc_walk_names()\fR function calls the \fIaction\fR(\|) function on each +element of the list so that an application can print appropriate help on the +set of events known to the library. The \fIarg\fR parameter is passed +uninterpreted from the caller on each invocation of the \fIaction\fR(\|) +function. +.sp +.LP +If the parameters specify an invalid or unknown CPU or register number, the +function silently returns without invoking the action function. +.SH USAGE +.sp +.LP +Prior to calling any of these functions, applications should call +\fBcpc_access\fR(3CPC) to determine if the counters are accessible on the +system. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelMT-Safe +_ +Interface StabilityObsolete +.TE + +.SH SEE ALSO +.sp +.LP +\fBcpc\fR(3CPC), \fBcpc_access\fR(3CPC), \fBcpc_cciname\fR(3CPC), +\fBcpc_cpuref\fR(3CPC), \fBcpc_npic\fR(3CPC), +\fBcpc_walk_events_all\fR(3CPC)\fBlibcpc\fR(3LIB), \fBattributes\fR(5) +.SH NOTES +.sp +.LP +The \fBcpc_getcpuver()\fR, \fBcpc_getcciname()\fR, \fBcpc_getcpuref()\fR, +\fBcpc_getusage()\fR, \fBcpc_getnpic()\fR, and \fBcpc_walk_names()\fR 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 \fBcpc_cciname\fR(3CPC), \fBcpc_cpuref\fR(3CPC), +\fBcpc_npic\fR(3CPC), and \fBcpc_npic\fR(3CPC) instead. +.sp +.LP +Only SPARC processors are described by the SPARC version of the library, and +only x86 processors are described by the x86 version of the library. diff --git a/usr/src/man/man3cpc/cpc_npic.3cpc b/usr/src/man/man3cpc/cpc_npic.3cpc new file mode 100644 index 0000000000..15d35abc0b --- /dev/null +++ b/usr/src/man/man3cpc/cpc_npic.3cpc @@ -0,0 +1,207 @@ +'\" te +.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH cpc_npic 3CPC "8 Oct 2008" "SunOS 5.11" "CPU Performance Counters Library Functions" +.SH NAME +cpc_npic, cpc_caps, cpc_cciname, cpc_cpuref, cpc_walk_events_all, +cpc_walk_generic_events_all, cpc_walk_events_pic, cpc_walk_generic_events_pic, +cpc_walk_attrs \- determine CPU performance counter configuration +.SH SYNOPSIS +.LP +.nf +cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-lcpc\fR [ \fIlibrary\fR\&.\|.\|. ] +#include <libcpc.h> + +\fBuint_t\fR \fBcpc_npic\fR(\fBcpc_t *\fR\fIcpc\fR); +.fi + +.LP +.nf +\fBuint_t\fR \fBcpc_caps\fR(\fBcpc_t *\fR\fIcpc\fR); +.fi + +.LP +.nf +\fBconst char *\fR\fBcpc_cciname\fR(\fBcpc_t *\fR\fIcpc\fR); +.fi + +.LP +.nf +\fBconst char *\fR\fBcpc_cpuref\fR(\fBcpc_t *\fR\fIcpc\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBcpc_walk_events_all\fR(\fBcpc_t *\fR\fIcpc\fR, \fBvoid *\fR\fIarg\fR, + \fBvoid\fR (*\fIaction\fR)(\fBvoid *\fR\fIarg\fR, const char *\fIevent\fR)); +.fi + +.LP +.nf +\fBvoid\fR \fBcpc_walk_generic_events_all\fR(\fBcpc_t *\fR\fIcpc\fR, \fBvoid *\fR\fIarg\fR, + \fBvoid\fR (*\fIaction\fR)(\fBvoid *\fR\fIarg\fR, \fBconst char *\fR\fIevent\fR)); +.fi + +.LP +.nf +\fBvoid\fR \fBcpc_walk_events_pic\fR(\fBcpc_t *\fR\fIcpc\fR, \fBuint_t\fR \fIpicno\fR, \fBvoid *\fR\fIarg\fR, + \fBvoid\fR (*\fIaction\fR)(\fBvoid *\fR\fIarg\fR, uint_t \fIpicno\fR, const char *\fIevent\fR)); +.fi + +.LP +.nf +\fBvoid\fR \fBcpc_walk_generic_events_pic\fR(\fBcpc_t *\fR\fIcpc\fR, \fBuint_t\fR \fIpicno\fR, + \fBvoid *\fR\fIarg\fR, \fBvoid\fR (*\fIaction\fR)(\fBvoid *\fR\fIarg\fR, \fBuint_t\fR \fIpicno\fR, + \fBconst char *\fR\fIevent\fR)); +.fi + +.LP +.nf +\fBvoid\fR \fBcpc_walk_attrs\fR(\fBcpc_t *\fR\fIcpc\fR, \fBvoid *\fR\fIarg\fR, + \fBvoid\fR (*\fIaction\fR)(\fBvoid *\fR\fIarg\fR, \fBconst char *\fR\fIattr\fR)); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBcpc_cciname()\fR function returns a printable description of the +processor performance counter interfaces, for example, the string UltraSPARC +III+ & IV. This name should not be assumed to be the same as the name the +manufacturer might otherwise ascribe to the processor. It simply names the +performance counter interfaces as understood by the system, and thus names the +set of performance counter events that can be described by that interface. +.sp +.LP +The \fBcpc_cpuref()\fR function returns a string that describes a reference +work that should be consulted to (allow a human to) understand the semantics of +the performance counter events that are known to the system. The string +returned might be substantially longer than 80 characters. Callers printing to +a terminal might want to insert line breaks as appropriate. +.sp +.LP +The \fBcpc_npic()\fR function returns the number of performance counters +accessible on the processor. +.sp +.LP +The \fBcpc_caps()\fR function returns a bitmap containing the bitwise +inclusive-OR of zero or more flags that describe the capabilities of the +processor. If \fBCPC_CAP_OVERFLOW_INTERRUPT\fR is present, the processor can +generate an interrupt when a hardware performance counter overflows. If +\fBCPC_CAP_OVERFLOW_PRECISE\fR is present, the processor can determine +precisely which counter overflowed, thereby affecting the behavior of the +overflow notification mechanism described in \fBcpc_bind_curlwp\fR(3CPC). +.sp +.LP +The system maintains a list of performance counter events supported by the +underlying processor. Some processors are able to count all events on all +hardware counters, while other processors restrict certain events to be counted +only on specific hardware counters. The system also maintains a list of +processor-specific attributes that can be used for advanced configuration of +the performance counter hardware. These functions allow applications to +determine what events and attributes are supported by the underlying processor. +The reference work pointed to by \fBcpc_cpuref()\fR should be consulted to +understand the reasons for and use of the attributes. +.sp +.LP +The \fBcpc_walk_events_all()\fR function calls the \fIaction\fR function on +each element of a global \fIevent\fR list. The \fIaction\fR function is called +with each event supported by the processor, regardless of which counter is +capable of counting it. The \fIaction\fR function is called only once for each +event, even if that event can be counted on more than one counter. +.sp +.LP +The \fBcpc_walk_events_pic()\fR function calls the action \fIfunction\fR with +each event supported by the counter indicated by the \fIpicno\fR argument, +where \fIpicno\fR ranges from 0 to the value returned by \fBcpc_npic()\fR. +.sp +.LP +The system maintains a list of platform independent performance counter events +known as generic events (see \fBgeneric_events\fR(3CPC)). +.sp +.LP +The \fBcpc_walk_generic_events_all()\fR function calls the action function on +each generic event available on the processor. The action function is called +for each generic event, regardless of which counter is capable of counting it. +The action function is called only once for each event, even if that event can +be counted on more than one counter. +.sp +.LP +The \fBcpc_walk_generic_events_pic()\fR function calls the action function with +each generic event supported by the counter indicated by the \fIpicno\fR +argument, where \fIpicno\fR ranges from 0 to the value returned by +\fBcpc_npic()\fR. +.sp +.LP +The system maintains a list of attributes that can be used to enable advanced +features of the performance counters on the underlying processor. The +\fBcpc_walk_attrs()\fR function calls the \fIaction\fR function for each +supported attribute name. See the reference material as returned by +\fBcpc_cpuref\fR(3CPC) for the semantics use of attributes. +.SH RETURN VALUES +.sp +.LP +The \fBcpc_cciname()\fR function always returns a printable description of the +processor performance counter interfaces. +.sp +.LP +The \fBcpc_cpuref()\fR function always returns a string that describes a +reference work. +.sp +.LP +The \fBcpc_npic()\fR function always returns the number of performance counters +accessible on the processor. +.sp +.LP +The \fBcpc_caps()\fR function always returns a bitmap containing the bitwise +inclusive-OR of zero or more flags that describe the capabilities of the +processor. +.sp +.LP +If the user-defined function specified by \fIaction\fR is not called, the +\fBcpc_walk_events_all()\fR, \fBcpc_walk_events_pic()\fR, +\fBcpc_walk_attrs()\fR, \fBcpc_walk_generic_events_pic()\fR, and +\fBcpc_walk_generic_events_pic()\fR functions set \fBerrno\fR to indicate the +error. +.SH ERRORS +.sp +.LP +The \fBcpc_walk_events_all()\fR, \fBcpc_walk_events_pic()\fR, +\fBcpc_walk_attrs()\fR, \fBcpc_walk_generic_events_pic()\fR, and +\fBcpc_walk_generic_events_pic()\fR functions will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBENOMEM\fR\fR +.ad +.RS 10n +.rt +There is not enough memory available. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBcpc_bind_curlwp\fR(3CPC), \fBgeneric_events\fR(3CPC), \fBlibcpc\fR(3LIB), +\fBattributes\fR(5) diff --git a/usr/src/man/man3cpc/cpc_open.3cpc b/usr/src/man/man3cpc/cpc_open.3cpc new file mode 100644 index 0000000000..ae654cd8d8 --- /dev/null +++ b/usr/src/man/man3cpc/cpc_open.3cpc @@ -0,0 +1,88 @@ +'\" te +.\" Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH cpc_open 3CPC "30 Jan 2004" "SunOS 5.11" "CPU Performance Counters Library Functions" +.SH NAME +cpc_open, cpc_close \- initialize the CPU Performance Counter library +.SH SYNOPSIS +.LP +.nf +cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-lcpc\fR [ \fIlibrary\fR\&.\|.\|. ] +#include <libcpc.h> + +\fBcpc_t *\fR\fBcpc_open\fR(\fBint\fR \fIvers\fR); +.fi + +.LP +.nf +\fBint\fR \fBcpc_close\fR(\fBcpc_t *\fR\fIcpc\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBcpc_open()\fR function initializes \fBlibcpc\fR(3LIB) and returns an +identifier that must be used as the \fIcpc\fR argument in subsequent +\fBlibcpc\fR function calls. The \fBcpc_open()\fR function takes an interface +version as an argument and returns \fINULL\fR if that version of the interface +is incompatible with the \fBlibcpc\fR implementation present on the system. +Usually, the argument has the value of \fBCPC_VER_CURRENT\fR bound to the +application when it was compiled. +.sp +.LP +The \fBcpc_close()\fR function releases all resources associated with the +\fIcpc\fR argument. Any bound counters utilized by the process are unbound. All +entities of type \fBcpc_set_t\fR and \fBcpc_buf_t\fR are invalidated and +destroyed. +.SH RETURN VALUES +.sp +.LP +If the version requested is supported by the implementation, \fBcpc_open()\fR +returns a \fBcpc_t\fR handle for use in all subsequent \fBlibcpc\fR operations. +If the implementation cannot support the version needed by the application, +\fBcpc_open()\fR returns \fINULL\fR, indicating that the application at least +needs to be recompiled to operate correctly on the new platform and might +require further changes. +.sp +.LP +The \fBcpc_close()\fR function always returns 0. +.SH ERRORS +.sp +.LP +These functions will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +The version requested by the client is incompatible with the implementation. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityEvolving +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBlibcpc\fR(3LIB), \fBattributes\fR(5) diff --git a/usr/src/man/man3cpc/cpc_pctx_bind_event.3cpc b/usr/src/man/man3cpc/cpc_pctx_bind_event.3cpc new file mode 100644 index 0000000000..afcb0645ce --- /dev/null +++ b/usr/src/man/man3cpc/cpc_pctx_bind_event.3cpc @@ -0,0 +1,130 @@ +'\" te +.\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH cpc_pctx_bind_event 3CPC "05 Mar 2007" "SunOS 5.11" "CPU Performance Counters Library Functions" +.SH NAME +cpc_pctx_bind_event, cpc_pctx_take_sample, cpc_pctx_rele, cpc_pctx_invalidate +\- access CPU performance counters in other processes +.SH SYNOPSIS +.LP +.nf +cc [ \fIflag\fR... ] \fIfile\fR... \(milcpc \(milpctx [ \fIlibrary\fR... ] +#include <libpctx.h> +#include <libcpc.h> + +\fBint\fR \fBcpc_pctx_bind_event\fR(\fBpctx_t *\fR\fIpctx\fR, \fBid_t\fR \fIlwpid\fR, \fBcpc_event_t *\fR\fIevent\fR, + \fBint\fR \fIflags\fR); +.fi + +.LP +.nf +\fBint\fR \fBcpc_pctx_take_sample\fR(\fBpctx_t *\fR\fIpctx\fR, \fBid_t\fR \fIlwpid\fR, \fBcpc_event_t *\fR\fIevent\fR); +.fi + +.LP +.nf +\fBint\fR \fBcpc_pctx_rele\fR(\fBpctx_t *\fR\fIpctx\fR, \fBid_t\fR \fIlwpid\fR); +.fi + +.LP +.nf +\fBint\fR \fBcpc_pctx_invalidate\fR(\fBpctx_t *\fR\fIpctx\fR, \fBid_t\fR \fIlwpid\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +These functions are designed to be run in the context of an event handler +created using the \fBlibpctx\fR(3LIB) family of functions that allow the +caller, also known as the \fIcontrolling process\fR, to manipulate the +performance counters in the context of a \fIcontrolled process\fR. The +controlled process is described by the \fIpctx\fR argument, which must be +obtained from an invocation of \fBpctx_capture\fR(3CPC) or +\fBpctx_create\fR(3CPC) and passed to the functions described on this page in +the context of an event handler. +.sp +.LP +The semantics of the functions \fBcpc_pctx_bind_event()\fR, +\fBcpc_pctx_take_sample()\fR, and \fBcpc_pctx_rele()\fR are directly analogous +to those of \fBcpc_bind_event()\fR, \fBcpc_take_sample()\fR, and +\fBcpc_rele()\fR described on the \fBcpc_bind_event\fR(3CPC) manual page. +.sp +.LP +The \fBcpc_pctx_invalidate()\fR function allows the performance context to be +invalidated in an \fBLWP\fR in the controlled process. +.SH RETURN VALUES +.sp +.LP +These functions return \fB0\fR on success. On failure, they return \fB\(mi1\fR +and set \fBerrno\fR to indicate the error. +.SH ERRORS +.sp +.LP +The \fBcpc_pctx_bind_event()\fR, \fBcpc_pctx_take_sample()\fR, and +\fBcpc_pctx_rele()\fR functions return the same \fBerrno\fR values the +analogous functions described on the \fBcpc_bind_event\fR(3CPC) manual page. In +addition, these function may fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEACCES\fR\fR +.ad +.RS 10n +.rt +For \fBcpc_pctx_bind_event()\fR, access to the requested hypervisor event was +denied. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBESRCH\fR\fR +.ad +.RS 10n +.rt +The value of the \fIlwpid\fR argument is invalid in the context of the +controlled process. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelUnsafe +_ +Interface StabilityEvolving +.TE + +.SH SEE ALSO +.sp +.LP +\fBcpc\fR(3CPC), \fBcpc_bind_event\fR(3CPC), \fBlibcpc\fR(3LIB), +\fBpctx_capture\fR(3CPC), \fBpctx_create\fR(3CPC), \fBattributes\fR(5) +.SH NOTES +.sp +.LP +The \fBcpc_pctx_bind_event()\fR, \fBcpc_pctx_invalidate()\fR, +\fBcpc_pctx_rele()\fR, and \fBcpc_pctx_take_sample()\fR 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 \fBcpc_bind_pctx\fR(3CPC), \fBcpc_unbind\fR(3CPC), and +\fBcpc_set_sample\fR(3CPC) instead. +.sp +.LP +The capability to create and analyze overflow events in other processes is not +available, though it may be made available in a future version of this API. In +the current implementation, the \fIflags\fR field must be specified as 0. diff --git a/usr/src/man/man3cpc/cpc_set_create.3cpc b/usr/src/man/man3cpc/cpc_set_create.3cpc new file mode 100644 index 0000000000..02dfa86aa9 --- /dev/null +++ b/usr/src/man/man3cpc/cpc_set_create.3cpc @@ -0,0 +1,258 @@ +'\" te +.\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH cpc_set_create 3CPC "20 Aug 2007" "SunOS 5.11" "CPU Performance Counters Library Functions" +.SH NAME +cpc_set_create, cpc_set_destroy, cpc_set_add_request, cpc_walk_requests \- +manage sets of counter requests +.SH SYNOPSIS +.LP +.nf +cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-lcpc\fR [ \fIlibrary\fR\&.\|.\|. ] +#include <libcpc.h> + +\fBcpc_set_t *\fR\fBcpc_set_create\fR(\fBcpc_t *\fR\fIcpc\fR); +.fi + +.LP +.nf +\fBint\fR \fBcpc_set_destroy\fR(\fBcpc_t *\fR\fIcpc\fR, \fBcpc_set_t *\fR\fIset\fR); +.fi + +.LP +.nf +\fBint\fR \fBcpc_set_add_request\fR(\fBcpc_t *\fR\fIcpc\fR, \fBcpc_set_t *\fR\fIset\fR, + \fBconst char *\fR\fIevent\fR, \fBuint64_t\fR \fIpreset\fR, \fBuint_t\fR \fIflags\fR, + \fBuint_t\fR \fInattrs\fR, \fBconst cpc_attr_t *\fR\fIattrs\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBcpc_walk_requests\fR(\fBcpc_t *\fR\fIcpc\fR, \fBcpc_set_t *\fR\fIset\fR, \fBvoid *\fR\fIarg\fR, + \fBvoid (*\fR\fIaction\fR)(void *\fIarg\fR, int \fIindex\fR, const char *\fIevent\fR, + uint64_t \fIpreset\fR, uint_t \fIflags\fR, int \fInattrs\fR, + const cpc_attr_t *\fIattrs\fR)); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBcpc_set_create()\fR function returns an initialized and empty CPC set. A +CPC set contains some number of requests, where a request represents a specific +configuration of a hardware performance instrumentation counter present on the +processor. The \fBcpc_set_t\fR data structure is opaque and must not be +accessed directly by the application. +.sp +.LP +Applications wanting to program one or more performance counters must create an +empty set with \fBcpc_set_create()\fR and add requests to the set with +\fBcpc_set_add_request()\fR. Once all requests have been added to a set, the +set must be bound to the hardware performance counters (see +\fBcpc_bind_curlwp()\fR, \fBcpc_bind_pctx()\fR, and \fBcpc_bind_cpu()\fR, all +described on \fBcpc_bind_curlwp\fR(3CPC)) before counting events. At bind time, +the system attempts to match each request with an available physical counter +capable of counting the event specified in the request. If the bind is +successful, a 64-bit virtualized counter is created to store the counts +accumulated by the hardware counter. These counts are stored and managed in CPC +buffers separate from the CPC set whose requests are being counted. See +\fBcpc_buf_create\fR(3CPC) and \fBcpc_set_sample\fR(3CPC). +.sp +.LP +The \fBcpc_set_add_request()\fR function specifies a configuration of a +hardware counter. The arguments to \fBcpc_set_add_request()\fR are: +.sp +.ne 2 +.mk +.na +\fB\fIevent\fR\fR +.ad +.RS 17n +.rt +A string containing the name of an event supported by the system's processor. +The \fBcpc_walk_events_all()\fR and \fBcpc_walk_events_pic()\fR functions (both +described on \fBcpc_npic\fR(3CPC)) can be used to query the processor for the +names of available events. Certain processors allow the use of raw event codes, +in which case a string representation of an event code in a form acceptable to +\fBstrtol\fR(3C) can be used as the \fIevent\fR argument. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIpreset\fR\fR +.ad +.RS 17n +.rt +The value with which the system initializes the counter. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fIflags\fR\fR +.ad +.RS 17n +.rt +Three flags are defined that modify the behavior of the counter acting on +behalf of this request: +.sp +.ne 2 +.mk +.na +\fB\fBCPC_COUNT_USER\fR\fR +.ad +.sp .6 +.RS 4n +The counter should count events that occur while the processor is in user mode. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCPC_COUNT_SYSTEM\fR\fR +.ad +.sp .6 +.RS 4n +The counter should count events that occur while the processor is in privileged +mode. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCPC_OVF_NOTIFY_EMT\fR\fR +.ad +.sp .6 +.RS 4n +Request a signal to be sent to the application when the physical counter +overflows. A \fBSIGEMT\fR signal is delivered if the processor is capable of +delivering an interrupt when the counter counts past its maximum value. All +requests in the set containing the counter that overflowed are stopped until +the set is rebound. +.RE + +At least one of \fBCPC_COUNT_USER\fR or \fBCPC_COUNT_SYSTEM\fR must be +specified to program the hardware for counting. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fInattrs\fR, \fIattrs\fR\fR +.ad +.RS 17n +.rt +The \fInattrs\fR argument specifies the number of attributes pointed to by the +\fIattrs\fR argument, which is an array of \fBcpc_attr_t\fR structures +containing processor-specific attributes that modify the request's +configuration. The \fBcpc_walk_attrs()\fR function (see \fBcpc_npic\fR(3CPC)) +can be used to query the processor for the list of attributes it accepts. The +library makes a private copy of the \fIattrs\fR array, allowing the application +to dispose of it immediately after calling \fBcpc_set_add_request()\fR. +.RE + +.sp +.LP +The \fBcpc_walk_requests()\fR function calls the action function on each +request that has been added to the set. The \fIarg\fR argument is passed +unmodified to the \fIaction\fR function with each call. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBcpc_set_create()\fR returns a handle to the +opaque \fBcpc_set_t\fR data structure. Otherwise, NULL is returned and +\fBerrno\fR is set to indicate the error. +.sp +.LP +Upon successful completion, \fBCpc_set_destroy()\fR returns 0. Otherwise, -1 is +returned and \fBerrno\fR is set to indicate the error. +.sp +.LP +Upon successful completion, \fBcpc_set_add_request()\fR returns an integer +index used to refer to the data generated by that request during data +retrieval. Otherwise, -1 is returned and \fBerrno\fR is set to indicate the +error. +.SH ERRORS +.sp +.LP +These functions will fail if: +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 10n +.rt +An event, attribute, or flag passed to \fBcpc_set_add_request()\fR was invalid. +.sp +For \fBcpc_set_destroy()\fR and \fBcpc_set_add_request()\fR, the set parameter +was not created with the given cpc_t. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOMEM\fR\fR +.ad +.RS 10n +.rt +There was not enough memory available to the process to create the library's +data structures. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityCommitted +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBcpc_bind_curlwp\fR(3CPC), \fBcpc_buf_create\fR(3CPC), \fBcpc_npic\fR(3CPC), +\fBcpc_seterrhndlr\fR(3CPC), \fBlibcpc\fR(3LIB), \fBstrtol\fR(3C), +\fBattributes\fR(5) +.SH NOTES +.sp +.LP +The system automatically determines which particular physical counter to use to +count the events specified by each request. Applications can force the system +to use a particular counter by specifying the counter number in an attribute +named \fIpicnum\fR that is passed to \fBcpc_set_add_request()\fR. Counters are +numbered from 0 to \fIn\fR - 1, where n is the number of counters in the +processor as returned by \fBcpc_npic\fR(3CPC). +.sp +.LP +Some processors, such as UltraSPARC, do not allow the hardware counters to be +programmed differently. In this case, all requests in the set must have the +same configuration, or an attempt to bind the set will return \fBEINVAL\fR. If +a \fBcpc_errhndlr_t\fR has been registered with \fBcpc_seterrhndlr\fR(3CPC), +the error handler is called with subcode \fBCPC_CONFLICTING_REQS\fR. For +example, on UltraSPARC \fBpic0\fR and \fBpic1\fR must both program events in +the same processor mode (user mode, kernel mode, or both). For example, +\fBpic0\fR cannot be programmed with \fBCPC_COUNT_USER\fR while \fBpic1\fR is +programmed with \fBCPC_COUNT_SYSTEM\fR. Refer to the hardware documentation +referenced by \fBcpc_cpuref\fR(3CPC) for details about a particular processor's +performance instrumentation hardware. diff --git a/usr/src/man/man3cpc/cpc_seterrfn.3cpc b/usr/src/man/man3cpc/cpc_seterrfn.3cpc new file mode 100644 index 0000000000..5eaa568af0 --- /dev/null +++ b/usr/src/man/man3cpc/cpc_seterrfn.3cpc @@ -0,0 +1,98 @@ +'\" te +.\" Copyright (c) 2004, Sun Microsystems, Inc. +.\" All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH cpc_seterrfn 3CPC "28 Mar 2005" "SunOS 5.11" "CPU Performance Counters Library Functions" +.SH NAME +cpc_seterrfn \- control libcpc error reporting +.SH SYNOPSIS +.LP +.nf +cc [ \fIflag\fR... ] \fIfile\fR... \(milcpc [ \fIlibrary\fR... ] +#include <libcpc.h> + +\fBtypedef void (\fR\fBcpc_errfn_t\fR)(\fBconst char *\fR\fIfn\fR, \fBconst char *\fR\fIfmt\fR, \fBva_list\fR \fIap\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBcpc_seterrfn\fR(\fBcpc_errfn_t *\fR\fIerrfn\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +For the convenience of programmers instrumenting their code, several +\fBlibcpc\fR(3LIB) functions automatically emit to \fBstderr\fR error messages +that attempt to provide a more detailed explanation of their error return +values. While this can be useful for simple programs, some applications may +wish to report their errors differently\(emfor example, to a window or to a log +file. +.sp +.LP +The \fBcpc_seterrfn()\fR function allows the caller to provide an alternate +function for reporting errors; the type signature is shown above. The \fIfn\fR +argument is passed the library function name that detected the error, the +format string \fIfmt\fR and argument pointer \fIap\fR can be passed directly to +\fBvsnprintf\fR(3C) or similar \fBvarargs\fR-based routine for formatting. +.sp +.LP +The default printing routine can be restored by calling the routine with an +\fIerrfn\fR argument of \fINULL\fR. +.SH EXAMPLES +.LP +\fBExample 1 \fRDebugging example. +.sp +.LP +This example produces error messages only when debugging the program containing +it, or when the \fBcpc_strtoevent()\fR function is reporting an error when +parsing an event specification + +.sp +.in +2 +.nf +\fBint debugging; +void +myapp_errfn(const char *fn, const char *fmt, va_list ap) +{ + if (strcmp(fn, "strtoevent") != 0 && !debugging) + return; + (void) fprintf(stderr, "myapp: cpc_%s(): ", fn); + (void) vfprintf(stderr, fmt, ap); +}\fR +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelUnsafe +_ +Interface StabilityObsolete +.TE + +.SH SEE ALSO +.sp +.LP +\fBcpc\fR(3CPC), \fBcpc_seterrhndlr\fR(3CPC), \fBlibcpc\fR(3LIB), +\fBvsnprintf\fR(3C), \fBattributes\fR(5) +.SH NOTES +.sp +.LP +The \fBcpc_seterrfn()\fR function exists for binary compatibility only. Source +containing this function will not compile. This function is obsolete and might +be removed in a future release. Applications should use +\fBcpc_seterrhndlr\fR(3CPC) instead. diff --git a/usr/src/man/man3cpc/cpc_seterrhndlr.3cpc b/usr/src/man/man3cpc/cpc_seterrhndlr.3cpc new file mode 100644 index 0000000000..359198dd74 --- /dev/null +++ b/usr/src/man/man3cpc/cpc_seterrhndlr.3cpc @@ -0,0 +1,200 @@ +'\" te +.\" Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH cpc_seterrhndlr 3CPC "30 Jan 2004" "SunOS 5.11" "CPU Performance Counters Library Functions" +.SH NAME +cpc_seterrhndlr \- control libcpc error reporting +.SH SYNOPSIS +.LP +.nf +cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-lcpc\fR [ \fIlibrary\fR\&.\|.\|. ] +#include <libcpc.h> + +\fBtypedef void(\fR\fBcpc_errhndlr_t\fR)(\fBcpc_t *\fR\fIcpc\fR, \fBconst char *\fR\fIfn\fR, \fBint\fR \fIsubcode\fR, + \fBconst char *\fR\fIfmt\fR, \fBva_list\fR \fIap\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBcpc_seterrhndlr\fR(\fBcpc_t *\fR\fIcpc\fR, \fBcpc_errhndlr_t *\fR\fIerrfn\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +For the convenience of programmers instrumenting their code, several +\fBlibcpc\fR(3LIB) functions automatically emit to \fBstderr\fR error messages +that attempt to provide a more detailed explanation of their error return +values. While this can be useful for simple programs, some applications might +wanat to report their errors differently, for example, to a window or to a log +file. +.sp +.LP +The \fBcpc_seterrhndlr()\fR function allows the caller to provide an alternate +function for reporting errors. The type signature is shown in the SYNOPSIS. The +\fIfn\fR argument is passed the library function name that detected the error, +an integer subcode indicating the specific error condidtion that has occurred, +and the format string \fIfmt\fR that contains a textual description of the +integer subcode. The format string \fIfmt\fR and argument pointer \fIap\fR can +be passed directly to \fBvsnprintf\fR(3C) or similar \fIvarargs\fR-based +function for formatting. +.sp +.LP +The integer subcodes are provided to allow programs to recognize error +conditions while using \fBlibcpc\fR. The \fIfmt\fR string is provided as a +convenience for easy printing. The error subcodes are: +.sp +.ne 2 +.mk +.na +\fB\fBCPC_INVALID_EVENT\fR\fR +.ad +.sp .6 +.RS 4n +A specified event is not supported by the processor. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCPC_INVALID_PICNUM\fR\fR +.ad +.sp .6 +.RS 4n +The counter number does not fall in the range of available counters. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCPC_INVALID_ATTRIBUTE\fR\fR +.ad +.sp .6 +.RS 4n +A specified attribute is not supported by the processor. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCPC_ATTRIBUTE_OUT_OF_RANGE\fR\fR +.ad +.sp .6 +.RS 4n +The value of an attribute is outside the range supported by the processor. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCPC_RESOURCE_UNAVAIL\fR\fR +.ad +.sp .6 +.RS 4n +A hardware resource necessary for completing an operation was unavailable. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCPC_PIC_NOT_CAPABLE\fR\fR +.ad +.sp .6 +.RS 4n +The requested counter cannot count an assigned event. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCPC_REQ_INVALID_FLAGS\fR\fR +.ad +.sp .6 +.RS 4n +One or more requests has invalid flags. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCPC_CONFLICTING_REQS\fR\fR +.ad +.sp .6 +.RS 4n +The requests in a set cannot be programmed onto the hardware at the same time. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBCPC_ATTR_REQUIRES_PRIVILEGE\fR\fR +.ad +.sp .6 +.RS 4n +A request contains an attribute which requires the cpc_cpu privilege, which the +process does not have. +.RE + +.sp +.LP +The default printing routine can be restored by calling the routine with an +\fIerrfn\fR argument of \fINULL\fR. +.SH EXAMPLES +.LP +\fBExample 1 \fRDebugging example. +.sp +.LP +The following example produces error messages only when debugging the program +containing it, or when the \fBcpc_bind_curlwp()\fR, \fBcpc_bind_cpu()\fR, or +\fBcpc_bind_pctx()\fR functions are reporting an error when binding a +cpc_set_t. + +.sp +.in +2 +.nf +int debugging; +void +myapp_errfn(const char *fn, int subcode, const char *fmt, va_list ap) +{ + if (strncmp(fn, "cpc_bind", 8) != 0 && !debugging) + return; + (void) fprintf(stderr, "myapp: cpc_%s(): ", fn); + (void) vfprintf(stderr, fmt, ap); +} +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityEvolving +_ +MT-LevelSafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBcpc_bind_curlwp\fR(3CPC), \fBlibcpc\fR(3LIB), \fBvsnprintf\fR(3C), +\fBattributes\fR(5) diff --git a/usr/src/man/man3cpc/cpc_shared_open.3cpc b/usr/src/man/man3cpc/cpc_shared_open.3cpc new file mode 100644 index 0000000000..74c483a63d --- /dev/null +++ b/usr/src/man/man3cpc/cpc_shared_open.3cpc @@ -0,0 +1,203 @@ +'\" te +.\" Copyright (c) 2004, Sun Microsystems, Inc. +.\" All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH cpc_shared_open 3CPC "28 Mar 2005" "SunOS 5.11" "CPU Performance Counters Library Functions" +.SH NAME +cpc_shared_open, cpc_shared_bind_event, cpc_shared_take_sample, +cpc_shared_rele, cpc_shared_close \- use CPU performance counters on processors +.SH SYNOPSIS +.LP +.nf +cc [ \fIflag\fR... ] \fIfile\fR... \(milcpc [ \fIlibrary\fR... ] +#include <libcpc.h> + +\fBint\fR \fBcpc_shared_open\fR(\fBvoid\fR); +.fi + +.LP +.nf +\fBint\fR \fBcpc_shared_bind_event\fR(\fBint\fR \fIfd\fR, \fBcpc_event_t *\fR\fIevent\fR, \fBint\fR \fIflags\fR); +.fi + +.LP +.nf +\fBint\fR \fBcpc_shared_take_sample\fR(\fBint\fR \fIfd\fR, \fBcpc_event_t *\fR\fIevent\fR); +.fi + +.LP +.nf +\fBint\fR \fBcpc_shared_rele\fR(\fBint\fR \fIfd\fR); +.fi + +.LP +.nf +\fBvoid\fR \fBcpc_shared_close\fR(\fBint\fR \fIfd\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBcpc_shared_open()\fR 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. +.sp +.LP +The \fBcpc_shared_bind_event()\fR, \fBcpc_shared_take_sample()\fR, and +\fBcpc_shared_rele()\fR functions are directly analogous to the corresponding +\fBcpc_bind_event()\fR, \fBcpc_take_sample()\fR, and \fBcpc_rele()\fR functions +described on the \fBcpc_bind_event\fR(3CPC)manual page, except that they +operate on the counters of a particular processor. +.SH USAGE +.sp +.LP +If a thread wishes to access the counters using this interface, it \fBmust\fR +do so using a thread bound to an lwp, (see the \fBTHR_BOUND\fR flag to +\fBthr_create\fR(3C)), that has in turn bound itself to a processor using +\fBprocessor_bind\fR(2). +.sp +.LP +Unlike the \fBcpc_bind_event\fR(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. +.sp +.LP +The first successful invocation of \fBcpc_shared_open()\fR will immediately +\fBinvalidate\fR \fIall\fR existing performance counter context on the system, +and \fBprevent\fR \fIall\fR subsequent attempts to bind counter context to lwps +from succeeding anywhere on the system until the last caller invokes +\fBcpc_shared_close()\fR. +.sp +.LP +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. +.sp +.LP +Access to the shared counters is mediated by file permissions on a \fBcpc\fR +pseudo device. Only a user with the {\fBPRIV_SYS_CONFIG\fR} privilege is +allowed to access the shared device. This control prevents use of the counters +on a per-lwp basis to other users. +.sp +.LP +The \fBCPC_BIND_LWP_INHERIT\fR and \fBCPC_BIND_EMT_OVF\fR flags are invalid for +the shared interface. +.SH RETURN VALUES +.sp +.LP +On success, the functions (except for \fBcpc_shared_close()\fR) return 0. On +failure, the functions return -1 and set \fBerrno\fR to indicate the reason. +.SH ERRORS +.sp +.ne 2 +.mk +.na +\fB\fBEACCES\fR\fR +.ad +.RS 11n +.rt +The caller does not have appropriate privilege to access the CPU performance +counters system-wide. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEAGAIN\fR\fR +.ad +.RS 11n +.rt +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. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEAGAIN\fR\fR +.ad +.RS 11n +.rt +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 \fBcpc_shared_close\fR(\|), before retrying the operation. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBEINVAL\fR\fR +.ad +.RS 11n +.rt +The counters cannot be accessed on the current CPU because the calling thread +is not bound to that CPU using \fBprocessor_bind\fR(2). +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENOTSUP\fR\fR +.ad +.RS 11n +.rt +The caller has attempted an operation that is illegal or not supported on the +current platform. +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBENXIO\fR\fR +.ad +.RS 11n +.rt +The current machine either has no performance counters, or has been configured +to disallow access to them system-wide. +.RE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +MT-LevelMT-Safe +_ +Interface StabilityObsolete +.TE + +.SH SEE ALSO +.sp +.LP +\fBprocessor_bind\fR(2), \fBcpc\fR(3CPC), \fBcpc_bind_cpu\fR(3CPC), +\fBcpc_bind_event\fR(3CPC), \fBcpc_set_sample\fR(3CPC), \fBcpc_unbind\fR(3CPC), +\fBlibcpc\fR(3LIB), \fBthr_create\fR(3C), \fBattributes\fR(5) +.SH NOTES +.sp +.LP +The \fBcpc_shared_open()\fR, \fBcpc_shared_bind_event()\fR, +\fBcpc_shared_take_sample()\fR, \fBcpc_shared_rele()\fR, and +\fBcpc_shared_close()\fR 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 +\fBcpc_bind_cpu\fR(3CPC), \fBcpc_set_sample\fR(3CPC), and +\fBcpc_unbind\fR(3CPC) instead. diff --git a/usr/src/man/man3cpc/cpc_strtoevent.3cpc b/usr/src/man/man3cpc/cpc_strtoevent.3cpc new file mode 100644 index 0000000000..afd1974a31 --- /dev/null +++ b/usr/src/man/man3cpc/cpc_strtoevent.3cpc @@ -0,0 +1,185 @@ +'\" te +.\" Copyright (c) 2004, Sun Microsystems, Inc. +.\" All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH cpc_strtoevent 3CPC "28 Mar 2005" "SunOS 5.11" "CPU Performance Counters Library Functions" +.SH NAME +cpc_strtoevent, cpc_eventtostr \- translate strings to and from events +.SH SYNOPSIS +.LP +.nf +cc [ \fIflag\fR... ] \fIfile\fR... \(milcpc [ \fIlibrary\fR... ] +#include <libcpc.h> + +\fBint\fR \fBcpc_strtoevent\fR(\fBint\fR \fIcpuver\fR, \fBconst char *\fR\fIspec\fR, \fBcpc_event_t *\fR\fIevent\fR); +.fi + +.LP +.nf +\fBchar *\fR\fBcpc_eventtostr\fR(\fBcpc_event_t *\fR\fIevent\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBcpc_strtoevent()\fR function translates an event specification to the +appropriate collection of control bits in a \fBcpc_event_t\fR structure pointed +to by the \fIevent\fR argument. The event specification is a +\fBgetsubopt\fR(3C)-style string that describes the event and any attributes +that the processor can apply to the event or events. If successful, the +funciton returns 0, the \fBce_cpuver\fR field and the ISA-dependent control +registers of event are initialized appropriately, and the rest of the +\fBcpc_event_t\fR structure is initialized to 0. +.sp +.LP +The \fBcpc_eventtostr()\fR function takes an event and constructs a compact +canonical string representation for that event. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBcpc_strtoevent()\fR 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 \fBcpc_seterrfn\fR(3CPC)). +.sp +.LP +Upon successful completion, \fBcpc_eventtostr()\fR returns a pointer to a +string. The string returned must be freed by the caller using \fBfree\fR(3C). +If \fBcpc_eventtostr()\fR fails, a null pointer is returned. +.SH USAGE +.sp +.LP +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 \fBcpc_getusage()\fR function (see \fBcpc_getcpuver\fR(3CPC)), but is +explained in further detail below. +.SS "UltraSPARC" +.sp +.LP +On UltraSPARC processors, the syntax for setting options is as follows: +.sp +.in +2 +.nf +\fBpic0\fR=<eventspec>,\fBpic1\fR=<eventspec> [\fB,sys\fR] [\fB,nouser\fR] +.fi +.in -2 +.sp + +.sp +.LP +This syntax, which reflects the simplicity of the options available using the +\fB%pcr\fR register, forces both counter events to be selected. By default +only user events are counted; however, the \fBsys\fR keyword allows system +(kernel) events to be counted as well. User event counting can be disabled by +specifying the \fBnouser\fR keyword. +.sp +.LP +The keywords \fBpic0\fR and \fBpic1\fR may be omitted; they can be used to +resolve ambiguities if they exist. +.SS "Pentium I" +.sp +.LP +On Pentium processors, the syntax for setting counter options is as follows: +.sp +.in +2 +.nf +\fBpic0\fR=<eventspec>,\fBpic1\fR=<eventspec> [\fB,sys[[0|1]]]\fR [\fB,nouser[[0|1]]]\fR +[\fB,noedge[[0|1]]]\fR [\fB,pc[[0|1]]]\fR +.fi +.in -2 +.sp + +.sp +.LP +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. +.sp +.LP +There are some additional keywords. The \fBnoedge\fR keyword specifies that the +counter should count clocks (duration) instead of events. The \fBpc\fR 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 uptoon how the motherboard +manufacturer has chosen to connect it, if it is connected at all. +.SS "Pentium II" +.sp +.LP +For Pentium II processors, the syntax is substantially more complex, reflecting +the complex configuration options available: +.sp +.in +2 +.nf +\fBpic0\fR=<eventspec>,\fBpic1\fR=<eventspec> [\fB,sys[[0|1]]]\fR +[\fB,nouser[[0|1]]]\fR [\fB,noedge[[0|1]]]\fR [\fB,pc[[0|1]]]\fR [\fB,inv[[0|1]]]\fR [\fB,int[[0|1]]]\fR +[\fB,cmask[0|1]\fR=<maskspec>] [\fB,umask[0|1]\fR=<maskspec>] +.fi +.in -2 +.sp + +.sp +.LP +This syntax is a straightforward extension of the earlier syntax. The +additional \fBinv\fR, \fBint\fR, \fBcmask0\fR, \fBcmask1\fR, \fBumask0\fR, and +\fBumask1\fR keywords allow extended counting semantics. The mask specification +is a number between 0 and 255, expressed in hexadecimal, octal or decimal +notation. +.SH EXAMPLES +.SS "SPARC" +.LP +\fBExample 1 \fRSPARC Example. +.sp +.in +2 +.nf +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); +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityObsolete +_ +MT-LevelMT-Safe +.TE + +.SH SEE ALSO +.sp +.LP +\fBcpc\fR(3CPC), \fBcpc_getcpuver\fR(3CPC), \fBcpc_set_add_request\fR(3CPC), +\fBcpc_seterrfn\fR(3CPC), \fBfree\fR(3C), \fBgetsubopt\fR(3C), +\fBlibcpc\fR(3LIB), \fBattributes\fR(5) +.SH NOTES +.sp +.LP +The \fBcpc_strtoevent()\fR and \fBcpc_eventtostr()\fR 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 \fBcpc_set_add_request\fR(3CPC) instead. +.sp +.LP +These functions are provided as a convenience only. As new processors are +usually released asynchronously with software, the library allows the +\fBpic0\fR and \fBpic1\fR keywords to interpret numeric values specified +directly in hexadecimal, octal, or decimal. diff --git a/usr/src/man/man3cpc/cpc_version.3cpc b/usr/src/man/man3cpc/cpc_version.3cpc new file mode 100644 index 0000000000..91b9b1d994 --- /dev/null +++ b/usr/src/man/man3cpc/cpc_version.3cpc @@ -0,0 +1,92 @@ +'\" te +.\" Copyright (c) 2003, Sun Microsystems, Inc. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH cpc_version 3CPC "28 Mar 2005" "SunOS 5.11" "CPU Performance Counters Library Functions" +.SH NAME +cpc_version \- coordinate CPC library and application versions +.SH SYNOPSIS +.LP +.nf +cc [ \fIflag\fR... ] \fIfile\fR... \(milcpc [ \fIlibrary\fR... ] +#include <libcpc.h> + +\fBuint_t\fR \fBcpc_version\fR(\fBuint_t\fR \fIversion\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBcpc_version()\fR function takes an interface version as an argument and +returns an interface version as a result. Usually, the argument will be the +value of \fBCPC_VER_CURRENT\fR bound to the application when it was compiled. +.SH RETURN VALUES +.sp +.LP +If the version requested is still supported by the implementation, +\fBcpc_version()\fR returns the requested version number and the application +can use the facilities of the library on that platform. If the implementation +cannot support the version needed by the application, \fBcpc_version()\fR +returns \fBCPC_VER_NONE\fR, indicating that the application will at least need +to be recompiled to operate correctly on the new platform, and may require +further changes. +.sp +.LP +If \fIversion\fR is \fBCPC_VER_NONE\fR, \fBcpc_version()\fR returns the most +current version of the library. +.SH EXAMPLES +.LP +\fBExample 1 \fR Protect an application from using an incompatible library. +.sp +.LP +The following lines of code protect an application from using an incompatible +library: + +.sp +.in +2 +.nf +if (cpc_version(CPC_VER_CURRENT) == CPC_VER_NONE) { + /* version mismatch - library cannot translate */ + exit(1); +} +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityEvolving +_ +MT-LevelUnsafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBcpc\fR(3CPC), \fBcpc_open\fR(3CPC), \fBlibcpc\fR(3LIB), \fBattributes\fR(5) +.SH NOTES +.sp +.LP +The \fBcpc_version()\fR function exists for binary compatibility only. Source +containing this function will not compile. This function is obsolete and might +be removed in a future release. Applications should use \fBcpc_open\fR(3CPC) +instead. +.sp +.LP +The version number is used only to express incompatible semantic changes in the +performance counter interfaces on the given platform within a single +instruction set architecture, for example, when a new set of performance +counter registers are added to an existing processor family that cannot be +specified in the existing \fBcpc_event_t\fR data structure. diff --git a/usr/src/man/man3cpc/generic_events.3cpc b/usr/src/man/man3cpc/generic_events.3cpc new file mode 100644 index 0000000000..278c0b8db0 --- /dev/null +++ b/usr/src/man/man3cpc/generic_events.3cpc @@ -0,0 +1,1480 @@ +'\" te +.\" Copyright (c) 2005 Innovative Computing Labs Computer Science Department, University of Tennessee, Knoxville, TN. All Rights Reserved. +.\" Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. +.\" * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. * Neither the name of the University of Tennessee nor the names of its contributors +.\" may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY +.\" AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, +.\" OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. This open source software +.\" license conforms to the BSD License template. +.\" Portions Copyright (c) 2008, Sun Microsystems Inc. All Rights Reserved. +.TH generic_events 3CPC "8 Oct 2008" "SunOS 5.11" "CPU Performance Counters Library Functions" +.SH NAME +generic_events \- generic performance counter events +.SH DESCRIPTION +.sp +.LP +The Solaris \fBcpc\fR(3CPC) subsystem implements a number of predefined, +generic performance counter events. Each generic event maps onto a single +platform specific event and one or more optional attributes. Each hardware +platform only need support a subset of the total set of generic events. +.sp +.LP +The defined generic events are: +.sp +.ne 2 +.mk +.na +\fB\fBPAPI_br_cn\fR\fR +.ad +.RS 16n +.rt +Conditional branch instructions +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAPI_br_ins\fR\fR +.ad +.RS 16n +.rt +Branch instructions taken +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAPI_br_msp\fR\fR +.ad +.RS 16n +.rt +Conditional branch instructions mispredicted +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAPI_br_ntk\fR\fR +.ad +.RS 16n +.rt +Conditional branch instructions not taken +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAPI_br_prc\fR\fR +.ad +.RS 16n +.rt +Conditional branch instructions correctly predicted +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAPI_br_ucn\fR\fR +.ad +.RS 16n +.rt +Unconditional branch instructions +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAPI_bru_idl\fR\fR +.ad +.RS 16n +.rt +Cycles branch units are idle +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAPI_btac_m\fR\fR +.ad +.RS 16n +.rt +Branch target address cache misses +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAPI_ca_cln\fR\fR +.ad +.RS 16n +.rt +Requests for exclusive access to clean cache line +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAPI_ca_inv\fR\fR +.ad +.RS 16n +.rt +Requests for cache invalidation +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAPI_ca_itv\fR\fR +.ad +.RS 16n +.rt +Requests for cache line intervention +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAPI_ca_shr\fR\fR +.ad +.RS 16n +.rt +Request for exclusive access to shared cache line +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAPI_ca_snp\fR\fR +.ad +.RS 16n +.rt +Request for cache snoop +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAPI_csr_fal\fR\fR +.ad +.RS 16n +.rt +Failed conditional store instructions +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAPI_csr_suc\fR\fR +.ad +.RS 16n +.rt +Successful conditional store instructions +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAPI_csr_tot\fR\fR +.ad +.RS 16n +.rt +Total conditional store instructions +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAPI_fad_ins\fR\fR +.ad +.RS 16n +.rt +Floating point add instructions +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAPI_fdv_ins\fR\fR +.ad +.RS 16n +.rt +Floating point divide instructions +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAPI_fma_ins\fR\fR +.ad +.RS 16n +.rt +Floating point multiply and add instructions +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAPI_fml_ins\fR\fR +.ad +.RS 16n +.rt +Floating point multiply instructions +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAPI_fnv_ins\fR\fR +.ad +.RS 16n +.rt +Floating point inverse instructions +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAPI_fp_ops\fR\fR +.ad +.RS 16n +.rt +Floating point operations +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAPI_fp_stal\fR\fR +.ad +.RS 16n +.rt +Cycles the floating point unit stalled +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAPI_fpu_idl\fR\fR +.ad +.RS 16n +.rt +Cycles the floating point units are idle +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAPI_fsq_ins\fR\fR +.ad +.RS 16n +.rt +Floating point sqrt instructions +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAPI_ful_ccy\fR\fR +.ad +.RS 16n +.rt +Cycles with maximum instructions completed +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAPI_ful_icy\fR\fR +.ad +.RS 16n +.rt +Cycles with maximum instruction issue +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAPI_fxu_idl\fR\fR +.ad +.RS 16n +.rt +Cycles when units are idle +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAPI_hw_int\fR\fR +.ad +.RS 16n +.rt +Hardware interrupts +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAPI_int_ins\fR\fR +.ad +.RS 16n +.rt +Integer instructions +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAPI_tot_cyc\fR\fR +.ad +.RS 16n +.rt +Total cycles +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAPI_tot_iis\fR\fR +.ad +.RS 16n +.rt +Instructions issued +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAPI_tot_ins\fR\fR +.ad +.RS 16n +.rt +Instructions completed +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAPI_vec_ins\fR\fR +.ad +.RS 16n +.rt +VectorSIMD instructions +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAPI_l1_dca\fR\fR +.ad +.RS 16n +.rt +Level 1 data cache accesses +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAPI_l1_dch\fR\fR +.ad +.RS 16n +.rt +Level 1 data cache hits +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAPI_l1_dcm\fR\fR +.ad +.RS 16n +.rt +Level 1 data cache misses +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAPI_l1_dcr\fR\fR +.ad +.RS 16n +.rt +Level 1 data cache reads +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAPI_l1_dcw\fR\fR +.ad +.RS 16n +.rt +Level 1 data cache writes +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAPI_l1_ica\fR\fR +.ad +.RS 16n +.rt +Level 1 instruction cache accesses +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAPI_l1_ich\fR\fR +.ad +.RS 16n +.rt +Level 1 instruction cache hits +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAPI_l1_icm\fR\fR +.ad +.RS 16n +.rt +Level 1 instruction cache misses +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAPI_l1_icr\fR\fR +.ad +.RS 16n +.rt +Level 1 instruction cache reads +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAPI_l1_icw\fR\fR +.ad +.RS 16n +.rt +Level 1 instruction cache writes +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAPI_l1_ldm\fR\fR +.ad +.RS 16n +.rt +Level 1 cache load misses +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAPI_l1_stm\fR\fR +.ad +.RS 16n +.rt +Level 1 cache store misses +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAPI_l1_tca\fR\fR +.ad +.RS 16n +.rt +Level 1 cache accesses +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAPI_l1_tch\fR\fR +.ad +.RS 16n +.rt +Level 1 cache hits +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAPI_l1_tcm\fR\fR +.ad +.RS 16n +.rt +Level 1 cache misses +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAPI_l1_tcr\fR\fR +.ad +.RS 16n +.rt +Level 1 cache reads +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAPI_l1_tcw\fR\fR +.ad +.RS 16n +.rt +Level 1 cache writes +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAPI_l2_dca\fR\fR +.ad +.RS 16n +.rt +Level 2 data cache accesses +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAPI_l2_dch\fR\fR +.ad +.RS 16n +.rt +Level 2 data cache hits +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAPI_l2_dcm\fR\fR +.ad +.RS 16n +.rt +Level 2 data cache misses +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAPI_l2_dcr\fR\fR +.ad +.RS 16n +.rt +Level 2 data cache reads +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAPI_l2_dcw\fR\fR +.ad +.RS 16n +.rt +Level 2 data cache writes +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAPI_l2_ica\fR\fR +.ad +.RS 16n +.rt +Level 2 instruction cache accesses +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAPI_l2_ich\fR\fR +.ad +.RS 16n +.rt +Level 2 instruction cache hits +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAPI_l2_icm\fR\fR +.ad +.RS 16n +.rt +Level 2 instruction cache misses +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAPI_l2_icr\fR\fR +.ad +.RS 16n +.rt +Level 2 instruction cache reads +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAPI_l2_icw\fR\fR +.ad +.RS 16n +.rt +Level 2 instruction cache writes +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAPI_l2_ldm\fR\fR +.ad +.RS 16n +.rt +Level 2 cache load misses +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAPI_l2_stm\fR\fR +.ad +.RS 16n +.rt +Level 2 cache store misses +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAPI_l2_tca\fR\fR +.ad +.RS 16n +.rt +Level 2 cache accesses +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAPI_l2_tch\fR\fR +.ad +.RS 16n +.rt +Level 2 cache hits +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAPI_l2_tcm\fR\fR +.ad +.RS 16n +.rt +Level 2 cache misses +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAPI_l2_tcr\fR\fR +.ad +.RS 16n +.rt +Level 2 cache reads +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAPI_l2_tcw\fR\fR +.ad +.RS 16n +.rt +Level 2 cache writes +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAPI_l3_dca\fR\fR +.ad +.RS 16n +.rt +Level 3 data cache accesses +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAPI_l3_dch\fR\fR +.ad +.RS 16n +.rt +Level 3 data cache hits +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAPI_l3_dcm\fR\fR +.ad +.RS 16n +.rt +Level 3 data cache misses +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAPI_l3_dcr\fR\fR +.ad +.RS 16n +.rt +Level 3 data cache reads +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAPI_l3_dcw\fR\fR +.ad +.RS 16n +.rt +Level 3 data cache writes +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAPI_l3_ica\fR\fR +.ad +.RS 16n +.rt +Level 3 instruction cache accesses +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAPI_l3_ich\fR\fR +.ad +.RS 16n +.rt +Level 3 instruction cache hits +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAPI_l3_icm\fR\fR +.ad +.RS 16n +.rt +Level 3 instruction cache misses +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAPI_l3_icr\fR\fR +.ad +.RS 16n +.rt +Level 3 instruction cache reads +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAPI_l3_icw\fR\fR +.ad +.RS 16n +.rt +Level 3 instruction cache writes +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAPI_l3_ldm\fR\fR +.ad +.RS 16n +.rt +Level 3 cache load misses +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAPI_l3_stm\fR\fR +.ad +.RS 16n +.rt +Level 3 cache store misses +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAPI_l3_tca\fR\fR +.ad +.RS 16n +.rt +Level 3 cache accesses +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAPI_l3_tch\fR\fR +.ad +.RS 16n +.rt +Level 3 cache hits +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAPI_l3_tcm\fR\fR +.ad +.RS 16n +.rt +Level 3 cache misses +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAPI_l3_tcr\fR\fR +.ad +.RS 16n +.rt +Level 3 cache reads +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAPI_l3_tcw\fR\fR +.ad +.RS 16n +.rt +Level 3 cache writes +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAPI_ld_ins\fR\fR +.ad +.RS 16n +.rt +Load Instructions +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAPI_lst_ins\fR\fR +.ad +.RS 16n +.rt +Loadstore Instructions +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAPI_lsu_idl\fR\fR +.ad +.RS 16n +.rt +Cycles load store units are idle +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAPI_mem_rcy\fR\fR +.ad +.RS 16n +.rt +Cycles stalled waiting for memory reads +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAPI_mem_scy\fR\fR +.ad +.RS 16n +.rt +Cycles stalled waiting for memory accesses +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAPI_mem_wcy\fR\fR +.ad +.RS 16n +.rt +Cycles stalled waiting for memory writes +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAPI_prf_dm\fR\fR +.ad +.RS 16n +.rt +Data prefetch cache misses +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAPI_res_stl\fR\fR +.ad +.RS 16n +.rt +Cycles stalled on any resource +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAPI_sr_ins\fR\fR +.ad +.RS 16n +.rt +Store Instructions +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAPI_stl_ccy\fR\fR +.ad +.RS 16n +.rt +Cycles with no instructions completed +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAPI_syc_ins\fR\fR +.ad +.RS 16n +.rt +Synchronization instructions completed +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAPI_tlb_dm\fR\fR +.ad +.RS 16n +.rt +Data TLB misses +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAPI_tlb_im\fR\fR +.ad +.RS 16n +.rt +Instruction TLB misses +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAPI_tlb_sd\fR\fR +.ad +.RS 16n +.rt +TLB shootdowns +.RE + +.sp +.ne 2 +.mk +.na +\fB\fBPAPI_tlb_tl\fR\fR +.ad +.RS 16n +.rt +Total TLB misses +.RE + +.sp +.LP +The tables below define mappings of generic events to platform events and any +associated attribute for all supported platforms. +.SS "AMD Opteron Family 0xF Processor" +.sp + +.sp +.TS +tab(); +cw(1.81i) cw(2.32i) cw(1.36i) +lw(1.81i) lw(2.32i) lw(1.36i) +. +Generic EventPlatform EventUnit Mask +_ +\fBPAPI_br_ins\fR\fBFR_retired_branches_w_excp_intr\fR0x0 +\fBPAPI_br_msp\fR\fBFR_retired_branches_mispred\fR0x0 +\fBPAPI_br_tkn\fR\fBFR_retired_taken_branches\fR0x0 +\fBPAPI_fp_ops\fR\fBFP_dispatched_fpu_ops\fR0x3 +\fBPAPI_fad_ins\fR\fBFP_dispatched_fpu_ops\fR0x1 +\fBPAPI_fml_ins\fR\fBFP_dispatched_fpu_ops\fR0x2 +\fBPAPI_fpu_idl\fR\fBFP_cycles_no_fpu_ops_retired\fR0x0 +\fBPAPI_tot_cyc\fR\fBBU_cpu_clk_unhalted\fR0x0 +\fBPAPI_tot_ins\fR\fBFR_retired_x86_instr_w_excp_intr\fR0x0 +\fBPAPI_l1_dca\fR\fBDC_access\fR0x0 +\fBPAPI_l1_dcm\fR\fBDC_miss\fR0x0 +\fBPAPI_l1_ldm\fR\fBDC_refill_from_L2\fR0xe +\fBPAPI_l1_stm\fR\fBDC_refill_from_L2\fR0x10 +\fBPAPI_l1_ica\fR\fBIC_fetch\fR0x0 +\fBPAPI_l1_icm\fR\fBIC_miss\fR0x0 +\fBPAPI_l1_icr\fR\fBIC_fetch\fR0x0 +\fBPAPI_l2_dch\fR\fBDC_refill_from_L2\fR0x1e +\fBPAPI_l2_dcm\fR\fBDC_refill_from_system\fR0x1e +\fBPAPI_l2_dcr\fR\fBDC_refill_from_L2\fR0xe +\fBPAPI_l2_dcw\fR\fBDC_refill_from_L2\fR0x10 +\fBPAPI_l2_ich\fR\fBIC_refill_from_L2\fR0x0 +\fBPAPI_l2_icm\fR\fBIC_refill_from_system\fR0x0 +\fBPAPI_l2_ldm\fR\fBDC_refill_from_system\fR0xe +\fBPAPI_l2_stm\fR\fBDC_refill_from_system\fR0x10 +\fBPAPI_res_stl\fR\fBFR_dispatch_stalls\fR0x0 +\fBPAPI_stl_icy\fR\fBFR_nothing_to_dispatch\fR0x0 +\fBPAPI_hw_int\fR\fBFR_taken_hardware_intrs\fR0x0 +\fBPAPI_tlb_dm\fR\fBDC_dtlb_L1_miss_L2_miss\fR0x0 +\fBPAPI_tlb_im\fR\fBIC_itlb_L1_miss_L2_miss\fR0x0 +\fBPAPI_fp_ins\fR\fBFR_retired_fpu_instr\fR0xd +\fBPAPI_vec_ins\fR\fBFR_retired_fpu_instr\fR0x4 +.TE + +.SS "AMD Opteron Family 0x10 Processors" +.sp + +.sp +.TS +tab(); +cw(1.81i) cw(2.32i) cw(1.36i) +lw(1.81i) lw(2.32i) lw(1.36i) +. +Generic EventPlatform EventEvent Mask +_ +\fBPAPI_br_ins\fR\fBFR_retired_branches_w_excp_intr\fR0x0 +\fBPAPI_br_msp\fR\fBFR_retired_branches_mispred\fR0x0 +\fBPAPI_br_tkn\fR\fBFR_retired_taken_branches\fR0x0 +\fBPAPI_fp_ops\fR\fBFP_dispatched_fpu_ops\fR0x3 +\fBPAPI_fad_ins\fR\fBFP_dispatched_fpu_ops\fR0x1 +\fBPAPI_fml_ins\fR\fBFP_dispatched_fpu_ops\fR0x2 +\fBPAPI_fpu_idl\fR\fBFP_cycles_no_fpu_ops_retired\fR0x0 +\fBPAPI_tot_cyc\fR\fBBU_cpu_clk_unhalted\fR0x0 +\fBPAPI_tot_ins\fR\fBFR_retired_x86_instr_w_excp_intr\fR0x0 +\fBPAPI_l1_dca\fR\fBDC_access\fR0x0 +\fBPAPI_l1_dcm\fR\fBDC_miss\fR0x0 +\fBPAPI_l1_ldm\fR\fBDC_refill_from_L2\fR0xe +\fBPAPI_l1_stm\fR\fBDC_refill_from_L2\fR0x10 +\fBPAPI_l1_ica\fR\fBIC_fetch\fR0x0 +\fBPAPI_l1_icm\fR\fBIC_miss\fR0x0 +\fBPAPI_l1_icr\fR\fBIC_fetch\fR0x0 +\fBPAPI_l2_dch\fR\fBDC_refill_from_L2\fR0x1e +\fBPAPI_l2_dcm\fR\fBDC_refill_from_system\fR0x1e +\fBPAPI_l2_dcr\fR\fBDC_refill_from_L2\fR0xe +\fBPAPI_l2_dcw\fR\fBDC_refill_from_L2\fR0x10 +\fBPAPI_l2_ich\fR\fBIC_refill_from_L2\fR0x0 +\fBPAPI_l2_icm\fR\fBIC_refill_from_system\fR0x0 +\fBPAPI_l2_ldm\fR\fBDC_refill_from_system\fR0xe +\fBPAPI_l2_stm\fR\fBDC_refill_from_system\fR0x10 +\fBPAPI_res_stl\fR\fBFR_dispatch_stalls\fR0x0 +\fBPAPI_stl_icy\fR\fBFR_nothing_to_dispatch\fR0x0 +\fBPAPI_hw_int\fR\fBFR_taken_hardware_intrs\fR0x0 +\fBPAPI_tlb_dm\fR\fBDC_dtlb_L1_miss_L2_miss\fR0x7 +\fBPAPI_tlb_im\fR\fBIC_itlb_L1_miss_L2_miss\fR0x3 +\fBPAPI_fp_ins\fR\fBFR_retired_fpu_instr\fR0xd +\fBPAPI_vec_ins\fR\fBFR_retired_fpu_instr\fR0x4 +\fBPAPI_l3_dcr\fR\fBL3_read_req\fR0xf1 +\fBPAPI_l3_icr\fR\fBL3_read_req\fR0xf2 +\fBPAPI_l3_tcr\fR\fBL3_read_req\fR0xf7 +\fBPAPI_l3_stm\fR\fBL3_miss\fR0xf4 +\fBPAPI_l3_ldm\fR\fBL3_miss\fR0xf3 +\fBPAPI_l3_tcm\fR\fBL3_miss\fR0xf7 +.TE + +.SS "Intel Pentium IV Processor" +.sp + +.sp +.TS +tab(); +cw(1.81i) cw(2.32i) cw(1.36i) +lw(1.81i) lw(2.32i) lw(1.36i) +. +Generic EventPlatform EventEvent Mask +_ +\fBPAPI_br_msp\fR\fBbranch_retired\fR0xa +\fBPAPI_br_ins\fR\fBbranch_retired\fR0xf +\fBPAPI_br_tkn\fR\fBbranch_retired\fR0xc +\fBPAPI_br_ntk\fR\fBbranch_retired\fR0x3 +\fBPAPI_br_prc\fR\fBbranch_retired\fR0x5 +\fBPAPI_tot_ins\fR\fBinstr_retired\fR0x3 +\fBPAPI_tot_cyc\fR\fBglobal_power_events\fR0x1 +\fBPAPI_tlb_dm\fR\fBpage_walk_type\fR0x1 +\fBPAPI_tlb_im\fR\fBpage_walk_type\fR0x2 +\fBPAPI_tlb_tm\fR\fBpage_walk_type\fR0x3 +\fBPAPI_l2_ldm\fR\fBBSQ_cache_reference\fR0x100 +\fBPAPI_l2_stm\fR\fBBSQ_cache_reference\fR0x400 +\fBPAPI_l2_tcm\fR\fBBSQ_cache_reference\fR0x500 +.TE + +.SS "Intel Pentium Pro/II/III Processor" +.sp + +.sp +.TS +tab(); +cw(1.81i) cw(2.32i) cw(1.36i) +lw(1.81i) lw(2.32i) lw(1.36i) +. +Generic EventPlatform EventEvent Mask +_ +\fBPAPI_ca_shr\fR\fBl2_ifetch\fR0xf +\fBPAPI_ca_cln\fR\fBbus_tran_rfo\fR0x0 +\fBPAPI_ca_itv\fR\fBbus_tran_inval\fR0x0 +\fBPAPI_tlb_im\fR\fBitlb_miss\fR0x0 +\fBPAPI_btac_m\fR\fBbtb_misses\fR0x0 +\fBPAPI_hw_int\fR\fBhw_int_rx\fR0x0 +\fBPAPI_br_cn\fR\fBbr_inst_retired\fR0x0 +\fBPAPI_br_tkn\fR\fBbr_taken_retired\fR0x0 +\fBPAPI_br_msp\fR\fBbr_miss_pred_taken_ret\fR0x0 +\fBPAPI_br_ins\fR\fBbr_inst_retired\fR0x0 +\fBPAPI_res_stl\fR\fBresource_stalls\fR0x0 +\fBPAPI_tot_iis\fR\fBinst_decoder\fR0x0 +\fBPAPI_tot_ins\fR\fBinst_retired\fR0x0 +\fBPAPI_tot_cyc\fR\fBcpu_clk_unhalted\fR0x0 +\fBPAPI_l1_dcm\fR\fBdcu_lines_in\fR0x0 +\fBPAPI_l1_icm\fR\fBl2_ifetch\fR0xf +\fBPAPI_l1_tcm\fR\fBl2_rqsts\fR0xf +\fBPAPI_l1_dca\fR\fBdata_mem_refs\fR0x0 +\fBPAPI_l1_ldm\fR\fBl2_ld\fR0xf +\fBPAPI_l1_stm\fR\fBl2_st\fR0xf +\fBPAPI_l2_icm\fR\fBbus_tran_ifetch\fR0x0 +\fBPAPI_l2_dcr\fR\fBl2_ld\fR0xf +\fBPAPI_l2_dcw\fR\fBl2_st\fR0xf +\fBPAPI_l2_tcm\fR\fBl2_lines_in\fR0x0 +\fBPAPI_l2_tca\fR\fBl2_rqsts\fR0xf +\fBPAPI_l2_tcw\fR\fBl2_st\fR0xf +\fBPAPI_l2_stm\fR\fBl2_m_lines_inm\fR0x0 +\fBPAPI_fp_ins\fR\fBflops\fR0x0 +\fBPAPI_fp_ops\fR\fBflops\fR0x0 +\fBPAPI_fml_ins\fR\fBmul\fR0x0 +\fBPAPI_fdv_ins\fR\fBdiv\fR0x0 +.TE + +.SS "UltraSPARC I/II Processor" +.sp + +.sp +.TS +tab(); +cw(2.75i) cw(2.75i) +lw(2.75i) lw(2.75i) +. +Generic EventPlatform Event +_ +\fBPAPI_tot_cyc\fR\fBCycle_cnt\fR +\fBPAPI_tot_ins\fR\fBInstr_cnt\fR +\fBPAPI_tot_iis\fR\fBInstr_cnt\fR +\fBPAPI_l1_dcr\fR\fBDC_rd\fR +\fBPAPI_l1_dcw\fR\fBDC_wr\fR +\fBPAPI_l1_ica\fR\fBIC_ref\fR +\fBPAPI_l1_ich\fR\fBIC_hit\fR +\fBPAPI_l2_tca\fR\fBEC_ref\fR +\fBPAPI_l2_dch\fR\fBEC_rd_hit\fR +\fBPAPI_l2_tch\fR\fBEC_hit\fR +\fBPAPI_l2_ich\fR\fBEC_ic_hit\fR +\fBPAPI_ca_inv\fR\fBEC_snoop_inv\fR +\fBPAPI_br_msp\fR\fBDispatch0_mispred\fR +\fBPAPI_ca_snp\fR\fBEC_snoop_cb\fR +.TE + +.SS "UltraSPARC III/IIIi/IV Processor" +.sp + +.sp +.TS +tab(); +cw(2.75i) cw(2.75i) +lw(2.75i) lw(2.75i) +. +Generic EventPlatform Event +_ +\fBPAPI_tot_cyc\fR\fBCycle_cnt\fR +\fBPAPI_tot_ins\fR\fBInstr_cnt\fR +\fBPAPI_tot_iis\fR\fBInstr_cnt\fR +\fBPAPI_fma_ins\fR\fBFA_pipe_completion\fR +\fBPAPI_fml_ins\fR\fBFM_pipe_completion\fR +\fBPAPI_l1_dcr\fR\fBDC_rd\fR +\fBPAPI_l1_dcw\fR\fBDC_wr\fR +\fBPAPI_l1_ica\fR\fBIC_ref\fR +\fBPAPI_l1_icm\fR\fBIC_miss\fR +\fBPAPI_l2_tca\fR\fBEC_ref\fR +\fBPAPI_l2_ldm\fR\fBEC_rd_miss\fR +\fBPAPI_l2_tcm\fR\fBEC_misses\fR +\fBPAPI_l2_icm\fR\fBEC_ic_miss\fR +\fBPAPI_tlb_dm\fR\fBDTLB_miss\fR +\fBPAPI_tlb_im\fR\fBITLB_miss\fR +\fBPAPI_br_ntk\fR\fBIU_Stat_Br_count_untaken\fR +\fBPAPI_br_msp\fR\fBDispatch0_mispred\fR +\fBPAPI_br_tkn\fR\fBIU_Stat_Br_count_taken\fR +\fBPAPI_ca_inv\fR\fBEC_snoop_inv\fR +\fBPAPI_ca_snp\fR\fBEC_snoop_cb\fR +.TE + +.SS "UltraSPARC IV+ Processor" +.sp + +.sp +.TS +tab(); +cw(2.75i) cw(2.75i) +lw(2.75i) lw(2.75i) +. +Generic EventPlatform Event +_ +\fBPAPI_tot_cyc\fR\fBCycle_cnt\fR +\fBPAPI_tot_ins\fR\fBInstr_cnt\fR +\fBPAPI_tot_iis\fR\fBInstr_cnt\fR +\fBPAPI_fma_ins\fR\fBFA_pipe_completion\fR +\fBPAPI_fml_ins\fR\fBFM_pipe_completion\fR +\fBPAPI_l1_dcr\fR\fBDC_rd\fR +\fBPAPI_l1_stm\fR\fBDC_wr_miss\fR +\fBPAPI_l1_ica\fR\fBIC_ref\fR +\fBPAPI_l1_icm\fR\fBIC_L2_req\fR +\fBPAPI_l1_ldm\fR\fBDC_rd_miss\fR +\fBPAPI_l1_dcw\fR\fBDC_wr\fR +\fBPAPI_l2_tca\fR\fBL2_ref\fR +\fBPAPI_l2_ldm\fR\fBL2_rd_miss\fR +\fBPAPI_l2_icm\fR\fBL2_IC_miss\fR +\fBPAPI_l2_stm\fR\fBL2_write_miss\fR +\fBPAPI_l2_tcm\fR\fBL2_miss\fR +\fBPAPI_l3_tcm\fR\fBL3_miss\fR +\fBPAPI_l3_icm\fR\fBL3_IC_miss\fR +\fBPAPI_l3_ldm\fR\fBL3_rd_miss\fR +\fBPAPI_tlb_im\fR\fBITLB_miss\fR +\fBPAPI_tlb_dm\fR\fBDTLB_miss\fR +\fBPAPI_br_tkn\fR\fBIU_stat_br_count_taken\fR +\fBPAPI_br_ntk\fR\fBIU_stat_br_count_untaken\fR +.TE + +.SS "Niagara T1 Processor" +.sp + +.sp +.TS +tab(); +cw(2.75i) cw(2.75i) +lw(2.75i) lw(2.75i) +. +Generic EventPlatform Event +_ +\fBPAPI_tot_cyc\fR\fBCycle_cnt\fR +\fBPAPI_l2_icm\fR\fBL2_imiss\fR +\fBPAPI_l2_ldm\fR\fBL2_dmiss_ld\fR +\fBPAPI_fp_ops\fR\fBFP_instr_cnt\fR +\fBPAPI_l1_icm\fR\fBIC_miss\fR +\fBPAPI_l1_dcm\fR\fBDC_miss\fR +\fBPAPI_tlb_im\fR\fBITLB_miss\fR +\fBPAPI_tlb_dm\fR\fBDTLB_miss\fR +.TE + +.SS "Niagara T2 Processor" +.sp + +.sp +.TS +tab(); +cw(2.75i) cw(2.75i) +lw(2.75i) lw(2.75i) +. +Generic EventPlatform Event +_ +\fBPAPI_tot_ins\fR\fBInstr_cnt\fR +\fBPAPI_l1_dcm\fR\fBDC_miss\fR +\fBPAPI_l1_icm\fR\fBIC_miss\fR +\fBPAPI_l2_icm\fR\fBL2_imiss\fR +\fBPAPI_l2_ldm\fR\fBL2_dmiss_ld\fR +\fBPAPI_tlb_dm\fR\fBDTLB_miss\fR +\fBPAPI_tlb_im\fR\fBITLB_miss\fR +\fBPAPI_tlb_tm\fR\fBTLB_miss\fR +\fBPAPI_br_tkn\fR\fBBr_taken\fR +\fBPAPI_br_ins\fR\fBBr_completed\fR +\fBPAPI_ld_ins\fR\fBInstr_ld\fR +\fBPAPI_sr_ins\fR\fBInstr_st\fR +.TE + +.SS "SPARC64 VI/VII Processor" +.sp + +.sp +.TS +tab(); +cw(2.75i) cw(2.75i) +lw(2.75i) lw(2.75i) +. +Generic EventPlatform Event +_ +\fBPAPI_tot_cyc\fR\fBcycle_counts\fR +\fBPAPI_tot_ins\fR\fBinstruction_counts\fR +\fBPAPI_br_tkn\fR\fBbranch_instructions\fR +\fBPAPI_fp_ops\fR\fBfloating_instructions\fR +\fBPAPI_fma_ins\fR\fBimpdep2_instructions\fR +\fBPAPI_l1_dcm\fR\fBop_r_iu_req_mi_go\fR +\fBPAPI_l1_icm\fR\fBif_r_iu_req_mi_go\fR +\fBPAPI_tlb_dm\fR\fBtrap_DMMU_miss\fR +\fBPAPI_tlb_im\fR\fBtrap_IMMU_miss\fR +.TE + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityVolatile +.TE + +.SH SEE ALSO +.sp +.LP +\fBcpc\fR(3CPC), \fBattributes\fR(5) +.SH NOTES +.sp +.LP +Generic names prefixed with "PAPI_" are taken from the University of +Tennessee's PAPI project, http://icl.cs.utk.edu/papi\&. diff --git a/usr/src/man/man3cpc/pctx_capture.3cpc b/usr/src/man/man3cpc/pctx_capture.3cpc new file mode 100644 index 0000000000..949314ce93 --- /dev/null +++ b/usr/src/man/man3cpc/pctx_capture.3cpc @@ -0,0 +1,147 @@ +'\" te +.\" Copyright (c) 2003, Sun Microsystems, Inc. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH pctx_capture 3CPC "13 May 2003" "SunOS 5.11" "CPU Performance Counters Library Functions" +.SH NAME +pctx_capture, pctx_create, pctx_run, pctx_release \- process context library +.SH SYNOPSIS +.LP +.nf +cc [ \fIflag\fR... ] \fIfile\fR... \(milpctx [ \fIlibrary\fR... ] +#include <libpctx.h> + +\fBtypedef void\fR \fB(pctx_errfn_t)\fR(\fBconst char *\fR\fIfn\fR, \fBconst char *\fR\fIfmt\fR, \fBva_list\fR \fIap\fR); +.fi + +.LP +.nf +\fBpctx_t *\fR\fBpctx_create\fR(\fBconst char *\fR\fIfilename\fR, \fBchar *const *\fR\fIargv\fR, \fBvoid *\fR\fIarg\fR, + \fBint\fR \fIverbose\fR, \fBpctx_errfn_t *\fR\fIerrfn\fR); +.fi + +.LP +.nf +\fBpctx_t *\fR\fBpctx_capture\fR(\fBpid_t\fR \fIpid\fR, \fBvoid *\fR\fIarg\fR, \fBint\fR \fIverbose\fR, + \fBpctx_errfn_t *\fR\fIerrfn\fR); +.fi + +.LP +.nf +\fBint\fR \fBpctx_run\fR(\fBpctx_t *\fR\fIpctx\fR, \fBuint_t\fR \fIsample\fR, \fBuint_t\fR \fInsamples\fR, + \fBint (*\fR\fItick\fR)(pctx *, \fBpid_t, id_t, void *));\fR +.fi + +.LP +.nf +\fBvoid\fR \fBpctx_release\fR(\fBpctx_t *\fR\fIpctx\fR); +.fi + +.SH DESCRIPTION +.sp +.LP +This family of functions allows a controlling process (the process that invokes +them) to create or capture controlled processes. The functions allow the +occurrence of various events of interest in the controlled process to cause the +controlled process to be stopped, and to cause callback routines to be invoked +in the controlling process. +.SS "\fBpctx_create()\fR and \fBpctx_capture()\fR" +.sp +.LP +There are two ways a process can be acquired by the process context functions. +First, a named application can be invoked with the usual \fIargv\fR[] array +using \fBpctx_create()\fR, which forks the caller and \fBexec\fRs the +application in the child. Alternatively, an existing process can be captured by +its process \fBID\fR using \fBpctx_capture()\fR. +.sp +.LP +Both functions accept a pointer to an opaque handle, \fIarg\fR; this is saved +and treated as a caller-private handle that is passed to the other functions in +the library. Both functions accept a pointer to a \fBprintf\fR(3C)-like error +routine \fIerrfn\fR; a default version is provided if \fINULL\fR is specified. +.sp +.LP +A freshly-created process is created stopped; similarly, a process that has +been successfully captured is stopped by the act of capturing it, thereby +allowing the caller to specify the handlers that should be called when various +events occur in the controlled process. The set of handlers is listed on the +\fBpctx_set_events\fR(3CPC) manual page. +.SS "\fBpctx_run()\fR" +.sp +.LP +Once the callback handlers have been set with \fBpctx_set_events()\fR, the +application can be set running using \fBpctx_run()\fR. This function starts the +event handling loop; it returns only when either the process has exited, the +number of time samples has expired, or an error has occurred (for example, if +the controlling process is not privileged, and the controlled process has +\fBexec\fR-ed a setuid program). +.sp +.LP +Every \fIsample\fR milliseconds the process is stopped and the \fItick\fR(\|) +routine is called so that, for example, the performance counters can be sampled +by the caller. No periodic sampling is performed if \fIsample\fR is 0. +.SS "\fBpctx_release()\fR" +.sp +.LP +Once \fBpctx_run()\fR has returned, the process can be released and the +underlying storage freed using \fBpctx_release()\fR. Releasing the process will +either allow the controlled process to continue (in the case of an existing +captured process and its children) or kill the process (if it and its children +were created using \fBpctx_create()\fR). +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBpctx_capture()\fR and \fBpctx_create()\fR return +a valid handle. Otherwise, the functions print a diagnostic message and return +\fINULL\fR. +.sp +.LP +Upon successful completion, \fBpctx_run()\fR returns \fB0\fR with the +controlled process either stopped or exited (if the controlled process has +invoked \fBexit\fR(2).) If an error has occurred (for example, if the +controlled process has \fBexec\fR-ed a set-\fBID\fR executable, if certain +callbacks have returned error indications, or if the process was unable to +respond to \fBproc\fR(4) requests) an error message is printed and the function +returns \(mi1. +.SH USAGE +.sp +.LP +Within an event handler in the controlling process, the controlled process can +be made to perform various system calls on its behalf. No system calls are +directly supported in this version of the API, though system calls are executed +by the \fBcpc_pctx\fR family of interfaces in \fBlibcpc\fR such as +\fBcpc_pctx_bind_event\fR(3CPC). A specially created agent \fBLWP\fR is used to +execute these system calls in the controlled process. See \fBproc\fR(4) for +more details. +.sp +.LP +While executing the event handler functions, the library arranges for the +signals \fBSIGTERM\fR, \fBSIGQUIT\fR, \fBSIGABRT\fR, and \fBSIGINT\fR to be +blocked to reduce the likelihood of a keyboard signal killing the controlling +process prematurely, thereby leaving the controlled process permanently stopped +while the agent \fBLWP\fR is still alive inside the controlled process. +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityEvolving +_ +MT-LevelUnsafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBfork\fR(2), \fBcpc\fR(3CPC), \fBpctx_set_events\fR(3CPC), +\fBlibpctx\fR(3LIB), \fBproc\fR(4), \fBattributes\fR(5) diff --git a/usr/src/man/man3cpc/pctx_set_events.3cpc b/usr/src/man/man3cpc/pctx_set_events.3cpc new file mode 100644 index 0000000000..dcab77aed4 --- /dev/null +++ b/usr/src/man/man3cpc/pctx_set_events.3cpc @@ -0,0 +1,196 @@ +'\" te +.\" Copyright (C) 2003, Sun Microsystems, Inc. All Rights Reserved. +.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. +.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License. +.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner] +.TH pctx_set_events 3CPC "13 May 2003" "SunOS 5.11" "CPU Performance Counters Library Functions" +.SH NAME +pctx_set_events \- associate callbacks with process events +.SH SYNOPSIS +.LP +.nf +cc [ \fIflag\fR... ] \fIfile\fR... \(milpctx [ \fIlibrary\fR... ] +#include <libpctx.h> + +typedef enum { + PCTX_NULL_EVENT = 0, + PCTX_SYSC_EXEC_EVENT, + PCTX_SYSC_FORK_EVENT, + PCTX_SYSC_EXIT_EVENT, + PCTX_SYSC_LWP_CREATE_EVENT, + PCTX_INIT_LWP_EVENT, + PCTX_FINI_LWP_EVENT, + PCTX_SYSC_LWP_EXIT_EVENT +} pctx_event_t; + +\fBtypedef int\fR \fBpctx_sysc_execfn_t\fR(\fBpctx_t *\fR\fIpctx\fR, \fBpid_t\fR \fIpid\fR, \fBid_t\fR \fIlwpid\fR, + \fBchar *\fR\fIcmd\fR, \fBvoid *\fR\fIarg\fR); +.fi + +.LP +.nf +\fBtypedef void\fR \fBpctx_sysc_forkfn_t\fR(\fBpctx_t *\fR\fIpctx\fR, + \fBpid_t\fR \fIpid\fR, \fBid_t\fR \fIlwpid\fR, \fBpid_t\fR \fIchild\fR, \fBvoid *\fR\fIarg\fR); +.fi + +.LP +.nf +\fBtypedef void\fR \fBpctx_sysc_exitfn_t\fR(\fBpctx_t *\fR\fIpctx\fR, \fBpid_t\fR \fIpid\fR, \fBid_t\fR \fIlwpid\fR, + \fBvoid *\fR\fIarg\fR); +.fi + +.LP +.nf +\fBtypedef int\fR \fBpctx_sysc_lwp_createfn_t\fR(\fBpctx_t *\fR\fIpctx\fR, \fBpid_t\fR \fIpid\fR, \fBid_t\fR \fIlwpid\fR, + \fBvoid *\fR\fIarg\fR); +.fi + +.LP +.nf +\fBtypedef int\fR \fBpctx_init_lwpfn_t\fR(\fBpctx_t *\fR\fIpctx\fR, \fBpid_t\fR \fIpid\fR, \fBid_t\fR \fIlwpid\fR, + \fBvoid *\fR\fIarg\fR); +.fi + +.LP +.nf +\fBtypedef int\fR \fBpctx_fini_lwpfn_t\fR(\fBpctx_t *\fR\fIpctx\fR, \fBpid_t\fR \fIpid\fR, \fBid_t\fR \fIlwpid\fR, + \fBvoid *\fR\fIarg\fR); +.fi + +.LP +.nf +\fBtypedef int\fR \fBpctx_sysc_lwp_exitfn_t\fR(\fBpctx_t *\fR\fIpctx\fR, \fBpid_t\fR \fIpid\fR, \fBid_t\fR \fIlwpid\fR, + \fBvoid *\fR\fIarg\fR); +.fi + +.LP +.nf +\fBint\fR \fBpctx_set_events\fR(\fBpctx_t *\fR\fIpctx\fR...); +.fi + +.SH DESCRIPTION +.sp +.LP +The \fBpctx_set_events()\fR function allows the caller (the controlling +process) to express interest in various events in the controlled process. See +\fBpctx_capture\fR(3CPC) for information about how the controlling process is +able to create, capture and manipulate the controlled process. +.sp +.LP +The \fBpctx_set_events()\fR function takes a \fBpctx_t\fR handle, followed by a +variable length list of pairs of \fBpctx_event_t\fR tags and their +corresponding handlers, terminated by a \fBPCTX_NULL_EVENT\fR tag. +.sp +.LP +Most of the events correspond closely to various classes of system calls, +though two additional pseudo-events (\fIinit_lwp\fR and \fIfini_lwp\fR) are +provided to allow callers to perform various housekeeping tasks. The +\fIinit_lwp\fR handler is called as soon as the library identifies a new +\fBLWP\fR, while \fIfini_lwp\fR is called just before the \fBLWP\fR disappears. +Thus the classic "hello world" program would see an \fIinit_lwp\fR event, a +\fIfini_lwp\fR event and (process) \fIexit\fR event, in that order. The table +below displays the interactions between the states of the controlled process +and the handlers executed by users of the library. +.sp + +.sp +.TS +tab() box; +cw(1.02i) |cw(1.14i) |cw(3.34i) +cw(1.02i) |cw(1.14i) |cw(3.34i) +. +System Calls and pctx Handlers +_ +System callHandlerComments +_ +\fBexec\fR,\fBexecve\fR\fIfini_lwp\fRT{ +Invoked serially on all lwps in the process. +T} +\fIexec\fRT{ +Only invoked if the \fBexec()\fR system call succeeded. +T} +\fIinit_lwp\fRT{ +If the exec succeeds, only invoked on lwp 1. If the exec fails, invoked serially on all lwps in the process. +T} +_ +\fBfork\fR, \fBvfork\fR, \fBfork1\fR\fIfork\fRT{ +Only invoked if the \fBfork()\fR system call succeeded. +T} +_ +\fBexit\fR\fIfini_lwp\fRInvoked on all lwps in the process. +\fIexit\fRInvoked on the exiting lwp. +.TE + +.sp +.LP +Each of the handlers is passed the caller's opaque handle, a \fBpctx_t\fR +handle, the pid, and lwpid of the process and lwp generating the event. The +\fIlwp_exit\fR, and (process) \fBexit\fR events are delivered \fIbefore\fR the +underlying system calls begin, while the \fBexec\fR, \fIfork\fR, and +\fIlwp_create\fR events are only delivered after the relevant system calls +complete successfully. The \fBexec\fR handler is passed a string that describes +the command being executed. Catching the \fIfork\fR event causes the calling +process to \fBfork\fR(2), then capture the child of the controlled process +using \fBpctx_capture\fR(\|) before handing control to the \fIfork\fR handler. +The process is released on return from the handler. +.SH RETURN VALUES +.sp +.LP +Upon successful completion, \fBpctx_set_events\fR(\|) returns 0. Otherwise, +the function returns -1. +.SH EXAMPLES +.LP +\fBExample 1 \fRHandleExec example. +.sp +.LP +This example captures an existing process whose process identifier is +\fIpid\fR, and arranges to call the \fIHandleExec\fR routine when the process +performs an \fBexec\fR(2). + +.sp +.in +2 +.nf +static void +HandleExec(pctx_t *pctx, pid_t pid, id_t lwpid, char *cmd, void *arg) +{ + (void) printf("pid %d execed '%s'\en", (int)pid, cmd); +} +int +main() +{ + ... + pctx = pctx_capture(pid, NULL, 1, NULL); + (void) pctx_set_events(pctx, + PCTX_SYSC_EXEC_EVENT, HandleExec, + ... + PCTX_NULL_EVENT); + (void) pctx_run(pctx, 0, 0, NULL); + pctx_release(pctx); +} +.fi +.in -2 + +.SH ATTRIBUTES +.sp +.LP +See \fBattributes\fR(5) for descriptions of the following attributes: +.sp + +.sp +.TS +tab() box; +cw(2.75i) |cw(2.75i) +lw(2.75i) |lw(2.75i) +. +ATTRIBUTE TYPEATTRIBUTE VALUE +_ +Interface StabilityEvolving +_ +MT-LevelUnsafe +.TE + +.SH SEE ALSO +.sp +.LP +\fBexec\fR(2), \fBexit\fR(2), \fBfork\fR(2), \fBvfork\fR(2), \fBfork1\fR(2), +\fBcpc\fR(3CPC), \fBlibpctx\fR(3LIB), \fBproc\fR(4), \fBattributes\fR(5) |