doc/man/pt_blk_next.3.md

   1 % PT_BLK_NEXT(3)
   2
   3 <!---
   4  ! Copyright (c) 2016-2018, Intel Corporation
   5  !
   6  ! Redistribution and use in source and binary forms, with or without
   7  ! modification, are permitted provided that the following conditions are met:
   8  !
   9  !  * Redistributions of source code must retain the above copyright notice,
  10  !    this list of conditions and the following disclaimer.
  11  !  * Redistributions in binary form must reproduce the above copyright notice,
  12  !    this list of conditions and the following disclaimer in the documentation
  13  !    and/or other materials provided with the distribution.
  14  !  * Neither the name of Intel Corporation nor the names of its contributors
  15  !    may be used to endorse or promote products derived from this software
  16  !    without specific prior written permission.
  17  !
  18  ! THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
  19  ! AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  20  ! IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  21  ! ARE DISCLAIMED. IN NO NEXT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
  22  ! LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  23  ! CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  24  ! SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  25  ! INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  26  ! CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  27  ! ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  28  ! POSSIBILITY OF SUCH DAMAGE.
  29  !-->
  30
  31 # NAME
  32
  33 pt_blk_next, pt_block - iterate over blocks of traced instructions
  34
  35
  36 # SYNOPSIS
  37
  38 | **\#include `<intel-pt.h>`**
  39 |
  40 | **struct pt_block;**
  41 |
  42 | **int pt_blk_next(struct pt_blk_decoder \**decoder*,**
  43 |                  **struct pt_blk \**blk*, size_t *size*);**
  44 |
  45 | **int pt_blk_next(struct pt_block_decoder \**decoder*,**
  46 |                 **struct pt_block \**block*, size_t *size*);**
  47
  48 Link with *-lipt*.
  49
  50
  51 # DESCRIPTION
  52
  53 **pt_blk_next**() provides the next block of instructions in execution order,
  54 which is described by the *pt_block* structure.
  55
  56 The *size* argument must be set to *sizeof(struct pt_block)*.  The function will
  57 provide at most *size* bytes of the *pt_block* structure.  A newer decoder
  58 library may truncate an extended *pt_block* object to *size* bytes.
  59
  60 An older decoder library may provide less *pt_block* fields.  Fields that are
  61 not provided will be zero-initialized.  For fields where zero is a valid value
  62 (e.g. for bit-fields), check the decoder library version to determine which
  63 fields are valid.  See **pt_library_version**(3).
  64
  65 On success, the next block of instructions is provided in the *pt_block* object
  66 pointed to by the *block* argument.  The *pt_block* structure is declared as:
  67
  68 ~~~{.c}
  69 /** A block of instructions.
  70  *
  71  * Instructions in this block are executed sequentially but are not necessarily
  72  * contiguous in memory.  Users are expected to follow direct branches.
  73  */
  74 struct pt_block {
  75     /** The IP of the first instruction in this block. */
  76     uint64_t ip;
  77
  78     /** The IP of the last instruction in this block.
  79      *
  80      * This can be used for error-detection.
  81      */
  82     uint64_t end_ip;
  83
  84     /** The image section that contains the instructions in this block.
  85      *
  86      * A value of zero means that the section did not have an identifier.
  87      * The section was not added via an image section cache or the memory
  88      * was read via the read memory callback.
  89      */
  90     int isid;
  91
  92     /** The execution mode for all instructions in this block. */
  93     enum pt_exec_mode mode;
  94
  95     /** The instruction class for the last instruction in this block.
  96      *
  97      * This field may be set to ptic_error to indicate that the instruction
  98      * class is not available.  The block decoder may choose to not provide
  99      * the instruction class in some cases for performance reasons.
 100      */
 101     enum pt_insn_class iclass;
 102
 103     /** The number of instructions in this block. */
 104     uint16_t ninsn;
 105
 106     /** The raw bytes of the last instruction in this block in case the
 107      * instruction does not fit entirely into this block's section.
 108      *
 109      * This field is only valid if \@truncated is set.
 110      */
 111     uint8_t raw[pt_max_insn_size];
 112
 113     /** The size of the last instruction in this block in bytes.
 114      *
 115      * This field is only valid if \@truncated is set.
 116      */
 117     uint8_t size;
 118
 119     /** A collection of flags giving additional information about the
 120      * instructions in this block.
 121      *
 122      * - all instructions in this block were executed speculatively.
 123      */
 124     uint32_t speculative:1;
 125
 126     /** - the last instruction in this block is truncated.
 127      *
 128      *    It starts in this block's section but continues in one or more
 129      *    other sections depending on how fragmented the memory image is.
 130      *
 131      *    The raw bytes for the last instruction are provided in \@raw and
 132      *    its size in \@size in this case.
 133      */
 134     uint32_t truncated:1;
 135 };
 136 ~~~
 137
 138 The fields of the *pt_block* structure are described in more detail below:
 139
 140 ip
 141 :   The virtual address of the first instruction in the block.  The address
 142     should be interpreted in the current address space context.
 143
 144 end_ip
 145 :   The virtual address of the last instruction in the block.  The address
 146     should be interpreted in the current address space context.
 147
 148     This can be used for error detection.  Reconstruction of the instructions in
 149     a block should end with the last instruction at *end_ip*.
 150
 151 isid
 152 :   The image section identifier of the section from which the block of
 153     instructions originated.  This will be zero unless the instructions came
 154     from a section that was added via an image section cache.  See
 155     **pt_image_add_cached**(3).
 156
 157     The image section identifier can be used for reading the memory containing
 158     an instruction in order to decode it and for tracing an instruction back to
 159     its binary file and from there to source code.
 160
 161 mode
 162 :   The execution mode at which the instructions in the block were executed.
 163     The *pt_exec_mode* enumeration is declared as:
 164
 165 ~~~{.c}
 166 /** An execution mode. */
 167 enum pt_exec_mode {
 168     ptem_unknown,
 169     ptem_16bit,
 170     ptem_32bit,
 171     ptem_64bit
 172 };
 173 ~~~
 174
 175 iclass
 176 :   A coarse classification of the last instruction in the block.  This may be
 177     *ptic_error* to indicate that the classification is not available.
 178
 179     The block decoder knows the instruction class of the instruction that ended
 180     the block most of the time.  If it does, it provides this information to
 181     save the caller the effort of decoding the instruction in some cases.
 182
 183 ninsn
 184 :   The number of instructions contained in this block.
 185
 186     The instructions are sequential in the sense that no trace is required for
 187     reconstructing them.  They are not necessarily contiguous in memory.
 188
 189     The IP of the first instruction is given in the *ip* field and the IP of
 190     other instructions can be determined by decoding and examining the previous
 191     instruction.
 192
 193 raw
 194 :   If the last instruction of this block can not be read entirely from this
 195     block's section, this field provides the instruction's raw bytes.
 196
 197     It is only valid if the *truncated* flag is set.
 198
 199 size
 200 :   If the last instruction of this block can not be read entirely from this
 201     block's section, this field provides the instruction's size in bytes.
 202
 203     It is only valid if the *truncated* flag is set.
 204
 205 speculative
 206 :   A flag giving the speculative execution status of all instructions in the
 207     block.  If set, the instructions were executed speculatively.  Otherwise,
 208     the instructions were executed normally.
 209
 210 truncated
 211 :   A flag saying whether the last instruction in this block can not be read
 212     entirely from this block's section.  Some bytes need to be read from one or
 213     more other sections.  This can happen when an image section is partially
 214     overwritten by another image section.
 215
 216     If set, the last instruction's memory is provided in *raw* and its size in
 217     *size*.
 218
 219
 220 # RETURN VALUE
 221
 222 **pt_blk_next**() returns zero or a positive value on success or a negative
 223 *pt_error_code* enumeration constant in case of an error.
 224
 225 On success, a bit-vector of *pt_status_flag* enumeration constants is returned.
 226 The *pt_status_flag* enumeration is declared as:
 227
 228 ~~~{.c}
 229 /** Decoder status flags. */
 230 enum pt_status_flag {
 231     /** There is an event pending. */
 232     pts_event_pending    = 1 << 0,
 233
 234     /** The address has been suppressed. */
 235     pts_ip_suppressed    = 1 << 1,
 236
 237     /** There is no more trace data available. */
 238     pts_eos              = 1 << 2
 239 };
 240 ~~~
 241
 242 The *pts_event_pending* flag indicates that one or more events are pending.  Use
 243 **pt_blk_event**(3) to process pending events before calling **pt_blk_next**()
 244 again.
 245
 246 The *pt_eos* flag indicates that the information contained in the Intel PT
 247 stream has been consumed.  Further calls to **pt_blk_next**() will continue to
 248 provide blocks for instructions as long as the instruction's addresses can be
 249 determined without further trace.
 250
 251
 252 # ERRORS
 253
 254 pte_invalid
 255 :   The *decoder* or *block* argument is NULL or the *size* argument is too
 256     small.
 257
 258 pte_eos
 259 :   Decode reached the end of the trace stream.
 260
 261 pte_nosync
 262 :   The decoder has not been synchronized onto the trace stream.  Use
 263     **pt_blk_sync_forward**(3), **pt_blk_sync_backward**(3), or
 264     **pt_blk_sync_set**(3) to synchronize *decoder*.
 265
 266 pte_bad_opc
 267 :   The decoder encountered an unsupported Intel PT packet opcode.
 268
 269 pte_bad_packet
 270 :   The decoder encountered an unsupported Intel PT packet payload.
 271
 272 pte_bad_query
 273 :   Execution flow reconstruction and trace got out of sync.
 274
 275     This typically means that, on its way to the virtual address of the next
 276     event, the decoder encountered a conditional or indirect branch for which it
 277     did not find guidance in the trace.
 278
 279
 280 # SEE ALSO
 281
 282 **pt_blk_alloc_decoder**(3), **pt_blk_free_decoder**(3),
 283 **pt_blk_sync_forward**(3), **pt_blk_sync_backward**(3),
 284 **pt_blk_sync_set**(3), **pt_blk_time**(3), **pt_blk_core_bus_ratio**(3),
 285 **pt_blk_event**(3)