1PT_QRY_EVENT(3)                                                PT_QRY_EVENT(3)
2
3
4

NAME

6       pt_qry_event, pt_insn_event, pt_blk_event - query an Intel(R) Processor
7       Trace decoder for an asynchronous event
8

SYNOPSIS

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
18       Link with -lipt.
19

DESCRIPTION

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
25       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
30       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
34              /** An event. */
35              struct pt_event {
36                  /** The type of the event. */
37                  enum pt_event_type type;
38
39                  /** A flag indicating that the event IP has been
40                   * suppressed.
41                   */
42                  uint32_t ip_suppressed:1;
43
44                  /** A flag indicating that the event is for status update. */
45                  uint32_t status_update:1;
46
47                  /** A flag indicating that the event has timing
48                   * information.
49                   */
50                  uint32_t has_tsc:1;
51
52                  /** 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
58                  /** 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
66                  /* Reserved space for future extensions. */
67                  uint64_t reserved[2];
68
69                  /** Event specific data. */
70                  union {
71                      /** Event: enabled. */
72                      struct {
73                          /** The address at which tracing resumes. */
74                          uint64_t ip;
75
76                          /** 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
82                      /** 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
91                          /* The exact source ip needs to be determined using
92                           * disassembly and the filter configuration.
93                           */
94                      } disabled;
95
96                      [...]
97                  } variant;
98              };
99
100       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
103       type   The type of the event as a pt_event_type enumeration,  which  is
104              declared as:
105
106              /** Event types. */
107              enum pt_event_type {
108                  /* Tracing has been enabled/disabled. */
109                  ptev_enabled,
110                  ptev_disabled,
111
112                  /* Tracing has been disabled asynchronously. */
113                  ptev_async_disabled,
114
115                  /* An asynchronous branch, e.g. interrupt. */
116                  ptev_async_branch,
117
118                  /* A synchronous paging event. */
119                  ptev_paging,
120
121                  /* An asynchronous paging event. */
122                  ptev_async_paging,
123
124                  /* Trace overflow. */
125                  ptev_overflow,
126
127                  /* An execution mode change. */
128                  ptev_exec_mode,
129
130                  /* A transactional execution state change. */
131                  ptev_tsx,
132
133                  /* Trace Stop. */
134                  ptev_stop,
135
136                  /* A synchronous vmcs event. */
137                  ptev_vmcs,
138
139                  /* An asynchronous vmcs event. */
140                  ptev_async_vmcs,
141
142                  /* Execution has stopped. */
143                  ptev_exstop,
144
145                  /* An MWAIT operation completed. */
146                  ptev_mwait,
147
148                  /* A power state was entered. */
149                  ptev_pwre,
150
151                  /* A power state was exited. */
152                  ptev_pwrx,
153
154                  /* A PTWRITE event. */
155                  ptev_ptwrite,
156
157                  /* A timing event. */
158                  ptev_tick,
159
160                  /* A core:bus ratio event. */
161                  ptev_cbr,
162
163                  /* A maintenance event. */
164                  ptev_mnt
165              };
166
167       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
172       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
177       has_tsc
178              A  flag  indicating  that the event’s timing-related fields tsc,
179              lost_mtc, and lost_cyc are valid.
180
181       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
186       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
194       variant
195              This field contains event-specific information.  See the  intel-
196              pt.h header file for details.
197

RETURN VALUE

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
203       On success, a bit-vector of pt_status_flag enumeration constants is re‐
204       turned.  The pt_status_flag enumeration is declared as:
205
206              /** Decoder status flags. */
207              enum pt_status_flag {
208                  /** There is an event pending. */
209                  pts_event_pending   = 1 << 0,
210
211                  /** The address has been suppressed. */
212                  pts_ip_suppressed   = 1 << 1,
213
214                  /** There is no more trace data available. */
215                  pts_eos             = 1 << 2
216              };
217

ERRORS

219       pte_invalid
220              The decoder or event argument is NULL or the  size  argument  is
221              too small.
222
223       pte_eos
224              Decode reached the end of the trace stream.
225
226       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
231       pte_bad_opc
232              The decoder encountered an unsupported Intel PT packet opcode.
233
234       pte_bad_packet
235              The decoder encountered an unsupported Intel PT packet payload.
236
237       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

SEE ALSO

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
249
250
251                                                               PT_QRY_EVENT(3)
Impressum