docs/how-to-build.md: use proper markup for directory names
[unleashed/tickless.git] / include / sys / cpc_pcbe.h
blobeb168fcf2c734093153a2a298605f97324956f74
1 /*
2 * CDDL HEADER START
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.
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.
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]
19 * CDDL HEADER END
22 * Copyright 2009 Sun Microsystems, Inc. All rights reserved.
23 * Use is subject to license terms.
27 * CPC Performance Counter Backend
29 * To utilize the performance counters on a given CPU, a pcbe (Performance
30 * Counter Backend) must be implemented for that CPU.
32 * This file defines the API which the kernel CPC implementation will call into.
36 #ifndef _SYS_CPC_PCBE_H
37 #define _SYS_CPC_PCBE_H
39 #include <sys/inttypes.h>
40 #include <sys/cpc_impl.h>
42 #ifdef __cplusplus
43 extern "C" {
44 #endif
47 * All PCBEs must use PCBE_VER_1.
49 #define PCBE_VER_1 1
51 #define PCBE_IMPL_NAME_P4HT "Pentium 4 with HyperThreading"
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;
71 extern pcbe_ops_t *pcbe_ops;
74 * uint_t pcbe_ver;
76 * Must always be set to PCBE_VER_1.
78 * uint_t pcbe_caps;
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.
85 * CPC_CAP_OVERFLOW_PRECISE:
86 * When an overflow interrupt occurs, the backend can
87 * determine programmatically exactly which counter
88 * overflowed.
90 * uint_t (*pcbe_ncounters)(void);
92 * Returns the number of counters on the processor.
94 * const char *(*pcbe_impl_name)(void);
96 * Returns a pointer to a string which uniquely identifies the CPC
97 * capabilities of the processor.
99 * const char *(*pcbe_cpuref)(void);
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.
105 * char *(*pcbe_list_events)(uint_t picnum);
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).
111 * char *(*pcbe_list_attrs)(void);
113 * Returns a pointer to a comma-separated list of attribute names which
114 * the PCBE supports.
116 * uint64_t (*pcbe_event_coverage)(char *event);
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).
122 * uint64_t (*pcbe_overflow_bitmap)(void);
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.
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);
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.
138 * void (*pcbe_program)(void *token);
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.
144 * void (*pcbe_allstop)(void);
146 * Stops all hardware performance counters.
148 * void (*pcbe_sample)(void *token);
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.
153 * void (*pcbe_free)(void *config);
155 * Frees the given configuration.
158 #ifdef __cplusplus
160 #endif
162 #endif /* _SYS_CPC_PCBE_H */