1PT_CONFIG(3) PT_CONFIG(3)
2
6 pt_config, pt_config_init, pt_cpu_errata - Intel(R) Processor Trace en‐
7 coder/decoder configuration
8
10 #include <intel-pt.h>
11 struct pt_config;
12 void pt_config_init(struct pt_config *config);
13 int pt_cpu_errata(struct pt_errata *errata, const struct pt_cpu *cpu);
14 Link with -lipt.
16
18 The pt_config structure defines an Intel Processor Trace (Intel PT) en‐
19 coder or decoder configuration. It is required for allocating a trace
20 packet encoder (see pt_alloc_encoder(3)), a trace packet decoder (see
21 pt_pkt_alloc_decoder(3)), a query decoder (see pt_qry_alloc_de‐
22 coder(3)), or an instruction flow decoder (see pt_insn_alloc_de‐
23 coder(3)).
24 pt_config_init() zero-initializes its config argument and sets config's
26 size field to sizeof(struct pt_config).
27 pt_cpu_errata() enables workarounds for known errata in its errata ar‐
29 gument for the processor defined by its family/model/stepping in its
30 cpu argument.
31 The pt_config structure is declared as:
33 /** An Intel PT decoder configuration. */
35 struct pt_config {
36 /** The size of the config structure in bytes. */
37 size_t size;
38 /** The trace buffer begin address. */
40 uint8_t *begin;
41 /** The trace buffer end address. */
43 uint8_t *end;
44 /** An optional callback for handling unknown packets.
46 *
47 * If \@callback is not NULL, it is called for any unknown
48 * opcode.
49 */
50 struct {
51 /** The callback function.
52 *
53 * It shall decode the packet at \@pos into \@unknown.
54 * It shall return the number of bytes read upon success.
55 * It shall return a negative pt_error_code otherwise.
56 * The below context is passed as \@context.
57 */
58 int (*callback)(struct pt_packet_unknown *unknown,
59 const struct pt_config *config,
60 const uint8_t *pos, void *context);
61 /** The user-defined context for this configuration. */
63 void *context;
64 } decode;
65 /** The cpu on which Intel PT has been recorded. */
67 struct pt_cpu cpu;
68 /** The errata to apply when encoding or decoding Intel PT. */
70 struct pt_errata errata;
71 /** The CTC frequency.
73 *
74 * This is only required if MTC packets have been enabled in
75 * IA32_RTIT_CTRL.MTCEn.
76 */
77 uint32_t cpuid_0x15_eax, cpuid_0x15_ebx;
78 /** The MTC frequency as defined in IA32_RTIT_CTL.MTCFreq.
80 *
81 * This is only required if MTC packets have been enabled in
82 * IA32_RTIT_CTRL.MTCEn.
83 */
84 uint8_t mtc_freq;
85 /** The nominal frequency as defined in
87 * MSR_PLATFORM_INFO[15:8].
88 *
89 * This is only required if CYC packets have been enabled in
90 * IA32_RTIT_CTRL.CYCEn.
91 *
92 * If zero, timing calibration will only be able to use MTC
93 * and CYC packets.
94 *
95 * If not zero, timing calibration will also be able to use
96 * CBR packets.
97 */
98 uint8_t nom_freq;
99 /** A collection of decoder-specific flags. */
101 struct pt_conf_flags flags;
102 /** The address filter configuration. */
104 struct pt_conf_addr_filter addr_filter;
105 };
106 The fields of the pt_config structure are described in more detail be‐
108 low:
109 size The size of the pt_config structure for backward and forward
111 compatibility. Set it to sizeof(struct pt_config).
112 begin, end
114 The begin and end of a user-allocated memory buffer; begin
115 points to the first byte of the buffer, end points to one past
116 the last byte in the buffer.
117 The packet encoder will generate Intel PT packets into the memo‐
119 ry buffer.
120 The decoders expect the buffer to contain raw Intel PT packets.
122 They decode directly from the buffer and expect the buffer to
123 remain valid until the decoder has been freed.
124 decode An optional packet decode callback function. If decode.callback
126 is not NULL, it will be called for any unknown packet with the
127 decoder configuration, the current decoder position and with a
128 user-defined context provided in callback.context as arguments.
129 If the callback function is able to decode the packet, it shall
131 return the size of the decoded packet and provide details in a
132 pt_packet_unknown object.
133 If the packet cannot be decoded, the callback function shall re‐
135 turn a negative pt_error_code enumeration constant.
136 The pt_packet_unknown object can be used to provide user-defined
138 information back to the user when using the packet decoder to
139 iterate over Intel PT packets. Other decoders ignore this in‐
140 formation but will skip the packet if a non-zero size is re‐
141 turned by the callback function.
142 cpu The processor on which the trace has been collected or for which
144 the trace should be generated. The processor is identified by
145 its family, model, and stepping.
146 /** A cpu vendor. */
148 enum pt_cpu_vendor {
149 pcv_unknown,
150 pcv_intel
151 };
152 /** A cpu identifier. */
154 struct pt_cpu {
155 /** The cpu vendor. */
156 enum pt_cpu_vendor vendor;
157 /** The cpu family. */
159 uint16_t family;
160 /** The cpu model. */
162 uint8_t model;
163 /** The stepping. */
165 uint8_t stepping;
166 };
167 errata The errata workarounds to be applied by the trace encoder or de‐
169 coder that is created using this configuration.
170 The pt_errata structure is a collection of one-bit-fields, one
172 for each supported erratum. Duplicate errata are indicated by
173 comments for the erratum for which the workaround was first im‐
174 plemented. Set the field of an erratum to enable the corre‐
175 spondig workaround.
176 The pt_errata structure is declared as:
178 /** A collection of Intel PT errata. */
180 struct pt_errata {
181 /** BDM70: Intel(R) Processor Trace PSB+ Packets May Contain
182 * Unexpected Packets.
183 *
184 * Same as: SKD024.
185 *
186 * Some Intel Processor Trace packets should be issued only
187 * between TIP.PGE and TIP.PGD packets. Due to this erratum,
188 * when a TIP.PGE packet is generated it may be preceded by a
189 * PSB+ that incorrectly includes FUP and MODE.Exec packets.
190 */
191 uint32_t bdm70:1;
192 /** BDM64: An Incorrect LBR or Intel(R) Processor Trace Packet
194 * May Be Recorded Following a Transactional Abort.
195 *
196 * Use of Intel(R) Transactional Synchronization Extensions
197 * (Intel(R) TSX) may result in a transactional abort. If an
198 * abort occurs immediately following a branch instruction,
199 * an incorrect branch target may be logged in an LBR (Last
200 * Branch Record) or in an Intel(R) Processor Trace (Intel(R)
201 * PT) packet before the LBR or Intel PT packet produced by
202 * the abort.
203 */
204 uint32_t bdm64:1;
205 [...]
207 };
208 cpuid_0x15_eax, cpuid_0x15_ebx
210 The values of eax and ebx on a cpuid call for leaf 0x15.
211 The value ebx/eax gives the ratio of the Core Crystal Clock
213 (CTC) to Timestamp Counter (TSC) frequency.
214 This field is ignored by the packet encoder and packet decoder.
216 It is required for other decoders if Mini Time Counter (MTC)
217 packets are enabled in the collected trace.
218 mtc_freq
220 The Mini Time Counter (MTC) frequency as defined in
221 IA32_RTIT_CTL.MTCFreq.
222 This field is ignored by the packet encoder and packet decoder.
224 It is required for other decoders if Mini Time Counter (MTC)
225 packets are enabled in the collected trace.
226 nom_freq
228 The nominal or max non-turbo frequency.
229 This field is ignored by the packet encoder and packet decoder.
231 It is used by other decoders if Cycle Count (CYC) packets are
232 enabled to improve timing calibration for cycle-accurate trac‐
233 ing.
234 If the field is zero, the time tracking algorithm will use Mini
236 Time Counter (MTC) and Cycle Count (CYC) packets for calibra‐
237 tion.
238 If the field is non-zero, the time tracking algorithm will addi‐
240 tionally be able to calibrate at Core:Bus Ratio (CBR) packets.
241 flags A collection of decoder-specific configuration flags.
243 addr_filter
245 The address filter configuration. It is declared as:
246 /** The address filter configuration. */
248 struct pt_conf_addr_filter {
249 /** The address filter configuration.
250 *
251 * This corresponds to the respective fields in IA32_RTIT_CTL MSR.
252 */
253 union {
254 uint64_t addr_cfg;
255 struct {
257 uint32_t addr0_cfg:4;
258 uint32_t addr1_cfg:4;
259 uint32_t addr2_cfg:4;
260 uint32_t addr3_cfg:4;
261 } ctl;
262 } config;
263 /** The address ranges configuration.
265 *
266 * This corresponds to the IA32_RTIT_ADDRn_A/B MSRs.
267 */
268 uint64_t addr0_a;
269 uint64_t addr0_b;
270 uint64_t addr1_a;
271 uint64_t addr1_b;
272 uint64_t addr2_a;
273 uint64_t addr2_b;
274 uint64_t addr3_a;
275 uint64_t addr3_b;
276 /* Reserve some space. */
278 uint64_t reserved[8];
279 };
280
282 pt_cpu_errata() returns zero on success or a negative pt_error_code
283 enumeration constant otherwise.
284
286 pt_cpu_errata() may return the following errors:
287 pte_invalid
289 The errata or cpu argument is NULL.
290
292 int foo(uint8_t *trace_buffer, size_t size, struct pt_cpu cpu) {
293 struct pt_config config;
294 int errcode;
295 pt_config_init(&config);
297 config.begin = trace_buffer;
298 config.end = trace_buffer + size;
299 config.cpu = cpu;
300 errcode = pt_cpu_errata(&config.errata, &config.cpu);
302 if (errcode < 0)
303 return errcode;
304 [...]
306 }
307
309 pt_alloc_encoder(3), pt_pkt_alloc_decoder(3), pt_qry_alloc_decoder(3),
310 pt_insn_alloc_decoder(3)
311 PT_CONFIG(3)