Home | History | Annotate | Download | only in common
      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 2008 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 #if defined(__sparc) || defined(__i386)
    167 
    168 /*
    169  * Obsolete libcpc interfaces.
    170  */
    171 #define	CPC_VER_NONE 0
    172 
    173 typedef struct _cpc_event cpc_event_t;
    174 
    175 extern uint_t cpc_version(uint_t ver);
    176 extern int cpc_access();
    177 extern int cpc_getcpuver(void);
    178 extern const char *cpc_getcciname(int cpuver);
    179 extern const char *cpc_getcpuref(int cpuver);
    180 extern uint_t cpc_getnpic(int cpuver);
    181 typedef void (cpc_errfn_t)(const char *fn, const char *fmt, va_list ap);
    182 extern void cpc_seterrfn(cpc_errfn_t *errfn);
    183 extern const char *cpc_getusage(int cpuver);
    184 extern void cpc_walk_names(int cpuver, int regno, void *arg,
    185     void (*action)(void *arg, int regno, const char *name, uint8_t bits));
    186 extern int cpc_strtoevent(int cpuver, const char *spec, cpc_event_t *event);
    187 extern char *cpc_eventtostr(cpc_event_t *event);
    188 extern void cpc_event_accum(cpc_event_t *accum, cpc_event_t *event);
    189 extern void cpc_event_diff(cpc_event_t *diff,
    190     cpc_event_t *left, cpc_event_t *right);
    191 extern int cpc_bind_event(cpc_event_t *event, int flags);
    192 extern int cpc_take_sample(cpc_event_t *event);
    193 extern int cpc_count_usr_events(int enable);
    194 extern int cpc_count_sys_events(int enable);
    195 extern int cpc_rele(void);
    196 extern int cpc_pctx_bind_event(pctx_t *pctx,
    197     id_t lwpid, cpc_event_t *event, int flags);
    198 extern int cpc_pctx_take_sample(pctx_t *pctx, id_t lwpid, cpc_event_t *event);
    199 extern int cpc_pctx_rele(pctx_t *pctx, id_t lwpid);
    200 extern int cpc_pctx_invalidate(pctx_t *pctx, id_t lwpid);
    201 extern int cpc_shared_open(void);
    202 extern void cpc_shared_close(int fd);
    203 extern int cpc_shared_bind_event(int fd, cpc_event_t *event, int flags);
    204 extern int cpc_shared_take_sample(int fd, cpc_event_t *event);
    205 extern int cpc_shared_rele(int fd);
    206 
    207 #endif /* __sparc || __i386 */
    208 
    209 #ifdef	__cplusplus
    210 }
    211 #endif
    212 
    213 #endif	/* _LIBCPC_H */
    214