2 * Copyright (c) 2013-2019, Intel Corporation
4 * Redistribution and use in source and binary forms, with or without
5 * modification, are permitted provided that the following conditions are met:
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.
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.
40 /* Intel(R) Processor Trace (Intel PT) decoder library.
42 * This file is logically structured into the following sections:
47 * - Packet encoder / decoder
50 * - Instruction flow decoder
57 struct pt_packet_decoder;
58 struct pt_query_decoder;
59 struct pt_insn_decoder;
60 struct pt_block_decoder;
64 /* A macro to mark functions as exported. */
66 # if defined(__GNUC__)
67 # define pt_export __attribute__((visibility("default")))
68 # elif defined(_MSC_VER)
69 # define pt_export __declspec(dllimport)
71 # error "unknown compiler"
80 /** The header version. */
81 #define LIBIPT_VERSION_MAJOR ${PT_VERSION_MAJOR}
82 #define LIBIPT_VERSION_MINOR ${PT_VERSION_MINOR}
83 #define LIBIPT_VERSION_PATCH ${PT_VERSION_PATCH}
85 #define LIBIPT_VERSION ((LIBIPT_VERSION_MAJOR << 8) + LIBIPT_VERSION_MINOR)
88 /** The library version. */
90 /** Major version number. */
93 /** Minor version number. */
102 /** Version extension. */
107 /** Return the library version. */
108 extern pt_export struct pt_version pt_library_version(void);
118 /* No error. Everything is OK. */
121 /* Internal decoder error. */
124 /* Invalid argument. */
127 /* Decoder out of sync. */
130 /* Unknown opcode. */
133 /* Unknown payload. */
136 /* Unexpected packet context. */
139 /* Decoder reached end of trace stream. */
142 /* No packet matching the query to be found. */
145 /* Decoder out of memory. */
148 /* Bad configuration. */
151 /* There is no IP. */
154 /* The IP has been suppressed. */
157 /* There is no memory mapped at the requested address. */
160 /* An instruction could not be decoded. */
163 /* No wall-clock time is available. */
166 /* No core:bus ratio available. */
169 /* Bad traced image. */
172 /* A locking error. */
175 /* The requested feature is not supported. */
178 /* The return address stack is empty. */
181 /* A compressed return is not indicated correctly by a taken branch. */
184 /* The current decoder state does not match the state in the trace. */
185 pte_bad_status_update,
187 /* The trace did not contain an expected enabled event. */
190 /* An event was ignored. */
193 /* Something overflowed. */
196 /* A file handling error. */
204 /** Decode a function return value into an pt_error_code. */
205 static inline enum pt_error_code pt_errcode(int status)
207 return (status >= 0) ? pte_ok : (enum pt_error_code) -status;
210 /** Return a human readable error string. */
211 extern pt_export const char *pt_errstr(enum pt_error_code);
225 /** A cpu identifier. */
227 /** The cpu vendor. */
228 enum pt_cpu_vendor vendor;
230 /** The cpu family. */
233 /** The cpu model. */
240 /** A collection of Intel PT errata. */
242 /** BDM70: Intel(R) Processor Trace PSB+ Packets May Contain
243 * Unexpected Packets.
245 * Same as: SKD024, SKL021, KBL021.
247 * Some Intel Processor Trace packets should be issued only between
248 * TIP.PGE and TIP.PGD packets. Due to this erratum, when a TIP.PGE
249 * packet is generated it may be preceded by a PSB+ that incorrectly
250 * includes FUP and MODE.Exec packets.
254 /** BDM64: An Incorrect LBR or Intel(R) Processor Trace Packet May Be
255 * Recorded Following a Transactional Abort.
257 * Use of Intel(R) Transactional Synchronization Extensions (Intel(R)
258 * TSX) may result in a transactional abort. If an abort occurs
259 * immediately following a branch instruction, an incorrect branch
260 * target may be logged in an LBR (Last Branch Record) or in an Intel(R)
261 * Processor Trace (Intel(R) PT) packet before the LBR or Intel PT
262 * packet produced by the abort.
266 /** SKD007: Intel(R) PT Buffer Overflow May Result in Incorrect Packets.
268 * Same as: SKL049, KBL041.
270 * Under complex micro-architectural conditions, an Intel PT (Processor
271 * Trace) OVF (Overflow) packet may be issued after the first byte of a
272 * multi-byte CYC (Cycle Count) packet, instead of any remaining bytes
277 /** SKD022: VM Entry That Clears TraceEn May Generate a FUP.
279 * Same as: SKL024, KBL023.
281 * If VM entry clears Intel(R) PT (Intel Processor Trace)
282 * IA32_RTIT_CTL.TraceEn (MSR 570H, bit 0) while PacketEn is 1 then a
283 * FUP (Flow Update Packet) will precede the TIP.PGD (Target IP Packet,
284 * Packet Generation Disable). VM entry can clear TraceEn if the
285 * VM-entry MSR-load area includes an entry for the IA32_RTIT_CTL MSR.
289 /** SKD010: Intel(R) PT FUP May be Dropped After OVF.
291 * Same as: SKD014, SKL033, KBL030.
293 * Some Intel PT (Intel Processor Trace) OVF (Overflow) packets may not
294 * be followed by a FUP (Flow Update Packet) or TIP.PGE (Target IP
295 * Packet, Packet Generation Enable).
299 /** SKL014: Intel(R) PT TIP.PGD May Not Have Target IP Payload.
303 * When Intel PT (Intel Processor Trace) is enabled and a direct
304 * unconditional branch clears IA32_RTIT_STATUS.FilterEn (MSR 571H, bit
305 * 0), due to this erratum, the resulting TIP.PGD (Target IP Packet,
306 * Packet Generation Disable) may not have an IP payload with the target
311 /** APL12: Intel(R) PT OVF May Be Followed By An Unexpected FUP Packet.
313 * Certain Intel PT (Processor Trace) packets including FUPs (Flow
314 * Update Packets), should be issued only between TIP.PGE (Target IP
315 * Packet - Packet Generaton Enable) and TIP.PGD (Target IP Packet -
316 * Packet Generation Disable) packets. When outside a TIP.PGE/TIP.PGD
317 * pair, as a result of IA32_RTIT_STATUS.FilterEn[0] (MSR 571H) being
318 * cleared, an OVF (Overflow) packet may be unexpectedly followed by a
323 /** APL11: Intel(R) PT OVF Pakcet May Be Followed by TIP.PGD Packet
325 * If Intel PT (Processor Trace) encounters an internal buffer overflow
326 * and generates an OVF (Overflow) packet just as IA32_RTIT_CTL (MSR
327 * 570H) bit 0 (TraceEn) is cleared, or during a far transfer that
328 * causes IA32_RTIT_STATUS.ContextEn[1] (MSR 571H) to be cleared, the
329 * OVF may be followed by a TIP.PGD (Target Instruction Pointer - Packet
330 * Generation Disable) packet.
334 /** SKL168: Intel(R) PT CYC Packets Can be Dropped When Immediately
337 * Due to a rare microarchitectural condition, generation of an Intel
338 * PT (Processor Trace) PSB (Packet Stream Boundary) packet can cause a
339 * single CYC (Cycle Count) packet, possibly along with an associated
340 * MTC (Mini Time Counter) packet, to be dropped.
344 /* Reserve a few bytes for the future. */
345 uint32_t reserved[15];
348 /** A collection of decoder-specific configuration flags. */
349 struct pt_conf_flags {
350 /** The decoder variant. */
352 /** Flags for the block decoder. */
354 /** End a block after a call instruction. */
355 uint32_t end_on_call:1;
357 /** Enable tick events for timing updates. */
358 uint32_t enable_tick_events:1;
360 /** End a block after a jump instruction. */
361 uint32_t end_on_jump:1;
363 /** Preserve timing calibration on overflow. */
364 uint32_t keep_tcal_on_ovf:1;
367 /** Flags for the instruction flow decoder. */
369 /** Enable tick events for timing updates. */
370 uint32_t enable_tick_events:1;
372 /** Preserve timing calibration on overflow. */
373 uint32_t keep_tcal_on_ovf:1;
376 /** Flags for the query decoder. */
378 /** Preserve timing calibration on overflow. */
379 uint32_t keep_tcal_on_ovf:1;
382 /* Reserve a few bytes for future extensions. */
383 uint32_t reserved[4];
387 /** The address filter configuration. */
388 struct pt_conf_addr_filter {
389 /** The address filter configuration.
391 * This corresponds to the respective fields in IA32_RTIT_CTL MSR.
397 uint32_t addr0_cfg:4;
398 uint32_t addr1_cfg:4;
399 uint32_t addr2_cfg:4;
400 uint32_t addr3_cfg:4;
404 /** The address ranges configuration.
406 * This corresponds to the IA32_RTIT_ADDRn_A/B MSRs.
417 /* Reserve some space. */
418 uint64_t reserved[8];
421 /** An unknown packet. */
422 struct pt_packet_unknown;
424 /** An Intel PT decoder configuration.
427 /** The size of the config structure in bytes. */
430 /** The trace buffer begin address. */
433 /** The trace buffer end address. */
436 /** An optional callback for handling unknown packets.
438 * If \@callback is not NULL, it is called for any unknown opcode.
441 /** The callback function.
443 * It shall decode the packet at \@pos into \@unknown.
444 * It shall return the number of bytes read upon success.
445 * It shall return a negative pt_error_code otherwise.
446 * The below context is passed as \@context.
448 int (*callback)(struct pt_packet_unknown *unknown,
449 const struct pt_config *config,
450 const uint8_t *pos, void *context);
452 /** The user-defined context for this configuration. */
456 /** The cpu on which Intel PT has been recorded. */
459 /** The errata to apply when encoding or decoding Intel PT. */
460 struct pt_errata errata;
462 /* The CTC frequency.
464 * This is only required if MTC packets have been enabled in
465 * IA32_RTIT_CTRL.MTCEn.
467 uint32_t cpuid_0x15_eax, cpuid_0x15_ebx;
469 /* The MTC frequency as defined in IA32_RTIT_CTL.MTCFreq.
471 * This is only required if MTC packets have been enabled in
472 * IA32_RTIT_CTRL.MTCEn.
476 /* The nominal frequency as defined in MSR_PLATFORM_INFO[15:8].
478 * This is only required if CYC packets have been enabled in
479 * IA32_RTIT_CTRL.CYCEn.
481 * If zero, timing calibration will only be able to use MTC and CYC
484 * If not zero, timing calibration will also be able to use CBR
489 /** A collection of decoder-specific flags. */
490 struct pt_conf_flags flags;
492 /** The address filter configuration. */
493 struct pt_conf_addr_filter addr_filter;
497 /** Zero-initialize an Intel PT configuration. */
498 static inline void pt_config_init(struct pt_config *config)
500 memset(config, 0, sizeof(*config));
502 config->size = sizeof(*config);
505 /** Determine errata for a given cpu.
507 * Updates \@errata based on \@cpu.
509 * Returns 0 on success, a negative error code otherwise.
510 * Returns -pte_invalid if \@errata or \@cpu is NULL.
511 * Returns -pte_bad_cpu if \@cpu is not known.
513 extern pt_export int pt_cpu_errata(struct pt_errata *errata,
514 const struct pt_cpu *cpu);
518 /* Packet encoder / decoder. */
522 /** Intel PT packet types. */
523 enum pt_packet_type {
524 /* An invalid packet. */
527 /* A packet decodable by the optional decoder callback. */
530 /* Actual packets supported by this library. */
558 /** The IP compression. */
559 enum pt_ip_compression {
560 /* The bits encode the payload size and the encoding scheme.
562 * No payload. The IP has been suppressed.
564 pt_ipc_suppressed = 0x0,
566 /* Payload: 16 bits. Update last IP. */
567 pt_ipc_update_16 = 0x01,
569 /* Payload: 32 bits. Update last IP. */
570 pt_ipc_update_32 = 0x02,
572 /* Payload: 48 bits. Sign extend to full address. */
573 pt_ipc_sext_48 = 0x03,
575 /* Payload: 48 bits. Update last IP. */
576 pt_ipc_update_48 = 0x04,
578 /* Payload: 64 bits. Full address. */
582 /** An execution mode. */
590 /** Mode packet leaves. */
596 /** A TNT-8 or TNT-64 packet. */
597 struct pt_packet_tnt {
598 /** TNT payload bit size. */
601 /** TNT payload excluding stop bit. */
605 /** A packet with IP payload. */
606 struct pt_packet_ip {
607 /** IP compression. */
608 enum pt_ip_compression ipc;
610 /** Zero-extended payload ip. */
614 /** A mode.exec packet. */
615 struct pt_packet_mode_exec {
616 /** The mode.exec csl bit. */
619 /** The mode.exec csd bit. */
623 static inline enum pt_exec_mode
624 pt_get_exec_mode(const struct pt_packet_mode_exec *packet)
627 return packet->csd ? ptem_unknown : ptem_64bit;
629 return packet->csd ? ptem_32bit : ptem_16bit;
632 static inline struct pt_packet_mode_exec
633 pt_set_exec_mode(enum pt_exec_mode mode)
635 struct pt_packet_mode_exec packet;
662 /** A mode.tsx packet. */
663 struct pt_packet_mode_tsx {
664 /** The mode.tsx intx bit. */
667 /** The mode.tsx abrt bit. */
671 /** A mode packet. */
672 struct pt_packet_mode {
674 enum pt_mode_leaf leaf;
678 /** Packet: mode.exec. */
679 struct pt_packet_mode_exec exec;
681 /** Packet: mode.tsx. */
682 struct pt_packet_mode_tsx tsx;
687 struct pt_packet_pip {
688 /** The CR3 value. */
691 /** The non-root bit. */
696 struct pt_packet_tsc {
697 /** The TSC value. */
702 struct pt_packet_cbr {
703 /** The core/bus cycle ratio. */
708 struct pt_packet_tma {
709 /** The crystal clock tick counter value. */
712 /** The fast counter value. */
717 struct pt_packet_mtc {
718 /** The crystal clock tick counter value. */
723 struct pt_packet_cyc {
724 /** The cycle counter value. */
728 /** A VMCS packet. */
729 struct pt_packet_vmcs {
730 /* The VMCS Base Address (i.e. the shifted payload). */
735 struct pt_packet_mnt {
736 /** The raw payload. */
740 /** A EXSTOP packet. */
741 struct pt_packet_exstop {
742 /** A flag specifying the binding of the packet:
744 * set: binds to the next FUP.
750 /** A MWAIT packet. */
751 struct pt_packet_mwait {
752 /** The MWAIT hints (EAX). */
755 /** The MWAIT extensions (ECX). */
759 /** A PWRE packet. */
760 struct pt_packet_pwre {
761 /** The resolved thread C-state. */
764 /** The resolved thread sub C-state. */
767 /** A flag indicating whether the C-state entry was initiated by h/w. */
771 /** A PWRX packet. */
772 struct pt_packet_pwrx {
773 /** The core C-state at the time of the wake. */
776 /** The deepest core C-state achieved during sleep. */
781 * - due to external interrupt received.
783 uint32_t interrupt:1;
785 /** - due to store to monitored address. */
788 /** - due to h/w autonomous condition such as HDC. */
789 uint32_t autonomous:1;
793 struct pt_packet_ptw {
794 /** The raw payload. */
797 /** The payload size as encoded in the packet. */
800 /** A flag saying whether a FUP is following PTW that provides
801 * the IP of the corresponding PTWRITE instruction.
806 static inline int pt_ptw_size(uint8_t plc)
817 return -pte_bad_packet;
820 return -pte_internal;
823 /** An unknown packet decodable by the optional decoder callback. */
824 struct pt_packet_unknown {
825 /** Pointer to the raw packet bytes. */
826 const uint8_t *packet;
828 /** Optional pointer to a user-defined structure. */
832 /** An Intel PT packet. */
834 /** The type of the packet.
836 * This also determines the \@payload field.
838 enum pt_packet_type type;
840 /** The size of the packet including opcode and payload. */
843 /** Packet specific data. */
845 /** Packets: pad, ovf, psb, psbend, stop - no payload. */
847 /** Packet: tnt-8, tnt-64. */
848 struct pt_packet_tnt tnt;
850 /** Packet: tip, fup, tip.pge, tip.pgd. */
851 struct pt_packet_ip ip;
854 struct pt_packet_mode mode;
857 struct pt_packet_pip pip;
860 struct pt_packet_tsc tsc;
863 struct pt_packet_cbr cbr;
866 struct pt_packet_tma tma;
869 struct pt_packet_mtc mtc;
872 struct pt_packet_cyc cyc;
875 struct pt_packet_vmcs vmcs;
878 struct pt_packet_mnt mnt;
880 /** Packet: exstop. */
881 struct pt_packet_exstop exstop;
883 /** Packet: mwait. */
884 struct pt_packet_mwait mwait;
887 struct pt_packet_pwre pwre;
890 struct pt_packet_pwrx pwrx;
893 struct pt_packet_ptw ptw;
895 /** Packet: unknown. */
896 struct pt_packet_unknown unknown;
902 /* Packet encoder. */
906 /** Allocate an Intel PT packet encoder.
908 * The encoder will work on the buffer defined in \@config, it shall contain
909 * raw trace data and remain valid for the lifetime of the encoder.
911 * The encoder starts at the beginning of the trace buffer.
913 extern pt_export struct pt_encoder *
914 pt_alloc_encoder(const struct pt_config *config);
916 /** Free an Intel PT packet encoder.
918 * The \@encoder must not be used after a successful return.
920 extern pt_export void pt_free_encoder(struct pt_encoder *encoder);
922 /** Hard set synchronization point of an Intel PT packet encoder.
924 * Synchronize \@encoder to \@offset within the trace buffer.
926 * Returns zero on success, a negative error code otherwise.
928 * Returns -pte_eos if the given offset is behind the end of the trace buffer.
929 * Returns -pte_invalid if \@encoder is NULL.
931 extern pt_export int pt_enc_sync_set(struct pt_encoder *encoder,
934 /** Get the current packet encoder position.
936 * Fills the current \@encoder position into \@offset.
938 * This is useful for reporting errors.
940 * Returns zero on success, a negative error code otherwise.
942 * Returns -pte_invalid if \@encoder or \@offset is NULL.
944 extern pt_export int pt_enc_get_offset(const struct pt_encoder *encoder,
947 /* Return a pointer to \@encoder's configuration.
949 * Returns a non-null pointer on success, NULL if \@encoder is NULL.
951 extern pt_export const struct pt_config *
952 pt_enc_get_config(const struct pt_encoder *encoder);
954 /** Encode an Intel PT packet.
956 * Writes \@packet at \@encoder's current position in the Intel PT buffer and
957 * advances the \@encoder beyond the written packet.
959 * The \@packet.size field is ignored.
961 * In case of errors, the \@encoder is not advanced and nothing is written
962 * into the Intel PT buffer.
964 * Returns the number of bytes written on success, a negative error code
967 * Returns -pte_bad_opc if \@packet.type is not known.
968 * Returns -pte_bad_packet if \@packet's payload is invalid.
969 * Returns -pte_eos if \@encoder reached the end of the Intel PT buffer.
970 * Returns -pte_invalid if \@encoder or \@packet is NULL.
972 extern pt_export int pt_enc_next(struct pt_encoder *encoder,
973 const struct pt_packet *packet);
977 /* Packet decoder. */
981 /** Allocate an Intel PT packet decoder.
983 * The decoder will work on the buffer defined in \@config, it shall contain
984 * raw trace data and remain valid for the lifetime of the decoder.
986 * The decoder needs to be synchronized before it can be used.
988 extern pt_export struct pt_packet_decoder *
989 pt_pkt_alloc_decoder(const struct pt_config *config);
991 /** Free an Intel PT packet decoder.
993 * The \@decoder must not be used after a successful return.
995 extern pt_export void pt_pkt_free_decoder(struct pt_packet_decoder *decoder);
997 /** Synchronize an Intel PT packet decoder.
999 * Search for the next synchronization point in forward or backward direction.
1001 * If \@decoder has not been synchronized, yet, the search is started at the
1002 * beginning of the trace buffer in case of forward synchronization and at the
1003 * end of the trace buffer in case of backward synchronization.
1005 * Returns zero or a positive value on success, a negative error code otherwise.
1007 * Returns -pte_eos if no further synchronization point is found.
1008 * Returns -pte_invalid if \@decoder is NULL.
1010 extern pt_export int pt_pkt_sync_forward(struct pt_packet_decoder *decoder);
1011 extern pt_export int pt_pkt_sync_backward(struct pt_packet_decoder *decoder);
1013 /** Hard set synchronization point of an Intel PT decoder.
1015 * Synchronize \@decoder to \@offset within the trace buffer.
1017 * Returns zero on success, a negative error code otherwise.
1019 * Returns -pte_eos if the given offset is behind the end of the trace buffer.
1020 * Returns -pte_invalid if \@decoder is NULL.
1022 extern pt_export int pt_pkt_sync_set(struct pt_packet_decoder *decoder,
1025 /** Get the current decoder position.
1027 * Fills the current \@decoder position into \@offset.
1029 * This is useful for reporting errors.
1031 * Returns zero on success, a negative error code otherwise.
1033 * Returns -pte_invalid if \@decoder or \@offset is NULL.
1034 * Returns -pte_nosync if \@decoder is out of sync.
1036 extern pt_export int pt_pkt_get_offset(const struct pt_packet_decoder *decoder,
1039 /** Get the position of the last synchronization point.
1041 * Fills the last synchronization position into \@offset.
1043 * This is useful when splitting a trace stream for parallel decoding.
1045 * Returns zero on success, a negative error code otherwise.
1047 * Returns -pte_invalid if \@decoder or \@offset is NULL.
1048 * Returns -pte_nosync if \@decoder is out of sync.
1050 extern pt_export int
1051 pt_pkt_get_sync_offset(const struct pt_packet_decoder *decoder,
1054 /* Return a pointer to \@decoder's configuration.
1056 * Returns a non-null pointer on success, NULL if \@decoder is NULL.
1058 extern pt_export const struct pt_config *
1059 pt_pkt_get_config(const struct pt_packet_decoder *decoder);
1061 /** Decode the next packet and advance the decoder.
1063 * Decodes the packet at \@decoder's current position into \@packet and
1064 * adjusts the \@decoder's position by the number of bytes the packet had
1067 * The \@size argument must be set to sizeof(struct pt_packet).
1069 * Returns the number of bytes consumed on success, a negative error code
1072 * Returns -pte_bad_opc if the packet is unknown.
1073 * Returns -pte_bad_packet if an unknown packet payload is encountered.
1074 * Returns -pte_eos if \@decoder reached the end of the Intel PT buffer.
1075 * Returns -pte_invalid if \@decoder or \@packet is NULL.
1076 * Returns -pte_nosync if \@decoder is out of sync.
1078 extern pt_export int pt_pkt_next(struct pt_packet_decoder *decoder,
1079 struct pt_packet *packet, size_t size);
1083 /* Query decoder. */
1087 /** Decoder status flags. */
1088 enum pt_status_flag {
1089 /** There is an event pending. */
1090 pts_event_pending = 1 << 0,
1092 /** The address has been suppressed. */
1093 pts_ip_suppressed = 1 << 1,
1095 /** There is no more trace data available. */
1100 enum pt_event_type {
1101 /* Tracing has been enabled/disabled. */
1105 /* Tracing has been disabled asynchronously. */
1106 ptev_async_disabled,
1108 /* An asynchronous branch, e.g. interrupt. */
1111 /* A synchronous paging event. */
1114 /* An asynchronous paging event. */
1117 /* Trace overflow. */
1120 /* An execution mode change. */
1123 /* A transactional execution state change. */
1129 /* A synchronous vmcs event. */
1132 /* An asynchronous vmcs event. */
1135 /* Execution has stopped. */
1138 /* An MWAIT operation completed. */
1141 /* A power state was entered. */
1144 /* A power state was exited. */
1147 /* A PTWRITE event. */
1150 /* A timing event. */
1153 /* A core:bus ratio event. */
1156 /* A maintenance event. */
1162 /** The type of the event. */
1163 enum pt_event_type type;
1165 /** A flag indicating that the event IP has been suppressed. */
1166 uint32_t ip_suppressed:1;
1168 /** A flag indicating that the event is for status update. */
1169 uint32_t status_update:1;
1171 /** A flag indicating that the event has timing information. */
1174 /** The time stamp count of the event.
1176 * This field is only valid if \@has_tsc is set.
1180 /** The number of lost mtc and cyc packets.
1182 * This gives an idea about the quality of the \@tsc. The more packets
1183 * were dropped, the less precise timing is.
1188 /* Reserved space for future extensions. */
1189 uint64_t reserved[2];
1191 /** Event specific data. */
1193 /** Event: enabled. */
1195 /** The address at which tracing resumes. */
1198 /** A flag indicating that tracing resumes from the IP
1199 * at which tracing had been disabled before.
1204 /** Event: disabled. */
1206 /** The destination of the first branch inside a
1209 * This field is not valid if \@ip_suppressed is set.
1213 /* The exact source ip needs to be determined using
1214 * disassembly and the filter configuration.
1218 /** Event: async disabled. */
1220 /** The source address of the asynchronous branch that
1225 /** The destination of the first branch inside a
1228 * This field is not valid if \@ip_suppressed is set.
1233 /** Event: async branch. */
1235 /** The branch source address. */
1238 /** The branch destination address.
1240 * This field is not valid if \@ip_suppressed is set.
1245 /** Event: paging. */
1247 /** The updated CR3 value.
1249 * The lower 5 bit have been zeroed out.
1250 * The upper bits have been zeroed out depending on the
1251 * maximum possible address.
1255 /** A flag indicating whether the cpu is operating in
1256 * vmx non-root (guest) mode.
1258 uint32_t non_root:1;
1260 /* The address at which the event is effective is
1261 * obvious from the disassembly.
1265 /** Event: async paging. */
1267 /** The updated CR3 value.
1269 * The lower 5 bit have been zeroed out.
1270 * The upper bits have been zeroed out depending on the
1271 * maximum possible address.
1275 /** A flag indicating whether the cpu is operating in
1276 * vmx non-root (guest) mode.
1278 uint32_t non_root:1;
1280 /** The address at which the event is effective. */
1284 /** Event: overflow. */
1286 /** The address at which tracing resumes after overflow.
1288 * This field is not valid, if ip_suppressed is set.
1289 * In this case, the overflow resolved while tracing
1295 /** Event: exec mode. */
1297 /** The execution mode. */
1298 enum pt_exec_mode mode;
1300 /** The address at which the event is effective. */
1306 /** The address at which the event is effective.
1308 * This field is not valid if \@ip_suppressed is set.
1312 /** A flag indicating speculative execution mode. */
1313 uint32_t speculative:1;
1315 /** A flag indicating speculative execution aborts. */
1321 /** The VMCS base address.
1323 * The address is zero-extended with the lower 12 bits
1328 /* The new VMCS base address should be stored and
1329 * applied on subsequent VM entries.
1333 /** Event: async vmcs. */
1335 /** The VMCS base address.
1337 * The address is zero-extended with the lower 12 bits
1342 /** The address at which the event is effective. */
1345 /* An async paging event that binds to the same IP
1346 * will always succeed this async vmcs event.
1350 /** Event: execution stopped. */
1352 /** The address at which execution has stopped. This is
1353 * the last instruction that did not complete.
1355 * This field is not valid, if \@ip_suppressed is set.
1360 /** Event: mwait. */
1362 /** The address of the instruction causing the mwait.
1364 * This field is not valid, if \@ip_suppressed is set.
1368 /** The mwait hints (eax).
1370 * Reserved bits are undefined.
1374 /** The mwait extensions (ecx).
1376 * Reserved bits are undefined.
1381 /** Event: power state entry. */
1383 /** The resolved thread C-state. */
1386 /** The resolved thread sub C-state. */
1389 /** A flag indicating whether the C-state entry was
1395 /** Event: power state exit. */
1397 /** The core C-state at the time of the wake. */
1400 /** The deepest core C-state achieved during sleep. */
1403 /** The wake reason:
1405 * - due to external interrupt received.
1407 uint32_t interrupt:1;
1409 /** - due to store to monitored address. */
1412 /** - due to h/w autonomous condition such as HDC. */
1413 uint32_t autonomous:1;
1416 /** Event: ptwrite. */
1418 /** The address of the ptwrite instruction.
1420 * This field is not valid, if \@ip_suppressed is set.
1422 * In this case, the address is obvious from the
1427 /** The size of the below \@payload in bytes. */
1430 /** The ptwrite payload. */
1436 /** The instruction address near which the tick occured.
1438 * A timestamp can sometimes be attributed directly to
1439 * an instruction (e.g. to an indirect branch that
1440 * receives CYC + TIP) and sometimes not (e.g. MTC).
1442 * This field is not valid, if \@ip_suppressed is set.
1449 /** The core:bus ratio. */
1455 /** The raw payload. */
1462 /** Allocate an Intel PT query decoder.
1464 * The decoder will work on the buffer defined in \@config, it shall contain
1465 * raw trace data and remain valid for the lifetime of the decoder.
1467 * The decoder needs to be synchronized before it can be used.
1469 extern pt_export struct pt_query_decoder *
1470 pt_qry_alloc_decoder(const struct pt_config *config);
1472 /** Free an Intel PT query decoder.
1474 * The \@decoder must not be used after a successful return.
1476 extern pt_export void pt_qry_free_decoder(struct pt_query_decoder *decoder);
1478 /** Synchronize an Intel PT query decoder.
1480 * Search for the next synchronization point in forward or backward direction.
1482 * If \@decoder has not been synchronized, yet, the search is started at the
1483 * beginning of the trace buffer in case of forward synchronization and at the
1484 * end of the trace buffer in case of backward synchronization.
1486 * If \@ip is not NULL, set it to last ip.
1488 * Returns a non-negative pt_status_flag bit-vector on success, a negative error
1491 * Returns -pte_bad_opc if an unknown packet is encountered.
1492 * Returns -pte_bad_packet if an unknown packet payload is encountered.
1493 * Returns -pte_eos if no further synchronization point is found.
1494 * Returns -pte_invalid if \@decoder is NULL.
1496 extern pt_export int pt_qry_sync_forward(struct pt_query_decoder *decoder,
1498 extern pt_export int pt_qry_sync_backward(struct pt_query_decoder *decoder,
1501 /** Manually synchronize an Intel PT query decoder.
1503 * Synchronize \@decoder on the syncpoint at \@offset. There must be a PSB
1504 * packet at \@offset.
1506 * If \@ip is not NULL, set it to last ip.
1508 * Returns a non-negative pt_status_flag bit-vector on success, a negative error
1511 * Returns -pte_bad_opc if an unknown packet is encountered.
1512 * Returns -pte_bad_packet if an unknown packet payload is encountered.
1513 * Returns -pte_eos if \@offset lies outside of \@decoder's trace buffer.
1514 * Returns -pte_eos if \@decoder reaches the end of its trace buffer.
1515 * Returns -pte_invalid if \@decoder is NULL.
1516 * Returns -pte_nosync if there is no syncpoint at \@offset.
1518 extern pt_export int pt_qry_sync_set(struct pt_query_decoder *decoder,
1519 uint64_t *ip, uint64_t offset);
1521 /** Get the current decoder position.
1523 * Fills the current \@decoder position into \@offset.
1525 * This is useful for reporting errors.
1527 * Returns zero on success, a negative error code otherwise.
1529 * Returns -pte_invalid if \@decoder or \@offset is NULL.
1530 * Returns -pte_nosync if \@decoder is out of sync.
1532 extern pt_export int pt_qry_get_offset(const struct pt_query_decoder *decoder,
1535 /** Get the position of the last synchronization point.
1537 * Fills the last synchronization position into \@offset.
1539 * This is useful for splitting a trace stream for parallel decoding.
1541 * Returns zero on success, a negative error code otherwise.
1543 * Returns -pte_invalid if \@decoder or \@offset is NULL.
1544 * Returns -pte_nosync if \@decoder is out of sync.
1546 extern pt_export int
1547 pt_qry_get_sync_offset(const struct pt_query_decoder *decoder,
1550 /* Return a pointer to \@decoder's configuration.
1552 * Returns a non-null pointer on success, NULL if \@decoder is NULL.
1554 extern pt_export const struct pt_config *
1555 pt_qry_get_config(const struct pt_query_decoder *decoder);
1557 /** Query whether the next unconditional branch has been taken.
1559 * On success, provides 1 (taken) or 0 (not taken) in \@taken for the next
1560 * conditional branch and updates \@decoder.
1562 * Returns a non-negative pt_status_flag bit-vector on success, a negative error
1565 * Returns -pte_bad_opc if an unknown packet is encountered.
1566 * Returns -pte_bad_packet if an unknown packet payload is encountered.
1567 * Returns -pte_bad_query if no conditional branch is found.
1568 * Returns -pte_eos if decoding reached the end of the Intel PT buffer.
1569 * Returns -pte_invalid if \@decoder or \@taken is NULL.
1570 * Returns -pte_nosync if \@decoder is out of sync.
1572 extern pt_export int pt_qry_cond_branch(struct pt_query_decoder *decoder,
1575 /** Get the next indirect branch destination.
1577 * On success, provides the linear destination address of the next indirect
1578 * branch in \@ip and updates \@decoder.
1580 * Returns a non-negative pt_status_flag bit-vector on success, a negative error
1583 * Returns -pte_bad_opc if an unknown packet is encountered.
1584 * Returns -pte_bad_packet if an unknown packet payload is encountered.
1585 * Returns -pte_bad_query if no indirect branch is found.
1586 * Returns -pte_eos if decoding reached the end of the Intel PT buffer.
1587 * Returns -pte_invalid if \@decoder or \@ip is NULL.
1588 * Returns -pte_nosync if \@decoder is out of sync.
1590 extern pt_export int pt_qry_indirect_branch(struct pt_query_decoder *decoder,
1593 /** Query the next pending event.
1595 * On success, provides the next event \@event and updates \@decoder.
1597 * The \@size argument must be set to sizeof(struct pt_event).
1599 * Returns a non-negative pt_status_flag bit-vector on success, a negative error
1602 * Returns -pte_bad_opc if an unknown packet is encountered.
1603 * Returns -pte_bad_packet if an unknown packet payload is encountered.
1604 * Returns -pte_bad_query if no event is found.
1605 * Returns -pte_eos if decoding reached the end of the Intel PT buffer.
1606 * Returns -pte_invalid if \@decoder or \@event is NULL.
1607 * Returns -pte_invalid if \@size is too small.
1608 * Returns -pte_nosync if \@decoder is out of sync.
1610 extern pt_export int pt_qry_event(struct pt_query_decoder *decoder,
1611 struct pt_event *event, size_t size);
1613 /** Query the current time.
1615 * On success, provides the time at the last query in \@time.
1617 * The time is similar to what a rdtsc instruction would return. Depending
1618 * on the configuration, the time may not be fully accurate. If TSC is not
1619 * enabled, the time is relative to the last synchronization and can't be used
1620 * to correlate with other TSC-based time sources. In this case, -pte_no_time
1621 * is returned and the relative time is provided in \@time.
1623 * Some timing-related packets may need to be dropped (mostly due to missing
1624 * calibration or incomplete configuration). To get an idea about the quality
1625 * of the estimated time, we record the number of dropped MTC and CYC packets.
1627 * If \@lost_mtc is not NULL, set it to the number of lost MTC packets.
1628 * If \@lost_cyc is not NULL, set it to the number of lost CYC packets.
1630 * Returns zero on success, a negative error code otherwise.
1632 * Returns -pte_invalid if \@decoder or \@time is NULL.
1633 * Returns -pte_no_time if there has not been a TSC packet.
1635 extern pt_export int pt_qry_time(struct pt_query_decoder *decoder,
1636 uint64_t *time, uint32_t *lost_mtc,
1637 uint32_t *lost_cyc);
1639 /** Return the current core bus ratio.
1641 * On success, provides the current core:bus ratio in \@cbr. The ratio is
1642 * defined as core cycles per bus clock cycle.
1644 * Returns zero on success, a negative error code otherwise.
1646 * Returns -pte_invalid if \@decoder or \@cbr is NULL.
1647 * Returns -pte_no_cbr if there has not been a CBR packet.
1649 extern pt_export int pt_qry_core_bus_ratio(struct pt_query_decoder *decoder,
1658 /** An Intel PT address space identifier.
1660 * This identifies a particular address space when adding file sections or
1661 * when reading memory.
1664 /** The size of this object - set to sizeof(struct pt_asid). */
1667 /** The CR3 value. */
1670 /** The VMCS Base address. */
1674 /** An unknown CR3 value to be used for pt_asid objects. */
1675 static const uint64_t pt_asid_no_cr3 = 0xffffffffffffffffull;
1677 /** An unknown VMCS Base value to be used for pt_asid objects. */
1678 static const uint64_t pt_asid_no_vmcs = 0xffffffffffffffffull;
1680 /** Initialize an address space identifier. */
1681 static inline void pt_asid_init(struct pt_asid *asid)
1683 asid->size = sizeof(*asid);
1684 asid->cr3 = pt_asid_no_cr3;
1685 asid->vmcs = pt_asid_no_vmcs;
1689 /** A cache of traced image sections. */
1690 struct pt_image_section_cache;
1692 /** Allocate a traced memory image section cache.
1694 * An optional \@name may be given to the cache. The name string is copied.
1696 * Returns a new traced memory image section cache on success, NULL otherwise.
1698 extern pt_export struct pt_image_section_cache *
1699 pt_iscache_alloc(const char *name);
1701 /** Free a traced memory image section cache.
1703 * The \@iscache must have been allocated with pt_iscache_alloc().
1704 * The \@iscache must not be used after a successful return.
1706 extern pt_export void pt_iscache_free(struct pt_image_section_cache *iscache);
1708 /** Set the image section cache limit.
1710 * Set the limit for a section cache in bytes. A non-zero limit will keep the
1711 * least recently used sections mapped until the limit is reached. A limit of
1712 * zero disables caching.
1714 * Returns zero on success, a negative pt_error_code otherwise.
1715 * Returns -pte_invalid if \@iscache is NULL.
1717 extern pt_export int
1718 pt_iscache_set_limit(struct pt_image_section_cache *iscache, uint64_t limit);
1720 /** Get the image section cache name.
1722 * Returns a pointer to \@iscache's name or NULL if there is no name.
1724 extern pt_export const char *
1725 pt_iscache_name(const struct pt_image_section_cache *iscache);
1727 /** Add a new file section to the traced memory image section cache.
1729 * Adds a new section consisting of \@size bytes starting at \@offset in
1730 * \@filename loaded at the virtual address \@vaddr if \@iscache does not
1731 * already contain such a section.
1733 * Returns an image section identifier (isid) uniquely identifying that section
1736 * The section is silently truncated to match the size of \@filename.
1738 * Returns a positive isid on success, a negative error code otherwise.
1740 * Returns -pte_invalid if \@iscache or \@filename is NULL.
1741 * Returns -pte_invalid if \@offset is too big.
1743 extern pt_export int pt_iscache_add_file(struct pt_image_section_cache *iscache,
1744 const char *filename, uint64_t offset,
1745 uint64_t size, uint64_t vaddr);
1747 /** Read memory from a cached file section
1749 * Reads \@size bytes of memory starting at virtual address \@vaddr in the
1750 * section identified by \@isid in \@iscache into \@buffer.
1752 * The caller is responsible for allocating a \@buffer of at least \@size bytes.
1754 * The read request may be truncated if it crosses section boundaries or if
1755 * \@size is getting too big. We support reading at least 4Kbyte in one chunk
1756 * unless the read would cross a section boundary.
1758 * Returns the number of bytes read on success, a negative error code otherwise.
1760 * Returns -pte_invalid if \@iscache or \@buffer is NULL.
1761 * Returns -pte_invalid if \@size is zero.
1762 * Returns -pte_nomap if \@vaddr is not contained in section \@isid.
1763 * Returns -pte_bad_image if \@iscache does not contain \@isid.
1765 extern pt_export int pt_iscache_read(struct pt_image_section_cache *iscache,
1766 uint8_t *buffer, uint64_t size, int isid,
1769 /** The traced memory image. */
1773 /** Allocate a traced memory image.
1775 * An optional \@name may be given to the image. The name string is copied.
1777 * Returns a new traced memory image on success, NULL otherwise.
1779 extern pt_export struct pt_image *pt_image_alloc(const char *name);
1781 /** Free a traced memory image.
1783 * The \@image must have been allocated with pt_image_alloc().
1784 * The \@image must not be used after a successful return.
1786 extern pt_export void pt_image_free(struct pt_image *image);
1788 /** Get the image name.
1790 * Returns a pointer to \@image's name or NULL if there is no name.
1792 extern pt_export const char *pt_image_name(const struct pt_image *image);
1794 /** Add a new file section to the traced memory image.
1796 * Adds \@size bytes starting at \@offset in \@filename. The section is
1797 * loaded at the virtual address \@vaddr in the address space \@asid.
1799 * The \@asid may be NULL or (partially) invalid. In that case only the valid
1800 * fields are considered when comparing with other address-spaces. Use this
1801 * when tracing a single process or when adding sections to all processes.
1803 * The section is silently truncated to match the size of \@filename.
1805 * Existing sections that would overlap with the new section will be shrunk
1808 * Returns zero on success, a negative error code otherwise.
1810 * Returns -pte_invalid if \@image or \@filename is NULL.
1811 * Returns -pte_invalid if \@offset is too big.
1813 extern pt_export int pt_image_add_file(struct pt_image *image,
1814 const char *filename, uint64_t offset,
1816 const struct pt_asid *asid,
1819 /** Add a section from an image section cache.
1821 * Add the section from \@iscache identified by \@isid in address space \@asid.
1823 * Existing sections that would overlap with the new section will be shrunk
1826 * Returns zero on success, a negative error code otherwise.
1827 * Returns -pte_invalid if \@image or \@iscache is NULL.
1828 * Returns -pte_bad_image if \@iscache does not contain \@isid.
1830 extern pt_export int pt_image_add_cached(struct pt_image *image,
1831 struct pt_image_section_cache *iscache,
1832 int isid, const struct pt_asid *asid);
1836 * Adds all sections from \@src to \@image. Sections that could not be added
1839 * Returns the number of ignored sections on success, a negative error code
1842 * Returns -pte_invalid if \@image or \@src is NULL.
1844 extern pt_export int pt_image_copy(struct pt_image *image,
1845 const struct pt_image *src);
1847 /** Remove all sections loaded from a file.
1849 * Removes all sections loaded from \@filename from the address space \@asid.
1850 * Specify the same \@asid that was used for adding sections from \@filename.
1852 * Returns the number of removed sections on success, a negative error code
1855 * Returns -pte_invalid if \@image or \@filename is NULL.
1857 extern pt_export int pt_image_remove_by_filename(struct pt_image *image,
1858 const char *filename,
1859 const struct pt_asid *asid);
1861 /** Remove all sections loaded into an address space.
1863 * Removes all sections loaded into \@asid. Specify the same \@asid that was
1864 * used for adding sections.
1866 * Returns the number of removed sections on success, a negative error code
1869 * Returns -pte_invalid if \@image is NULL.
1871 extern pt_export int pt_image_remove_by_asid(struct pt_image *image,
1872 const struct pt_asid *asid);
1874 /** A read memory callback function.
1876 * It shall read \@size bytes of memory from address space \@asid starting
1877 * at \@ip into \@buffer.
1879 * It shall return the number of bytes read on success.
1880 * It shall return a negative pt_error_code otherwise.
1882 typedef int (read_memory_callback_t)(uint8_t *buffer, size_t size,
1883 const struct pt_asid *asid,
1884 uint64_t ip, void *context);
1886 /** Set the memory callback for the traced memory image.
1888 * Sets \@callback for reading memory. The callback is used for addresses
1889 * that are not found in file sections. The \@context argument is passed
1890 * to \@callback on each use.
1892 * There can only be one callback at any time. A subsequent call will replace
1893 * the previous callback. If \@callback is NULL, the callback is removed.
1895 * Returns -pte_invalid if \@image is NULL.
1897 extern pt_export int pt_image_set_callback(struct pt_image *image,
1898 read_memory_callback_t *callback,
1903 /* Instruction flow decoder. */
1907 /** The instruction class.
1909 * We provide only a very coarse classification suitable for reconstructing
1910 * the execution flow.
1912 enum pt_insn_class {
1913 /* The instruction could not be classified. */
1916 /* The instruction is something not listed below. */
1919 /* The instruction is a near (function) call. */
1922 /* The instruction is a near (function) return. */
1925 /* The instruction is a near unconditional jump. */
1928 /* The instruction is a near conditional jump. */
1931 /* The instruction is a call-like far transfer.
1932 * E.g. SYSCALL, SYSENTER, or FAR CALL.
1936 /* The instruction is a return-like far transfer.
1937 * E.g. SYSRET, SYSEXIT, IRET, or FAR RET.
1941 /* The instruction is a jump-like far transfer.
1946 /* The instruction is a PTWRITE. */
1950 /** The maximal size of an instruction. */
1952 pt_max_insn_size = 15
1955 /** A single traced instruction. */
1957 /** The virtual address in its process. */
1960 /** The image section identifier for the section containing this
1963 * A value of zero means that the section did not have an identifier.
1964 * The section was not added via an image section cache or the memory
1965 * was read via the read memory callback.
1969 /** The execution mode. */
1970 enum pt_exec_mode mode;
1972 /** A coarse classification. */
1973 enum pt_insn_class iclass;
1975 /** The raw bytes. */
1976 uint8_t raw[pt_max_insn_size];
1978 /** The size in bytes. */
1981 /** A collection of flags giving additional information:
1983 * - the instruction was executed speculatively.
1985 uint32_t speculative:1;
1987 /** - this instruction is truncated in its image section.
1989 * It starts in the image section identified by \@isid and continues
1990 * in one or more other sections.
1992 uint32_t truncated:1;
1996 /** Allocate an Intel PT instruction flow decoder.
1998 * The decoder will work on the buffer defined in \@config, it shall contain
1999 * raw trace data and remain valid for the lifetime of the decoder.
2001 * The decoder needs to be synchronized before it can be used.
2003 extern pt_export struct pt_insn_decoder *
2004 pt_insn_alloc_decoder(const struct pt_config *config);
2006 /** Free an Intel PT instruction flow decoder.
2008 * This will destroy the decoder's default image.
2010 * The \@decoder must not be used after a successful return.
2012 extern pt_export void pt_insn_free_decoder(struct pt_insn_decoder *decoder);
2014 /** Synchronize an Intel PT instruction flow decoder.
2016 * Search for the next synchronization point in forward or backward direction.
2018 * If \@decoder has not been synchronized, yet, the search is started at the
2019 * beginning of the trace buffer in case of forward synchronization and at the
2020 * end of the trace buffer in case of backward synchronization.
2022 * Returns zero or a positive value on success, a negative error code otherwise.
2024 * Returns -pte_bad_opc if an unknown packet is encountered.
2025 * Returns -pte_bad_packet if an unknown packet payload is encountered.
2026 * Returns -pte_eos if no further synchronization point is found.
2027 * Returns -pte_invalid if \@decoder is NULL.
2029 extern pt_export int pt_insn_sync_forward(struct pt_insn_decoder *decoder);
2030 extern pt_export int pt_insn_sync_backward(struct pt_insn_decoder *decoder);
2032 /** Manually synchronize an Intel PT instruction flow decoder.
2034 * Synchronize \@decoder on the syncpoint at \@offset. There must be a PSB
2035 * packet at \@offset.
2037 * Returns zero or a positive value on success, a negative error code otherwise.
2039 * Returns -pte_bad_opc if an unknown packet is encountered.
2040 * Returns -pte_bad_packet if an unknown packet payload is encountered.
2041 * Returns -pte_eos if \@offset lies outside of \@decoder's trace buffer.
2042 * Returns -pte_eos if \@decoder reaches the end of its trace buffer.
2043 * Returns -pte_invalid if \@decoder is NULL.
2044 * Returns -pte_nosync if there is no syncpoint at \@offset.
2046 extern pt_export int pt_insn_sync_set(struct pt_insn_decoder *decoder,
2049 /** Get the current decoder position.
2051 * Fills the current \@decoder position into \@offset.
2053 * This is useful for reporting errors.
2055 * Returns zero on success, a negative error code otherwise.
2057 * Returns -pte_invalid if \@decoder or \@offset is NULL.
2058 * Returns -pte_nosync if \@decoder is out of sync.
2060 extern pt_export int pt_insn_get_offset(const struct pt_insn_decoder *decoder,
2063 /** Get the position of the last synchronization point.
2065 * Fills the last synchronization position into \@offset.
2067 * Returns zero on success, a negative error code otherwise.
2069 * Returns -pte_invalid if \@decoder or \@offset is NULL.
2070 * Returns -pte_nosync if \@decoder is out of sync.
2072 extern pt_export int
2073 pt_insn_get_sync_offset(const struct pt_insn_decoder *decoder,
2076 /** Get the traced image.
2078 * The returned image may be modified as long as no decoder that uses this
2081 * Returns a pointer to the traced image the decoder uses for reading memory.
2082 * Returns NULL if \@decoder is NULL.
2084 extern pt_export struct pt_image *
2085 pt_insn_get_image(struct pt_insn_decoder *decoder);
2087 /** Set the traced image.
2089 * Sets the image that \@decoder uses for reading memory to \@image. If \@image
2090 * is NULL, sets the image to \@decoder's default image.
2092 * Only one image can be active at any time.
2094 * Returns zero on success, a negative error code otherwise.
2095 * Return -pte_invalid if \@decoder is NULL.
2097 extern pt_export int pt_insn_set_image(struct pt_insn_decoder *decoder,
2098 struct pt_image *image);
2100 /* Return a pointer to \@decoder's configuration.
2102 * Returns a non-null pointer on success, NULL if \@decoder is NULL.
2104 extern pt_export const struct pt_config *
2105 pt_insn_get_config(const struct pt_insn_decoder *decoder);
2107 /** Return the current time.
2109 * On success, provides the time at the last preceding timing packet in \@time.
2111 * The time is similar to what a rdtsc instruction would return. Depending
2112 * on the configuration, the time may not be fully accurate. If TSC is not
2113 * enabled, the time is relative to the last synchronization and can't be used
2114 * to correlate with other TSC-based time sources. In this case, -pte_no_time
2115 * is returned and the relative time is provided in \@time.
2117 * Some timing-related packets may need to be dropped (mostly due to missing
2118 * calibration or incomplete configuration). To get an idea about the quality
2119 * of the estimated time, we record the number of dropped MTC and CYC packets.
2121 * If \@lost_mtc is not NULL, set it to the number of lost MTC packets.
2122 * If \@lost_cyc is not NULL, set it to the number of lost CYC packets.
2124 * Returns zero on success, a negative error code otherwise.
2126 * Returns -pte_invalid if \@decoder or \@time is NULL.
2127 * Returns -pte_no_time if there has not been a TSC packet.
2129 extern pt_export int pt_insn_time(struct pt_insn_decoder *decoder,
2130 uint64_t *time, uint32_t *lost_mtc,
2131 uint32_t *lost_cyc);
2133 /** Return the current core bus ratio.
2135 * On success, provides the current core:bus ratio in \@cbr. The ratio is
2136 * defined as core cycles per bus clock cycle.
2138 * Returns zero on success, a negative error code otherwise.
2140 * Returns -pte_invalid if \@decoder or \@cbr is NULL.
2141 * Returns -pte_no_cbr if there has not been a CBR packet.
2143 extern pt_export int pt_insn_core_bus_ratio(struct pt_insn_decoder *decoder,
2146 /** Return the current address space identifier.
2148 * On success, provides the current address space identifier in \@asid.
2150 * The \@size argument must be set to sizeof(struct pt_asid). At most \@size
2151 * bytes will be copied and \@asid->size will be set to the actual size of the
2152 * provided address space identifier.
2154 * Returns zero on success, a negative error code otherwise.
2156 * Returns -pte_invalid if \@decoder or \@asid is NULL.
2158 extern pt_export int pt_insn_asid(const struct pt_insn_decoder *decoder,
2159 struct pt_asid *asid, size_t size);
2161 /** Determine the next instruction.
2163 * On success, provides the next instruction in execution order in \@insn.
2165 * The \@size argument must be set to sizeof(struct pt_insn).
2167 * Returns a non-negative pt_status_flag bit-vector on success, a negative error
2170 * Returns pts_eos to indicate the end of the trace stream. Subsequent calls
2171 * to pt_insn_next() will continue to return pts_eos until trace is required
2172 * to determine the next instruction.
2174 * Returns -pte_bad_context if the decoder encountered an unexpected packet.
2175 * Returns -pte_bad_opc if the decoder encountered unknown packets.
2176 * Returns -pte_bad_packet if the decoder encountered unknown packet payloads.
2177 * Returns -pte_bad_query if the decoder got out of sync.
2178 * Returns -pte_eos if decoding reached the end of the Intel PT buffer.
2179 * Returns -pte_invalid if \@decoder or \@insn is NULL.
2180 * Returns -pte_nomap if the memory at the instruction address can't be read.
2181 * Returns -pte_nosync if \@decoder is out of sync.
2183 extern pt_export int pt_insn_next(struct pt_insn_decoder *decoder,
2184 struct pt_insn *insn, size_t size);
2186 /** Get the next pending event.
2188 * On success, provides the next event in \@event and updates \@decoder.
2190 * The \@size argument must be set to sizeof(struct pt_event).
2192 * Returns a non-negative pt_status_flag bit-vector on success, a negative error
2195 * Returns -pte_bad_query if there is no event.
2196 * Returns -pte_invalid if \@decoder or \@event is NULL.
2197 * Returns -pte_invalid if \@size is too small.
2199 extern pt_export int pt_insn_event(struct pt_insn_decoder *decoder,
2200 struct pt_event *event, size_t size);
2204 /* Block decoder. */
2208 /** A block of instructions.
2210 * Instructions in this block are executed sequentially but are not necessarily
2211 * contiguous in memory. Users are expected to follow direct branches.
2214 /** The IP of the first instruction in this block. */
2217 /** The IP of the last instruction in this block.
2219 * This can be used for error-detection.
2223 /** The image section that contains the instructions in this block.
2225 * A value of zero means that the section did not have an identifier.
2226 * The section was not added via an image section cache or the memory
2227 * was read via the read memory callback.
2231 /** The execution mode for all instructions in this block. */
2232 enum pt_exec_mode mode;
2234 /** The instruction class for the last instruction in this block.
2236 * This field may be set to ptic_error to indicate that the instruction
2237 * class is not available. The block decoder may choose to not provide
2238 * the instruction class in some cases for performance reasons.
2240 enum pt_insn_class iclass;
2242 /** The number of instructions in this block. */
2245 /** The raw bytes of the last instruction in this block in case the
2246 * instruction does not fit entirely into this block's section.
2248 * This field is only valid if \@truncated is set.
2250 uint8_t raw[pt_max_insn_size];
2252 /** The size of the last instruction in this block in bytes.
2254 * This field is only valid if \@truncated is set.
2258 /** A collection of flags giving additional information about the
2259 * instructions in this block.
2261 * - all instructions in this block were executed speculatively.
2263 uint32_t speculative:1;
2265 /** - the last instruction in this block is truncated.
2267 * It starts in this block's section but continues in one or more
2268 * other sections depending on how fragmented the memory image is.
2270 * The raw bytes for the last instruction are provided in \@raw and
2271 * its size in \@size in this case.
2273 uint32_t truncated:1;
2276 /** Allocate an Intel PT block decoder.
2278 * The decoder will work on the buffer defined in \@config, it shall contain
2279 * raw trace data and remain valid for the lifetime of the decoder.
2281 * The decoder needs to be synchronized before it can be used.
2283 extern pt_export struct pt_block_decoder *
2284 pt_blk_alloc_decoder(const struct pt_config *config);
2286 /** Free an Intel PT block decoder.
2288 * This will destroy the decoder's default image.
2290 * The \@decoder must not be used after a successful return.
2292 extern pt_export void pt_blk_free_decoder(struct pt_block_decoder *decoder);
2294 /** Synchronize an Intel PT block decoder.
2296 * Search for the next synchronization point in forward or backward direction.
2298 * If \@decoder has not been synchronized, yet, the search is started at the
2299 * beginning of the trace buffer in case of forward synchronization and at the
2300 * end of the trace buffer in case of backward synchronization.
2302 * Returns zero or a positive value on success, a negative error code otherwise.
2304 * Returns -pte_bad_opc if an unknown packet is encountered.
2305 * Returns -pte_bad_packet if an unknown packet payload is encountered.
2306 * Returns -pte_eos if no further synchronization point is found.
2307 * Returns -pte_invalid if \@decoder is NULL.
2309 extern pt_export int pt_blk_sync_forward(struct pt_block_decoder *decoder);
2310 extern pt_export int pt_blk_sync_backward(struct pt_block_decoder *decoder);
2312 /** Manually synchronize an Intel PT block decoder.
2314 * Synchronize \@decoder on the syncpoint at \@offset. There must be a PSB
2315 * packet at \@offset.
2317 * Returns zero or a positive value on success, a negative error code otherwise.
2319 * Returns -pte_bad_opc if an unknown packet is encountered.
2320 * Returns -pte_bad_packet if an unknown packet payload is encountered.
2321 * Returns -pte_eos if \@offset lies outside of \@decoder's trace buffer.
2322 * Returns -pte_eos if \@decoder reaches the end of its trace buffer.
2323 * Returns -pte_invalid if \@decoder is NULL.
2324 * Returns -pte_nosync if there is no syncpoint at \@offset.
2326 extern pt_export int pt_blk_sync_set(struct pt_block_decoder *decoder,
2329 /** Get the current decoder position.
2331 * Fills the current \@decoder position into \@offset.
2333 * This is useful for reporting errors.
2335 * Returns zero on success, a negative error code otherwise.
2337 * Returns -pte_invalid if \@decoder or \@offset is NULL.
2338 * Returns -pte_nosync if \@decoder is out of sync.
2340 extern pt_export int pt_blk_get_offset(const struct pt_block_decoder *decoder,
2343 /** Get the position of the last synchronization point.
2345 * Fills the last synchronization position into \@offset.
2347 * Returns zero on success, a negative error code otherwise.
2349 * Returns -pte_invalid if \@decoder or \@offset is NULL.
2350 * Returns -pte_nosync if \@decoder is out of sync.
2352 extern pt_export int
2353 pt_blk_get_sync_offset(const struct pt_block_decoder *decoder,
2356 /** Get the traced image.
2358 * The returned image may be modified as long as \@decoder is not running.
2360 * Returns a pointer to the traced image \@decoder uses for reading memory.
2361 * Returns NULL if \@decoder is NULL.
2363 extern pt_export struct pt_image *
2364 pt_blk_get_image(struct pt_block_decoder *decoder);
2366 /** Set the traced image.
2368 * Sets the image that \@decoder uses for reading memory to \@image. If \@image
2369 * is NULL, sets the image to \@decoder's default image.
2371 * Only one image can be active at any time.
2373 * Returns zero on success, a negative error code otherwise.
2374 * Return -pte_invalid if \@decoder is NULL.
2376 extern pt_export int pt_blk_set_image(struct pt_block_decoder *decoder,
2377 struct pt_image *image);
2379 /* Return a pointer to \@decoder's configuration.
2381 * Returns a non-null pointer on success, NULL if \@decoder is NULL.
2383 extern pt_export const struct pt_config *
2384 pt_blk_get_config(const struct pt_block_decoder *decoder);
2386 /** Return the current time.
2388 * On success, provides the time at the last preceding timing packet in \@time.
2390 * The time is similar to what a rdtsc instruction would return. Depending
2391 * on the configuration, the time may not be fully accurate. If TSC is not
2392 * enabled, the time is relative to the last synchronization and can't be used
2393 * to correlate with other TSC-based time sources. In this case, -pte_no_time
2394 * is returned and the relative time is provided in \@time.
2396 * Some timing-related packets may need to be dropped (mostly due to missing
2397 * calibration or incomplete configuration). To get an idea about the quality
2398 * of the estimated time, we record the number of dropped MTC and CYC packets.
2400 * If \@lost_mtc is not NULL, set it to the number of lost MTC packets.
2401 * If \@lost_cyc is not NULL, set it to the number of lost CYC packets.
2403 * Returns zero on success, a negative error code otherwise.
2405 * Returns -pte_invalid if \@decoder or \@time is NULL.
2406 * Returns -pte_no_time if there has not been a TSC packet.
2408 extern pt_export int pt_blk_time(struct pt_block_decoder *decoder,
2409 uint64_t *time, uint32_t *lost_mtc,
2410 uint32_t *lost_cyc);
2412 /** Return the current core bus ratio.
2414 * On success, provides the current core:bus ratio in \@cbr. The ratio is
2415 * defined as core cycles per bus clock cycle.
2417 * Returns zero on success, a negative error code otherwise.
2419 * Returns -pte_invalid if \@decoder or \@cbr is NULL.
2420 * Returns -pte_no_cbr if there has not been a CBR packet.
2422 extern pt_export int pt_blk_core_bus_ratio(struct pt_block_decoder *decoder,
2425 /** Return the current address space identifier.
2427 * On success, provides the current address space identifier in \@asid.
2429 * The \@size argument must be set to sizeof(struct pt_asid). At most \@size
2430 * bytes will be copied and \@asid->size will be set to the actual size of the
2431 * provided address space identifier.
2433 * Returns zero on success, a negative error code otherwise.
2435 * Returns -pte_invalid if \@decoder or \@asid is NULL.
2437 extern pt_export int pt_blk_asid(const struct pt_block_decoder *decoder,
2438 struct pt_asid *asid, size_t size);
2440 /** Determine the next block of instructions.
2442 * On success, provides the next block of instructions in execution order in
2445 * The \@size argument must be set to sizeof(struct pt_block).
2447 * Returns a non-negative pt_status_flag bit-vector on success, a negative error
2450 * Returns pts_eos to indicate the end of the trace stream. Subsequent calls
2451 * to pt_block_next() will continue to return pts_eos until trace is required
2452 * to determine the next instruction.
2454 * Returns -pte_bad_context if the decoder encountered an unexpected packet.
2455 * Returns -pte_bad_opc if the decoder encountered unknown packets.
2456 * Returns -pte_bad_packet if the decoder encountered unknown packet payloads.
2457 * Returns -pte_bad_query if the decoder got out of sync.
2458 * Returns -pte_eos if decoding reached the end of the Intel PT buffer.
2459 * Returns -pte_invalid if \@decoder or \@block is NULL.
2460 * Returns -pte_nomap if the memory at the instruction address can't be read.
2461 * Returns -pte_nosync if \@decoder is out of sync.
2463 extern pt_export int pt_blk_next(struct pt_block_decoder *decoder,
2464 struct pt_block *block, size_t size);
2466 /** Get the next pending event.
2468 * On success, provides the next event in \@event and updates \@decoder.
2470 * The \@size argument must be set to sizeof(struct pt_event).
2472 * Returns a non-negative pt_status_flag bit-vector on success, a negative error
2475 * Returns -pte_bad_query if there is no event.
2476 * Returns -pte_invalid if \@decoder or \@event is NULL.
2477 * Returns -pte_invalid if \@size is too small.
2479 extern pt_export int pt_blk_event(struct pt_block_decoder *decoder,
2480 struct pt_event *event, size_t size);
2486 #endif /* INTEL_PT_H */