1PT_INSN_NEXT(3) PT_INSN_NEXT(3)
2
6 pt_insn_next, pt_insn - iterate over traced instructions
7
9 #include <intel-pt.h>
10 struct pt_insn;
11 int pt_insn_next(struct pt_insn_decoder *decoder,
12 struct pt_insn *insn, size_t size);
13 Link with -lipt.
15
17 pt_insn_next() provides the next instruction in execution order, which
18 is described by the pt_insn structure.
19 The size argument must be set to sizeof(struct pt_insn). The function
21 will provide at most size bytes of the pt_insn structure. A newer de‐
22 coder library may truncate an extended pt_insn object to size bytes.
23 An older decoder library may provide less pt_insn fields. Fields that
25 are not provided will be zero-initialized. For fields where zero is a
26 valid value (e.g. for bit-fields), check the decoder library version to
27 determine which fields are valid. See pt_library_version(3).
28 On success, the next instruction is provided in the pt_insn object
30 pointed to by the insn argument. The pt_insn structure is declared as:
31 /** A single traced instruction. */
33 struct pt_insn {
34 /** The virtual address in its process. */
35 uint64_t ip;
36 /** The image section identifier for the section containing this
38 * instruction.
39 *
40 * A value of zero means that the section did not have an identifier.
41 * The section was not added via an image section cache or the memory
42 * was read via the read memory callback.
43 */
44 int isid;
45 /** The execution mode. */
47 enum pt_exec_mode mode;
48 /** A coarse classification. */
50 enum pt_insn_class iclass;
51 /** The raw bytes. */
53 uint8_t raw[pt_max_insn_size];
54 /** The size in bytes. */
56 uint8_t size;
57 /** A collection of flags giving additional information:
59 *
60 * - the instruction was executed speculatively.
61 */
62 uint32_t speculative:1;
63 /** - this instruction is truncated in its image section.
65 *
66 * It starts in the image section identified by \@isid and continues
67 * in one or more other sections.
68 */
69 uint32_t truncated:1;
70 };
71 The fields of the pt_insn structure are described in more detail below:
73 ip The virtual address of the instruction. The address should be
75 interpreted in the current address space context.
76 isid The image section identifier of the section from which the in‐
78 struction originated. This will be zero unless the instruction
79 came from a section that was added via an image section cache.
80 See pt_image_add_cached(3).
81 The image section identifier can be used to trace an instruction
83 back to its binary file and from there to source code.
84 mode The execution mode at which the instruction was executed. The
86 pt_exec_mode enumeration is declared as:
87 /** An execution mode. */
89 enum pt_exec_mode {
90 ptem_unknown,
91 ptem_16bit,
92 ptem_32bit,
93 ptem_64bit
94 };
95 iclass A coarse classification of the instruction suitable for con‐
97 structing a call back trace. The pt_insn_class enumeration is
98 declared as:
99 /** The instruction class.
101 *
102 * We provide only a very coarse classification suitable for
103 * reconstructing the execution flow.
104 */
105 enum pt_insn_class {
106 /* The instruction could not be classified. */
107 ptic_error,
108 /* The instruction is something not listed below. */
110 ptic_other,
111 /* The instruction is a near (function) call. */
113 ptic_call,
114 /* The instruction is a near (function) return. */
116 ptic_return,
117 /* The instruction is a near unconditional jump. */
119 ptic_jump,
120 /* The instruction is a near conditional jump. */
122 ptic_cond_jump,
123 /* The instruction is a call-like far transfer.
125 * E.g. SYSCALL, SYSENTER, or FAR CALL.
126 */
127 ptic_far_call,
128 /* The instruction is a return-like far transfer.
130 * E.g. SYSRET, SYSEXIT, IRET, or FAR RET.
131 */
132 ptic_far_return,
133 /* The instruction is a jump-like far transfer.
135 * E.g. FAR JMP.
136 */
137 ptic_far_jump
138 };
139 raw The memory containing the instruction.
141 size The size of the instruction in bytes.
143 speculative
145 A flag giving the speculative execution status of the instruc‐
146 tion. If set, the instruction was executed speculatively. Oth‐
147 erwise, the instruction was executed normally.
148 truncated
150 A flag saying whether this instruction spans more than one image
151 section. If clear, this instruction originates from a single
152 section identified by isid. If set, the instruction overlaps
153 two or more image sections. In this case, isid identifies the
154 section that contains the first byte.
155
157 pt_insn_next() returns zero or a positive value on success or a nega‐
158 tive pt_error_code enumeration constant in case of an error.
159 On success, a bit-vector of pt_status_flag enumeration constants is re‐
161 turned. The pt_status_flag enumeration is declared as:
162 /** Decoder status flags. */
164 enum pt_status_flag {
165 /** There is an event pending. */
166 pts_event_pending = 1 << 0,
167 /** The address has been suppressed. */
169 pts_ip_suppressed = 1 << 1,
170 /** There is no more trace data available. */
172 pts_eos = 1 << 2
173 };
174 The pts_event_pending flag indicates that one or more events are pend‐
176 ing. Use pt_insn_event(3) to process pending events before calling
177 pt_insn_next() again.
178 The pt_eos flag indicates that the information contained in the Intel
180 PT stream has been consumed. Further calls to pt_insn_next() will con‐
181 tinue to provide instructions as long as the instruction's address can
182 be determined without further trace.
183
185 pte_invalid
186 The decoder or insn argument is NULL or the size argument is too
187 small.
188 pte_eos
190 Decode reached the end of the trace stream.
191 pte_nosync
193 The decoder has not been synchronized onto the trace stream.
194 Use pt_insn_sync_forward(3), pt_insn_sync_backward(3), or pt_in‐
195 sn_sync_set(3) to synchronize decoder.
196 pte_bad_opc
198 The decoder encountered an unsupported Intel PT packet opcode.
199 pte_bad_packet
201 The decoder encountered an unsupported Intel PT packet payload.
202 pte_bad_query
204 Execution flow reconstruction and trace got out of sync.
205 This typically means that, on its way to the virtual address of
207 the next event, the decoder encountered a conditional or indi‐
208 rect branch for which it did not find guidance in the trace.
209
211 pt_insn_alloc_decoder(3), pt_insn_free_decoder(3), pt_insn_sync_for‐
212 ward(3), pt_insn_sync_backward(3), pt_insn_sync_set(3), pt_in‐
213 sn_time(3), pt_insn_core_bus_ratio(3), pt_insn_event(3)
214 PT_INSN_NEXT(3)