usr/src/lib/libcpc/common/libcpc.h

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