1PT_PKT_SYNC_FORWARD(3)                                  PT_PKT_SYNC_FORWARD(3)
2
3
4

NAME

6       pt_pkt_sync_forward,  pt_pkt_sync_backward,  pt_pkt_sync_set - synchro‐
7       nize an Intel(R) Processor Trace packet decoder
8

SYNOPSIS

10       #include <intel-pt.h>
11       int pt_pkt_sync_forward(struct pt_packet_decoder *decoder);
12       int pt_pkt_sync_backward(struct pt_packet_decoder *decoder);
13       int pt_pkt_sync_set(struct pt_packet_decoder *decoder,
14                           uint64_t offset);
15
16       Link with -lipt.
17

DESCRIPTION

19       pt_pkt_sync_forward() and pt_pkt_sync_backward() synchronize  an  Intel
20       Processor  Trace  (Intel  PT) packet decoder pointed to by decoder onto
21       the trace stream in decoder's trace buffer.  They search for  a  Packet
22       Stream  Boundary  (PSB)  packet in the trace stream and, if successful,
23       set decoder's current position to that packet.
24
25       pt_pkt_sync_forward() searches in forward direction from decoder's cur‐
26       rent position towards the end of the trace buffer.  If decoder has been
27       newly allocated and has not been synchronized yet,  the  search  starts
28       from the beginning of the trace.
29
30       pt_pkt_sync_backward()  searches  in  backward direction from decoder's
31       current position towards the beginning of the trace buffer.  If decoder
32       has  been newly allocated and has not been synchronized yet, the search
33       starts from the end of the trace.
34
35       pt_pkt_sync_set() sets decoder's current position to offset bytes  from
36       the beginning of its trace buffer.
37

RETURN VALUE

39       All  synchronization  functions return zero or a positive value on suc‐
40       cess or a negative pt_error_code enumeration constant in case of an er‐
41       ror.
42

ERRORS

44       pte_invalid
45              The decoder argument is NULL.
46
47       pte_eos
48              There   is   no   (further)  PSB  packet  in  the  trace  stream
49              (pt_pkt_sync_forward() and pt_pkt_sync_backward()) or the offset
50              argument  is too big and the resulting position would be outside
51              of decoder's trace buffer (pt_pkt_sync_set()).
52

EXAMPLE

54       The following example re-synchronizes an Intel PT packet decoder  after
55       decode errors:
56
57              int foo(struct pt_packet_decoder *decoder) {
58                  for (;;) {
59                      int errcode;
60
61                      errcode = pt_pkt_sync_forward(decoder);
62                      if (errcode < 0)
63                          return errcode;
64
65                      do {
66                          errcode = decode(decoder);
67                      } while (errcode >= 0);
68                  }
69              }
70

SEE ALSO

72       pt_pkt_alloc_decoder(3),  pt_pkt_free_decoder(3), pt_pkt_get_offset(3),
73       pt_pkt_get_sync_offset(3), pt_pkt_get_config(3), pt_pkt_next(3)
74
75
76
77                                                        PT_PKT_SYNC_FORWARD(3)
Impressum