2 * Debug Store (DS) support
4 * This provides a low-level interface to the hardware's Debug Store
5 * feature that is used for branch trace store (BTS) and
6 * precise-event based sampling (PEBS).
9 * - DS and BTS hardware configuration
10 * - buffer overflow handling (to be done)
14 * - security checking (is the caller allowed to trace the task)
15 * - buffer allocation (memory accounting)
18 * Copyright (C) 2007-2008 Intel Corporation.
19 * Markus Metzger <markus.t.metzger@intel.com>, 2007-2008
26 #include <linux/types.h>
27 #include <linux/init.h>
28 #include <linux/err.h>
39 typedef void (*bts_ovfl_callback_t)(struct bts_tracer *);
40 typedef void (*pebs_ovfl_callback_t)(struct pebs_tracer *);
44 * A list of features plus corresponding macros to talk about them in
45 * the ds_request function's flags parameter.
47 * We use the enum to index an array of corresponding control bits;
48 * we use the macro to index a flags bit-vector.
53 #define BTS_KERNEL (1 << dsf_bts_kernel)
54 /* trace kernel-mode branches */
57 #define BTS_USER (1 << dsf_bts_user)
58 /* trace user-mode branches */
62 dsf_pebs = dsf_bts_max,
65 dsf_ctl_max = dsf_pebs_max,
66 dsf_bts_timestamps = dsf_ctl_max,
67 #define BTS_TIMESTAMPS (1 << dsf_bts_timestamps)
68 /* add timestamps into BTS trace */
70 #define BTS_USER_FLAGS (BTS_KERNEL | BTS_USER | BTS_TIMESTAMPS)
77 * Due to alignement constraints, the actual buffer may be slightly
78 * smaller than the requested or provided buffer.
80 * Returns a pointer to a tracer structure on success, or
81 * ERR_PTR(errcode) on failure.
83 * The interrupt threshold is independent from the overflow callback
84 * to allow users to use their own overflow interrupt handling mechanism.
86 * task: the task to request recording for;
87 * NULL for per-cpu recording on the current cpu
88 * base: the base pointer for the (non-pageable) buffer;
89 * size: the size of the provided buffer in bytes
90 * ovfl: pointer to a function to be called on buffer overflow;
91 * NULL if cyclic buffer requested
92 * th: the interrupt threshold in records from the end of the buffer;
93 * -1 if no interrupt threshold is requested.
94 * flags: a bit-mask of the above flags
96 extern struct bts_tracer *ds_request_bts(struct task_struct *task,
97 void *base, size_t size,
98 bts_ovfl_callback_t ovfl,
99 size_t th, unsigned int flags);
100 extern struct pebs_tracer *ds_request_pebs(struct task_struct *task,
101 void *base, size_t size,
102 pebs_ovfl_callback_t ovfl,
103 size_t th, unsigned int flags);
106 * Release BTS or PEBS resources
107 * Suspend and resume BTS or PEBS tracing
109 * tracer: the tracer handle returned from ds_request_~()
111 extern void ds_release_bts(struct bts_tracer *tracer);
112 extern void ds_suspend_bts(struct bts_tracer *tracer);
113 extern void ds_resume_bts(struct bts_tracer *tracer);
114 extern void ds_release_pebs(struct pebs_tracer *tracer);
115 extern void ds_suspend_pebs(struct pebs_tracer *tracer);
116 extern void ds_resume_pebs(struct pebs_tracer *tracer);
120 * The raw DS buffer state as it is used for BTS and PEBS recording.
122 * This is the low-level, arch-dependent interface for working
123 * directly on the raw trace data.
126 /* the number of bts/pebs records */
128 /* the size of a bts/pebs record in bytes */
130 /* pointers into the raw buffer:
131 - to the first entry */
133 /* - one beyond the last entry */
135 /* - one beyond the newest entry */
137 /* - the interrupt threshold */
139 /* flags given on ds_request() */
144 * An arch-independent view on branch trace data.
148 #define BTS_INVALID bts_invalid
151 #define BTS_BRANCH bts_branch
154 #define BTS_TASK_ARRIVES bts_task_arrives
157 #define BTS_TASK_DEPARTS bts_task_departs
159 bts_qual_bit_size = 4,
160 bts_qual_max = (1 << bts_qual_bit_size),
171 /* BTS_TASK_ARRIVES or BTS_TASK_DEPARTS */
183 * This gives access to the raw DS state and adds functions to provide
184 * an arch-independent view of the BTS data.
189 int (*read)(struct bts_tracer *tracer, const void *at,
190 struct bts_struct *out);
191 int (*write)(struct bts_tracer *tracer, const struct bts_struct *in);
198 * This gives access to the raw DS state and the PEBS-specific counter
204 /* the PEBS reset value */
205 unsigned long long reset_value;
210 * Read the BTS or PEBS trace.
212 * Returns a view on the trace collected for the parameter tracer.
214 * The view remains valid as long as the traced task is not running or
215 * the tracer is suspended.
216 * Writes into the trace buffer are not reflected.
218 * tracer: the tracer handle returned from ds_request_~()
220 extern const struct bts_trace *ds_read_bts(struct bts_tracer *tracer);
221 extern const struct pebs_trace *ds_read_pebs(struct pebs_tracer *tracer);
225 * Reset the write pointer of the BTS/PEBS buffer.
227 * Returns 0 on success; -Eerrno on error
229 * tracer: the tracer handle returned from ds_request_~()
231 extern int ds_reset_bts(struct bts_tracer *tracer);
232 extern int ds_reset_pebs(struct pebs_tracer *tracer);
235 * Set the PEBS counter reset value.
237 * Returns 0 on success; -Eerrno on error
239 * tracer: the tracer handle returned from ds_request_pebs()
240 * value: the new counter reset value
242 extern int ds_set_pebs_reset(struct pebs_tracer *tracer, u64 value);
248 extern void __cpuinit ds_init_intel(struct cpuinfo_x86 *);
251 * Context switch work
253 extern void ds_switch_to(struct task_struct *prev, struct task_struct *next);
256 * Task clone/init and cleanup work
258 extern void ds_copy_thread(struct task_struct *tsk, struct task_struct *father);
259 extern void ds_exit_thread(struct task_struct *tsk);
261 #else /* CONFIG_X86_DS */
264 static inline void __cpuinit ds_init_intel(struct cpuinfo_x86 *ignored) {}
265 static inline void ds_switch_to(struct task_struct *prev,
266 struct task_struct *next) {}
267 static inline void ds_copy_thread(struct task_struct *tsk,
268 struct task_struct *father) {}
269 static inline void ds_exit_thread(struct task_struct *tsk) {}
271 #endif /* CONFIG_X86_DS */
272 #endif /* _ASM_X86_DS_H */