xref: /titanic_50/usr/src/lib/libcpc/common/libcpc.h (revision 2eeaed14a5e2ed9bd811643ad5bffc3510ca0310)
1 /*
2  * CDDL HEADER START
3  *
4  * The contents of this file are subject to the terms of the
5  * Common Development and Distribution License, Version 1.0 only
6  * (the "License").  You may not use this file except in compliance
7  * with the License.
8  *
9  * You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
10  * or http://www.opensolaris.org/os/licensing.
11  * See the License for the specific language governing permissions
12  * and limitations under the License.
13  *
14  * When distributing Covered Code, include this CDDL HEADER in each
15  * file and include the License file at usr/src/OPENSOLARIS.LICENSE.
16  * If applicable, add the following below this CDDL HEADER, with the
17  * fields enclosed by brackets "[]" replaced with your own identifying
18  * information: Portions Copyright [yyyy] [name of copyright owner]
19  *
20  * CDDL HEADER END
21  */
22 /*
23  * Copyright 2004 Sun Microsystems, Inc.  All rights reserved.
24  * Use is subject to license terms.
25  */
26 
27 #ifndef	_LIBCPC_H
28 #define	_LIBCPC_H
29 
30 #pragma ident	"%Z%%M%	%I%	%E% SMI"
31 
32 #include <sys/types.h>
33 #include <sys/cpc_impl.h>
34 #include <inttypes.h>
35 #include <libpctx.h>
36 #include <stdarg.h>
37 #include <signal.h>
38 #include <string.h>
39 #include <ucontext.h>
40 #include <sys/processor.h>
41 
42 /*
43  * This library allows hardware performance counters present in
44  * certain processors to be used by applications to monitor their
45  * own statistics, the statistics of others, or the statistics of a given CPU.
46  */
47 
48 #ifdef	__cplusplus
49 extern "C" {
50 #endif
51 
52 typedef struct __cpc cpc_t;
53 typedef struct __cpc_set cpc_set_t;
54 typedef struct __cpc_buf cpc_buf_t;
55 
56 /*
57  * Current library version must be passed to cpc_open().
58  */
59 #define	CPC_VER_CURRENT		2
60 
61 /*
62  * Initializes the library for use and returns a pointer to an identifier that
63  * must be used as the cpc argument in subsequent libcpc calls.
64  */
65 extern cpc_t *cpc_open(int ver);
66 extern int cpc_close(cpc_t *cpc);
67 
68 /*
69  * Query information about the underlying processor.
70  */
71 extern uint_t cpc_npic(cpc_t *cpc);
72 extern uint_t cpc_caps(cpc_t *cpc);
73 extern const char *cpc_cciname(cpc_t *cpc);
74 extern const char *cpc_cpuref(cpc_t *cpc);
75 
76 /*
77  * A vprintf-like error handling routine can be passed to the
78  * library for use by more sophisticated callers.
79  * If specified as NULL, errors are written to stderr.
80  */
81 typedef void (cpc_errhndlr_t)(const char *fn, int subcode, const char *fmt,
82     va_list ap);
83 extern int cpc_seterrhndlr(cpc_t *cpc, cpc_errhndlr_t *fn);
84 
85 extern cpc_set_t *cpc_set_create(cpc_t *cpc);
86 extern int cpc_set_destroy(cpc_t *cpc, cpc_set_t *set);
87 
88 /*
89  * If successful, returns an index for the new request within the set which is
90  * needed later to retrieve the request's data.
91  * Returns -1 if unsuccessful and sets errno to indicate the error.
92  */
93 extern int cpc_set_add_request(cpc_t *cpc, cpc_set_t *set, const char *event,
94     uint64_t preset, uint_t flags, uint_t nattrs, const cpc_attr_t *attrs);
95 
96 extern cpc_buf_t *cpc_buf_create(cpc_t *cpc, cpc_set_t *set);
97 extern int cpc_buf_destroy(cpc_t *cpc, cpc_buf_t *buf);
98 
99 /*
100  * Binds the set to the current LWP.
101  */
102 extern int cpc_bind_curlwp(cpc_t *cpc, cpc_set_t *set, uint_t flags);
103 
104 /*
105  * Binds the set to the specified LWP in a process controlled via libpctx.
106  */
107 extern int cpc_bind_pctx(cpc_t *cpc, pctx_t *pctx, id_t id, cpc_set_t *set,
108 	    uint_t flags);
109 
110 /*
111  * Binds the set to the specified CPU.  The process must have sufficient
112  * privileges to bind to the CPU via processor_bind(2).  An LWP can only
113  * bind to one CPU at a time.  To measure more than one CPU simultaneously,
114  * one LWP must be created for each CPU.
115  */
116 extern int cpc_bind_cpu(cpc_t *cpc, processorid_t id, cpc_set_t *set,
117 	uint_t flags);
118 
119 /*
120  * Set the starting value for the indexed counter, and restart counting for a
121  * set that was frozen by a counter overflow.
122  */
123 extern int cpc_request_preset(cpc_t *cpc, int index, uint64_t preset);
124 extern int cpc_set_restart(cpc_t *cpc, cpc_set_t *set);
125 
126 /*
127  * Unbinds the set and frees up associated resources. cpc_buf_t's must be
128  * explicitly freed via cpc_buf_destroy().
129  */
130 extern int cpc_unbind(cpc_t *cpc, cpc_set_t *set);
131 
132 /*
133  * Samples a set into a cpc_buf_t. The provided set must be bound, and the
134  * buf must have been created with the set being sampled.
135  */
136 extern int cpc_set_sample(cpc_t *cpc, cpc_set_t *set, cpc_buf_t *buf);
137 
138 extern void cpc_buf_sub(cpc_t *cpc, cpc_buf_t *ds, cpc_buf_t *a, cpc_buf_t *b);
139 extern void cpc_buf_add(cpc_t *cpc, cpc_buf_t *ds, cpc_buf_t *a, cpc_buf_t *b);
140 extern void cpc_buf_copy(cpc_t *cpc, cpc_buf_t *ds, cpc_buf_t *src);
141 extern void cpc_buf_zero(cpc_t *cpc, cpc_buf_t *buf);
142 
143 /*
144  * Gets or sets the value of the request specified by index.
145  */
146 extern int cpc_buf_get(cpc_t *cpc, cpc_buf_t *buf, int index, uint64_t *val);
147 extern int cpc_buf_set(cpc_t *cpc, cpc_buf_t *buf, int index, uint64_t val);
148 extern hrtime_t cpc_buf_hrtime(cpc_t *cpc, cpc_buf_t *buf);
149 extern uint64_t cpc_buf_tick(cpc_t *cpc, cpc_buf_t *buf);
150 
151 extern void cpc_walk_requests(cpc_t *cpc, cpc_set_t *set, void *arg,
152     void (*action)(void *arg, int index, const char *event, uint64_t preset,
153 	uint_t flags, int nattrs, const cpc_attr_t *attrs));
154 
155 extern void cpc_walk_events_all(cpc_t *cpc, void *arg,
156     void (*action)(void *arg, const char *event));
157 extern void cpc_walk_events_pic(cpc_t *cpc, uint_t picno, void *arg,
158     void (*action)(void *arg, uint_t picno, const char *event));
159 extern void cpc_walk_attrs(cpc_t *cpc, void *arg,
160     void (*action)(void *arg, const char *attr));
161 
162 extern int cpc_enable(cpc_t *cpc);
163 extern int cpc_disable(cpc_t *cpc);
164 
165 #if defined(__sparc) || defined(__i386)
166 
167 /*
168  * Obsolete libcpc interfaces.
169  */
170 #define	CPC_VER_NONE 0
171 
172 typedef struct _cpc_event cpc_event_t;
173 
174 extern uint_t cpc_version(uint_t ver);
175 extern int cpc_access();
176 extern int cpc_getcpuver(void);
177 extern const char *cpc_getcciname(int cpuver);
178 extern const char *cpc_getcpuref(int cpuver);
179 extern uint_t cpc_getnpic(int cpuver);
180 typedef void (cpc_errfn_t)(const char *fn, const char *fmt, va_list ap);
181 extern void cpc_seterrfn(cpc_errfn_t *errfn);
182 extern const char *cpc_getusage(int cpuver);
183 extern void cpc_walk_names(int cpuver, int regno, void *arg,
184     void (*action)(void *arg, int regno, const char *name, uint8_t bits));
185 extern int cpc_strtoevent(int cpuver, const char *spec, cpc_event_t *event);
186 extern char *cpc_eventtostr(cpc_event_t *event);
187 extern void cpc_event_accum(cpc_event_t *accum, cpc_event_t *event);
188 extern void cpc_event_diff(cpc_event_t *diff,
189     cpc_event_t *left, cpc_event_t *right);
190 extern int cpc_bind_event(cpc_event_t *event, int flags);
191 extern int cpc_take_sample(cpc_event_t *event);
192 extern int cpc_count_usr_events(int enable);
193 extern int cpc_count_sys_events(int enable);
194 extern int cpc_rele(void);
195 extern int cpc_pctx_bind_event(pctx_t *pctx,
196     id_t lwpid, cpc_event_t *event, int flags);
197 extern int cpc_pctx_take_sample(pctx_t *pctx, id_t lwpid, cpc_event_t *event);
198 extern int cpc_pctx_rele(pctx_t *pctx, id_t lwpid);
199 extern int cpc_pctx_invalidate(pctx_t *pctx, id_t lwpid);
200 extern int cpc_shared_open(void);
201 extern void cpc_shared_close(int fd);
202 extern int cpc_shared_bind_event(int fd, cpc_event_t *event, int flags);
203 extern int cpc_shared_take_sample(int fd, cpc_event_t *event);
204 extern int cpc_shared_rele(int fd);
205 
206 #endif /* __sparc || __i386 */
207 
208 #ifdef	__cplusplus
209 }
210 #endif
211 
212 #endif	/* _LIBCPC_H */
213