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