include/sys/cpc_pcbe.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 /*
  27  * CPC Performance Counter Backend
  28  *
  29  * To utilize the performance counters on a given CPU, a pcbe (Performance
  30  * Counter Backend) must be implemented for that CPU.
  31  *
  32  * This file defines the API which the kernel CPC implementation will call into.
  33  *
  34  */
  35
  36 #ifndef _SYS_CPC_PCBE_H
  37 #define _SYS_CPC_PCBE_H
  38
  39 #include <sys/inttypes.h>
  40 #include <sys/cpc_impl.h>
  41
  42 #ifdef  __cplusplus
  43 extern "C" {
  44 #endif
  45
  46 /*
  47  * All PCBEs must use PCBE_VER_1.
  48  */
  49 #define PCBE_VER_1      1
  50
  51 #define PCBE_IMPL_NAME_P4HT     "Pentium 4 with HyperThreading"
  52
  53 typedef struct __pcbe_ops {
  54         uint_t          pcbe_ver;
  55         uint_t          pcbe_caps;
  56         uint_t          (*pcbe_ncounters)(void);
  57         const char      *(*pcbe_impl_name)(void);
  58         const char      *(*pcbe_cpuref)(void);
  59         char            *(*pcbe_list_events)(uint_t picnum);
  60         char            *(*pcbe_list_attrs)(void);
  61         uint64_t        (*pcbe_event_coverage)(char *event);
  62         uint64_t        (*pcbe_overflow_bitmap)(void);
  63         int             (*pcbe_configure)(uint_t, char *, uint64_t, uint_t,
  64                                 uint_t, kcpc_attr_t *, void **, void *);
  65         void            (*pcbe_program)(void *);
  66         void            (*pcbe_allstop)(void);
  67         void            (*pcbe_sample)(void *);
  68         void            (*pcbe_free)(void *);
  69 } pcbe_ops_t;
  70
  71 extern pcbe_ops_t *pcbe_ops;
  72
  73 /*
  74  * uint_t pcbe_ver;
  75  *
  76  *      Must always be set to PCBE_VER_1.
  77  *
  78  * uint_t pcbe_caps;
  79  *
  80  *      Bitmask of capability flags which define the processor's capabilities:
  81  *              CPC_CAP_OVERFLOW_INTERRUPT:
  82  *                      This processor can generate an interrupt when a counter
  83  *                      overflows.
  84  *
  85  *              CPC_CAP_OVERFLOW_PRECISE:
  86  *                      When an overflow interrupt occurs, the backend can
  87  *                      determine programmatically exactly which counter
  88  *                      overflowed.
  89  *
  90  * uint_t (*pcbe_ncounters)(void);
  91  *
  92  *      Returns the number of counters on the processor.
  93  *
  94  * const char *(*pcbe_impl_name)(void);
  95  *
  96  *      Returns a pointer to a string which uniquely identifies the CPC
  97  *      capabilities of the processor.
  98  *
  99  * const char *(*pcbe_cpuref)(void);
 100  *
 101  *      Returns a pointer to a string which points to a reference manual of
 102  *      some sort which should be consulted to understand the performance
 103  *      counters.
 104  *
 105  * char *(*pcbe_list_events)(uint_t picnum);
 106  *
 107  *      Returns a pointer to a comma-separated list of events which the given
 108  *      counter number is capable of counting. picnum starts at 0 and goes as
 109  *      high as (ncounters - 1).
 110  *
 111  * char *(*pcbe_list_attrs)(void);
 112  *
 113  *      Returns a pointer to a comma-separated list of attribute names which
 114  *      the PCBE supports.
 115  *
 116  * uint64_t (*pcbe_event_coverage)(char *event);
 117  *
 118  *      Returns a bitmask indicating which counters are capable of counting the
 119  *      named event. Counter n is deemed capable if bit (1 << n) is turned on,
 120  *      where counters range from 0 to (ncounters - 1).
 121  *
 122  * uint64_t (*pcbe_overflow_bitmap)(void);
 123  *
 124  *      Called by the kernel when a performance counter interrupt is received.
 125  *      This routine must return a bitmap of counters indicating which ones have
 126  *      overflowed. If the platform cannot determine this, it must act as if
 127  *      _all_ of its counters have overflowed.
 128  *
 129  * int (*pcbe_configure)(uint_t picnum, char *event, uint64_t preset,
 130  *                              uint_t flags, uint_t nattrs, kcpc_attr_t *attrp,
 131  *                              void **configp, void *token);
 132  *
 133  *      Returns a pointer to a PCBE-private data structure which can later be
 134  *      used to program the indicated picnum according to the arguments.
 135  *      token may be passed to kcpc_next_config() in order to walk the list of
 136  *      configurations which will be programmed together.
 137  *
 138  * void (*pcbe_program)(void *token);
 139  *
 140  *      Collects all configurations which will be programmed together, via
 141  *      kcpc_next_config(), programs them onto the hardware, and starts the
 142  *      performance counters.
 143  *
 144  * void (*pcbe_allstop)(void);
 145  *
 146  *      Stops all hardware performance counters.
 147  *
 148  * void (*pcbe_sample)(void *token);
 149  *
 150  *      Samples the values in the performance couters and updates the locations
 151  *      returned by kcpc_next_config() with the delta since the last sample.
 152  *
 153  * void (*pcbe_free)(void *config);
 154  *
 155  *      Frees the given configuration.
 156  */
 157
 158 #ifdef  __cplusplus
 159 }
 160 #endif
 161
 162 #endif /* _SYS_CPC_PCBE_H */