1PT_QRY_SYNC_FORWARD(3) PT_QRY_SYNC_FORWARD(3)
2
6 pt_qry_sync_forward, pt_qry_sync_backward, pt_qry_sync_set - synchro‐
7 nize an Intel(R) Processor Trace query decoder
8
10 #include <intel-pt.h>
11 int pt_qry_sync_forward(struct pt_query_decoder *decoder,
12 uint64_t *ip);
13 int pt_qry_sync_backward(struct pt_query_decoder *decoder,
14 uint64_t *ip);
15 int pt_qry_sync_set(struct pt_query_decoder *decoder,
16 uint64_t *ip, uint64_t offset);
17 Link with -lipt.
19
21 These functions synchronize an Intel Processor Trace (Intel PT) query
22 decoder pointed to by decoder onto the trace stream in decoder’s trace
23 buffer.
24 They search for a Packet Stream Boundary (PSB) packet in the trace
26 stream and, if successful, set decoder’s current position and synchro‐
27 nization position to that packet and start processing packets. For
28 synchronization to be successfull, there must be a full PSB+ header in
29 the trace stream.
30 If the ip argument is not NULL, these functions provide the code memory
32 address at which tracing starts in the variable pointed to by ip. If
33 tracing is disabled at the synchronization point, the lack of an IP is
34 indicated in the return value by setting the pts_ip_suppressed bit.
35 pt_qry_sync_forward() searches in forward direction from decoder’s cur‐
37 rent position towards the end of the trace buffer. If decoder has been
38 newly allocated and has not been synchronized yet, the search starts
39 from the beginning of the trace.
40 pt_qry_sync_backward() searches in backward direction from decoder’s
42 current position towards the beginning of the trace buffer. If decoder
43 has been newly allocated and has not been synchronized yet, the search
44 starts from the end of the trace.
45 pt_qry_sync_set() searches at offset bytes from the beginning of its
47 trace buffer.
48
50 All synchronization functions return zero or a positive value on suc‐
51 cess or a negative pt_error_code enumeration constant in case of an er‐
52 ror.
53 On success, a bit-vector of pt_status_flag enumeration constants is re‐
55 turned. The pt_status_flag enumeration is declared as:
56 /** Decoder status flags. */
58 enum pt_status_flag {
59 /** There is an event pending. */
60 pts_event_pending = 1 << 0,
61 /** The address has been suppressed. */
63 pts_ip_suppressed = 1 << 1,
64 /** There is no more trace data available. */
66 pts_eos = 1 << 2
67 };
68
70 pte_invalid
71 The decoder argument is NULL.
72 pte_eos
74 There is no (further) PSB+ header in the trace stream
75 (pt_qry_sync_forward() and pt_qry_sync_backward()) or at offset
76 bytes into the trace buffer (pt_qry_sync_set()).
77 pte_nosync
79 There is no PSB packet at offset bytes from the beginning of the
80 trace (pt_qry_sync_set() only).
81 pte_bad_opc
83 The decoder encountered an unsupported Intel PT packet opcode.
84 pte_bad_packet
86 The decoder encountered an unsupported Intel PT packet payload.
87
89 The following example re-synchronizes an Intel PT query decoder after
90 decode errors:
91 int foo(struct pt_query_decoder *decoder) {
93 for (;;) {
94 int errcode;
95 errcode = pt_qry_sync_forward(decoder);
97 if (errcode < 0)
98 return errcode;
99 do {
101 errcode = decode(decoder);
102 } while (errcode >= 0);
103 }
104 }
105
107 pt_qry_alloc_decoder(3), pt_qry_free_decoder(3), pt_qry_get_offset(3),
108 pt_qry_get_sync_offset(3), pt_qry_get_config(3), pt_qry_cond_branch(3),
109 pt_qry_indirect_branch(3), pt_qry_event(3), pt_qry_time(3),
110 pt_qry_core_bus_ratio(3)
111 PT_QRY_SYNC_FORWARD(3)