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
43extern "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
53typedef 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
71extern 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 */
163