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 36extern "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 56struct pt_encoder; 57struct pt_packet_decoder; 58struct pt_query_decoder; 59struct pt_insn_decoder; 60struct 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. */ 88struct 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. */ 107extern pt_export struct pt_version pt_library_version(void); 108 109 110 111/* Errors. */ 112 113 114 115/** Error codes. */ 116enum 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. */ 204static 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. */ 210extern pt_export const char *pt_errstr(enum pt_error_code); 211 212 213 214/* Configuration. */ 215 216 217 218/** A cpu vendor. */ 219enum pt_cpu_vendor { 220 pcv_unknown, 221 pcv_intel 222}; 223 224/** A cpu identifier. */ 225struct 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. */ 240struct 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. */ 338struct 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. */ 365struct 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. */ 399struct pt_packet_unknown; 400 401/** An Intel PT decoder configuration. 402 */ 403struct 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. */ 475static 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 */ 490extern 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. */ 500enum 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. */ 536enum 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. */ 560enum pt_exec_mode { 561 ptem_unknown, 562 ptem_16bit, 563 ptem_32bit, 564 ptem_64bit 565}; 566 567/** Mode packet leaves. */ 568enum pt_mode_leaf { 569 pt_mol_exec = 0x00, 570 pt_mol_tsx = 0x20 571}; 572 573/** A TNT-8 or TNT-64 packet. */ 574struct 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. */ 583struct 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. */ 592struct 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 600static inline enum pt_exec_mode 601pt_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 609static inline struct pt_packet_mode_exec 610pt_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. */ 640struct 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. */ 649struct 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. */ 664struct 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. */ 673struct pt_packet_tsc { 674 /** The TSC value. */ 675 uint64_t tsc; 676}; 677 678/** A CBR packet. */ 679struct pt_packet_cbr { 680 /** The core/bus cycle ratio. */ 681 uint8_t ratio; 682}; 683 684/** A TMA packet. */ 685struct 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. */ 694struct pt_packet_mtc { 695 /** The crystal clock tick counter value. */ 696 uint8_t ctc; 697}; 698 699/** A CYC packet. */ 700struct pt_packet_cyc { 701 /** The cycle counter value. */ 702 uint64_t value; 703}; 704 705/** A VMCS packet. */ 706struct pt_packet_vmcs { 707 /* The VMCS Base Address (i.e. the shifted payload). */ 708 uint64_t base; 709}; 710 711/** A MNT packet. */ 712struct pt_packet_mnt { 713 /** The raw payload. */ 714 uint64_t payload; 715}; 716 717/** A EXSTOP packet. */ 718struct 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. */ 728struct 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. */ 737struct 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. */ 749struct 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. */ 770struct 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 783static 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. */ 801struct 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. */ 810struct 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 */ 890extern pt_export struct pt_encoder * 891pt_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 */ 897extern 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 */ 908extern 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 */ 921extern 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 */ 928extern pt_export const struct pt_config * 929pt_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 */ 949extern 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 */ 965extern pt_export struct pt_packet_decoder * 966pt_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 */ 972extern 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 */ 987extern pt_export int pt_pkt_sync_forward(struct pt_packet_decoder *decoder); 988extern 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 */ 999extern 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 */ 1013extern 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 */ 1027extern pt_export int 1028pt_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 */ 1035extern pt_export const struct pt_config * 1036pt_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 */ 1055extern 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. */ 1065enum 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. */ 1077enum 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. */ 1138struct 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 */ 1446extern pt_export struct pt_query_decoder * 1447pt_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 */ 1453extern 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 */ 1473extern pt_export int pt_qry_sync_forward(struct pt_query_decoder *decoder, 1474 uint64_t *ip); 1475extern 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 */ 1495extern 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 */ 1509extern 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 */ 1523extern pt_export int 1524pt_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 */ 1531extern pt_export const struct pt_config * 1532pt_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 */ 1549extern 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 */ 1567extern 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 */ 1587extern 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 */ 1612extern 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 */ 1626extern 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 */ 1640struct 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. */ 1652static const uint64_t pt_asid_no_cr3 = 0xffffffffffffffffull; 1653 1654/** An unknown VMCS Base value to be used for pt_asid objects. */ 1655static const uint64_t pt_asid_no_vmcs = 0xffffffffffffffffull; 1656 1657/** Initialize an address space identifier. */ 1658static 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. */ 1667struct 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 */ 1675extern pt_export struct pt_image_section_cache * 1676pt_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 */ 1683extern 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 */ 1694extern pt_export int 1695pt_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 */ 1701extern pt_export const char * 1702pt_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 */ 1720extern 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 */ 1742extern 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. */ 1747struct 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 */ 1756extern 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 */ 1763extern 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 */ 1769extern 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 */ 1790extern 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 */ 1807extern 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 */ 1821extern 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 */ 1834extern 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 */ 1848extern 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 */ 1859typedef 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 */ 1874extern 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 */ 1889enum 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. */ 1928enum { 1929 pt_max_insn_size = 15 1930}; 1931 1932/** A single traced instruction. */ 1933struct 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 */ 1980extern pt_export struct pt_insn_decoder * 1981pt_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 */ 1989extern 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 */ 2006extern pt_export int pt_insn_sync_forward(struct pt_insn_decoder *decoder); 2007extern 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 */ 2023extern 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 */ 2037extern 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 */ 2049extern pt_export int 2050pt_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 */ 2061extern pt_export struct pt_image * 2062pt_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 */ 2074extern 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 */ 2081extern pt_export const struct pt_config * 2082pt_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 */ 2106extern 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 */ 2120extern 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 */ 2135extern 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 */ 2160extern 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 */ 2176extern 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 */ 2190struct 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 */ 2260extern pt_export struct pt_block_decoder * 2261pt_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 */ 2269extern 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 */ 2286extern pt_export int pt_blk_sync_forward(struct pt_block_decoder *decoder); 2287extern 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 */ 2303extern 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 */ 2317extern 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 */ 2329extern pt_export int 2330pt_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 */ 2340extern pt_export struct pt_image * 2341pt_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 */ 2353extern 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 */ 2360extern pt_export const struct pt_config * 2361pt_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 */ 2385extern 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 */ 2399extern 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 */ 2414extern 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 */ 2440extern 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 */ 2456extern 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