cpc_set_create(3CPC)				    CPU Performance Counters Library Functions				      cpc_set_create(3CPC)

NAME

       cpc_set_create, cpc_set_destroy, cpc_set_add_request, cpc_walk_requests - manage sets of counter requests

SYNOPSIS

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

       cpc_set_t *cpc_set_create(cpc_t *cpc);

       int cpc_set_destroy(cpc_t *cpc, cpc_set_t *set);

       int cpc_set_add_request(cpc_t *cpc, cpc_set_t *set,
	    const char *event, uint64_t preset, uint_t flags,
	    uint_t nattrs, const cpc_attr_t *attrs);

       void cpc_walk_requests(cpc_t *cpc, cpc_set_t *set, void *arg,
	    void (*action)(void *arg, int index, const char *event,
	    uint64_t preset, uint_t flags, int nattrs,
	    const cpc_attr_t *attrs));

DESCRIPTION

       The  cpc_set_create() function returns an initialized and empty CPC set. A CPC set contains some number of requests, where a request repre-
       sents a specific configuration of a hardware performance instrumentation counter present on the processor. The cpc_set_t data structure	is
       opaque and must not be accessed directly by the application.

       Applications wanting to program one or more performance counters must create an empty set with cpc_set_create() and add requests to the set
       with cpc_set_add_request(). Once all requests have been added to a set, the set must be bound to the  hardware  performance  counters  (see
       cpc_bind_curlwp(),  cpc_bind_pctx(),  and cpc_bind_cpu(), all described on cpc_bind_curlwp(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  cpc_buf_create(3CPC)  and  cpc_set_sam-
       ple(3CPC).

       The cpc_set_add_request() function specifies a configuration of a hardware counter.  The arguments to cpc_set_add_request() are:

       event		A  string  containing  the  name  of  an  event  supported  by	the  system's  processor.  The	cpc_walk_events_all()  and
			cpc_walk_events_pic() functions (both described on cpc_npic(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 strtol(3C) can be used as the event argument.

       preset		The value with which the system initializes the counter.

       flags		Three flags are defined that modify the behavior of the counter acting on behalf of this request:

			CPC_COUNT_USER

			    The counter should count events that occur while the processor is in user mode.

			CPC_COUNT_SYSTEM

			    The counter should count events that occur while the processor is in privileged mode.

			CPC_OVF_NOTIFY_EMT

			    Request a signal to be sent to the application when the physical counter overflows. A SIGEMT 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.

			At least one of CPC_COUNT_USER or CPC_COUNT_SYSTEM must be specified to program the hardware for counting.

       nattrs, attrs	The nattrs argument specifies the number of attributes pointed to by the attrs argument, which is an array  of	cpc_attr_t
			structures containing processor-specific attributes that modify the request's configuration. The cpc_walk_attrs() function
			(see cpc_npic(3CPC)) can be used to query the processor for the list of attributes it accepts. The library makes a private
			copy of the attrs array, allowing the application to dispose of it immediately after calling cpc_set_add_request().

       The  cpc_walk_requests()  function  calls  the  action  function on each request that has been added to the set. The arg argument is passed
       unmodified to the action function with each call.

RETURN VALUES

       Upon successful completion, cpc_set_create() returns a handle to the opaque cpc_set_t data structure. Otherwise, NULL is returned and errno
       is set to indicate the error.

       Upon successful completion, Cpc_set_destroy() returns 0. Otherwise, -1 is returned and errno is set to indicate the error.

       Upon  successful completion, cpc_set_add_request() returns an integer index used to refer to the data generated by that request during data
       retrieval. Otherwise, -1 is returned and errno is set to indicate the error.

ERRORS

       These functions will fail if:

       EINVAL	 An event, attribute, or flag passed to cpc_set_add_request() was invalid.

		 For cpc_set_destroy() and cpc_set_add_request(), the set parameter was not created with the given cpc_t.

       ENOMEM	 There was not enough memory available to the process to create the library's data structures.

ATTRIBUTES

       See attributes(5) for descriptions of the following attributes:

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE TYPE	     |	    ATTRIBUTE VALUE	   |
       +-----------------------------+-----------------------------+
       |Interface Stability	     |Committed 		   |
       +-----------------------------+-----------------------------+
       |MT-Level		     |Safe			   |
       +-----------------------------+-----------------------------+

SEE ALSO

       cpc_bind_curlwp(3CPC), cpc_buf_create(3CPC), cpc_npic(3CPC), cpc_seterrhndlr(3CPC), libcpc(3LIB), strtol(3C), attributes(5)

NOTES

       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 picnum that is passed to
       cpc_set_add_request(). Counters are numbered from 0 to n - 1, where  n  is  the	number	of  counters  in  the  processor  as  returned	by
       cpc_npic(3CPC).

       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 EINVAL. If a cpc_errhndlr_t has been registered with cpc_seter-
       rhndlr(3CPC),  the  error  handler  is called with subcode CPC_CONFLICTING_REQS. For example, on UltraSPARC pic0 and pic1 must both program
       events in the same processor mode (user mode, kernel mode, or both). For example, pic0 cannot be programmed with CPC_COUNT_USER while  pic1
       is programmed with CPC_COUNT_SYSTEM. Refer to the hardware documentation referenced by cpc_cpuref(3CPC) for details about a particular pro-
       cessor's performance instrumentation hardware.

SunOS 5.11							    20 Aug 2007 					      cpc_set_create(3CPC)