1PT_QRY_EVENT(3) PT_QRY_EVENT(3)
2
6 pt_qry_event, pt_insn_event, pt_blk_event - query an Intel(R) Processor
7 Trace decoder for an asynchronous event
8
10 #include <intel-pt.h>
11 int pt_qry_event(struct pt_query_decoder *decoder,
12 struct pt_event *event, size_t size);
13 int pt_insn_event(struct pt_insn_decoder *decoder,
14 struct pt_event *event, size_t size);
15 int pt_blk_event(struct pt_block_decoder *decoder,
16 struct pt_event *event, size_t size);
17 Link with -lipt.
19
21 pt_qry_event(), pt_insn_event(), and pt_blk_event() provide the next
22 pending asynchronous event in decoder's Intel Processor Trace (Intel
23 PT) decode in the pt_event object pointed to by the event argument.
24 The size argument must be set to sizeof(struct pt_event). The function
26 will provide at most size bytes of the pt_event structure. A newer de‐
27 coder library may provide event types that are not yet defined. Those
28 events may be truncated.
29 On success, detailed information about the event is provided in the
31 pt_event object pointed to by the event argument. The pt_event struc‐
32 ture is declared as:
33 /** An event. */
35 struct pt_event {
36 /** The type of the event. */
37 enum pt_event_type type;
38 /** A flag indicating that the event IP has been
40 * suppressed.
41 */
42 uint32_t ip_suppressed:1;
43 /** A flag indicating that the event is for status update. */
45 uint32_t status_update:1;
46 /** A flag indicating that the event has timing
48 * information.
49 */
50 uint32_t has_tsc:1;
51 /** The time stamp count of the event.
53 *
54 * This field is only valid if \@has_tsc is set.
55 */
56 uint64_t tsc;
57 /** The number of lost mtc and cyc packets.
59 *
60 * This gives an idea about the quality of the \@tsc. The
61 * more packets were dropped, the less precise timing is.
62 */
63 uint32_t lost_mtc;
64 uint32_t lost_cyc;
65 /* Reserved space for future extensions. */
67 uint64_t reserved[2];
68 /** Event specific data. */
70 union {
71 /** Event: enabled. */
72 struct {
73 /** The address at which tracing resumes. */
74 uint64_t ip;
75 /** A flag indicating that tracing resumes from the IP
77 * at which tracing had been disabled before.
78 */
79 uint32_t resumed:1;
80 } enabled;
81 /** Event: disabled. */
83 struct {
84 /** The destination of the first branch inside a
85 * filtered area.
86 *
87 * This field is not valid if \@ip_suppressed is set.
88 */
89 uint64_t ip;
90 /* The exact source ip needs to be determined using
92 * disassembly and the filter configuration.
93 */
94 } disabled;
95 [...]
97 } variant;
98 };
99 See the intel-pt.h header file for more detail. The common fields of
101 the pt_event structure are described in more detail below:
102 type The type of the event as a pt_event_type enumeration, which is
104 declared as:
105 /** Event types. */
107 enum pt_event_type {
108 /* Tracing has been enabled/disabled. */
109 ptev_enabled,
110 ptev_disabled,
111 /* Tracing has been disabled asynchronously. */
113 ptev_async_disabled,
114 /* An asynchronous branch, e.g. interrupt. */
116 ptev_async_branch,
117 /* A synchronous paging event. */
119 ptev_paging,
120 /* An asynchronous paging event. */
122 ptev_async_paging,
123 /* Trace overflow. */
125 ptev_overflow,
126 /* An execution mode change. */
128 ptev_exec_mode,
129 /* A transactional execution state change. */
131 ptev_tsx,
132 /* Trace Stop. */
134 ptev_stop,
135 /* A synchronous vmcs event. */
137 ptev_vmcs,
138 /* An asynchronous vmcs event. */
140 ptev_async_vmcs,
141 /* Execution has stopped. */
143 ptev_exstop,
144 /* An MWAIT operation completed. */
146 ptev_mwait,
147 /* A power state was entered. */
149 ptev_pwre,
150 /* A power state was exited. */
152 ptev_pwrx,
153 /* A PTWRITE event. */
155 ptev_ptwrite,
156 /* A timing event. */
158 ptev_tick,
159 /* A core:bus ratio event. */
161 ptev_cbr,
162 /* A maintenance event. */
164 ptev_mnt
165 };
166 ip_suppressed
168 A flag indicating whether the ip field in the event-dependent
169 part is not valid because the value has been suppressed in the
170 trace.
171 status_update
173 A flag indicating whether the event is for updating the de‐
174 coder's status. Status update events originate from Intel PT
175 packets in PSB+.
176 has_tsc
178 A flag indicating that the event's timing-related fields tsc,
179 lost_mtc, and lost_cyc are valid.
180 tsc The last time stamp count before the event. Depending on the
182 timing configuration, the timestamp can be more or less precise.
183 For cycle-accurate tracing, event packets are typically CYC-eli‐
184 gible so the timestamp should be cycle-accurate.
185 lost_mtc, lost_cyc
187 The number of lost MTC and CYC updates. An update is lost if
188 the decoder was not able to process an MTC or CYC packet due to
189 missing information. This can be either missing calibration or
190 missing configuration information. The number of lost MTC and
191 CYC updates gives a rough idea about the quality of the tsc
192 field.
193 variant
195 This field contains event-specific information. See the in‐
196 tel-pt.h header file for details.
197
199 pt_qry_event(), pt_insn_event(), and pt_blk_event() return zero or a
200 positive value on success or a negative pt_error_code enumeration con‐
201 stant in *case of an error.
202 On success, a bit-vector of pt_status_flag enumeration constants is re‐
204 turned. The pt_status_flag enumeration is declared as:
205 /** Decoder status flags. */
207 enum pt_status_flag {
208 /** There is an event pending. */
209 pts_event_pending = 1 << 0,
210 /** The address has been suppressed. */
212 pts_ip_suppressed = 1 << 1,
213 /** There is no more trace data available. */
215 pts_eos = 1 << 2
216 };
217
219 pte_invalid
220 The decoder or event argument is NULL or the size argument is
221 too small.
222 pte_eos
224 Decode reached the end of the trace stream.
225 pte_nosync
227 The decoder has not been synchronized onto the trace stream.
228 Use pt_qry_sync_forward(3), pt_qry_sync_backward(3), or
229 pt_qry_sync_set(3) to synchronize decoder.
230 pte_bad_opc
232 The decoder encountered an unsupported Intel PT packet opcode.
233 pte_bad_packet
235 The decoder encountered an unsupported Intel PT packet payload.
236 pte_bad_query
238 The query does not match the data provided in the Intel PT
239 stream. Based on the trace, the decoder expected a call to
240 pt_qry_cond_branch(3) or pt_qry_indirect_branch(3). This usual‐
241 ly means that execution flow reconstruction and trace got out of
242 sync.
243
245 pt_qry_alloc_decoder(3), pt_qry_free_decoder(3), pt_qry_cond_branch(3),
246 pt_qry_indirect_branch(3), pt_qry_time(3), pt_qry_core_bus_ratio(3),
247 pt_insn_next(3), pt_blk_next(3)
248 PT_QRY_EVENT(3)