2 * Copyright (c) 2013-2018, 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}
84 #define LIBIPT_VERSION ((LIBIPT_VERSION_MAJOR << 8) + LIBIPT_VERSION_MINOR)
87 /** The library version. */
89 /** Major version number. */
92 /** Minor version number. */
101 /** Version extension. */
106 /** Return the library version. */
107 extern pt_export struct pt_version pt_library_version(void);
117 /* No error. Everything is OK. */
120 /* Internal decoder error. */
123 /* Invalid argument. */
126 /* Decoder out of sync. */
129 /* Unknown opcode. */
132 /* Unknown payload. */
135 /* Unexpected packet context. */
138 /* Decoder reached end of trace stream. */
141 /* No packet matching the query to be found. */
144 /* Decoder out of memory. */
147 /* Bad configuration. */
150 /* There is no IP. */
153 /* The IP has been suppressed. */
156 /* There is no memory mapped at the requested address. */
159 /* An instruction could not be decoded. */
162 /* No wall-clock time is available. */
165 /* No core:bus ratio available. */
168 /* Bad traced image. */
171 /* A locking error. */
174 /* The requested feature is not supported. */
177 /* The return address stack is empty. */
180 /* A compressed return is not indicated correctly by a taken branch. */
183 /* The current decoder state does not match the state in the trace. */
184 pte_bad_status_update,
186 /* The trace did not contain an expected enabled event. */
189 /* An event was ignored. */
192 /* Something overflowed. */
195 /* A file handling error. */
203 /** Decode a function return value into an pt_error_code. */
204 static inline enum pt_error_code pt_errcode(int status)
206 return (status >= 0) ? pte_ok : (enum pt_error_code) -status;
209 /** Return a human readable error string. */
210 extern pt_export const char *pt_errstr(enum pt_error_code);
224 /** A cpu identifier. */
226 /** The cpu vendor. */
227 enum pt_cpu_vendor vendor;
229 /** The cpu family. */
232 /** The cpu model. */
239 /** A collection of Intel PT errata. */
241 /** BDM70: Intel(R) Processor Trace PSB+ Packets May Contain
242 * Unexpected Packets.
244 * Same as: SKD024, SKL021, KBL021.
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.
253 /** BDM64: An Incorrect LBR or Intel(R) Processor Trace Packet May Be
254 * Recorded Following a Transactional Abort.
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.
265 /** SKD007: Intel(R) PT Buffer Overflow May Result in Incorrect Packets.
267 * Same as: SKL049, KBL041.
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
276 /** SKD022: VM Entry That Clears TraceEn May Generate a FUP.
278 * Same as: SKL024, KBL023.
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.
288 /** SKD010: Intel(R) PT FUP May be Dropped After OVF.
290 * Same as: SKD014, SKL033, KBL030.
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).
298 /** SKL014: Intel(R) PT TIP.PGD May Not Have Target IP Payload.
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
310 /** APL12: Intel(R) PT OVF May Be Followed By An Unexpected FUP Packet.
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
322 /** APL11: Intel(R) PT OVF Pakcet May Be Followed by TIP.PGD Packet
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.
333 /* Reserve a few bytes for the future. */
334 uint32_t reserved[15];
337 /** A collection of decoder-specific configuration flags. */
338 struct pt_conf_flags {
339 /** The decoder variant. */
341 /** Flags for the block decoder. */
343 /** End a block after a call instruction. */
344 uint32_t end_on_call:1;
346 /** Enable tick events for timing updates. */
347 uint32_t enable_tick_events:1;
349 /** End a block after a jump instruction. */
350 uint32_t end_on_jump:1;
353 /** Flags for the instruction flow decoder. */
355 /** Enable tick events for timing updates. */
356 uint32_t enable_tick_events:1;
359 /* Reserve a few bytes for future extensions. */
360 uint32_t reserved[4];
364 /** The address filter configuration. */
365 struct pt_conf_addr_filter {
366 /** The address filter configuration.
368 * This corresponds to the respective fields in IA32_RTIT_CTL MSR.
374 uint32_t addr0_cfg:4;
375 uint32_t addr1_cfg:4;
376 uint32_t addr2_cfg:4;
377 uint32_t addr3_cfg:4;
381 /** The address ranges configuration.
383 * This corresponds to the IA32_RTIT_ADDRn_A/B MSRs.
394 /* Reserve some space. */
395 uint64_t reserved[8];
398 /** An unknown packet. */
399 struct pt_packet_unknown;
401 /** An Intel PT decoder configuration.
404 /** The size of the config structure in bytes. */
407 /** The trace buffer begin address. */
410 /** The trace buffer end address. */
413 /** An optional callback for handling unknown packets.
415 * If \@callback is not NULL, it is called for any unknown opcode.
418 /** The callback function.
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.
425 int (*callback)(struct pt_packet_unknown *unknown,
426 const struct pt_config *config,
427 const uint8_t *pos, void *context);
429 /** The user-defined context for this configuration. */
433 /** The cpu on which Intel PT has been recorded. */
436 /** The errata to apply when encoding or decoding Intel PT. */
437 struct pt_errata errata;
439 /* The CTC frequency.
441 * This is only required if MTC packets have been enabled in
442 * IA32_RTIT_CTRL.MTCEn.
444 uint32_t cpuid_0x15_eax, cpuid_0x15_ebx;
446 /* The MTC frequency as defined in IA32_RTIT_CTL.MTCFreq.
448 * This is only required if MTC packets have been enabled in
449 * IA32_RTIT_CTRL.MTCEn.
453 /* The nominal frequency as defined in MSR_PLATFORM_INFO[15:8].
455 * This is only required if CYC packets have been enabled in
456 * IA32_RTIT_CTRL.CYCEn.
458 * If zero, timing calibration will only be able to use MTC and CYC
461 * If not zero, timing calibration will also be able to use CBR
466 /** A collection of decoder-specific flags. */
467 struct pt_conf_flags flags;
469 /** The address filter configuration. */
470 struct pt_conf_addr_filter addr_filter;
474 /** Zero-initialize an Intel PT configuration. */
475 static inline void pt_config_init(struct pt_config *config)
477 memset(config, 0, sizeof(*config));
479 config->size = sizeof(*config);
482 /** Determine errata for a given cpu.
484 * Updates \@errata based on \@cpu.
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.
490 extern pt_export int pt_cpu_errata(struct pt_errata *errata,
491 const struct pt_cpu *cpu);
495 /* Packet encoder / decoder. */
499 /** Intel PT packet types. */
500 enum pt_packet_type {
501 /* An invalid packet. */
504 /* A packet decodable by the optional decoder callback. */
507 /* Actual packets supported by this library. */
535 /** The IP compression. */
536 enum pt_ip_compression {
537 /* The bits encode the payload size and the encoding scheme.
539 * No payload. The IP has been suppressed.
541 pt_ipc_suppressed = 0x0,
543 /* Payload: 16 bits. Update last IP. */
544 pt_ipc_update_16 = 0x01,
546 /* Payload: 32 bits. Update last IP. */
547 pt_ipc_update_32 = 0x02,
549 /* Payload: 48 bits. Sign extend to full address. */
550 pt_ipc_sext_48 = 0x03,
552 /* Payload: 48 bits. Update last IP. */
553 pt_ipc_update_48 = 0x04,
555 /* Payload: 64 bits. Full address. */
559 /** An execution mode. */
567 /** Mode packet leaves. */
573 /** A TNT-8 or TNT-64 packet. */
574 struct pt_packet_tnt {
575 /** TNT payload bit size. */
578 /** TNT payload excluding stop bit. */
582 /** A packet with IP payload. */
583 struct pt_packet_ip {
584 /** IP compression. */
585 enum pt_ip_compression ipc;
587 /** Zero-extended payload ip. */
591 /** A mode.exec packet. */
592 struct pt_packet_mode_exec {
593 /** The mode.exec csl bit. */
596 /** The mode.exec csd bit. */
600 static inline enum pt_exec_mode
601 pt_get_exec_mode(const struct pt_packet_mode_exec *packet)
604 return packet->csd ? ptem_unknown : ptem_64bit;
606 return packet->csd ? ptem_32bit : ptem_16bit;
609 static inline struct pt_packet_mode_exec
610 pt_set_exec_mode(enum pt_exec_mode mode)
612 struct pt_packet_mode_exec packet;
639 /** A mode.tsx packet. */
640 struct pt_packet_mode_tsx {
641 /** The mode.tsx intx bit. */
644 /** The mode.tsx abrt bit. */
648 /** A mode packet. */
649 struct pt_packet_mode {
651 enum pt_mode_leaf leaf;
655 /** Packet: mode.exec. */
656 struct pt_packet_mode_exec exec;
658 /** Packet: mode.tsx. */
659 struct pt_packet_mode_tsx tsx;
664 struct pt_packet_pip {
665 /** The CR3 value. */
668 /** The non-root bit. */
673 struct pt_packet_tsc {
674 /** The TSC value. */
679 struct pt_packet_cbr {
680 /** The core/bus cycle ratio. */
685 struct pt_packet_tma {
686 /** The crystal clock tick counter value. */
689 /** The fast counter value. */
694 struct pt_packet_mtc {
695 /** The crystal clock tick counter value. */
700 struct pt_packet_cyc {
701 /** The cycle counter value. */
705 /** A VMCS packet. */
706 struct pt_packet_vmcs {
707 /* The VMCS Base Address (i.e. the shifted payload). */
712 struct pt_packet_mnt {
713 /** The raw payload. */
717 /** A EXSTOP packet. */
718 struct pt_packet_exstop {
719 /** A flag specifying the binding of the packet:
721 * set: binds to the next FUP.
727 /** A MWAIT packet. */
728 struct pt_packet_mwait {
729 /** The MWAIT hints (EAX). */
732 /** The MWAIT extensions (ECX). */
736 /** A PWRE packet. */
737 struct pt_packet_pwre {
738 /** The resolved thread C-state. */
741 /** The resolved thread sub C-state. */
744 /** A flag indicating whether the C-state entry was initiated by h/w. */
748 /** A PWRX packet. */
749 struct pt_packet_pwrx {
750 /** The core C-state at the time of the wake. */
753 /** The deepest core C-state achieved during sleep. */
758 * - due to external interrupt received.
760 uint32_t interrupt:1;
762 /** - due to store to monitored address. */
765 /** - due to h/w autonomous condition such as HDC. */
766 uint32_t autonomous:1;
770 struct pt_packet_ptw {
771 /** The raw payload. */
774 /** The payload size as encoded in the packet. */
777 /** A flag saying whether a FUP is following PTW that provides
778 * the IP of the corresponding PTWRITE instruction.
783 static inline int pt_ptw_size(uint8_t plc)
794 return -pte_bad_packet;
797 return -pte_internal;
800 /** An unknown packet decodable by the optional decoder callback. */
801 struct pt_packet_unknown {
802 /** Pointer to the raw packet bytes. */
803 const uint8_t *packet;
805 /** Optional pointer to a user-defined structure. */
809 /** An Intel PT packet. */
811 /** The type of the packet.
813 * This also determines the \@payload field.
815 enum pt_packet_type type;
817 /** The size of the packet including opcode and payload. */
820 /** Packet specific data. */
822 /** Packets: pad, ovf, psb, psbend, stop - no payload. */
824 /** Packet: tnt-8, tnt-64. */
825 struct pt_packet_tnt tnt;
827 /** Packet: tip, fup, tip.pge, tip.pgd. */
828 struct pt_packet_ip ip;
831 struct pt_packet_mode mode;
834 struct pt_packet_pip pip;
837 struct pt_packet_tsc tsc;
840 struct pt_packet_cbr cbr;
843 struct pt_packet_tma tma;
846 struct pt_packet_mtc mtc;
849 struct pt_packet_cyc cyc;
852 struct pt_packet_vmcs vmcs;
855 struct pt_packet_mnt mnt;
857 /** Packet: exstop. */
858 struct pt_packet_exstop exstop;
860 /** Packet: mwait. */
861 struct pt_packet_mwait mwait;
864 struct pt_packet_pwre pwre;
867 struct pt_packet_pwrx pwrx;
870 struct pt_packet_ptw ptw;
872 /** Packet: unknown. */
873 struct pt_packet_unknown unknown;
879 /* Packet encoder. */
883 /** Allocate an Intel PT packet encoder.
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.
888 * The encoder starts at the beginning of the trace buffer.
890 extern pt_export struct pt_encoder *
891 pt_alloc_encoder(const struct pt_config *config);
893 /** Free an Intel PT packet encoder.
895 * The \@encoder must not be used after a successful return.
897 extern pt_export void pt_free_encoder(struct pt_encoder *encoder);
899 /** Hard set synchronization point of an Intel PT packet encoder.
901 * Synchronize \@encoder to \@offset within the trace buffer.
903 * Returns zero on success, a negative error code otherwise.
905 * Returns -pte_eos if the given offset is behind the end of the trace buffer.
906 * Returns -pte_invalid if \@encoder is NULL.
908 extern pt_export int pt_enc_sync_set(struct pt_encoder *encoder,
911 /** Get the current packet encoder position.
913 * Fills the current \@encoder position into \@offset.
915 * This is useful for reporting errors.
917 * Returns zero on success, a negative error code otherwise.
919 * Returns -pte_invalid if \@encoder or \@offset is NULL.
921 extern pt_export int pt_enc_get_offset(const struct pt_encoder *encoder,
924 /* Return a pointer to \@encoder's configuration.
926 * Returns a non-null pointer on success, NULL if \@encoder is NULL.
928 extern pt_export const struct pt_config *
929 pt_enc_get_config(const struct pt_encoder *encoder);
931 /** Encode an Intel PT packet.
933 * Writes \@packet at \@encoder's current position in the Intel PT buffer and
934 * advances the \@encoder beyond the written packet.
936 * The \@packet.size field is ignored.
938 * In case of errors, the \@encoder is not advanced and nothing is written
939 * into the Intel PT buffer.
941 * Returns the number of bytes written on success, a negative error code
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.
949 extern pt_export int pt_enc_next(struct pt_encoder *encoder,
950 const struct pt_packet *packet);
954 /* Packet decoder. */
958 /** Allocate an Intel PT packet decoder.
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.
963 * The decoder needs to be synchronized before it can be used.
965 extern pt_export struct pt_packet_decoder *
966 pt_pkt_alloc_decoder(const struct pt_config *config);
968 /** Free an Intel PT packet decoder.
970 * The \@decoder must not be used after a successful return.
972 extern pt_export void pt_pkt_free_decoder(struct pt_packet_decoder *decoder);
974 /** Synchronize an Intel PT packet decoder.
976 * Search for the next synchronization point in forward or backward direction.
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.
982 * Returns zero or a positive value on success, a negative error code otherwise.
984 * Returns -pte_eos if no further synchronization point is found.
985 * Returns -pte_invalid if \@decoder is NULL.
987 extern pt_export int pt_pkt_sync_forward(struct pt_packet_decoder *decoder);
988 extern pt_export int pt_pkt_sync_backward(struct pt_packet_decoder *decoder);
990 /** Hard set synchronization point of an Intel PT decoder.
992 * Synchronize \@decoder to \@offset within the trace buffer.
994 * Returns zero on success, a negative error code otherwise.
996 * Returns -pte_eos if the given offset is behind the end of the trace buffer.
997 * Returns -pte_invalid if \@decoder is NULL.
999 extern pt_export int pt_pkt_sync_set(struct pt_packet_decoder *decoder,
1002 /** Get the current decoder position.
1004 * Fills the current \@decoder position into \@offset.
1006 * This is useful for reporting errors.
1008 * Returns zero on success, a negative error code otherwise.
1010 * Returns -pte_invalid if \@decoder or \@offset is NULL.
1011 * Returns -pte_nosync if \@decoder is out of sync.
1013 extern pt_export int pt_pkt_get_offset(const struct pt_packet_decoder *decoder,
1016 /** Get the position of the last synchronization point.
1018 * Fills the last synchronization position into \@offset.
1020 * This is useful when splitting a trace stream for parallel decoding.
1022 * Returns zero on success, a negative error code otherwise.
1024 * Returns -pte_invalid if \@decoder or \@offset is NULL.
1025 * Returns -pte_nosync if \@decoder is out of sync.
1027 extern pt_export int
1028 pt_pkt_get_sync_offset(const struct pt_packet_decoder *decoder,
1031 /* Return a pointer to \@decoder's configuration.
1033 * Returns a non-null pointer on success, NULL if \@decoder is NULL.
1035 extern pt_export const struct pt_config *
1036 pt_pkt_get_config(const struct pt_packet_decoder *decoder);
1038 /** Decode the next packet and advance the decoder.
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
1044 * The \@size argument must be set to sizeof(struct pt_packet).
1046 * Returns the number of bytes consumed on success, a negative error code
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.
1055 extern pt_export int pt_pkt_next(struct pt_packet_decoder *decoder,
1056 struct pt_packet *packet, size_t size);
1060 /* Query decoder. */
1064 /** Decoder status flags. */
1065 enum pt_status_flag {
1066 /** There is an event pending. */
1067 pts_event_pending = 1 << 0,
1069 /** The address has been suppressed. */
1070 pts_ip_suppressed = 1 << 1,
1072 /** There is no more trace data available. */
1077 enum pt_event_type {
1078 /* Tracing has been enabled/disabled. */
1082 /* Tracing has been disabled asynchronously. */
1083 ptev_async_disabled,
1085 /* An asynchronous branch, e.g. interrupt. */
1088 /* A synchronous paging event. */
1091 /* An asynchronous paging event. */
1094 /* Trace overflow. */
1097 /* An execution mode change. */
1100 /* A transactional execution state change. */
1106 /* A synchronous vmcs event. */
1109 /* An asynchronous vmcs event. */
1112 /* Execution has stopped. */
1115 /* An MWAIT operation completed. */
1118 /* A power state was entered. */
1121 /* A power state was exited. */
1124 /* A PTWRITE event. */
1127 /* A timing event. */
1130 /* A core:bus ratio event. */
1133 /* A maintenance event. */
1139 /** The type of the event. */
1140 enum pt_event_type type;
1142 /** A flag indicating that the event IP has been suppressed. */
1143 uint32_t ip_suppressed:1;
1145 /** A flag indicating that the event is for status update. */
1146 uint32_t status_update:1;
1148 /** A flag indicating that the event has timing information. */
1151 /** The time stamp count of the event.
1153 * This field is only valid if \@has_tsc is set.
1157 /** The number of lost mtc and cyc packets.
1159 * This gives an idea about the quality of the \@tsc. The more packets
1160 * were dropped, the less precise timing is.
1165 /* Reserved space for future extensions. */
1166 uint64_t reserved[2];
1168 /** Event specific data. */
1170 /** Event: enabled. */
1172 /** The address at which tracing resumes. */
1175 /** A flag indicating that tracing resumes from the IP
1176 * at which tracing had been disabled before.
1181 /** Event: disabled. */
1183 /** The destination of the first branch inside a
1186 * This field is not valid if \@ip_suppressed is set.
1190 /* The exact source ip needs to be determined using
1191 * disassembly and the filter configuration.
1195 /** Event: async disabled. */
1197 /** The source address of the asynchronous branch that
1202 /** The destination of the first branch inside a
1205 * This field is not valid if \@ip_suppressed is set.
1210 /** Event: async branch. */
1212 /** The branch source address. */
1215 /** The branch destination address.
1217 * This field is not valid if \@ip_suppressed is set.
1222 /** Event: paging. */
1224 /** The updated CR3 value.
1226 * The lower 5 bit have been zeroed out.
1227 * The upper bits have been zeroed out depending on the
1228 * maximum possible address.
1232 /** A flag indicating whether the cpu is operating in
1233 * vmx non-root (guest) mode.
1235 uint32_t non_root:1;
1237 /* The address at which the event is effective is
1238 * obvious from the disassembly.
1242 /** Event: async paging. */
1244 /** The updated CR3 value.
1246 * The lower 5 bit have been zeroed out.
1247 * The upper bits have been zeroed out depending on the
1248 * maximum possible address.
1252 /** A flag indicating whether the cpu is operating in
1253 * vmx non-root (guest) mode.
1255 uint32_t non_root:1;
1257 /** The address at which the event is effective. */
1261 /** Event: overflow. */
1263 /** The address at which tracing resumes after overflow.
1265 * This field is not valid, if ip_suppressed is set.
1266 * In this case, the overflow resolved while tracing
1272 /** Event: exec mode. */
1274 /** The execution mode. */
1275 enum pt_exec_mode mode;
1277 /** The address at which the event is effective. */
1283 /** The address at which the event is effective.
1285 * This field is not valid if \@ip_suppressed is set.
1289 /** A flag indicating speculative execution mode. */
1290 uint32_t speculative:1;
1292 /** A flag indicating speculative execution aborts. */
1298 /** The VMCS base address.
1300 * The address is zero-extended with the lower 12 bits
1305 /* The new VMCS base address should be stored and
1306 * applied on subsequent VM entries.
1310 /** Event: async vmcs. */
1312 /** The VMCS base address.
1314 * The address is zero-extended with the lower 12 bits
1319 /** The address at which the event is effective. */
1322 /* An async paging event that binds to the same IP
1323 * will always succeed this async vmcs event.
1327 /** Event: execution stopped. */
1329 /** The address at which execution has stopped. This is
1330 * the last instruction that did not complete.
1332 * This field is not valid, if \@ip_suppressed is set.
1337 /** Event: mwait. */
1339 /** The address of the instruction causing the mwait.
1341 * This field is not valid, if \@ip_suppressed is set.
1345 /** The mwait hints (eax).
1347 * Reserved bits are undefined.
1351 /** The mwait extensions (ecx).
1353 * Reserved bits are undefined.
1358 /** Event: power state entry. */
1360 /** The resolved thread C-state. */
1363 /** The resolved thread sub C-state. */
1366 /** A flag indicating whether the C-state entry was
1372 /** Event: power state exit. */
1374 /** The core C-state at the time of the wake. */
1377 /** The deepest core C-state achieved during sleep. */
1380 /** The wake reason:
1382 * - due to external interrupt received.
1384 uint32_t interrupt:1;
1386 /** - due to store to monitored address. */
1389 /** - due to h/w autonomous condition such as HDC. */
1390 uint32_t autonomous:1;
1393 /** Event: ptwrite. */
1395 /** The address of the ptwrite instruction.
1397 * This field is not valid, if \@ip_suppressed is set.
1399 * In this case, the address is obvious from the
1404 /** The size of the below \@payload in bytes. */
1407 /** The ptwrite payload. */
1413 /** The instruction address near which the tick occured.
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).
1419 * This field is not valid, if \@ip_suppressed is set.
1426 /** The core:bus ratio. */
1432 /** The raw payload. */
1439 /** Allocate an Intel PT query decoder.
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.
1444 * The decoder needs to be synchronized before it can be used.
1446 extern pt_export struct pt_query_decoder *
1447 pt_qry_alloc_decoder(const struct pt_config *config);
1449 /** Free an Intel PT query decoder.
1451 * The \@decoder must not be used after a successful return.
1453 extern pt_export void pt_qry_free_decoder(struct pt_query_decoder *decoder);
1455 /** Synchronize an Intel PT query decoder.
1457 * Search for the next synchronization point in forward or backward direction.
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.
1463 * If \@ip is not NULL, set it to last ip.
1465 * Returns a non-negative pt_status_flag bit-vector on success, a negative error
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.
1473 extern pt_export int pt_qry_sync_forward(struct pt_query_decoder *decoder,
1475 extern pt_export int pt_qry_sync_backward(struct pt_query_decoder *decoder,
1478 /** Manually synchronize an Intel PT query decoder.
1480 * Synchronize \@decoder on the syncpoint at \@offset. There must be a PSB
1481 * packet at \@offset.
1483 * If \@ip is not NULL, set it to last ip.
1485 * Returns a non-negative pt_status_flag bit-vector on success, a negative error
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.
1495 extern pt_export int pt_qry_sync_set(struct pt_query_decoder *decoder,
1496 uint64_t *ip, uint64_t offset);
1498 /** Get the current decoder position.
1500 * Fills the current \@decoder position into \@offset.
1502 * This is useful for reporting errors.
1504 * Returns zero on success, a negative error code otherwise.
1506 * Returns -pte_invalid if \@decoder or \@offset is NULL.
1507 * Returns -pte_nosync if \@decoder is out of sync.
1509 extern pt_export int pt_qry_get_offset(const struct pt_query_decoder *decoder,
1512 /** Get the position of the last synchronization point.
1514 * Fills the last synchronization position into \@offset.
1516 * This is useful for splitting a trace stream for parallel decoding.
1518 * Returns zero on success, a negative error code otherwise.
1520 * Returns -pte_invalid if \@decoder or \@offset is NULL.
1521 * Returns -pte_nosync if \@decoder is out of sync.
1523 extern pt_export int
1524 pt_qry_get_sync_offset(const struct pt_query_decoder *decoder,
1527 /* Return a pointer to \@decoder's configuration.
1529 * Returns a non-null pointer on success, NULL if \@decoder is NULL.
1531 extern pt_export const struct pt_config *
1532 pt_qry_get_config(const struct pt_query_decoder *decoder);
1534 /** Query whether the next unconditional branch has been taken.
1536 * On success, provides 1 (taken) or 0 (not taken) in \@taken for the next
1537 * conditional branch and updates \@decoder.
1539 * Returns a non-negative pt_status_flag bit-vector on success, a negative error
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.
1549 extern pt_export int pt_qry_cond_branch(struct pt_query_decoder *decoder,
1552 /** Get the next indirect branch destination.
1554 * On success, provides the linear destination address of the next indirect
1555 * branch in \@ip and updates \@decoder.
1557 * Returns a non-negative pt_status_flag bit-vector on success, a negative error
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.
1567 extern pt_export int pt_qry_indirect_branch(struct pt_query_decoder *decoder,
1570 /** Query the next pending event.
1572 * On success, provides the next event \@event and updates \@decoder.
1574 * The \@size argument must be set to sizeof(struct pt_event).
1576 * Returns a non-negative pt_status_flag bit-vector on success, a negative error
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.
1587 extern pt_export int pt_qry_event(struct pt_query_decoder *decoder,
1588 struct pt_event *event, size_t size);
1590 /** Query the current time.
1592 * On success, provides the time at the last query in \@time.
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.
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.
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.
1607 * Returns zero on success, a negative error code otherwise.
1609 * Returns -pte_invalid if \@decoder or \@time is NULL.
1610 * Returns -pte_no_time if there has not been a TSC packet.
1612 extern pt_export int pt_qry_time(struct pt_query_decoder *decoder,
1613 uint64_t *time, uint32_t *lost_mtc,
1614 uint32_t *lost_cyc);
1616 /** Return the current core bus ratio.
1618 * On success, provides the current core:bus ratio in \@cbr. The ratio is
1619 * defined as core cycles per bus clock cycle.
1621 * Returns zero on success, a negative error code otherwise.
1623 * Returns -pte_invalid if \@decoder or \@cbr is NULL.
1624 * Returns -pte_no_cbr if there has not been a CBR packet.
1626 extern pt_export int pt_qry_core_bus_ratio(struct pt_query_decoder *decoder,
1635 /** An Intel PT address space identifier.
1637 * This identifies a particular address space when adding file sections or
1638 * when reading memory.
1641 /** The size of this object - set to sizeof(struct pt_asid). */
1644 /** The CR3 value. */
1647 /** The VMCS Base address. */
1651 /** An unknown CR3 value to be used for pt_asid objects. */
1652 static const uint64_t pt_asid_no_cr3 = 0xffffffffffffffffull;
1654 /** An unknown VMCS Base value to be used for pt_asid objects. */
1655 static const uint64_t pt_asid_no_vmcs = 0xffffffffffffffffull;
1657 /** Initialize an address space identifier. */
1658 static inline void pt_asid_init(struct pt_asid *asid)
1660 asid->size = sizeof(*asid);
1661 asid->cr3 = pt_asid_no_cr3;
1662 asid->vmcs = pt_asid_no_vmcs;
1666 /** A cache of traced image sections. */
1667 struct pt_image_section_cache;
1669 /** Allocate a traced memory image section cache.
1671 * An optional \@name may be given to the cache. The name string is copied.
1673 * Returns a new traced memory image section cache on success, NULL otherwise.
1675 extern pt_export struct pt_image_section_cache *
1676 pt_iscache_alloc(const char *name);
1678 /** Free a traced memory image section cache.
1680 * The \@iscache must have been allocated with pt_iscache_alloc().
1681 * The \@iscache must not be used after a successful return.
1683 extern pt_export void pt_iscache_free(struct pt_image_section_cache *iscache);
1685 /** Set the image section cache limit.
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.
1691 * Returns zero on success, a negative pt_error_code otherwise.
1692 * Returns -pte_invalid if \@iscache is NULL.
1694 extern pt_export int
1695 pt_iscache_set_limit(struct pt_image_section_cache *iscache, uint64_t limit);
1697 /** Get the image section cache name.
1699 * Returns a pointer to \@iscache's name or NULL if there is no name.
1701 extern pt_export const char *
1702 pt_iscache_name(const struct pt_image_section_cache *iscache);
1704 /** Add a new file section to the traced memory image section cache.
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.
1710 * Returns an image section identifier (isid) uniquely identifying that section
1713 * The section is silently truncated to match the size of \@filename.
1715 * Returns a positive isid on success, a negative error code otherwise.
1717 * Returns -pte_invalid if \@iscache or \@filename is NULL.
1718 * Returns -pte_invalid if \@offset is too big.
1720 extern pt_export int pt_iscache_add_file(struct pt_image_section_cache *iscache,
1721 const char *filename, uint64_t offset,
1722 uint64_t size, uint64_t vaddr);
1724 /** Read memory from a cached file section
1726 * Reads \@size bytes of memory starting at virtual address \@vaddr in the
1727 * section identified by \@isid in \@iscache into \@buffer.
1729 * The caller is responsible for allocating a \@buffer of at least \@size bytes.
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.
1735 * Returns the number of bytes read on success, a negative error code otherwise.
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.
1742 extern pt_export int pt_iscache_read(struct pt_image_section_cache *iscache,
1743 uint8_t *buffer, uint64_t size, int isid,
1746 /** The traced memory image. */
1750 /** Allocate a traced memory image.
1752 * An optional \@name may be given to the image. The name string is copied.
1754 * Returns a new traced memory image on success, NULL otherwise.
1756 extern pt_export struct pt_image *pt_image_alloc(const char *name);
1758 /** Free a traced memory image.
1760 * The \@image must have been allocated with pt_image_alloc().
1761 * The \@image must not be used after a successful return.
1763 extern pt_export void pt_image_free(struct pt_image *image);
1765 /** Get the image name.
1767 * Returns a pointer to \@image's name or NULL if there is no name.
1769 extern pt_export const char *pt_image_name(const struct pt_image *image);
1771 /** Add a new file section to the traced memory image.
1773 * Adds \@size bytes starting at \@offset in \@filename. The section is
1774 * loaded at the virtual address \@vaddr in the address space \@asid.
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.
1780 * The section is silently truncated to match the size of \@filename.
1782 * Existing sections that would overlap with the new section will be shrunk
1785 * Returns zero on success, a negative error code otherwise.
1787 * Returns -pte_invalid if \@image or \@filename is NULL.
1788 * Returns -pte_invalid if \@offset is too big.
1790 extern pt_export int pt_image_add_file(struct pt_image *image,
1791 const char *filename, uint64_t offset,
1793 const struct pt_asid *asid,
1796 /** Add a section from an image section cache.
1798 * Add the section from \@iscache identified by \@isid in address space \@asid.
1800 * Existing sections that would overlap with the new section will be shrunk
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.
1807 extern pt_export int pt_image_add_cached(struct pt_image *image,
1808 struct pt_image_section_cache *iscache,
1809 int isid, const struct pt_asid *asid);
1813 * Adds all sections from \@src to \@image. Sections that could not be added
1816 * Returns the number of ignored sections on success, a negative error code
1819 * Returns -pte_invalid if \@image or \@src is NULL.
1821 extern pt_export int pt_image_copy(struct pt_image *image,
1822 const struct pt_image *src);
1824 /** Remove all sections loaded from a file.
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.
1829 * Returns the number of removed sections on success, a negative error code
1832 * Returns -pte_invalid if \@image or \@filename is NULL.
1834 extern pt_export int pt_image_remove_by_filename(struct pt_image *image,
1835 const char *filename,
1836 const struct pt_asid *asid);
1838 /** Remove all sections loaded into an address space.
1840 * Removes all sections loaded into \@asid. Specify the same \@asid that was
1841 * used for adding sections.
1843 * Returns the number of removed sections on success, a negative error code
1846 * Returns -pte_invalid if \@image is NULL.
1848 extern pt_export int pt_image_remove_by_asid(struct pt_image *image,
1849 const struct pt_asid *asid);
1851 /** A read memory callback function.
1853 * It shall read \@size bytes of memory from address space \@asid starting
1854 * at \@ip into \@buffer.
1856 * It shall return the number of bytes read on success.
1857 * It shall return a negative pt_error_code otherwise.
1859 typedef int (read_memory_callback_t)(uint8_t *buffer, size_t size,
1860 const struct pt_asid *asid,
1861 uint64_t ip, void *context);
1863 /** Set the memory callback for the traced memory image.
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.
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.
1872 * Returns -pte_invalid if \@image is NULL.
1874 extern pt_export int pt_image_set_callback(struct pt_image *image,
1875 read_memory_callback_t *callback,
1880 /* Instruction flow decoder. */
1884 /** The instruction class.
1886 * We provide only a very coarse classification suitable for reconstructing
1887 * the execution flow.
1889 enum pt_insn_class {
1890 /* The instruction could not be classified. */
1893 /* The instruction is something not listed below. */
1896 /* The instruction is a near (function) call. */
1899 /* The instruction is a near (function) return. */
1902 /* The instruction is a near unconditional jump. */
1905 /* The instruction is a near conditional jump. */
1908 /* The instruction is a call-like far transfer.
1909 * E.g. SYSCALL, SYSENTER, or FAR CALL.
1913 /* The instruction is a return-like far transfer.
1914 * E.g. SYSRET, SYSEXIT, IRET, or FAR RET.
1918 /* The instruction is a jump-like far transfer.
1923 /* The instruction is a PTWRITE. */
1927 /** The maximal size of an instruction. */
1929 pt_max_insn_size = 15
1932 /** A single traced instruction. */
1934 /** The virtual address in its process. */
1937 /** The image section identifier for the section containing this
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.
1946 /** The execution mode. */
1947 enum pt_exec_mode mode;
1949 /** A coarse classification. */
1950 enum pt_insn_class iclass;
1952 /** The raw bytes. */
1953 uint8_t raw[pt_max_insn_size];
1955 /** The size in bytes. */
1958 /** A collection of flags giving additional information:
1960 * - the instruction was executed speculatively.
1962 uint32_t speculative:1;
1964 /** - this instruction is truncated in its image section.
1966 * It starts in the image section identified by \@isid and continues
1967 * in one or more other sections.
1969 uint32_t truncated:1;
1973 /** Allocate an Intel PT instruction flow decoder.
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.
1978 * The decoder needs to be synchronized before it can be used.
1980 extern pt_export struct pt_insn_decoder *
1981 pt_insn_alloc_decoder(const struct pt_config *config);
1983 /** Free an Intel PT instruction flow decoder.
1985 * This will destroy the decoder's default image.
1987 * The \@decoder must not be used after a successful return.
1989 extern pt_export void pt_insn_free_decoder(struct pt_insn_decoder *decoder);
1991 /** Synchronize an Intel PT instruction flow decoder.
1993 * Search for the next synchronization point in forward or backward direction.
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.
1999 * Returns zero or a positive value on success, a negative error code otherwise.
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.
2006 extern pt_export int pt_insn_sync_forward(struct pt_insn_decoder *decoder);
2007 extern pt_export int pt_insn_sync_backward(struct pt_insn_decoder *decoder);
2009 /** Manually synchronize an Intel PT instruction flow decoder.
2011 * Synchronize \@decoder on the syncpoint at \@offset. There must be a PSB
2012 * packet at \@offset.
2014 * Returns zero or a positive value on success, a negative error code otherwise.
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.
2023 extern pt_export int pt_insn_sync_set(struct pt_insn_decoder *decoder,
2026 /** Get the current decoder position.
2028 * Fills the current \@decoder position into \@offset.
2030 * This is useful for reporting errors.
2032 * Returns zero on success, a negative error code otherwise.
2034 * Returns -pte_invalid if \@decoder or \@offset is NULL.
2035 * Returns -pte_nosync if \@decoder is out of sync.
2037 extern pt_export int pt_insn_get_offset(const struct pt_insn_decoder *decoder,
2040 /** Get the position of the last synchronization point.
2042 * Fills the last synchronization position into \@offset.
2044 * Returns zero on success, a negative error code otherwise.
2046 * Returns -pte_invalid if \@decoder or \@offset is NULL.
2047 * Returns -pte_nosync if \@decoder is out of sync.
2049 extern pt_export int
2050 pt_insn_get_sync_offset(const struct pt_insn_decoder *decoder,
2053 /** Get the traced image.
2055 * The returned image may be modified as long as no decoder that uses this
2058 * Returns a pointer to the traced image the decoder uses for reading memory.
2059 * Returns NULL if \@decoder is NULL.
2061 extern pt_export struct pt_image *
2062 pt_insn_get_image(struct pt_insn_decoder *decoder);
2064 /** Set the traced image.
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.
2069 * Only one image can be active at any time.
2071 * Returns zero on success, a negative error code otherwise.
2072 * Return -pte_invalid if \@decoder is NULL.
2074 extern pt_export int pt_insn_set_image(struct pt_insn_decoder *decoder,
2075 struct pt_image *image);
2077 /* Return a pointer to \@decoder's configuration.
2079 * Returns a non-null pointer on success, NULL if \@decoder is NULL.
2081 extern pt_export const struct pt_config *
2082 pt_insn_get_config(const struct pt_insn_decoder *decoder);
2084 /** Return the current time.
2086 * On success, provides the time at the last preceding timing packet in \@time.
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.
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.
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.
2101 * Returns zero on success, a negative error code otherwise.
2103 * Returns -pte_invalid if \@decoder or \@time is NULL.
2104 * Returns -pte_no_time if there has not been a TSC packet.
2106 extern pt_export int pt_insn_time(struct pt_insn_decoder *decoder,
2107 uint64_t *time, uint32_t *lost_mtc,
2108 uint32_t *lost_cyc);
2110 /** Return the current core bus ratio.
2112 * On success, provides the current core:bus ratio in \@cbr. The ratio is
2113 * defined as core cycles per bus clock cycle.
2115 * Returns zero on success, a negative error code otherwise.
2117 * Returns -pte_invalid if \@decoder or \@cbr is NULL.
2118 * Returns -pte_no_cbr if there has not been a CBR packet.
2120 extern pt_export int pt_insn_core_bus_ratio(struct pt_insn_decoder *decoder,
2123 /** Return the current address space identifier.
2125 * On success, provides the current address space identifier in \@asid.
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.
2131 * Returns zero on success, a negative error code otherwise.
2133 * Returns -pte_invalid if \@decoder or \@asid is NULL.
2135 extern pt_export int pt_insn_asid(const struct pt_insn_decoder *decoder,
2136 struct pt_asid *asid, size_t size);
2138 /** Determine the next instruction.
2140 * On success, provides the next instruction in execution order in \@insn.
2142 * The \@size argument must be set to sizeof(struct pt_insn).
2144 * Returns a non-negative pt_status_flag bit-vector on success, a negative error
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.
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.
2160 extern pt_export int pt_insn_next(struct pt_insn_decoder *decoder,
2161 struct pt_insn *insn, size_t size);
2163 /** Get the next pending event.
2165 * On success, provides the next event in \@event and updates \@decoder.
2167 * The \@size argument must be set to sizeof(struct pt_event).
2169 * Returns a non-negative pt_status_flag bit-vector on success, a negative error
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.
2176 extern pt_export int pt_insn_event(struct pt_insn_decoder *decoder,
2177 struct pt_event *event, size_t size);
2181 /* Block decoder. */
2185 /** A block of instructions.
2187 * Instructions in this block are executed sequentially but are not necessarily
2188 * contiguous in memory. Users are expected to follow direct branches.
2191 /** The IP of the first instruction in this block. */
2194 /** The IP of the last instruction in this block.
2196 * This can be used for error-detection.
2200 /** The image section that contains the instructions in this block.
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.
2208 /** The execution mode for all instructions in this block. */
2209 enum pt_exec_mode mode;
2211 /** The instruction class for the last instruction in this block.
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.
2217 enum pt_insn_class iclass;
2219 /** The number of instructions in this block. */
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.
2225 * This field is only valid if \@truncated is set.
2227 uint8_t raw[pt_max_insn_size];
2229 /** The size of the last instruction in this block in bytes.
2231 * This field is only valid if \@truncated is set.
2235 /** A collection of flags giving additional information about the
2236 * instructions in this block.
2238 * - all instructions in this block were executed speculatively.
2240 uint32_t speculative:1;
2242 /** - the last instruction in this block is truncated.
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.
2247 * The raw bytes for the last instruction are provided in \@raw and
2248 * its size in \@size in this case.
2250 uint32_t truncated:1;
2253 /** Allocate an Intel PT block decoder.
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.
2258 * The decoder needs to be synchronized before it can be used.
2260 extern pt_export struct pt_block_decoder *
2261 pt_blk_alloc_decoder(const struct pt_config *config);
2263 /** Free an Intel PT block decoder.
2265 * This will destroy the decoder's default image.
2267 * The \@decoder must not be used after a successful return.
2269 extern pt_export void pt_blk_free_decoder(struct pt_block_decoder *decoder);
2271 /** Synchronize an Intel PT block decoder.
2273 * Search for the next synchronization point in forward or backward direction.
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.
2279 * Returns zero or a positive value on success, a negative error code otherwise.
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.
2286 extern pt_export int pt_blk_sync_forward(struct pt_block_decoder *decoder);
2287 extern pt_export int pt_blk_sync_backward(struct pt_block_decoder *decoder);
2289 /** Manually synchronize an Intel PT block decoder.
2291 * Synchronize \@decoder on the syncpoint at \@offset. There must be a PSB
2292 * packet at \@offset.
2294 * Returns zero or a positive value on success, a negative error code otherwise.
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.
2303 extern pt_export int pt_blk_sync_set(struct pt_block_decoder *decoder,
2306 /** Get the current decoder position.
2308 * Fills the current \@decoder position into \@offset.
2310 * This is useful for reporting errors.
2312 * Returns zero on success, a negative error code otherwise.
2314 * Returns -pte_invalid if \@decoder or \@offset is NULL.
2315 * Returns -pte_nosync if \@decoder is out of sync.
2317 extern pt_export int pt_blk_get_offset(const struct pt_block_decoder *decoder,
2320 /** Get the position of the last synchronization point.
2322 * Fills the last synchronization position into \@offset.
2324 * Returns zero on success, a negative error code otherwise.
2326 * Returns -pte_invalid if \@decoder or \@offset is NULL.
2327 * Returns -pte_nosync if \@decoder is out of sync.
2329 extern pt_export int
2330 pt_blk_get_sync_offset(const struct pt_block_decoder *decoder,
2333 /** Get the traced image.
2335 * The returned image may be modified as long as \@decoder is not running.
2337 * Returns a pointer to the traced image \@decoder uses for reading memory.
2338 * Returns NULL if \@decoder is NULL.
2340 extern pt_export struct pt_image *
2341 pt_blk_get_image(struct pt_block_decoder *decoder);
2343 /** Set the traced image.
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.
2348 * Only one image can be active at any time.
2350 * Returns zero on success, a negative error code otherwise.
2351 * Return -pte_invalid if \@decoder is NULL.
2353 extern pt_export int pt_blk_set_image(struct pt_block_decoder *decoder,
2354 struct pt_image *image);
2356 /* Return a pointer to \@decoder's configuration.
2358 * Returns a non-null pointer on success, NULL if \@decoder is NULL.
2360 extern pt_export const struct pt_config *
2361 pt_blk_get_config(const struct pt_block_decoder *decoder);
2363 /** Return the current time.
2365 * On success, provides the time at the last preceding timing packet in \@time.
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.
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.
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.
2380 * Returns zero on success, a negative error code otherwise.
2382 * Returns -pte_invalid if \@decoder or \@time is NULL.
2383 * Returns -pte_no_time if there has not been a TSC packet.
2385 extern pt_export int pt_blk_time(struct pt_block_decoder *decoder,
2386 uint64_t *time, uint32_t *lost_mtc,
2387 uint32_t *lost_cyc);
2389 /** Return the current core bus ratio.
2391 * On success, provides the current core:bus ratio in \@cbr. The ratio is
2392 * defined as core cycles per bus clock cycle.
2394 * Returns zero on success, a negative error code otherwise.
2396 * Returns -pte_invalid if \@decoder or \@cbr is NULL.
2397 * Returns -pte_no_cbr if there has not been a CBR packet.
2399 extern pt_export int pt_blk_core_bus_ratio(struct pt_block_decoder *decoder,
2402 /** Return the current address space identifier.
2404 * On success, provides the current address space identifier in \@asid.
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.
2410 * Returns zero on success, a negative error code otherwise.
2412 * Returns -pte_invalid if \@decoder or \@asid is NULL.
2414 extern pt_export int pt_blk_asid(const struct pt_block_decoder *decoder,
2415 struct pt_asid *asid, size_t size);
2417 /** Determine the next block of instructions.
2419 * On success, provides the next block of instructions in execution order in
2422 * The \@size argument must be set to sizeof(struct pt_block).
2424 * Returns a non-negative pt_status_flag bit-vector on success, a negative error
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.
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.
2440 extern pt_export int pt_blk_next(struct pt_block_decoder *decoder,
2441 struct pt_block *block, size_t size);
2443 /** Get the next pending event.
2445 * On success, provides the next event in \@event and updates \@decoder.
2447 * The \@size argument must be set to sizeof(struct pt_event).
2449 * Returns a non-negative pt_status_flag bit-vector on success, a negative error
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.
2456 extern pt_export int pt_blk_event(struct pt_block_decoder *decoder,
2457 struct pt_event *event, size_t size);
2463 #endif /* INTEL_PT_H */