doc/man/pt_insn_alloc_decoder.3.md

   1 % PT_INSN_ALLOC_DECODER(3)
   2
   3 <!---
   4  ! Copyright (c) 2015-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 EVENT 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_insn_alloc_decoder, pt_insn_free_decoder - allocate/free an Intel(R)
  34 Processor Trace instruction flow decoder
  35
  36
  37 # SYNOPSIS
  38
  39 | **\#include `<intel-pt.h>`**
  40 |
  41 | **struct pt_insn_decoder \***
  42 | **pt_insn_alloc_decoder(const struct pt_config \**config*);**
  43 |
  44 | **void pt_insn_free_decoder(struct pt_insn_decoder \**decoder*);**
  45
  46 Link with *-lipt*.
  47
  48
  49 # DESCRIPTION
  50
  51 An instruction flow decoder decodes raw Intel Processor Trace (Intel PT) into a
  52 sequence of instructions described by the *pt_insn* structure.  See
  53 **pt_insn_next**(3).
  54
  55 **pt_insn_alloc_decoder**() allocates a new instruction flow decoder and returns
  56 a pointer to it.  The *config* argument points to a *pt_config* object.  See
  57 **pt_config**(3).  The *config* argument will not be referenced by the returned
  58 decoder but the trace buffer defined by the *config* argument's *begin* and
  59 *end* fields will.
  60
  61 The returned instruction flow decoder needs to be synchronized onto the trace
  62 stream before it can be used.  To synchronize the instruction flow decoder, use
  63 **pt_insn_sync_forward**(3), **pt_insn_sync_backward**(3), or
  64 **pt_insn_sync_set**(3).
  65
  66 **pt_insn_free_decoder**() frees the Intel PT instruction flow decoder pointed
  67 to by *decoder*.  The *decoder* argument must be NULL or point to a decoder that
  68 has been allocated by a call to **pt_insn_alloc_decoder**().
  69
  70
  71 # RETURN VALUE
  72
  73 **pt_insn_alloc_decoder**() returns a pointer to a *pt_insn_decoder* object on
  74 success or NULL in case of an error.
  75
  76
  77 # EXAMPLE
  78
  79 ~~~{.c}
  80 int foo(const struct pt_config *config) {
  81         struct pt_insn_decoder *decoder;
  82         errcode;
  83
  84         decoder = pt_insn_alloc_decoder(config);
  85         if (!decoder)
  86                 return pte_nomem;
  87
  88         errcode = bar(decoder);
  89
  90         pt_insn_free_decoder(decoder);
  91         return errcode;
  92 }
  93 ~~~
  94
  95
  96 # SEE ALSO
  97
  98 **pt_config**(3), **pt_insn_sync_forward**(3), **pt_insn_sync_backward**(3),
  99 **pt_insn_sync_set**(3), **pt_insn_get_offset**(3), **pt_insn_get_sync_offset**(3),
 100 **pt_insn_get_image**(3), **pt_insn_set_image**(3), **pt_insn_get_config**(3),
 101 **pt_insn_time**(3), **pt_insn_core_bus_ratio**(3), **pt_insn_next**(3)