1PT_INSN_SYNC_FORWARD(3)                                PT_INSN_SYNC_FORWARD(3)
2
3
4

NAME

6       pt_insn_sync_forward,  pt_insn_sync_backward,  pt_insn_sync_set  - syn‐
7       chronize an Intel(R) Processor Trace instruction flow decoder
8

SYNOPSIS

10       #include <intel-pt.h>
11       int pt_insn_sync_forward(struct pt_insn_decoder *decoder);
12       int pt_insn_sync_backward(struct pt_insn_decoder *decoder);
13       int pt_insn_sync_set(struct pt_insn_decoder *decoder,
14                            uint64_t offset);
15
16       Link with -lipt.
17

DESCRIPTION

19       These functions synchronize an Intel Processor  Trace  (Intel  PT)  in‐
20       struction  flow  decoder pointed to by decoder onto the trace stream in
21       decoder's trace buffer.
22
23       They search for a Packet Stream Boundary  (PSB)  packet  in  the  trace
24       stream  and, if successful, set decoder's current position and synchro‐
25       nization position to that packet and  start  processing  packets.   For
26       synchronization  to be successfull, there must be a full PSB+ header in
27       the trace stream.
28
29       pt_insn_sync_forward() searches in  forward  direction  from  decoder's
30       current  position  towards the end of the trace buffer.  If decoder has
31       been newly allocated and has not  been  synchronized  yet,  the  search
32       starts from the beginning of the trace.
33
34       pt_insn_sync_backward()  searches  in backward direction from decoder's
35       current position towards the beginning of the trace buffer.  If decoder
36       has  been newly allocated and has not been synchronized yet, the search
37       starts from the end of the trace.
38
39       pt_insn_sync_set() searches at offset bytes from the beginning  of  its
40       trace buffer.
41

RETURN VALUE

43       All  synchronization  functions return zero or a positive value on suc‐
44       cess or a negative pt_error_code enumeration constant in case of an er‐
45       ror.
46
47       On success, a bit-vector of pt_status_flag enumeration constants is re‐
48       turned.  The pt_status_flag enumeration is declared as:
49
50              /** Decoder status flags. */
51              enum pt_status_flag {
52                  /** There is an event pending. */
53                  pts_event_pending   = 1 << 0,
54
55                  /** The address has been suppressed. */
56                  pts_ip_suppressed   = 1 << 1,
57
58                  /** There is no more trace data available. */
59                  pts_eos             = 1 << 2
60              };
61
62       The pts_event_pending flag indicates that one or more events are  pend‐
63       ing.   Use  pt_insn_event(3)  to  process pending events before calling
64       pt_insn_next(3).
65
66       The pt_eos flag indicates that the information contained in  the  Intel
67       PT  stream has been consumed.  Calls to pt_insn_next() will provide in‐
68       structions as long as the instruction's address can be determined with‐
69       out trace.
70

ERRORS

72       pte_invalid
73              The decoder argument is NULL.
74
75       pte_eos
76              There  is  no  (further) PSB+ header in the trace stream (pt_in‐
77              sn_sync_forward()  and  pt_insn_sync_backward())  or  at  offset
78              bytes into the trace buffer (pt_insn_sync_set()).
79
80       pte_nosync
81              There is no PSB packet at offset bytes from the beginning of the
82              trace (pt_insn_sync_set() only).
83
84       pte_bad_opc
85              The decoder encountered an unsupported Intel PT packet opcode.
86
87       pte_bad_packet
88              The decoder encountered an unsupported Intel PT packet payload.
89

EXAMPLE

91       The following example re-synchronizes an Intel PT instruction flow  de‐
92       coder after decode errors:
93
94              int foo(struct pt_insn_decoder *decoder) {
95                  for (;;) {
96                      int status;
97
98                      status = pt_insn_sync_forward(decoder);
99                      if (status < 0)
100                          return status;
101
102                      do {
103                          status = decode(decoder, status);
104                      } while (status >= 0);
105                  }
106              }
107

SEE ALSO

109       pt_insn_alloc_decoder(3),   pt_insn_free_decoder(3),   pt_insn_get_off‐
110       set(3),   pt_insn_get_sync_offset(3),   pt_insn_get_config(3),   pt_in‐
111       sn_time(3),    pt_insn_core_bus_ratio(3),    pt_insn_next(3),    pt_in‐
112       sn_event(3)
113
114
115
116                                                       PT_INSN_SYNC_FORWARD(3)
Impressum