1PT_CONFIG(3)                                                      PT_CONFIG(3)
2
3
4

NAME

6       pt_config, pt_config_init, pt_cpu_errata - Intel(R) Processor Trace en‐
7       coder/decoder configuration
8

SYNOPSIS

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
15       Link with -lipt.
16

DESCRIPTION

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
25       pt_config_init() zero-initializes its config argument and sets config's
26       size field to sizeof(struct pt_config).
27
28       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
32       The pt_config structure is declared as:
33
34              /** An Intel PT decoder configuration. */
35              struct pt_config {
36                  /** The size of the config structure in bytes. */
37                  size_t size;
38
39                  /** The trace buffer begin address. */
40                  uint8_t *begin;
41
42                  /** The trace buffer end address. */
43                  uint8_t *end;
44
45                  /** 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
62                      /** The user-defined context for this configuration. */
63                      void *context;
64                  } decode;
65
66                  /** The cpu on which Intel PT has been recorded. */
67                  struct pt_cpu cpu;
68
69                  /** The errata to apply when encoding or decoding Intel PT. */
70                  struct pt_errata errata;
71
72                  /** 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
79                  /** 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
86                  /** 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
100                  /** A collection of decoder-specific flags. */
101                  struct pt_conf_flags flags;
102
103                  /** The address filter configuration. */
104                  struct pt_conf_addr_filter addr_filter;
105              };
106
107       The fields of the pt_config structure are described in more detail  be‐
108       low:
109
110       size   The  size  of  the  pt_config structure for backward and forward
111              compatibility.  Set it to sizeof(struct pt_config).
112
113       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
118              The packet encoder will generate Intel PT packets into the memo‐
119              ry buffer.
120
121              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
125       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
130              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
134              If the packet cannot be decoded, the callback function shall re‐
135              turn a negative pt_error_code enumeration constant.
136
137              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
143       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
147              /** A cpu vendor. */
148              enum pt_cpu_vendor {
149                  pcv_unknown,
150                  pcv_intel
151              };
152
153              /** A cpu identifier. */
154              struct pt_cpu {
155                  /** The cpu vendor. */
156                  enum pt_cpu_vendor vendor;
157
158                  /** The cpu family. */
159                  uint16_t family;
160
161                  /** The cpu model. */
162                  uint8_t model;
163
164                  /** The stepping. */
165                  uint8_t stepping;
166              };
167
168       errata The errata workarounds to be applied by the trace encoder or de‐
169              coder that is created using this configuration.
170
171              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
177              The pt_errata structure is declared as:
178
179              /** 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
193                  /** 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
206                  [...]
207              };
208
209       cpuid_0x15_eax, cpuid_0x15_ebx
210              The values of eax and ebx on a cpuid call for leaf 0x15.
211
212              The value ebx/eax gives the ratio  of  the  Core  Crystal  Clock
213              (CTC) to Timestamp Counter (TSC) frequency.
214
215              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
219       mtc_freq
220              The   Mini   Time   Counter   (MTC)   frequency  as  defined  in
221              IA32_RTIT_CTL.MTCFreq.
222
223              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
227       nom_freq
228              The nominal or max non-turbo frequency.
229
230              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
235              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
239              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
242       flags  A collection of decoder-specific configuration flags.
243
244       addr_filter
245              The address filter configuration.  It is declared as:
246
247              /** 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
256                      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
264                  /** 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
277                  /* Reserve some space. */
278                  uint64_t reserved[8];
279              };
280

RETURN VALUE

282       pt_cpu_errata() returns zero on success  or  a  negative  pt_error_code
283       enumeration constant otherwise.
284

ERRORS

286       pt_cpu_errata() may return the following errors:
287
288       pte_invalid
289              The errata or cpu argument is NULL.
290

EXAMPLE

292              int foo(uint8_t *trace_buffer, size_t size, struct pt_cpu cpu) {
293                  struct pt_config config;
294                  int errcode;
295
296                  pt_config_init(&config);
297                  config.begin = trace_buffer;
298                  config.end = trace_buffer + size;
299                  config.cpu = cpu;
300
301                  errcode = pt_cpu_errata(&config.errata, &config.cpu);
302                  if (errcode < 0)
303                      return errcode;
304
305                  [...]
306              }
307

SEE ALSO

309       pt_alloc_encoder(3),  pt_pkt_alloc_decoder(3), pt_qry_alloc_decoder(3),
310       pt_insn_alloc_decoder(3)
311
312
313
314                                                                  PT_CONFIG(3)
Impressum