1PT_INSN_NEXT(3)                                                PT_INSN_NEXT(3)
2
3
4

NAME

6       pt_insn_next, pt_insn - iterate over traced instructions
7

SYNOPSIS

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
14       Link with -lipt.
15

DESCRIPTION

17       pt_insn_next()  provides the next instruction in execution order, which
18       is described by the pt_insn structure.
19
20       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
24       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
29       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
32              /** A single traced instruction. */
33              struct pt_insn {
34                  /** The virtual address in its process. */
35                  uint64_t ip;
36
37                  /** 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
46                  /** The execution mode. */
47                  enum pt_exec_mode mode;
48
49                  /** A coarse classification. */
50                  enum pt_insn_class iclass;
51
52                  /** The raw bytes. */
53                  uint8_t raw[pt_max_insn_size];
54
55                  /** The size in bytes. */
56                  uint8_t size;
57
58                  /** A collection of flags giving additional information:
59                   *
60                   * - the instruction was executed speculatively.
61                   */
62                  uint32_t speculative:1;
63
64                  /** - 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
72       The fields of the pt_insn structure are described in more detail below:
73
74       ip     The virtual address of the instruction.  The address  should  be
75              interpreted in the current address space context.
76
77       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
82              The image section identifier can be used to trace an instruction
83              back to its binary file and from there to source code.
84
85       mode   The  execution  mode at which the instruction was executed.  The
86              pt_exec_mode enumeration is declared as:
87
88              /** An execution mode. */
89              enum pt_exec_mode {
90                  ptem_unknown,
91                  ptem_16bit,
92                  ptem_32bit,
93                  ptem_64bit
94              };
95
96       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
100              /** 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
109                  /* The instruction is something not listed below. */
110                  ptic_other,
111
112                  /* The instruction is a near (function) call. */
113                  ptic_call,
114
115                  /* The instruction is a near (function) return. */
116                  ptic_return,
117
118                  /* The instruction is a near unconditional jump. */
119                  ptic_jump,
120
121                  /* The instruction is a near conditional jump. */
122                  ptic_cond_jump,
123
124                  /* The instruction is a call-like far transfer.
125                   * E.g. SYSCALL, SYSENTER, or FAR CALL.
126                   */
127                  ptic_far_call,
128
129                  /* The instruction is a return-like far transfer.
130                   * E.g. SYSRET, SYSEXIT, IRET, or FAR RET.
131                   */
132                  ptic_far_return,
133
134                  /* The instruction is a jump-like far transfer.
135                   * E.g. FAR JMP.
136                   */
137                  ptic_far_jump
138              };
139
140       raw    The memory containing the instruction.
141
142       size   The size of the instruction in bytes.
143
144       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
149       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

RETURN VALUE

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
160       On success, a bit-vector of pt_status_flag enumeration constants is re‐
161       turned.  The pt_status_flag enumeration is declared as:
162
163              /** Decoder status flags. */
164              enum pt_status_flag {
165                  /** There is an event pending. */
166                  pts_event_pending   = 1 << 0,
167
168                  /** The address has been suppressed. */
169                  pts_ip_suppressed   = 1 << 1,
170
171                  /** There is no more trace data available. */
172                  pts_eos             = 1 << 2
173              };
174
175       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
179       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

ERRORS

185       pte_invalid
186              The decoder or insn argument is NULL or the size argument is too
187              small.
188
189       pte_eos
190              Decode reached the end of the trace stream.
191
192       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
197       pte_bad_opc
198              The decoder encountered an unsupported Intel PT packet opcode.
199
200       pte_bad_packet
201              The decoder encountered an unsupported Intel PT packet payload.
202
203       pte_bad_query
204              Execution flow reconstruction and trace got out of sync.
205
206              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

SEE ALSO

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
215
216
217                                                               PT_INSN_NEXT(3)
Impressum