'\" te .\" Copyright (c) 2000, 2014, Oracle and/or its affiliates. All rights reserved. .TH cpc_set_create 3CPC "2 Jan 2014" "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 \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 or hardware sampling 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 and hardware sampling 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 for the CPC request and the sampling buffer is created to store the sampling results for the SMPL request. These 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 and a hardware sampling. 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, \fBcpc_walk_events_all_common()\fR, \fBcpc_walk_events_pic()\fR, and \fBcpc_walk_events_pic_common()\fR functions (all 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 For a CPU performance counter (CPC) request, you can 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 CPC requests in the set containing the counter that overflowed are stopped until the set is rebound. .sp For a hardware sampling (SMPL) request, you can request a signal to be sent to the application when the specified number of SMPL records for the SMPL request have been collected. A \fBSIGEMT\fR signal is delivered if the processor is capable of delivering an interrupt when a certain number of SMPL records have been collected. SMPL requests will not be stopped even after any SMPL request in the set has collected the requested number of SMPL records and the counter associated with any CPC request in the set overflowed. .RE .sp .ne 2 .mk .na \fB\fBCPC_HW_SMPL\fR\fR .ad .sp .6 .RS 4n When adding a hardware sampling ( SMPL) request, this flag must be specified. When adding a CPU performance counter (CPC) request, this flag should not be specified. .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 and \fBcpc_walk_attrs_common()\fR functions (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. .sp When adding a SMPL request, the number of SMPL records to collect must be requested by using the \fIsmpl_nrecs\fR attribute, which should be an integer value greater than 0 and equal to or smaller than the supported maximum value returned by \fBcpc_get_max_smpl_rec_count()\fR function. .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. The \fIflag\fR argument passed to \fIaction\fR function will include \fBCPC_HW_SMPL\fR flag for a SMPL request. Note that the flag is not included for a CPC request. .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) for a CPC request and by \fBcpc_npic\fR(3CPC) for a SMPL request. .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.