1 /*
2 * Copyright (c) 2013-2018, Intel Corporation
3 *
4 * Redistribution and use in source and binary forms, with or without
5 * modification, are permitted provided that the following conditions are met:
6 *
7 * * Redistributions of source code must retain the above copyright notice,
8 * this list of conditions and the following disclaimer.
9 * * Redistributions in binary form must reproduce the above copyright notice,
10 * this list of conditions and the following disclaimer in the documentation
11 * and/or other materials provided with the distribution.
12 * * Neither the name of Intel Corporation nor the names of its contributors
13 * may be used to endorse or promote products derived from this software
14 * without specific prior written permission.
15 *
16 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
17 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
20 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
21 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
22 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
23 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
24 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
25 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
26 * POSSIBILITY OF SUCH DAMAGE.
27 */
28
29 #ifndef INTEL_PT_H
30 #define INTEL_PT_H
31
32 #include <stdint.h>
33 #include <string.h>
34
35 #ifdef __cplusplus
36 extern "C" {
37 #endif
38
39
40 /* Intel(R) Processor Trace (Intel PT) decoder library.
41 *
42 * This file is logically structured into the following sections:
43 *
44 * - Version
45 * - Errors
46 * - Configuration
47 * - Packet encoder / decoder
48 * - Query decoder
49 * - Traced image
50 * - Instruction flow decoder
51 * - Block decoder
52 */
53
54
55
56 struct pt_encoder;
57 struct pt_packet_decoder;
58 struct pt_query_decoder;
59 struct pt_insn_decoder;
60 struct pt_block_decoder;
61
62
63
64 /* A macro to mark functions as exported. */
65 #ifndef pt_export
66 # if defined(__GNUC__)
67 # define pt_export __attribute__((visibility("default")))
68 # elif defined(_MSC_VER)
69 # define pt_export __declspec(dllimport)
70 # else
71 # error "unknown compiler"
72 # endif
73 #endif
74
75
76
77 /* Version. */
78
79
80 /** The header version. */
81 #define LIBIPT_VERSION_MAJOR ${PT_VERSION_MAJOR}
82 #define LIBIPT_VERSION_MINOR ${PT_VERSION_MINOR}
83
84 #define LIBIPT_VERSION ((LIBIPT_VERSION_MAJOR << 8) + LIBIPT_VERSION_MINOR)
85
86
87 /** The library version. */
88 struct pt_version {
89 /** Major version number. */
90 uint8_t major;
91
92 /** Minor version number. */
93 uint8_t minor;
94
95 /** Reserved bits. */
96 uint16_t reserved;
97
98 /** Build number. */
99 uint32_t build;
100
101 /** Version extension. */
102 const char *ext;
103 };
104
105
106 /** Return the library version. */
107 extern pt_export struct pt_version pt_library_version(void);
108
109
110
111 /* Errors. */
112
113
114
115 /** Error codes. */
116 enum pt_error_code {
117 /* No error. Everything is OK. */
118 pte_ok,
119
120 /* Internal decoder error. */
121 pte_internal,
122
123 /* Invalid argument. */
124 pte_invalid,
125
126 /* Decoder out of sync. */
127 pte_nosync,
128
129 /* Unknown opcode. */
130 pte_bad_opc,
131
132 /* Unknown payload. */
133 pte_bad_packet,
134
135 /* Unexpected packet context. */
136 pte_bad_context,
137
138 /* Decoder reached end of trace stream. */
139 pte_eos,
140
141 /* No packet matching the query to be found. */
142 pte_bad_query,
143
144 /* Decoder out of memory. */
145 pte_nomem,
146
147 /* Bad configuration. */
148 pte_bad_config,
149
150 /* There is no IP. */
151 pte_noip,
152
153 /* The IP has been suppressed. */
154 pte_ip_suppressed,
155
156 /* There is no memory mapped at the requested address. */
157 pte_nomap,
158
159 /* An instruction could not be decoded. */
160 pte_bad_insn,
161
162 /* No wall-clock time is available. */
163 pte_no_time,
164
165 /* No core:bus ratio available. */
166 pte_no_cbr,
167
168 /* Bad traced image. */
169 pte_bad_image,
170
171 /* A locking error. */
172 pte_bad_lock,
173
174 /* The requested feature is not supported. */
175 pte_not_supported,
176
177 /* The return address stack is empty. */
178 pte_retstack_empty,
179
180 /* A compressed return is not indicated correctly by a taken branch. */
181 pte_bad_retcomp,
182
183 /* The current decoder state does not match the state in the trace. */
184 pte_bad_status_update,
185
186 /* The trace did not contain an expected enabled event. */
187 pte_no_enable,
188
189 /* An event was ignored. */
190 pte_event_ignored,
191
192 /* Something overflowed. */
193 pte_overflow,
194
195 /* A file handling error. */
196 pte_bad_file,
197
198 /* Unknown cpu. */
199 pte_bad_cpu
200 };
201
202
203 /** Decode a function return value into an pt_error_code. */
pt_errcode(int status)204 static inline enum pt_error_code pt_errcode(int status)
205 {
206 return (status >= 0) ? pte_ok : (enum pt_error_code) -status;
207 }
208
209 /** Return a human readable error string. */
210 extern pt_export const char *pt_errstr(enum pt_error_code);
211
212
213
214 /* Configuration. */
215
216
217
218 /** A cpu vendor. */
219 enum pt_cpu_vendor {
220 pcv_unknown,
221 pcv_intel
222 };
223
224 /** A cpu identifier. */
225 struct pt_cpu {
226 /** The cpu vendor. */
227 enum pt_cpu_vendor vendor;
228
229 /** The cpu family. */
230 uint16_t family;
231
232 /** The cpu model. */
233 uint8_t model;
234
235 /** The stepping. */
236 uint8_t stepping;
237 };
238
239 /** A collection of Intel PT errata. */
240 struct pt_errata {
241 /** BDM70: Intel(R) Processor Trace PSB+ Packets May Contain
242 * Unexpected Packets.
243 *
244 * Same as: SKD024, SKL021, KBL021.
245 *
246 * Some Intel Processor Trace packets should be issued only between
247 * TIP.PGE and TIP.PGD packets. Due to this erratum, when a TIP.PGE
248 * packet is generated it may be preceded by a PSB+ that incorrectly
249 * includes FUP and MODE.Exec packets.
250 */
251 uint32_t bdm70:1;
252
253 /** BDM64: An Incorrect LBR or Intel(R) Processor Trace Packet May Be
254 * Recorded Following a Transactional Abort.
255 *
256 * Use of Intel(R) Transactional Synchronization Extensions (Intel(R)
257 * TSX) may result in a transactional abort. If an abort occurs
258 * immediately following a branch instruction, an incorrect branch
259 * target may be logged in an LBR (Last Branch Record) or in an Intel(R)
260 * Processor Trace (Intel(R) PT) packet before the LBR or Intel PT
261 * packet produced by the abort.
262 */
263 uint32_t bdm64:1;
264
265 /** SKD007: Intel(R) PT Buffer Overflow May Result in Incorrect Packets.
266 *
267 * Same as: SKL049, KBL041.
268 *
269 * Under complex micro-architectural conditions, an Intel PT (Processor
270 * Trace) OVF (Overflow) packet may be issued after the first byte of a
271 * multi-byte CYC (Cycle Count) packet, instead of any remaining bytes
272 * of the CYC.
273 */
274 uint32_t skd007:1;
275
276 /** SKD022: VM Entry That Clears TraceEn May Generate a FUP.
277 *
278 * Same as: SKL024, KBL023.
279 *
280 * If VM entry clears Intel(R) PT (Intel Processor Trace)
281 * IA32_RTIT_CTL.TraceEn (MSR 570H, bit 0) while PacketEn is 1 then a
282 * FUP (Flow Update Packet) will precede the TIP.PGD (Target IP Packet,
283 * Packet Generation Disable). VM entry can clear TraceEn if the
284 * VM-entry MSR-load area includes an entry for the IA32_RTIT_CTL MSR.
285 */
286 uint32_t skd022:1;
287
288 /** SKD010: Intel(R) PT FUP May be Dropped After OVF.
289 *
290 * Same as: SKD014, SKL033, KBL030.
291 *
292 * Some Intel PT (Intel Processor Trace) OVF (Overflow) packets may not
293 * be followed by a FUP (Flow Update Packet) or TIP.PGE (Target IP
294 * Packet, Packet Generation Enable).
295 */
296 uint32_t skd010:1;
297
298 /** SKL014: Intel(R) PT TIP.PGD May Not Have Target IP Payload.
299 *
300 * Same as: KBL014.
301 *
302 * When Intel PT (Intel Processor Trace) is enabled and a direct
303 * unconditional branch clears IA32_RTIT_STATUS.FilterEn (MSR 571H, bit
304 * 0), due to this erratum, the resulting TIP.PGD (Target IP Packet,
305 * Packet Generation Disable) may not have an IP payload with the target
306 * IP.
307 */
308 uint32_t skl014:1;
309
310 /** APL12: Intel(R) PT OVF May Be Followed By An Unexpected FUP Packet.
311 *
312 * Certain Intel PT (Processor Trace) packets including FUPs (Flow
313 * Update Packets), should be issued only between TIP.PGE (Target IP
314 * Packet - Packet Generaton Enable) and TIP.PGD (Target IP Packet -
315 * Packet Generation Disable) packets. When outside a TIP.PGE/TIP.PGD
316 * pair, as a result of IA32_RTIT_STATUS.FilterEn[0] (MSR 571H) being
317 * cleared, an OVF (Overflow) packet may be unexpectedly followed by a
318 * FUP.
319 */
320 uint32_t apl12:1;
321
322 /** APL11: Intel(R) PT OVF Pakcet May Be Followed by TIP.PGD Packet
323 *
324 * If Intel PT (Processor Trace) encounters an internal buffer overflow
325 * and generates an OVF (Overflow) packet just as IA32_RTIT_CTL (MSR
326 * 570H) bit 0 (TraceEn) is cleared, or during a far transfer that
327 * causes IA32_RTIT_STATUS.ContextEn[1] (MSR 571H) to be cleared, the
328 * OVF may be followed by a TIP.PGD (Target Instruction Pointer - Packet
329 * Generation Disable) packet.
330 */
331 uint32_t apl11:1;
332
333 /* Reserve a few bytes for the future. */
334 uint32_t reserved[15];
335 };
336
337 /** A collection of decoder-specific configuration flags. */
338 struct pt_conf_flags {
339 /** The decoder variant. */
340 union {
341 /** Flags for the block decoder. */
342 struct {
343 /** End a block after a call instruction. */
344 uint32_t end_on_call:1;
345
346 /** Enable tick events for timing updates. */
347 uint32_t enable_tick_events:1;
348
349 /** End a block after a jump instruction. */
350 uint32_t end_on_jump:1;
351 } block;
352
353 /** Flags for the instruction flow decoder. */
354 struct {
355 /** Enable tick events for timing updates. */
356 uint32_t enable_tick_events:1;
357 } insn;
358
359 /* Reserve a few bytes for future extensions. */
360 uint32_t reserved[4];
361 } variant;
362 };
363
364 /** The address filter configuration. */
365 struct pt_conf_addr_filter {
366 /** The address filter configuration.
367 *
368 * This corresponds to the respective fields in IA32_RTIT_CTL MSR.
369 */
370 union {
371 uint64_t addr_cfg;
372
373 struct {
374 uint32_t addr0_cfg:4;
375 uint32_t addr1_cfg:4;
376 uint32_t addr2_cfg:4;
377 uint32_t addr3_cfg:4;
378 } ctl;
379 } config;
380
381 /** The address ranges configuration.
382 *
383 * This corresponds to the IA32_RTIT_ADDRn_A/B MSRs.
384 */
385 uint64_t addr0_a;
386 uint64_t addr0_b;
387 uint64_t addr1_a;
388 uint64_t addr1_b;
389 uint64_t addr2_a;
390 uint64_t addr2_b;
391 uint64_t addr3_a;
392 uint64_t addr3_b;
393
394 /* Reserve some space. */
395 uint64_t reserved[8];
396 };
397
398 /** An unknown packet. */
399 struct pt_packet_unknown;
400
401 /** An Intel PT decoder configuration.
402 */
403 struct pt_config {
404 /** The size of the config structure in bytes. */
405 size_t size;
406
407 /** The trace buffer begin address. */
408 uint8_t *begin;
409
410 /** The trace buffer end address. */
411 uint8_t *end;
412
413 /** An optional callback for handling unknown packets.
414 *
415 * If \@callback is not NULL, it is called for any unknown opcode.
416 */
417 struct {
418 /** The callback function.
419 *
420 * It shall decode the packet at \@pos into \@unknown.
421 * It shall return the number of bytes read upon success.
422 * It shall return a negative pt_error_code otherwise.
423 * The below context is passed as \@context.
424 */
425 int (*callback)(struct pt_packet_unknown *unknown,
426 const struct pt_config *config,
427 const uint8_t *pos, void *context);
428
429 /** The user-defined context for this configuration. */
430 void *context;
431 } decode;
432
433 /** The cpu on which Intel PT has been recorded. */
434 struct pt_cpu cpu;
435
436 /** The errata to apply when encoding or decoding Intel PT. */
437 struct pt_errata errata;
438
439 /* The CTC frequency.
440 *
441 * This is only required if MTC packets have been enabled in
442 * IA32_RTIT_CTRL.MTCEn.
443 */
444 uint32_t cpuid_0x15_eax, cpuid_0x15_ebx;
445
446 /* The MTC frequency as defined in IA32_RTIT_CTL.MTCFreq.
447 *
448 * This is only required if MTC packets have been enabled in
449 * IA32_RTIT_CTRL.MTCEn.
450 */
451 uint8_t mtc_freq;
452
453 /* The nominal frequency as defined in MSR_PLATFORM_INFO[15:8].
454 *
455 * This is only required if CYC packets have been enabled in
456 * IA32_RTIT_CTRL.CYCEn.
457 *
458 * If zero, timing calibration will only be able to use MTC and CYC
459 * packets.
460 *
461 * If not zero, timing calibration will also be able to use CBR
462 * packets.
463 */
464 uint8_t nom_freq;
465
466 /** A collection of decoder-specific flags. */
467 struct pt_conf_flags flags;
468
469 /** The address filter configuration. */
470 struct pt_conf_addr_filter addr_filter;
471 };
472
473
474 /** Zero-initialize an Intel PT configuration. */
pt_config_init(struct pt_config * config)475 static inline void pt_config_init(struct pt_config *config)
476 {
477 memset(config, 0, sizeof(*config));
478
479 config->size = sizeof(*config);
480 }
481
482 /** Determine errata for a given cpu.
483 *
484 * Updates \@errata based on \@cpu.
485 *
486 * Returns 0 on success, a negative error code otherwise.
487 * Returns -pte_invalid if \@errata or \@cpu is NULL.
488 * Returns -pte_bad_cpu if \@cpu is not known.
489 */
490 extern pt_export int pt_cpu_errata(struct pt_errata *errata,
491 const struct pt_cpu *cpu);
492
493
494
495 /* Packet encoder / decoder. */
496
497
498
499 /** Intel PT packet types. */
500 enum pt_packet_type {
501 /* An invalid packet. */
502 ppt_invalid,
503
504 /* A packet decodable by the optional decoder callback. */
505 ppt_unknown,
506
507 /* Actual packets supported by this library. */
508 ppt_pad,
509 ppt_psb,
510 ppt_psbend,
511 ppt_fup,
512 ppt_tip,
513 ppt_tip_pge,
514 ppt_tip_pgd,
515 ppt_tnt_8,
516 ppt_tnt_64,
517 ppt_mode,
518 ppt_pip,
519 ppt_vmcs,
520 ppt_cbr,
521 ppt_tsc,
522 ppt_tma,
523 ppt_mtc,
524 ppt_cyc,
525 ppt_stop,
526 ppt_ovf,
527 ppt_mnt,
528 ppt_exstop,
529 ppt_mwait,
530 ppt_pwre,
531 ppt_pwrx,
532 ppt_ptw
533 };
534
535 /** The IP compression. */
536 enum pt_ip_compression {
537 /* The bits encode the payload size and the encoding scheme.
538 *
539 * No payload. The IP has been suppressed.
540 */
541 pt_ipc_suppressed = 0x0,
542
543 /* Payload: 16 bits. Update last IP. */
544 pt_ipc_update_16 = 0x01,
545
546 /* Payload: 32 bits. Update last IP. */
547 pt_ipc_update_32 = 0x02,
548
549 /* Payload: 48 bits. Sign extend to full address. */
550 pt_ipc_sext_48 = 0x03,
551
552 /* Payload: 48 bits. Update last IP. */
553 pt_ipc_update_48 = 0x04,
554
555 /* Payload: 64 bits. Full address. */
556 pt_ipc_full = 0x06
557 };
558
559 /** An execution mode. */
560 enum pt_exec_mode {
561 ptem_unknown,
562 ptem_16bit,
563 ptem_32bit,
564 ptem_64bit
565 };
566
567 /** Mode packet leaves. */
568 enum pt_mode_leaf {
569 pt_mol_exec = 0x00,
570 pt_mol_tsx = 0x20
571 };
572
573 /** A TNT-8 or TNT-64 packet. */
574 struct pt_packet_tnt {
575 /** TNT payload bit size. */
576 uint8_t bit_size;
577
578 /** TNT payload excluding stop bit. */
579 uint64_t payload;
580 };
581
582 /** A packet with IP payload. */
583 struct pt_packet_ip {
584 /** IP compression. */
585 enum pt_ip_compression ipc;
586
587 /** Zero-extended payload ip. */
588 uint64_t ip;
589 };
590
591 /** A mode.exec packet. */
592 struct pt_packet_mode_exec {
593 /** The mode.exec csl bit. */
594 uint32_t csl:1;
595
596 /** The mode.exec csd bit. */
597 uint32_t csd:1;
598 };
599
600 static inline enum pt_exec_mode
pt_get_exec_mode(const struct pt_packet_mode_exec * packet)601 pt_get_exec_mode(const struct pt_packet_mode_exec *packet)
602 {
603 if (packet->csl)
604 return packet->csd ? ptem_unknown : ptem_64bit;
605 else
606 return packet->csd ? ptem_32bit : ptem_16bit;
607 }
608
609 static inline struct pt_packet_mode_exec
pt_set_exec_mode(enum pt_exec_mode mode)610 pt_set_exec_mode(enum pt_exec_mode mode)
611 {
612 struct pt_packet_mode_exec packet;
613
614 switch (mode) {
615 default:
616 packet.csl = 1;
617 packet.csd = 1;
618 break;
619
620 case ptem_64bit:
621 packet.csl = 1;
622 packet.csd = 0;
623 break;
624
625 case ptem_32bit:
626 packet.csl = 0;
627 packet.csd = 1;
628 break;
629
630 case ptem_16bit:
631 packet.csl = 0;
632 packet.csd = 0;
633 break;
634 }
635
636 return packet;
637 }
638
639 /** A mode.tsx packet. */
640 struct pt_packet_mode_tsx {
641 /** The mode.tsx intx bit. */
642 uint32_t intx:1;
643
644 /** The mode.tsx abrt bit. */
645 uint32_t abrt:1;
646 };
647
648 /** A mode packet. */
649 struct pt_packet_mode {
650 /** Mode leaf. */
651 enum pt_mode_leaf leaf;
652
653 /** Mode bits. */
654 union {
655 /** Packet: mode.exec. */
656 struct pt_packet_mode_exec exec;
657
658 /** Packet: mode.tsx. */
659 struct pt_packet_mode_tsx tsx;
660 } bits;
661 };
662
663 /** A PIP packet. */
664 struct pt_packet_pip {
665 /** The CR3 value. */
666 uint64_t cr3;
667
668 /** The non-root bit. */
669 uint32_t nr:1;
670 };
671
672 /** A TSC packet. */
673 struct pt_packet_tsc {
674 /** The TSC value. */
675 uint64_t tsc;
676 };
677
678 /** A CBR packet. */
679 struct pt_packet_cbr {
680 /** The core/bus cycle ratio. */
681 uint8_t ratio;
682 };
683
684 /** A TMA packet. */
685 struct pt_packet_tma {
686 /** The crystal clock tick counter value. */
687 uint16_t ctc;
688
689 /** The fast counter value. */
690 uint16_t fc;
691 };
692
693 /** A MTC packet. */
694 struct pt_packet_mtc {
695 /** The crystal clock tick counter value. */
696 uint8_t ctc;
697 };
698
699 /** A CYC packet. */
700 struct pt_packet_cyc {
701 /** The cycle counter value. */
702 uint64_t value;
703 };
704
705 /** A VMCS packet. */
706 struct pt_packet_vmcs {
707 /* The VMCS Base Address (i.e. the shifted payload). */
708 uint64_t base;
709 };
710
711 /** A MNT packet. */
712 struct pt_packet_mnt {
713 /** The raw payload. */
714 uint64_t payload;
715 };
716
717 /** A EXSTOP packet. */
718 struct pt_packet_exstop {
719 /** A flag specifying the binding of the packet:
720 *
721 * set: binds to the next FUP.
722 * clear: standalone.
723 */
724 uint32_t ip:1;
725 };
726
727 /** A MWAIT packet. */
728 struct pt_packet_mwait {
729 /** The MWAIT hints (EAX). */
730 uint32_t hints;
731
732 /** The MWAIT extensions (ECX). */
733 uint32_t ext;
734 };
735
736 /** A PWRE packet. */
737 struct pt_packet_pwre {
738 /** The resolved thread C-state. */
739 uint8_t state;
740
741 /** The resolved thread sub C-state. */
742 uint8_t sub_state;
743
744 /** A flag indicating whether the C-state entry was initiated by h/w. */
745 uint32_t hw:1;
746 };
747
748 /** A PWRX packet. */
749 struct pt_packet_pwrx {
750 /** The core C-state at the time of the wake. */
751 uint8_t last;
752
753 /** The deepest core C-state achieved during sleep. */
754 uint8_t deepest;
755
756 /** The wake reason:
757 *
758 * - due to external interrupt received.
759 */
760 uint32_t interrupt:1;
761
762 /** - due to store to monitored address. */
763 uint32_t store:1;
764
765 /** - due to h/w autonomous condition such as HDC. */
766 uint32_t autonomous:1;
767 };
768
769 /** A PTW packet. */
770 struct pt_packet_ptw {
771 /** The raw payload. */
772 uint64_t payload;
773
774 /** The payload size as encoded in the packet. */
775 uint8_t plc;
776
777 /** A flag saying whether a FUP is following PTW that provides
778 * the IP of the corresponding PTWRITE instruction.
779 */
780 uint32_t ip:1;
781 };
782
pt_ptw_size(uint8_t plc)783 static inline int pt_ptw_size(uint8_t plc)
784 {
785 switch (plc) {
786 case 0:
787 return 4;
788
789 case 1:
790 return 8;
791
792 case 2:
793 case 3:
794 return -pte_bad_packet;
795 }
796
797 return -pte_internal;
798 }
799
800 /** An unknown packet decodable by the optional decoder callback. */
801 struct pt_packet_unknown {
802 /** Pointer to the raw packet bytes. */
803 const uint8_t *packet;
804
805 /** Optional pointer to a user-defined structure. */
806 void *priv;
807 };
808
809 /** An Intel PT packet. */
810 struct pt_packet {
811 /** The type of the packet.
812 *
813 * This also determines the \@payload field.
814 */
815 enum pt_packet_type type;
816
817 /** The size of the packet including opcode and payload. */
818 uint8_t size;
819
820 /** Packet specific data. */
821 union {
822 /** Packets: pad, ovf, psb, psbend, stop - no payload. */
823
824 /** Packet: tnt-8, tnt-64. */
825 struct pt_packet_tnt tnt;
826
827 /** Packet: tip, fup, tip.pge, tip.pgd. */
828 struct pt_packet_ip ip;
829
830 /** Packet: mode. */
831 struct pt_packet_mode mode;
832
833 /** Packet: pip. */
834 struct pt_packet_pip pip;
835
836 /** Packet: tsc. */
837 struct pt_packet_tsc tsc;
838
839 /** Packet: cbr. */
840 struct pt_packet_cbr cbr;
841
842 /** Packet: tma. */
843 struct pt_packet_tma tma;
844
845 /** Packet: mtc. */
846 struct pt_packet_mtc mtc;
847
848 /** Packet: cyc. */
849 struct pt_packet_cyc cyc;
850
851 /** Packet: vmcs. */
852 struct pt_packet_vmcs vmcs;
853
854 /** Packet: mnt. */
855 struct pt_packet_mnt mnt;
856
857 /** Packet: exstop. */
858 struct pt_packet_exstop exstop;
859
860 /** Packet: mwait. */
861 struct pt_packet_mwait mwait;
862
863 /** Packet: pwre. */
864 struct pt_packet_pwre pwre;
865
866 /** Packet: pwrx. */
867 struct pt_packet_pwrx pwrx;
868
869 /** Packet: ptw. */
870 struct pt_packet_ptw ptw;
871
872 /** Packet: unknown. */
873 struct pt_packet_unknown unknown;
874 } payload;
875 };
876
877
878
879 /* Packet encoder. */
880
881
882
883 /** Allocate an Intel PT packet encoder.
884 *
885 * The encoder will work on the buffer defined in \@config, it shall contain
886 * raw trace data and remain valid for the lifetime of the encoder.
887 *
888 * The encoder starts at the beginning of the trace buffer.
889 */
890 extern pt_export struct pt_encoder *
891 pt_alloc_encoder(const struct pt_config *config);
892
893 /** Free an Intel PT packet encoder.
894 *
895 * The \@encoder must not be used after a successful return.
896 */
897 extern pt_export void pt_free_encoder(struct pt_encoder *encoder);
898
899 /** Hard set synchronization point of an Intel PT packet encoder.
900 *
901 * Synchronize \@encoder to \@offset within the trace buffer.
902 *
903 * Returns zero on success, a negative error code otherwise.
904 *
905 * Returns -pte_eos if the given offset is behind the end of the trace buffer.
906 * Returns -pte_invalid if \@encoder is NULL.
907 */
908 extern pt_export int pt_enc_sync_set(struct pt_encoder *encoder,
909 uint64_t offset);
910
911 /** Get the current packet encoder position.
912 *
913 * Fills the current \@encoder position into \@offset.
914 *
915 * This is useful for reporting errors.
916 *
917 * Returns zero on success, a negative error code otherwise.
918 *
919 * Returns -pte_invalid if \@encoder or \@offset is NULL.
920 */
921 extern pt_export int pt_enc_get_offset(const struct pt_encoder *encoder,
922 uint64_t *offset);
923
924 /* Return a pointer to \@encoder's configuration.
925 *
926 * Returns a non-null pointer on success, NULL if \@encoder is NULL.
927 */
928 extern pt_export const struct pt_config *
929 pt_enc_get_config(const struct pt_encoder *encoder);
930
931 /** Encode an Intel PT packet.
932 *
933 * Writes \@packet at \@encoder's current position in the Intel PT buffer and
934 * advances the \@encoder beyond the written packet.
935 *
936 * The \@packet.size field is ignored.
937 *
938 * In case of errors, the \@encoder is not advanced and nothing is written
939 * into the Intel PT buffer.
940 *
941 * Returns the number of bytes written on success, a negative error code
942 * otherwise.
943 *
944 * Returns -pte_bad_opc if \@packet.type is not known.
945 * Returns -pte_bad_packet if \@packet's payload is invalid.
946 * Returns -pte_eos if \@encoder reached the end of the Intel PT buffer.
947 * Returns -pte_invalid if \@encoder or \@packet is NULL.
948 */
949 extern pt_export int pt_enc_next(struct pt_encoder *encoder,
950 const struct pt_packet *packet);
951
952
953
954 /* Packet decoder. */
955
956
957
958 /** Allocate an Intel PT packet decoder.
959 *
960 * The decoder will work on the buffer defined in \@config, it shall contain
961 * raw trace data and remain valid for the lifetime of the decoder.
962 *
963 * The decoder needs to be synchronized before it can be used.
964 */
965 extern pt_export struct pt_packet_decoder *
966 pt_pkt_alloc_decoder(const struct pt_config *config);
967
968 /** Free an Intel PT packet decoder.
969 *
970 * The \@decoder must not be used after a successful return.
971 */
972 extern pt_export void pt_pkt_free_decoder(struct pt_packet_decoder *decoder);
973
974 /** Synchronize an Intel PT packet decoder.
975 *
976 * Search for the next synchronization point in forward or backward direction.
977 *
978 * If \@decoder has not been synchronized, yet, the search is started at the
979 * beginning of the trace buffer in case of forward synchronization and at the
980 * end of the trace buffer in case of backward synchronization.
981 *
982 * Returns zero or a positive value on success, a negative error code otherwise.
983 *
984 * Returns -pte_eos if no further synchronization point is found.
985 * Returns -pte_invalid if \@decoder is NULL.
986 */
987 extern pt_export int pt_pkt_sync_forward(struct pt_packet_decoder *decoder);
988 extern pt_export int pt_pkt_sync_backward(struct pt_packet_decoder *decoder);
989
990 /** Hard set synchronization point of an Intel PT decoder.
991 *
992 * Synchronize \@decoder to \@offset within the trace buffer.
993 *
994 * Returns zero on success, a negative error code otherwise.
995 *
996 * Returns -pte_eos if the given offset is behind the end of the trace buffer.
997 * Returns -pte_invalid if \@decoder is NULL.
998 */
999 extern pt_export int pt_pkt_sync_set(struct pt_packet_decoder *decoder,
1000 uint64_t offset);
1001
1002 /** Get the current decoder position.
1003 *
1004 * Fills the current \@decoder position into \@offset.
1005 *
1006 * This is useful for reporting errors.
1007 *
1008 * Returns zero on success, a negative error code otherwise.
1009 *
1010 * Returns -pte_invalid if \@decoder or \@offset is NULL.
1011 * Returns -pte_nosync if \@decoder is out of sync.
1012 */
1013 extern pt_export int pt_pkt_get_offset(const struct pt_packet_decoder *decoder,
1014 uint64_t *offset);
1015
1016 /** Get the position of the last synchronization point.
1017 *
1018 * Fills the last synchronization position into \@offset.
1019 *
1020 * This is useful when splitting a trace stream for parallel decoding.
1021 *
1022 * Returns zero on success, a negative error code otherwise.
1023 *
1024 * Returns -pte_invalid if \@decoder or \@offset is NULL.
1025 * Returns -pte_nosync if \@decoder is out of sync.
1026 */
1027 extern pt_export int
1028 pt_pkt_get_sync_offset(const struct pt_packet_decoder *decoder,
1029 uint64_t *offset);
1030
1031 /* Return a pointer to \@decoder's configuration.
1032 *
1033 * Returns a non-null pointer on success, NULL if \@decoder is NULL.
1034 */
1035 extern pt_export const struct pt_config *
1036 pt_pkt_get_config(const struct pt_packet_decoder *decoder);
1037
1038 /** Decode the next packet and advance the decoder.
1039 *
1040 * Decodes the packet at \@decoder's current position into \@packet and
1041 * adjusts the \@decoder's position by the number of bytes the packet had
1042 * consumed.
1043 *
1044 * The \@size argument must be set to sizeof(struct pt_packet).
1045 *
1046 * Returns the number of bytes consumed on success, a negative error code
1047 * otherwise.
1048 *
1049 * Returns -pte_bad_opc if the packet is unknown.
1050 * Returns -pte_bad_packet if an unknown packet payload is encountered.
1051 * Returns -pte_eos if \@decoder reached the end of the Intel PT buffer.
1052 * Returns -pte_invalid if \@decoder or \@packet is NULL.
1053 * Returns -pte_nosync if \@decoder is out of sync.
1054 */
1055 extern pt_export int pt_pkt_next(struct pt_packet_decoder *decoder,
1056 struct pt_packet *packet, size_t size);
1057
1058
1059
1060 /* Query decoder. */
1061
1062
1063
1064 /** Decoder status flags. */
1065 enum pt_status_flag {
1066 /** There is an event pending. */
1067 pts_event_pending = 1 << 0,
1068
1069 /** The address has been suppressed. */
1070 pts_ip_suppressed = 1 << 1,
1071
1072 /** There is no more trace data available. */
1073 pts_eos = 1 << 2
1074 };
1075
1076 /** Event types. */
1077 enum pt_event_type {
1078 /* Tracing has been enabled/disabled. */
1079 ptev_enabled,
1080 ptev_disabled,
1081
1082 /* Tracing has been disabled asynchronously. */
1083 ptev_async_disabled,
1084
1085 /* An asynchronous branch, e.g. interrupt. */
1086 ptev_async_branch,
1087
1088 /* A synchronous paging event. */
1089 ptev_paging,
1090
1091 /* An asynchronous paging event. */
1092 ptev_async_paging,
1093
1094 /* Trace overflow. */
1095 ptev_overflow,
1096
1097 /* An execution mode change. */
1098 ptev_exec_mode,
1099
1100 /* A transactional execution state change. */
1101 ptev_tsx,
1102
1103 /* Trace Stop. */
1104 ptev_stop,
1105
1106 /* A synchronous vmcs event. */
1107 ptev_vmcs,
1108
1109 /* An asynchronous vmcs event. */
1110 ptev_async_vmcs,
1111
1112 /* Execution has stopped. */
1113 ptev_exstop,
1114
1115 /* An MWAIT operation completed. */
1116 ptev_mwait,
1117
1118 /* A power state was entered. */
1119 ptev_pwre,
1120
1121 /* A power state was exited. */
1122 ptev_pwrx,
1123
1124 /* A PTWRITE event. */
1125 ptev_ptwrite,
1126
1127 /* A timing event. */
1128 ptev_tick,
1129
1130 /* A core:bus ratio event. */
1131 ptev_cbr,
1132
1133 /* A maintenance event. */
1134 ptev_mnt
1135 };
1136
1137 /** An event. */
1138 struct pt_event {
1139 /** The type of the event. */
1140 enum pt_event_type type;
1141
1142 /** A flag indicating that the event IP has been suppressed. */
1143 uint32_t ip_suppressed:1;
1144
1145 /** A flag indicating that the event is for status update. */
1146 uint32_t status_update:1;
1147
1148 /** A flag indicating that the event has timing information. */
1149 uint32_t has_tsc:1;
1150
1151 /** The time stamp count of the event.
1152 *
1153 * This field is only valid if \@has_tsc is set.
1154 */
1155 uint64_t tsc;
1156
1157 /** The number of lost mtc and cyc packets.
1158 *
1159 * This gives an idea about the quality of the \@tsc. The more packets
1160 * were dropped, the less precise timing is.
1161 */
1162 uint32_t lost_mtc;
1163 uint32_t lost_cyc;
1164
1165 /* Reserved space for future extensions. */
1166 uint64_t reserved[2];
1167
1168 /** Event specific data. */
1169 union {
1170 /** Event: enabled. */
1171 struct {
1172 /** The address at which tracing resumes. */
1173 uint64_t ip;
1174
1175 /** A flag indicating that tracing resumes from the IP
1176 * at which tracing had been disabled before.
1177 */
1178 uint32_t resumed:1;
1179 } enabled;
1180
1181 /** Event: disabled. */
1182 struct {
1183 /** The destination of the first branch inside a
1184 * filtered area.
1185 *
1186 * This field is not valid if \@ip_suppressed is set.
1187 */
1188 uint64_t ip;
1189
1190 /* The exact source ip needs to be determined using
1191 * disassembly and the filter configuration.
1192 */
1193 } disabled;
1194
1195 /** Event: async disabled. */
1196 struct {
1197 /** The source address of the asynchronous branch that
1198 * disabled tracing.
1199 */
1200 uint64_t at;
1201
1202 /** The destination of the first branch inside a
1203 * filtered area.
1204 *
1205 * This field is not valid if \@ip_suppressed is set.
1206 */
1207 uint64_t ip;
1208 } async_disabled;
1209
1210 /** Event: async branch. */
1211 struct {
1212 /** The branch source address. */
1213 uint64_t from;
1214
1215 /** The branch destination address.
1216 *
1217 * This field is not valid if \@ip_suppressed is set.
1218 */
1219 uint64_t to;
1220 } async_branch;
1221
1222 /** Event: paging. */
1223 struct {
1224 /** The updated CR3 value.
1225 *
1226 * The lower 5 bit have been zeroed out.
1227 * The upper bits have been zeroed out depending on the
1228 * maximum possible address.
1229 */
1230 uint64_t cr3;
1231
1232 /** A flag indicating whether the cpu is operating in
1233 * vmx non-root (guest) mode.
1234 */
1235 uint32_t non_root:1;
1236
1237 /* The address at which the event is effective is
1238 * obvious from the disassembly.
1239 */
1240 } paging;
1241
1242 /** Event: async paging. */
1243 struct {
1244 /** The updated CR3 value.
1245 *
1246 * The lower 5 bit have been zeroed out.
1247 * The upper bits have been zeroed out depending on the
1248 * maximum possible address.
1249 */
1250 uint64_t cr3;
1251
1252 /** A flag indicating whether the cpu is operating in
1253 * vmx non-root (guest) mode.
1254 */
1255 uint32_t non_root:1;
1256
1257 /** The address at which the event is effective. */
1258 uint64_t ip;
1259 } async_paging;
1260
1261 /** Event: overflow. */
1262 struct {
1263 /** The address at which tracing resumes after overflow.
1264 *
1265 * This field is not valid, if ip_suppressed is set.
1266 * In this case, the overflow resolved while tracing
1267 * was disabled.
1268 */
1269 uint64_t ip;
1270 } overflow;
1271
1272 /** Event: exec mode. */
1273 struct {
1274 /** The execution mode. */
1275 enum pt_exec_mode mode;
1276
1277 /** The address at which the event is effective. */
1278 uint64_t ip;
1279 } exec_mode;
1280
1281 /** Event: tsx. */
1282 struct {
1283 /** The address at which the event is effective.
1284 *
1285 * This field is not valid if \@ip_suppressed is set.
1286 */
1287 uint64_t ip;
1288
1289 /** A flag indicating speculative execution mode. */
1290 uint32_t speculative:1;
1291
1292 /** A flag indicating speculative execution aborts. */
1293 uint32_t aborted:1;
1294 } tsx;
1295
1296 /** Event: vmcs. */
1297 struct {
1298 /** The VMCS base address.
1299 *
1300 * The address is zero-extended with the lower 12 bits
1301 * all zero.
1302 */
1303 uint64_t base;
1304
1305 /* The new VMCS base address should be stored and
1306 * applied on subsequent VM entries.
1307 */
1308 } vmcs;
1309
1310 /** Event: async vmcs. */
1311 struct {
1312 /** The VMCS base address.
1313 *
1314 * The address is zero-extended with the lower 12 bits
1315 * all zero.
1316 */
1317 uint64_t base;
1318
1319 /** The address at which the event is effective. */
1320 uint64_t ip;
1321
1322 /* An async paging event that binds to the same IP
1323 * will always succeed this async vmcs event.
1324 */
1325 } async_vmcs;
1326
1327 /** Event: execution stopped. */
1328 struct {
1329 /** The address at which execution has stopped. This is
1330 * the last instruction that did not complete.
1331 *
1332 * This field is not valid, if \@ip_suppressed is set.
1333 */
1334 uint64_t ip;
1335 } exstop;
1336
1337 /** Event: mwait. */
1338 struct {
1339 /** The address of the instruction causing the mwait.
1340 *
1341 * This field is not valid, if \@ip_suppressed is set.
1342 */
1343 uint64_t ip;
1344
1345 /** The mwait hints (eax).
1346 *
1347 * Reserved bits are undefined.
1348 */
1349 uint32_t hints;
1350
1351 /** The mwait extensions (ecx).
1352 *
1353 * Reserved bits are undefined.
1354 */
1355 uint32_t ext;
1356 } mwait;
1357
1358 /** Event: power state entry. */
1359 struct {
1360 /** The resolved thread C-state. */
1361 uint8_t state;
1362
1363 /** The resolved thread sub C-state. */
1364 uint8_t sub_state;
1365
1366 /** A flag indicating whether the C-state entry was
1367 * initiated by h/w.
1368 */
1369 uint32_t hw:1;
1370 } pwre;
1371
1372 /** Event: power state exit. */
1373 struct {
1374 /** The core C-state at the time of the wake. */
1375 uint8_t last;
1376
1377 /** The deepest core C-state achieved during sleep. */
1378 uint8_t deepest;
1379
1380 /** The wake reason:
1381 *
1382 * - due to external interrupt received.
1383 */
1384 uint32_t interrupt:1;
1385
1386 /** - due to store to monitored address. */
1387 uint32_t store:1;
1388
1389 /** - due to h/w autonomous condition such as HDC. */
1390 uint32_t autonomous:1;
1391 } pwrx;
1392
1393 /** Event: ptwrite. */
1394 struct {
1395 /** The address of the ptwrite instruction.
1396 *
1397 * This field is not valid, if \@ip_suppressed is set.
1398 *
1399 * In this case, the address is obvious from the
1400 * disassembly.
1401 */
1402 uint64_t ip;
1403
1404 /** The size of the below \@payload in bytes. */
1405 uint8_t size;
1406
1407 /** The ptwrite payload. */
1408 uint64_t payload;
1409 } ptwrite;
1410
1411 /** Event: tick. */
1412 struct {
1413 /** The instruction address near which the tick occured.
1414 *
1415 * A timestamp can sometimes be attributed directly to
1416 * an instruction (e.g. to an indirect branch that
1417 * receives CYC + TIP) and sometimes not (e.g. MTC).
1418 *
1419 * This field is not valid, if \@ip_suppressed is set.
1420 */
1421 uint64_t ip;
1422 } tick;
1423
1424 /** Event: cbr. */
1425 struct {
1426 /** The core:bus ratio. */
1427 uint16_t ratio;
1428 } cbr;
1429
1430 /** Event: mnt. */
1431 struct {
1432 /** The raw payload. */
1433 uint64_t payload;
1434 } mnt;
1435 } variant;
1436 };
1437
1438
1439 /** Allocate an Intel PT query decoder.
1440 *
1441 * The decoder will work on the buffer defined in \@config, it shall contain
1442 * raw trace data and remain valid for the lifetime of the decoder.
1443 *
1444 * The decoder needs to be synchronized before it can be used.
1445 */
1446 extern pt_export struct pt_query_decoder *
1447 pt_qry_alloc_decoder(const struct pt_config *config);
1448
1449 /** Free an Intel PT query decoder.
1450 *
1451 * The \@decoder must not be used after a successful return.
1452 */
1453 extern pt_export void pt_qry_free_decoder(struct pt_query_decoder *decoder);
1454
1455 /** Synchronize an Intel PT query decoder.
1456 *
1457 * Search for the next synchronization point in forward or backward direction.
1458 *
1459 * If \@decoder has not been synchronized, yet, the search is started at the
1460 * beginning of the trace buffer in case of forward synchronization and at the
1461 * end of the trace buffer in case of backward synchronization.
1462 *
1463 * If \@ip is not NULL, set it to last ip.
1464 *
1465 * Returns a non-negative pt_status_flag bit-vector on success, a negative error
1466 * code otherwise.
1467 *
1468 * Returns -pte_bad_opc if an unknown packet is encountered.
1469 * Returns -pte_bad_packet if an unknown packet payload is encountered.
1470 * Returns -pte_eos if no further synchronization point is found.
1471 * Returns -pte_invalid if \@decoder is NULL.
1472 */
1473 extern pt_export int pt_qry_sync_forward(struct pt_query_decoder *decoder,
1474 uint64_t *ip);
1475 extern pt_export int pt_qry_sync_backward(struct pt_query_decoder *decoder,
1476 uint64_t *ip);
1477
1478 /** Manually synchronize an Intel PT query decoder.
1479 *
1480 * Synchronize \@decoder on the syncpoint at \@offset. There must be a PSB
1481 * packet at \@offset.
1482 *
1483 * If \@ip is not NULL, set it to last ip.
1484 *
1485 * Returns a non-negative pt_status_flag bit-vector on success, a negative error
1486 * code otherwise.
1487 *
1488 * Returns -pte_bad_opc if an unknown packet is encountered.
1489 * Returns -pte_bad_packet if an unknown packet payload is encountered.
1490 * Returns -pte_eos if \@offset lies outside of \@decoder's trace buffer.
1491 * Returns -pte_eos if \@decoder reaches the end of its trace buffer.
1492 * Returns -pte_invalid if \@decoder is NULL.
1493 * Returns -pte_nosync if there is no syncpoint at \@offset.
1494 */
1495 extern pt_export int pt_qry_sync_set(struct pt_query_decoder *decoder,
1496 uint64_t *ip, uint64_t offset);
1497
1498 /** Get the current decoder position.
1499 *
1500 * Fills the current \@decoder position into \@offset.
1501 *
1502 * This is useful for reporting errors.
1503 *
1504 * Returns zero on success, a negative error code otherwise.
1505 *
1506 * Returns -pte_invalid if \@decoder or \@offset is NULL.
1507 * Returns -pte_nosync if \@decoder is out of sync.
1508 */
1509 extern pt_export int pt_qry_get_offset(const struct pt_query_decoder *decoder,
1510 uint64_t *offset);
1511
1512 /** Get the position of the last synchronization point.
1513 *
1514 * Fills the last synchronization position into \@offset.
1515 *
1516 * This is useful for splitting a trace stream for parallel decoding.
1517 *
1518 * Returns zero on success, a negative error code otherwise.
1519 *
1520 * Returns -pte_invalid if \@decoder or \@offset is NULL.
1521 * Returns -pte_nosync if \@decoder is out of sync.
1522 */
1523 extern pt_export int
1524 pt_qry_get_sync_offset(const struct pt_query_decoder *decoder,
1525 uint64_t *offset);
1526
1527 /* Return a pointer to \@decoder's configuration.
1528 *
1529 * Returns a non-null pointer on success, NULL if \@decoder is NULL.
1530 */
1531 extern pt_export const struct pt_config *
1532 pt_qry_get_config(const struct pt_query_decoder *decoder);
1533
1534 /** Query whether the next unconditional branch has been taken.
1535 *
1536 * On success, provides 1 (taken) or 0 (not taken) in \@taken for the next
1537 * conditional branch and updates \@decoder.
1538 *
1539 * Returns a non-negative pt_status_flag bit-vector on success, a negative error
1540 * code otherwise.
1541 *
1542 * Returns -pte_bad_opc if an unknown packet is encountered.
1543 * Returns -pte_bad_packet if an unknown packet payload is encountered.
1544 * Returns -pte_bad_query if no conditional branch is found.
1545 * Returns -pte_eos if decoding reached the end of the Intel PT buffer.
1546 * Returns -pte_invalid if \@decoder or \@taken is NULL.
1547 * Returns -pte_nosync if \@decoder is out of sync.
1548 */
1549 extern pt_export int pt_qry_cond_branch(struct pt_query_decoder *decoder,
1550 int *taken);
1551
1552 /** Get the next indirect branch destination.
1553 *
1554 * On success, provides the linear destination address of the next indirect
1555 * branch in \@ip and updates \@decoder.
1556 *
1557 * Returns a non-negative pt_status_flag bit-vector on success, a negative error
1558 * code otherwise.
1559 *
1560 * Returns -pte_bad_opc if an unknown packet is encountered.
1561 * Returns -pte_bad_packet if an unknown packet payload is encountered.
1562 * Returns -pte_bad_query if no indirect branch is found.
1563 * Returns -pte_eos if decoding reached the end of the Intel PT buffer.
1564 * Returns -pte_invalid if \@decoder or \@ip is NULL.
1565 * Returns -pte_nosync if \@decoder is out of sync.
1566 */
1567 extern pt_export int pt_qry_indirect_branch(struct pt_query_decoder *decoder,
1568 uint64_t *ip);
1569
1570 /** Query the next pending event.
1571 *
1572 * On success, provides the next event \@event and updates \@decoder.
1573 *
1574 * The \@size argument must be set to sizeof(struct pt_event).
1575 *
1576 * Returns a non-negative pt_status_flag bit-vector on success, a negative error
1577 * code otherwise.
1578 *
1579 * Returns -pte_bad_opc if an unknown packet is encountered.
1580 * Returns -pte_bad_packet if an unknown packet payload is encountered.
1581 * Returns -pte_bad_query if no event is found.
1582 * Returns -pte_eos if decoding reached the end of the Intel PT buffer.
1583 * Returns -pte_invalid if \@decoder or \@event is NULL.
1584 * Returns -pte_invalid if \@size is too small.
1585 * Returns -pte_nosync if \@decoder is out of sync.
1586 */
1587 extern pt_export int pt_qry_event(struct pt_query_decoder *decoder,
1588 struct pt_event *event, size_t size);
1589
1590 /** Query the current time.
1591 *
1592 * On success, provides the time at the last query in \@time.
1593 *
1594 * The time is similar to what a rdtsc instruction would return. Depending
1595 * on the configuration, the time may not be fully accurate. If TSC is not
1596 * enabled, the time is relative to the last synchronization and can't be used
1597 * to correlate with other TSC-based time sources. In this case, -pte_no_time
1598 * is returned and the relative time is provided in \@time.
1599 *
1600 * Some timing-related packets may need to be dropped (mostly due to missing
1601 * calibration or incomplete configuration). To get an idea about the quality
1602 * of the estimated time, we record the number of dropped MTC and CYC packets.
1603 *
1604 * If \@lost_mtc is not NULL, set it to the number of lost MTC packets.
1605 * If \@lost_cyc is not NULL, set it to the number of lost CYC packets.
1606 *
1607 * Returns zero on success, a negative error code otherwise.
1608 *
1609 * Returns -pte_invalid if \@decoder or \@time is NULL.
1610 * Returns -pte_no_time if there has not been a TSC packet.
1611 */
1612 extern pt_export int pt_qry_time(struct pt_query_decoder *decoder,
1613 uint64_t *time, uint32_t *lost_mtc,
1614 uint32_t *lost_cyc);
1615
1616 /** Return the current core bus ratio.
1617 *
1618 * On success, provides the current core:bus ratio in \@cbr. The ratio is
1619 * defined as core cycles per bus clock cycle.
1620 *
1621 * Returns zero on success, a negative error code otherwise.
1622 *
1623 * Returns -pte_invalid if \@decoder or \@cbr is NULL.
1624 * Returns -pte_no_cbr if there has not been a CBR packet.
1625 */
1626 extern pt_export int pt_qry_core_bus_ratio(struct pt_query_decoder *decoder,
1627 uint32_t *cbr);
1628
1629
1630
1631 /* Traced image. */
1632
1633
1634
1635 /** An Intel PT address space identifier.
1636 *
1637 * This identifies a particular address space when adding file sections or
1638 * when reading memory.
1639 */
1640 struct pt_asid {
1641 /** The size of this object - set to sizeof(struct pt_asid). */
1642 size_t size;
1643
1644 /** The CR3 value. */
1645 uint64_t cr3;
1646
1647 /** The VMCS Base address. */
1648 uint64_t vmcs;
1649 };
1650
1651 /** An unknown CR3 value to be used for pt_asid objects. */
1652 static const uint64_t pt_asid_no_cr3 = 0xffffffffffffffffull;
1653
1654 /** An unknown VMCS Base value to be used for pt_asid objects. */
1655 static const uint64_t pt_asid_no_vmcs = 0xffffffffffffffffull;
1656
1657 /** Initialize an address space identifier. */
pt_asid_init(struct pt_asid * asid)1658 static inline void pt_asid_init(struct pt_asid *asid)
1659 {
1660 asid->size = sizeof(*asid);
1661 asid->cr3 = pt_asid_no_cr3;
1662 asid->vmcs = pt_asid_no_vmcs;
1663 }
1664
1665
1666 /** A cache of traced image sections. */
1667 struct pt_image_section_cache;
1668
1669 /** Allocate a traced memory image section cache.
1670 *
1671 * An optional \@name may be given to the cache. The name string is copied.
1672 *
1673 * Returns a new traced memory image section cache on success, NULL otherwise.
1674 */
1675 extern pt_export struct pt_image_section_cache *
1676 pt_iscache_alloc(const char *name);
1677
1678 /** Free a traced memory image section cache.
1679 *
1680 * The \@iscache must have been allocated with pt_iscache_alloc().
1681 * The \@iscache must not be used after a successful return.
1682 */
1683 extern pt_export void pt_iscache_free(struct pt_image_section_cache *iscache);
1684
1685 /** Set the image section cache limit.
1686 *
1687 * Set the limit for a section cache in bytes. A non-zero limit will keep the
1688 * least recently used sections mapped until the limit is reached. A limit of
1689 * zero disables caching.
1690 *
1691 * Returns zero on success, a negative pt_error_code otherwise.
1692 * Returns -pte_invalid if \@iscache is NULL.
1693 */
1694 extern pt_export int
1695 pt_iscache_set_limit(struct pt_image_section_cache *iscache, uint64_t limit);
1696
1697 /** Get the image section cache name.
1698 *
1699 * Returns a pointer to \@iscache's name or NULL if there is no name.
1700 */
1701 extern pt_export const char *
1702 pt_iscache_name(const struct pt_image_section_cache *iscache);
1703
1704 /** Add a new file section to the traced memory image section cache.
1705 *
1706 * Adds a new section consisting of \@size bytes starting at \@offset in
1707 * \@filename loaded at the virtual address \@vaddr if \@iscache does not
1708 * already contain such a section.
1709 *
1710 * Returns an image section identifier (isid) uniquely identifying that section
1711 * in \@iscache.
1712 *
1713 * The section is silently truncated to match the size of \@filename.
1714 *
1715 * Returns a positive isid on success, a negative error code otherwise.
1716 *
1717 * Returns -pte_invalid if \@iscache or \@filename is NULL.
1718 * Returns -pte_invalid if \@offset is too big.
1719 */
1720 extern pt_export int pt_iscache_add_file(struct pt_image_section_cache *iscache,
1721 const char *filename, uint64_t offset,
1722 uint64_t size, uint64_t vaddr);
1723
1724 /** Read memory from a cached file section
1725 *
1726 * Reads \@size bytes of memory starting at virtual address \@vaddr in the
1727 * section identified by \@isid in \@iscache into \@buffer.
1728 *
1729 * The caller is responsible for allocating a \@buffer of at least \@size bytes.
1730 *
1731 * The read request may be truncated if it crosses section boundaries or if
1732 * \@size is getting too big. We support reading at least 4Kbyte in one chunk
1733 * unless the read would cross a section boundary.
1734 *
1735 * Returns the number of bytes read on success, a negative error code otherwise.
1736 *
1737 * Returns -pte_invalid if \@iscache or \@buffer is NULL.
1738 * Returns -pte_invalid if \@size is zero.
1739 * Returns -pte_nomap if \@vaddr is not contained in section \@isid.
1740 * Returns -pte_bad_image if \@iscache does not contain \@isid.
1741 */
1742 extern pt_export int pt_iscache_read(struct pt_image_section_cache *iscache,
1743 uint8_t *buffer, uint64_t size, int isid,
1744 uint64_t vaddr);
1745
1746 /** The traced memory image. */
1747 struct pt_image;
1748
1749
1750 /** Allocate a traced memory image.
1751 *
1752 * An optional \@name may be given to the image. The name string is copied.
1753 *
1754 * Returns a new traced memory image on success, NULL otherwise.
1755 */
1756 extern pt_export struct pt_image *pt_image_alloc(const char *name);
1757
1758 /** Free a traced memory image.
1759 *
1760 * The \@image must have been allocated with pt_image_alloc().
1761 * The \@image must not be used after a successful return.
1762 */
1763 extern pt_export void pt_image_free(struct pt_image *image);
1764
1765 /** Get the image name.
1766 *
1767 * Returns a pointer to \@image's name or NULL if there is no name.
1768 */
1769 extern pt_export const char *pt_image_name(const struct pt_image *image);
1770
1771 /** Add a new file section to the traced memory image.
1772 *
1773 * Adds \@size bytes starting at \@offset in \@filename. The section is
1774 * loaded at the virtual address \@vaddr in the address space \@asid.
1775 *
1776 * The \@asid may be NULL or (partially) invalid. In that case only the valid
1777 * fields are considered when comparing with other address-spaces. Use this
1778 * when tracing a single process or when adding sections to all processes.
1779 *
1780 * The section is silently truncated to match the size of \@filename.
1781 *
1782 * Existing sections that would overlap with the new section will be shrunk
1783 * or split.
1784 *
1785 * Returns zero on success, a negative error code otherwise.
1786 *
1787 * Returns -pte_invalid if \@image or \@filename is NULL.
1788 * Returns -pte_invalid if \@offset is too big.
1789 */
1790 extern pt_export int pt_image_add_file(struct pt_image *image,
1791 const char *filename, uint64_t offset,
1792 uint64_t size,
1793 const struct pt_asid *asid,
1794 uint64_t vaddr);
1795
1796 /** Add a section from an image section cache.
1797 *
1798 * Add the section from \@iscache identified by \@isid in address space \@asid.
1799 *
1800 * Existing sections that would overlap with the new section will be shrunk
1801 * or split.
1802 *
1803 * Returns zero on success, a negative error code otherwise.
1804 * Returns -pte_invalid if \@image or \@iscache is NULL.
1805 * Returns -pte_bad_image if \@iscache does not contain \@isid.
1806 */
1807 extern pt_export int pt_image_add_cached(struct pt_image *image,
1808 struct pt_image_section_cache *iscache,
1809 int isid, const struct pt_asid *asid);
1810
1811 /** Copy an image.
1812 *
1813 * Adds all sections from \@src to \@image. Sections that could not be added
1814 * will be ignored.
1815 *
1816 * Returns the number of ignored sections on success, a negative error code
1817 * otherwise.
1818 *
1819 * Returns -pte_invalid if \@image or \@src is NULL.
1820 */
1821 extern pt_export int pt_image_copy(struct pt_image *image,
1822 const struct pt_image *src);
1823
1824 /** Remove all sections loaded from a file.
1825 *
1826 * Removes all sections loaded from \@filename from the address space \@asid.
1827 * Specify the same \@asid that was used for adding sections from \@filename.
1828 *
1829 * Returns the number of removed sections on success, a negative error code
1830 * otherwise.
1831 *
1832 * Returns -pte_invalid if \@image or \@filename is NULL.
1833 */
1834 extern pt_export int pt_image_remove_by_filename(struct pt_image *image,
1835 const char *filename,
1836 const struct pt_asid *asid);
1837
1838 /** Remove all sections loaded into an address space.
1839 *
1840 * Removes all sections loaded into \@asid. Specify the same \@asid that was
1841 * used for adding sections.
1842 *
1843 * Returns the number of removed sections on success, a negative error code
1844 * otherwise.
1845 *
1846 * Returns -pte_invalid if \@image is NULL.
1847 */
1848 extern pt_export int pt_image_remove_by_asid(struct pt_image *image,
1849 const struct pt_asid *asid);
1850
1851 /** A read memory callback function.
1852 *
1853 * It shall read \@size bytes of memory from address space \@asid starting
1854 * at \@ip into \@buffer.
1855 *
1856 * It shall return the number of bytes read on success.
1857 * It shall return a negative pt_error_code otherwise.
1858 */
1859 typedef int (read_memory_callback_t)(uint8_t *buffer, size_t size,
1860 const struct pt_asid *asid,
1861 uint64_t ip, void *context);
1862
1863 /** Set the memory callback for the traced memory image.
1864 *
1865 * Sets \@callback for reading memory. The callback is used for addresses
1866 * that are not found in file sections. The \@context argument is passed
1867 * to \@callback on each use.
1868 *
1869 * There can only be one callback at any time. A subsequent call will replace
1870 * the previous callback. If \@callback is NULL, the callback is removed.
1871 *
1872 * Returns -pte_invalid if \@image is NULL.
1873 */
1874 extern pt_export int pt_image_set_callback(struct pt_image *image,
1875 read_memory_callback_t *callback,
1876 void *context);
1877
1878
1879
1880 /* Instruction flow decoder. */
1881
1882
1883
1884 /** The instruction class.
1885 *
1886 * We provide only a very coarse classification suitable for reconstructing
1887 * the execution flow.
1888 */
1889 enum pt_insn_class {
1890 /* The instruction could not be classified. */
1891 ptic_error,
1892
1893 /* The instruction is something not listed below. */
1894 ptic_other,
1895
1896 /* The instruction is a near (function) call. */
1897 ptic_call,
1898
1899 /* The instruction is a near (function) return. */
1900 ptic_return,
1901
1902 /* The instruction is a near unconditional jump. */
1903 ptic_jump,
1904
1905 /* The instruction is a near conditional jump. */
1906 ptic_cond_jump,
1907
1908 /* The instruction is a call-like far transfer.
1909 * E.g. SYSCALL, SYSENTER, or FAR CALL.
1910 */
1911 ptic_far_call,
1912
1913 /* The instruction is a return-like far transfer.
1914 * E.g. SYSRET, SYSEXIT, IRET, or FAR RET.
1915 */
1916 ptic_far_return,
1917
1918 /* The instruction is a jump-like far transfer.
1919 * E.g. FAR JMP.
1920 */
1921 ptic_far_jump,
1922
1923 /* The instruction is a PTWRITE. */
1924 ptic_ptwrite
1925 };
1926
1927 /** The maximal size of an instruction. */
1928 enum {
1929 pt_max_insn_size = 15
1930 };
1931
1932 /** A single traced instruction. */
1933 struct pt_insn {
1934 /** The virtual address in its process. */
1935 uint64_t ip;
1936
1937 /** The image section identifier for the section containing this
1938 * instruction.
1939 *
1940 * A value of zero means that the section did not have an identifier.
1941 * The section was not added via an image section cache or the memory
1942 * was read via the read memory callback.
1943 */
1944 int isid;
1945
1946 /** The execution mode. */
1947 enum pt_exec_mode mode;
1948
1949 /** A coarse classification. */
1950 enum pt_insn_class iclass;
1951
1952 /** The raw bytes. */
1953 uint8_t raw[pt_max_insn_size];
1954
1955 /** The size in bytes. */
1956 uint8_t size;
1957
1958 /** A collection of flags giving additional information:
1959 *
1960 * - the instruction was executed speculatively.
1961 */
1962 uint32_t speculative:1;
1963
1964 /** - this instruction is truncated in its image section.
1965 *
1966 * It starts in the image section identified by \@isid and continues
1967 * in one or more other sections.
1968 */
1969 uint32_t truncated:1;
1970 };
1971
1972
1973 /** Allocate an Intel PT instruction flow decoder.
1974 *
1975 * The decoder will work on the buffer defined in \@config, it shall contain
1976 * raw trace data and remain valid for the lifetime of the decoder.
1977 *
1978 * The decoder needs to be synchronized before it can be used.
1979 */
1980 extern pt_export struct pt_insn_decoder *
1981 pt_insn_alloc_decoder(const struct pt_config *config);
1982
1983 /** Free an Intel PT instruction flow decoder.
1984 *
1985 * This will destroy the decoder's default image.
1986 *
1987 * The \@decoder must not be used after a successful return.
1988 */
1989 extern pt_export void pt_insn_free_decoder(struct pt_insn_decoder *decoder);
1990
1991 /** Synchronize an Intel PT instruction flow decoder.
1992 *
1993 * Search for the next synchronization point in forward or backward direction.
1994 *
1995 * If \@decoder has not been synchronized, yet, the search is started at the
1996 * beginning of the trace buffer in case of forward synchronization and at the
1997 * end of the trace buffer in case of backward synchronization.
1998 *
1999 * Returns zero or a positive value on success, a negative error code otherwise.
2000 *
2001 * Returns -pte_bad_opc if an unknown packet is encountered.
2002 * Returns -pte_bad_packet if an unknown packet payload is encountered.
2003 * Returns -pte_eos if no further synchronization point is found.
2004 * Returns -pte_invalid if \@decoder is NULL.
2005 */
2006 extern pt_export int pt_insn_sync_forward(struct pt_insn_decoder *decoder);
2007 extern pt_export int pt_insn_sync_backward(struct pt_insn_decoder *decoder);
2008
2009 /** Manually synchronize an Intel PT instruction flow decoder.
2010 *
2011 * Synchronize \@decoder on the syncpoint at \@offset. There must be a PSB
2012 * packet at \@offset.
2013 *
2014 * Returns zero or a positive value on success, a negative error code otherwise.
2015 *
2016 * Returns -pte_bad_opc if an unknown packet is encountered.
2017 * Returns -pte_bad_packet if an unknown packet payload is encountered.
2018 * Returns -pte_eos if \@offset lies outside of \@decoder's trace buffer.
2019 * Returns -pte_eos if \@decoder reaches the end of its trace buffer.
2020 * Returns -pte_invalid if \@decoder is NULL.
2021 * Returns -pte_nosync if there is no syncpoint at \@offset.
2022 */
2023 extern pt_export int pt_insn_sync_set(struct pt_insn_decoder *decoder,
2024 uint64_t offset);
2025
2026 /** Get the current decoder position.
2027 *
2028 * Fills the current \@decoder position into \@offset.
2029 *
2030 * This is useful for reporting errors.
2031 *
2032 * Returns zero on success, a negative error code otherwise.
2033 *
2034 * Returns -pte_invalid if \@decoder or \@offset is NULL.
2035 * Returns -pte_nosync if \@decoder is out of sync.
2036 */
2037 extern pt_export int pt_insn_get_offset(const struct pt_insn_decoder *decoder,
2038 uint64_t *offset);
2039
2040 /** Get the position of the last synchronization point.
2041 *
2042 * Fills the last synchronization position into \@offset.
2043 *
2044 * Returns zero on success, a negative error code otherwise.
2045 *
2046 * Returns -pte_invalid if \@decoder or \@offset is NULL.
2047 * Returns -pte_nosync if \@decoder is out of sync.
2048 */
2049 extern pt_export int
2050 pt_insn_get_sync_offset(const struct pt_insn_decoder *decoder,
2051 uint64_t *offset);
2052
2053 /** Get the traced image.
2054 *
2055 * The returned image may be modified as long as no decoder that uses this
2056 * image is running.
2057 *
2058 * Returns a pointer to the traced image the decoder uses for reading memory.
2059 * Returns NULL if \@decoder is NULL.
2060 */
2061 extern pt_export struct pt_image *
2062 pt_insn_get_image(struct pt_insn_decoder *decoder);
2063
2064 /** Set the traced image.
2065 *
2066 * Sets the image that \@decoder uses for reading memory to \@image. If \@image
2067 * is NULL, sets the image to \@decoder's default image.
2068 *
2069 * Only one image can be active at any time.
2070 *
2071 * Returns zero on success, a negative error code otherwise.
2072 * Return -pte_invalid if \@decoder is NULL.
2073 */
2074 extern pt_export int pt_insn_set_image(struct pt_insn_decoder *decoder,
2075 struct pt_image *image);
2076
2077 /* Return a pointer to \@decoder's configuration.
2078 *
2079 * Returns a non-null pointer on success, NULL if \@decoder is NULL.
2080 */
2081 extern pt_export const struct pt_config *
2082 pt_insn_get_config(const struct pt_insn_decoder *decoder);
2083
2084 /** Return the current time.
2085 *
2086 * On success, provides the time at the last preceding timing packet in \@time.
2087 *
2088 * The time is similar to what a rdtsc instruction would return. Depending
2089 * on the configuration, the time may not be fully accurate. If TSC is not
2090 * enabled, the time is relative to the last synchronization and can't be used
2091 * to correlate with other TSC-based time sources. In this case, -pte_no_time
2092 * is returned and the relative time is provided in \@time.
2093 *
2094 * Some timing-related packets may need to be dropped (mostly due to missing
2095 * calibration or incomplete configuration). To get an idea about the quality
2096 * of the estimated time, we record the number of dropped MTC and CYC packets.
2097 *
2098 * If \@lost_mtc is not NULL, set it to the number of lost MTC packets.
2099 * If \@lost_cyc is not NULL, set it to the number of lost CYC packets.
2100 *
2101 * Returns zero on success, a negative error code otherwise.
2102 *
2103 * Returns -pte_invalid if \@decoder or \@time is NULL.
2104 * Returns -pte_no_time if there has not been a TSC packet.
2105 */
2106 extern pt_export int pt_insn_time(struct pt_insn_decoder *decoder,
2107 uint64_t *time, uint32_t *lost_mtc,
2108 uint32_t *lost_cyc);
2109
2110 /** Return the current core bus ratio.
2111 *
2112 * On success, provides the current core:bus ratio in \@cbr. The ratio is
2113 * defined as core cycles per bus clock cycle.
2114 *
2115 * Returns zero on success, a negative error code otherwise.
2116 *
2117 * Returns -pte_invalid if \@decoder or \@cbr is NULL.
2118 * Returns -pte_no_cbr if there has not been a CBR packet.
2119 */
2120 extern pt_export int pt_insn_core_bus_ratio(struct pt_insn_decoder *decoder,
2121 uint32_t *cbr);
2122
2123 /** Return the current address space identifier.
2124 *
2125 * On success, provides the current address space identifier in \@asid.
2126 *
2127 * The \@size argument must be set to sizeof(struct pt_asid). At most \@size
2128 * bytes will be copied and \@asid->size will be set to the actual size of the
2129 * provided address space identifier.
2130 *
2131 * Returns zero on success, a negative error code otherwise.
2132 *
2133 * Returns -pte_invalid if \@decoder or \@asid is NULL.
2134 */
2135 extern pt_export int pt_insn_asid(const struct pt_insn_decoder *decoder,
2136 struct pt_asid *asid, size_t size);
2137
2138 /** Determine the next instruction.
2139 *
2140 * On success, provides the next instruction in execution order in \@insn.
2141 *
2142 * The \@size argument must be set to sizeof(struct pt_insn).
2143 *
2144 * Returns a non-negative pt_status_flag bit-vector on success, a negative error
2145 * code otherwise.
2146 *
2147 * Returns pts_eos to indicate the end of the trace stream. Subsequent calls
2148 * to pt_insn_next() will continue to return pts_eos until trace is required
2149 * to determine the next instruction.
2150 *
2151 * Returns -pte_bad_context if the decoder encountered an unexpected packet.
2152 * Returns -pte_bad_opc if the decoder encountered unknown packets.
2153 * Returns -pte_bad_packet if the decoder encountered unknown packet payloads.
2154 * Returns -pte_bad_query if the decoder got out of sync.
2155 * Returns -pte_eos if decoding reached the end of the Intel PT buffer.
2156 * Returns -pte_invalid if \@decoder or \@insn is NULL.
2157 * Returns -pte_nomap if the memory at the instruction address can't be read.
2158 * Returns -pte_nosync if \@decoder is out of sync.
2159 */
2160 extern pt_export int pt_insn_next(struct pt_insn_decoder *decoder,
2161 struct pt_insn *insn, size_t size);
2162
2163 /** Get the next pending event.
2164 *
2165 * On success, provides the next event in \@event and updates \@decoder.
2166 *
2167 * The \@size argument must be set to sizeof(struct pt_event).
2168 *
2169 * Returns a non-negative pt_status_flag bit-vector on success, a negative error
2170 * code otherwise.
2171 *
2172 * Returns -pte_bad_query if there is no event.
2173 * Returns -pte_invalid if \@decoder or \@event is NULL.
2174 * Returns -pte_invalid if \@size is too small.
2175 */
2176 extern pt_export int pt_insn_event(struct pt_insn_decoder *decoder,
2177 struct pt_event *event, size_t size);
2178
2179
2180
2181 /* Block decoder. */
2182
2183
2184
2185 /** A block of instructions.
2186 *
2187 * Instructions in this block are executed sequentially but are not necessarily
2188 * contiguous in memory. Users are expected to follow direct branches.
2189 */
2190 struct pt_block {
2191 /** The IP of the first instruction in this block. */
2192 uint64_t ip;
2193
2194 /** The IP of the last instruction in this block.
2195 *
2196 * This can be used for error-detection.
2197 */
2198 uint64_t end_ip;
2199
2200 /** The image section that contains the instructions in this block.
2201 *
2202 * A value of zero means that the section did not have an identifier.
2203 * The section was not added via an image section cache or the memory
2204 * was read via the read memory callback.
2205 */
2206 int isid;
2207
2208 /** The execution mode for all instructions in this block. */
2209 enum pt_exec_mode mode;
2210
2211 /** The instruction class for the last instruction in this block.
2212 *
2213 * This field may be set to ptic_error to indicate that the instruction
2214 * class is not available. The block decoder may choose to not provide
2215 * the instruction class in some cases for performance reasons.
2216 */
2217 enum pt_insn_class iclass;
2218
2219 /** The number of instructions in this block. */
2220 uint16_t ninsn;
2221
2222 /** The raw bytes of the last instruction in this block in case the
2223 * instruction does not fit entirely into this block's section.
2224 *
2225 * This field is only valid if \@truncated is set.
2226 */
2227 uint8_t raw[pt_max_insn_size];
2228
2229 /** The size of the last instruction in this block in bytes.
2230 *
2231 * This field is only valid if \@truncated is set.
2232 */
2233 uint8_t size;
2234
2235 /** A collection of flags giving additional information about the
2236 * instructions in this block.
2237 *
2238 * - all instructions in this block were executed speculatively.
2239 */
2240 uint32_t speculative:1;
2241
2242 /** - the last instruction in this block is truncated.
2243 *
2244 * It starts in this block's section but continues in one or more
2245 * other sections depending on how fragmented the memory image is.
2246 *
2247 * The raw bytes for the last instruction are provided in \@raw and
2248 * its size in \@size in this case.
2249 */
2250 uint32_t truncated:1;
2251 };
2252
2253 /** Allocate an Intel PT block decoder.
2254 *
2255 * The decoder will work on the buffer defined in \@config, it shall contain
2256 * raw trace data and remain valid for the lifetime of the decoder.
2257 *
2258 * The decoder needs to be synchronized before it can be used.
2259 */
2260 extern pt_export struct pt_block_decoder *
2261 pt_blk_alloc_decoder(const struct pt_config *config);
2262
2263 /** Free an Intel PT block decoder.
2264 *
2265 * This will destroy the decoder's default image.
2266 *
2267 * The \@decoder must not be used after a successful return.
2268 */
2269 extern pt_export void pt_blk_free_decoder(struct pt_block_decoder *decoder);
2270
2271 /** Synchronize an Intel PT block decoder.
2272 *
2273 * Search for the next synchronization point in forward or backward direction.
2274 *
2275 * If \@decoder has not been synchronized, yet, the search is started at the
2276 * beginning of the trace buffer in case of forward synchronization and at the
2277 * end of the trace buffer in case of backward synchronization.
2278 *
2279 * Returns zero or a positive value on success, a negative error code otherwise.
2280 *
2281 * Returns -pte_bad_opc if an unknown packet is encountered.
2282 * Returns -pte_bad_packet if an unknown packet payload is encountered.
2283 * Returns -pte_eos if no further synchronization point is found.
2284 * Returns -pte_invalid if \@decoder is NULL.
2285 */
2286 extern pt_export int pt_blk_sync_forward(struct pt_block_decoder *decoder);
2287 extern pt_export int pt_blk_sync_backward(struct pt_block_decoder *decoder);
2288
2289 /** Manually synchronize an Intel PT block decoder.
2290 *
2291 * Synchronize \@decoder on the syncpoint at \@offset. There must be a PSB
2292 * packet at \@offset.
2293 *
2294 * Returns zero or a positive value on success, a negative error code otherwise.
2295 *
2296 * Returns -pte_bad_opc if an unknown packet is encountered.
2297 * Returns -pte_bad_packet if an unknown packet payload is encountered.
2298 * Returns -pte_eos if \@offset lies outside of \@decoder's trace buffer.
2299 * Returns -pte_eos if \@decoder reaches the end of its trace buffer.
2300 * Returns -pte_invalid if \@decoder is NULL.
2301 * Returns -pte_nosync if there is no syncpoint at \@offset.
2302 */
2303 extern pt_export int pt_blk_sync_set(struct pt_block_decoder *decoder,
2304 uint64_t offset);
2305
2306 /** Get the current decoder position.
2307 *
2308 * Fills the current \@decoder position into \@offset.
2309 *
2310 * This is useful for reporting errors.
2311 *
2312 * Returns zero on success, a negative error code otherwise.
2313 *
2314 * Returns -pte_invalid if \@decoder or \@offset is NULL.
2315 * Returns -pte_nosync if \@decoder is out of sync.
2316 */
2317 extern pt_export int pt_blk_get_offset(const struct pt_block_decoder *decoder,
2318 uint64_t *offset);
2319
2320 /** Get the position of the last synchronization point.
2321 *
2322 * Fills the last synchronization position into \@offset.
2323 *
2324 * Returns zero on success, a negative error code otherwise.
2325 *
2326 * Returns -pte_invalid if \@decoder or \@offset is NULL.
2327 * Returns -pte_nosync if \@decoder is out of sync.
2328 */
2329 extern pt_export int
2330 pt_blk_get_sync_offset(const struct pt_block_decoder *decoder,
2331 uint64_t *offset);
2332
2333 /** Get the traced image.
2334 *
2335 * The returned image may be modified as long as \@decoder is not running.
2336 *
2337 * Returns a pointer to the traced image \@decoder uses for reading memory.
2338 * Returns NULL if \@decoder is NULL.
2339 */
2340 extern pt_export struct pt_image *
2341 pt_blk_get_image(struct pt_block_decoder *decoder);
2342
2343 /** Set the traced image.
2344 *
2345 * Sets the image that \@decoder uses for reading memory to \@image. If \@image
2346 * is NULL, sets the image to \@decoder's default image.
2347 *
2348 * Only one image can be active at any time.
2349 *
2350 * Returns zero on success, a negative error code otherwise.
2351 * Return -pte_invalid if \@decoder is NULL.
2352 */
2353 extern pt_export int pt_blk_set_image(struct pt_block_decoder *decoder,
2354 struct pt_image *image);
2355
2356 /* Return a pointer to \@decoder's configuration.
2357 *
2358 * Returns a non-null pointer on success, NULL if \@decoder is NULL.
2359 */
2360 extern pt_export const struct pt_config *
2361 pt_blk_get_config(const struct pt_block_decoder *decoder);
2362
2363 /** Return the current time.
2364 *
2365 * On success, provides the time at the last preceding timing packet in \@time.
2366 *
2367 * The time is similar to what a rdtsc instruction would return. Depending
2368 * on the configuration, the time may not be fully accurate. If TSC is not
2369 * enabled, the time is relative to the last synchronization and can't be used
2370 * to correlate with other TSC-based time sources. In this case, -pte_no_time
2371 * is returned and the relative time is provided in \@time.
2372 *
2373 * Some timing-related packets may need to be dropped (mostly due to missing
2374 * calibration or incomplete configuration). To get an idea about the quality
2375 * of the estimated time, we record the number of dropped MTC and CYC packets.
2376 *
2377 * If \@lost_mtc is not NULL, set it to the number of lost MTC packets.
2378 * If \@lost_cyc is not NULL, set it to the number of lost CYC packets.
2379 *
2380 * Returns zero on success, a negative error code otherwise.
2381 *
2382 * Returns -pte_invalid if \@decoder or \@time is NULL.
2383 * Returns -pte_no_time if there has not been a TSC packet.
2384 */
2385 extern pt_export int pt_blk_time(struct pt_block_decoder *decoder,
2386 uint64_t *time, uint32_t *lost_mtc,
2387 uint32_t *lost_cyc);
2388
2389 /** Return the current core bus ratio.
2390 *
2391 * On success, provides the current core:bus ratio in \@cbr. The ratio is
2392 * defined as core cycles per bus clock cycle.
2393 *
2394 * Returns zero on success, a negative error code otherwise.
2395 *
2396 * Returns -pte_invalid if \@decoder or \@cbr is NULL.
2397 * Returns -pte_no_cbr if there has not been a CBR packet.
2398 */
2399 extern pt_export int pt_blk_core_bus_ratio(struct pt_block_decoder *decoder,
2400 uint32_t *cbr);
2401
2402 /** Return the current address space identifier.
2403 *
2404 * On success, provides the current address space identifier in \@asid.
2405 *
2406 * The \@size argument must be set to sizeof(struct pt_asid). At most \@size
2407 * bytes will be copied and \@asid->size will be set to the actual size of the
2408 * provided address space identifier.
2409 *
2410 * Returns zero on success, a negative error code otherwise.
2411 *
2412 * Returns -pte_invalid if \@decoder or \@asid is NULL.
2413 */
2414 extern pt_export int pt_blk_asid(const struct pt_block_decoder *decoder,
2415 struct pt_asid *asid, size_t size);
2416
2417 /** Determine the next block of instructions.
2418 *
2419 * On success, provides the next block of instructions in execution order in
2420 * \@block.
2421 *
2422 * The \@size argument must be set to sizeof(struct pt_block).
2423 *
2424 * Returns a non-negative pt_status_flag bit-vector on success, a negative error
2425 * code otherwise.
2426 *
2427 * Returns pts_eos to indicate the end of the trace stream. Subsequent calls
2428 * to pt_block_next() will continue to return pts_eos until trace is required
2429 * to determine the next instruction.
2430 *
2431 * Returns -pte_bad_context if the decoder encountered an unexpected packet.
2432 * Returns -pte_bad_opc if the decoder encountered unknown packets.
2433 * Returns -pte_bad_packet if the decoder encountered unknown packet payloads.
2434 * Returns -pte_bad_query if the decoder got out of sync.
2435 * Returns -pte_eos if decoding reached the end of the Intel PT buffer.
2436 * Returns -pte_invalid if \@decoder or \@block is NULL.
2437 * Returns -pte_nomap if the memory at the instruction address can't be read.
2438 * Returns -pte_nosync if \@decoder is out of sync.
2439 */
2440 extern pt_export int pt_blk_next(struct pt_block_decoder *decoder,
2441 struct pt_block *block, size_t size);
2442
2443 /** Get the next pending event.
2444 *
2445 * On success, provides the next event in \@event and updates \@decoder.
2446 *
2447 * The \@size argument must be set to sizeof(struct pt_event).
2448 *
2449 * Returns a non-negative pt_status_flag bit-vector on success, a negative error
2450 * code otherwise.
2451 *
2452 * Returns -pte_bad_query if there is no event.
2453 * Returns -pte_invalid if \@decoder or \@event is NULL.
2454 * Returns -pte_invalid if \@size is too small.
2455 */
2456 extern pt_export int pt_blk_event(struct pt_block_decoder *decoder,
2457 struct pt_event *event, size_t size);
2458
2459 #ifdef __cplusplus
2460 }
2461 #endif
2462
2463 #endif /* INTEL_PT_H */
2464