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 * - per-thread and per-cpu allocation of BTS and PEBS
10 * - buffer memory allocation (optional)
11 * - buffer overflow handling
15 * - get_task_struct on all parameter tasks
16 * - current is allowed to trace parameter tasks
19 * Copyright (C) 2007-2008 Intel Corporation.
20 * Markus Metzger <markus.t.metzger@intel.com>, 2007-2008
27 #include <linux/types.h>
28 #include <linux/init.h>
29 #include <linux/err.h>
39 typedef void (*bts_ovfl_callback_t)(struct bts_tracer *);
40 typedef void (*pebs_ovfl_callback_t)(struct pebs_tracer *);
45 * Due to alignement constraints, the actual buffer may be slightly
46 * smaller than the requested or provided buffer.
48 * Returns a pointer to a tracer structure on success, or
49 * ERR_PTR(errcode) on failure.
51 * The interrupt threshold is independent from the overflow callback
52 * to allow users to use their own overflow interrupt handling mechanism.
54 * task: the task to request recording for;
55 * NULL for per-cpu recording on the current cpu
56 * base: the base pointer for the (non-pageable) buffer;
57 * NULL if buffer allocation requested
58 * size: the size of the requested or provided buffer in bytes
59 * ovfl: pointer to a function to be called on buffer overflow;
60 * NULL if cyclic buffer requested
61 * th: the interrupt threshold in records from the end of the buffer;
62 * -1 if no interrupt threshold is requested.
64 extern struct bts_tracer *ds_request_bts(struct task_struct *task,
65 void *base, size_t size,
66 bts_ovfl_callback_t ovfl, size_t th);
67 extern struct pebs_tracer *ds_request_pebs(struct task_struct *task,
68 void *base, size_t size,
69 pebs_ovfl_callback_t ovfl,
73 * Release BTS or PEBS resources
75 * Frees buffers allocated on ds_request.
77 * Returns 0 on success; -Eerrno otherwise
79 * tracer: the tracer handle returned from ds_request_~()
81 extern int ds_release_bts(struct bts_tracer *tracer);
82 extern int ds_release_pebs(struct pebs_tracer *tracer);
85 * Get the (array) index of the write pointer.
86 * (assuming an array of BTS/PEBS records)
88 * Returns 0 on success; -Eerrno on error
90 * tracer: the tracer handle returned from ds_request_~()
91 * pos (out): will hold the result
93 extern int ds_get_bts_index(struct bts_tracer *tracer, size_t *pos);
94 extern int ds_get_pebs_index(struct pebs_tracer *tracer, size_t *pos);
97 * Get the (array) index one record beyond the end of the array.
98 * (assuming an array of BTS/PEBS records)
100 * Returns 0 on success; -Eerrno on error
102 * tracer: the tracer handle returned from ds_request_~()
103 * pos (out): will hold the result
105 extern int ds_get_bts_end(struct bts_tracer *tracer, size_t *pos);
106 extern int ds_get_pebs_end(struct pebs_tracer *tracer, size_t *pos);
109 * Provide a pointer to the BTS/PEBS record at parameter index.
110 * (assuming an array of BTS/PEBS records)
112 * The pointer points directly into the buffer. The user is
113 * responsible for copying the record.
115 * Returns the size of a single record on success; -Eerrno on error
117 * tracer: the tracer handle returned from ds_request_~()
118 * index: the index of the requested record
119 * record (out): pointer to the requested record
121 extern int ds_access_bts(struct bts_tracer *tracer,
122 size_t index, const void **record);
123 extern int ds_access_pebs(struct pebs_tracer *tracer,
124 size_t index, const void **record);
127 * Write one or more BTS/PEBS records at the write pointer index and
128 * advance the write pointer.
130 * If size is not a multiple of the record size, trailing bytes are
133 * May result in one or more overflow notifications.
135 * If called during overflow handling, that is, with index >=
136 * interrupt threshold, the write will wrap around.
138 * An overflow notification is given if and when the interrupt
139 * threshold is reached during or after the write.
141 * Returns the number of bytes written or -Eerrno.
143 * tracer: the tracer handle returned from ds_request_~()
144 * buffer: the buffer to write
145 * size: the size of the buffer
147 extern int ds_write_bts(struct bts_tracer *tracer,
148 const void *buffer, size_t size);
149 extern int ds_write_pebs(struct pebs_tracer *tracer,
150 const void *buffer, size_t size);
153 * Reset the write pointer of the BTS/PEBS buffer.
155 * Returns 0 on success; -Eerrno on error
157 * tracer: the tracer handle returned from ds_request_~()
159 extern int ds_reset_bts(struct bts_tracer *tracer);
160 extern int ds_reset_pebs(struct pebs_tracer *tracer);
163 * Clear the BTS/PEBS buffer and reset the write pointer.
164 * The entire buffer will be zeroed out.
166 * Returns 0 on success; -Eerrno on error
168 * tracer: the tracer handle returned from ds_request_~()
170 extern int ds_clear_bts(struct bts_tracer *tracer);
171 extern int ds_clear_pebs(struct pebs_tracer *tracer);
174 * Provide the PEBS counter reset value.
176 * Returns 0 on success; -Eerrno on error
178 * tracer: the tracer handle returned from ds_request_pebs()
179 * value (out): the counter reset value
181 extern int ds_get_pebs_reset(struct pebs_tracer *tracer, u64 *value);
184 * Set the PEBS counter reset value.
186 * Returns 0 on success; -Eerrno on error
188 * tracer: the tracer handle returned from ds_request_pebs()
189 * value: the new counter reset value
191 extern int ds_set_pebs_reset(struct pebs_tracer *tracer, u64 value);
197 extern void __cpuinit ds_init_intel(struct cpuinfo_x86 *);
202 * The DS context - part of struct thread_struct.
204 #define MAX_SIZEOF_DS (12 * 8)
207 /* pointer to the DS configuration; goes into MSR_IA32_DS_AREA */
208 unsigned char ds[MAX_SIZEOF_DS];
209 /* the owner of the BTS and PEBS configuration, respectively */
210 struct ds_tracer *owner[2];
213 /* a pointer to the context location inside the thread_struct
214 * or the per_cpu context array */
215 struct ds_context **this;
216 /* a pointer to the task owning this context, or NULL, if the
217 * context is owned by a cpu */
218 struct task_struct *task;
221 /* called by exit_thread() to free leftover contexts */
222 extern void ds_free(struct ds_context *context);
224 #else /* CONFIG_X86_DS */
227 static inline void __cpuinit ds_init_intel(struct cpuinfo_x86 *ignored) {}
229 #endif /* CONFIG_X86_DS */
230 #endif /* _ASM_X86_DS_H */