1PT_BLK_NEXT(3)                                                  PT_BLK_NEXT(3)
2
3
4

NAME

6       pt_blk_next, pt_block - iterate over blocks of traced instructions
7

SYNOPSIS

9       #include <intel-pt.h>
10       struct pt_block;
11       int pt_blk_next(struct pt_blk_decoder *decoder,
12                        struct pt_blk *blk, size_t size);
13       int pt_blk_next(struct pt_block_decoder *decoder,
14                       struct pt_block *block, size_t size);
15
16       Link with -lipt.
17

DESCRIPTION

19       pt_blk_next()  provides the next block of instructions in execution or‐
20       der, which is described by the pt_block structure.
21
22       The size argument must be set to sizeof(struct pt_block).  The function
23       will provide at most size bytes of the pt_block structure.  A newer de‐
24       coder library may truncate an extended pt_block object to size bytes.
25
26       An older decoder library may provide less pt_block fields.  Fields that
27       are  not provided will be zero-initialized.  For fields where zero is a
28       valid value (e.g. for bit-fields), check the decoder library version to
29       determine which fields are valid.  See pt_library_version(3).
30
31       On  success, the next block of instructions is provided in the pt_block
32       object pointed to by the block argument.  The pt_block structure is de‐
33       clared as:
34
35              /** A block of instructions.
36               *
37               * Instructions in this block are executed sequentially but are not necessarily
38               * contiguous in memory.  Users are expected to follow direct branches.
39               */
40              struct pt_block {
41                  /** The IP of the first instruction in this block. */
42                  uint64_t ip;
43
44                  /** The IP of the last instruction in this block.
45                   *
46                   * This can be used for error-detection.
47                   */
48                  uint64_t end_ip;
49
50                  /** The image section that contains the instructions in this block.
51                   *
52                   * A value of zero means that the section did not have an identifier.
53                   * The section was not added via an image section cache or the memory
54                   * was read via the read memory callback.
55                   */
56                  int isid;
57
58                  /** The execution mode for all instructions in this block. */
59                  enum pt_exec_mode mode;
60
61                  /** The instruction class for the last instruction in this block.
62                   *
63                   * This field may be set to ptic_error to indicate that the instruction
64                   * class is not available.  The block decoder may choose to not provide
65                   * the instruction class in some cases for performance reasons.
66                   */
67                  enum pt_insn_class iclass;
68
69                  /** The number of instructions in this block. */
70                  uint16_t ninsn;
71
72                  /** The raw bytes of the last instruction in this block in case the
73                   * instruction does not fit entirely into this block's section.
74                   *
75                   * This field is only valid if \@truncated is set.
76                   */
77                  uint8_t raw[pt_max_insn_size];
78
79                  /** The size of the last instruction in this block in bytes.
80                   *
81                   * This field is only valid if \@truncated is set.
82                   */
83                  uint8_t size;
84
85                  /** A collection of flags giving additional information about the
86                   * instructions in this block.
87                   *
88                   * - all instructions in this block were executed speculatively.
89                   */
90                  uint32_t speculative:1;
91
92                  /** - the last instruction in this block is truncated.
93                   *
94                   *    It starts in this block's section but continues in one or more
95                   *    other sections depending on how fragmented the memory image is.
96                   *
97                   *    The raw bytes for the last instruction are provided in \@raw and
98                   *    its size in \@size in this case.
99                   */
100                  uint32_t truncated:1;
101              };
102
103       The  fields  of the pt_block structure are described in more detail be‐
104       low:
105
106       ip     The virtual address of the first instruction in the block.   The
107              address  should be interpreted in the current address space con‐
108              text.
109
110       end_ip The virtual address of the last instruction in the  block.   The
111              address  should be interpreted in the current address space con‐
112              text.
113
114              This can be used for error detection.  Reconstruction of the in‐
115              structions  in  a  block should end with the last instruction at
116              end_ip.
117
118       isid   The image section identifier of the section from which the block
119              of  instructions  originated.   This will be zero unless the in‐
120              structions came from a section that was added via an image  sec‐
121              tion cache.  See pt_image_add_cached(3).
122
123              The  image section identifier can be used for reading the memory
124              containing an instruction in order to decode it and for  tracing
125              an  instruction back to its binary file and from there to source
126              code.
127
128       mode   The execution mode at which the instructions in the  block  were
129              executed.  The pt_exec_mode enumeration is declared as:
130
131              /** An execution mode. */
132              enum pt_exec_mode {
133                  ptem_unknown,
134                  ptem_16bit,
135                  ptem_32bit,
136                  ptem_64bit
137              };
138
139       iclass A  coarse  classification  of the last instruction in the block.
140              This may be ptic_error to indicate that  the  classification  is
141              not available.
142
143              The block decoder knows the instruction class of the instruction
144              that ended the block most of the time.  If it does, it  provides
145              this  information  to save the caller the effort of decoding the
146              instruction in some cases.
147
148       ninsn  The number of instructions contained in this block.
149
150              The instructions are sequential in the sense that  no  trace  is
151              required for reconstructing them.  They are not necessarily con‐
152              tiguous in memory.
153
154              The IP of the first instruction is given in the ip field and the
155              IP of other instructions can be determined by decoding and exam‐
156              ining the previous instruction.
157
158       raw    If the last instruction of this block can not be  read  entirely
159              from this block's section, this field provides the instruction's
160              raw bytes.
161
162              It is only valid if the truncated flag is set.
163
164       size   If the last instruction of this block can not be  read  entirely
165              from this block's section, this field provides the instruction's
166              size in bytes.
167
168              It is only valid if the truncated flag is set.
169
170       speculative
171              A flag giving the speculative execution status of  all  instruc‐
172              tions  in  the  block.   If  set, the instructions were executed
173              speculatively.  Otherwise, the instructions were  executed  nor‐
174              mally.
175
176       truncated
177              A flag saying whether the last instruction in this block can not
178              be read entirely from this block's section.  Some bytes need  to
179              be  read  from one or more other sections.  This can happen when
180              an image section is partially overwritten by another image  sec‐
181              tion.
182
183              If set, the last instruction's memory is provided in raw and its
184              size in size.
185

RETURN VALUE

187       pt_blk_next() returns zero or a positive value on success or a negative
188       pt_error_code enumeration constant in case of an error.
189
190       On success, a bit-vector of pt_status_flag enumeration constants is re‐
191       turned.  The pt_status_flag enumeration is declared as:
192
193              /** Decoder status flags. */
194              enum pt_status_flag {
195                  /** There is an event pending. */
196                  pts_event_pending    = 1 << 0,
197
198                  /** The address has been suppressed. */
199                  pts_ip_suppressed    = 1 << 1,
200
201                  /** There is no more trace data available. */
202                  pts_eos              = 1 << 2
203              };
204
205       The pts_event_pending flag indicates that one or more events are  pend‐
206       ing.   Use  pt_blk_event(3)  to  process  pending events before calling
207       pt_blk_next() again.
208
209       The pt_eos flag indicates that the information contained in  the  Intel
210       PT  stream has been consumed.  Further calls to pt_blk_next() will con‐
211       tinue to provide blocks for instructions as long as  the  instruction's
212       addresses can be determined without further trace.
213

ERRORS

215       pte_invalid
216              The  decoder  or  block argument is NULL or the size argument is
217              too small.
218
219       pte_eos
220              Decode reached the end of the trace stream.
221
222       pte_nosync
223              The decoder has not been synchronized  onto  the  trace  stream.
224              Use    pt_blk_sync_forward(3),    pt_blk_sync_backward(3),    or
225              pt_blk_sync_set(3) to synchronize decoder.
226
227       pte_bad_opc
228              The decoder encountered an unsupported Intel PT packet opcode.
229
230       pte_bad_packet
231              The decoder encountered an unsupported Intel PT packet payload.
232
233       pte_bad_query
234              Execution flow reconstruction and trace got out of sync.
235
236              This typically means that, on its way to the virtual address  of
237              the  next  event, the decoder encountered a conditional or indi‐
238              rect branch for which it did not find guidance in the trace.
239

SEE ALSO

241       pt_blk_alloc_decoder(3),    pt_blk_free_decoder(3),    pt_blk_sync_for‐
242       ward(3),  pt_blk_sync_backward(3),  pt_blk_sync_set(3), pt_blk_time(3),
243       pt_blk_core_bus_ratio(3), pt_blk_event(3)
244
245
246
247                                                                PT_BLK_NEXT(3)
Impressum