1PT_QRY_ALLOC_DECODER(3)                                PT_QRY_ALLOC_DECODER(3)
2
3
4

NAME

6       pt_qry_alloc_decoder,  pt_qry_free_decoder  - allocate/free an Intel(R)
7       Processor Trace query decoder
8

SYNOPSIS

10       #include <intel-pt.h>
11       struct pt_query_decoder *
12       pt_qry_alloc_decoder(const struct pt_config *config);
13       void pt_qry_free_decoder(struct pt_query_decoder *decoder);
14
15       Link with -lipt.
16

DESCRIPTION

18       A query decoder decodes raw Intel Processor Trace (Intel PT)  and  pro‐
19       vides functions for querying the decoder about:
20
21       · whether the next conditional branch was taken (or not taken)
22
23       · the destination of the next indirect branch
24
25       This  information  can be used to reconstruct the execution flow of the
26       traced code.  As long as the flow is clear, follow the  flow.   If  the
27       flow cannot be determined by examining the current instruction, ask the
28       query decoder.
29
30       In addition, the query decoder indicates asynchronous  events  via  the
31       return value of its query functions and provides an additional function
32       to query for  such  asynchronous  events.   See  pt_qry_cond_branch(3),
33       pt_qry_indirect_branch(3), and pt_qry_event(3).
34
35       pt_qry_alloc_decoder()  allocates  a  new  query  decoder and returns a
36       pointer to it.  The config argument points to a pt_config object.   See
37       pt_config(3).   The  config  argument will not be referenced by the re‐
38       turned decoder but the trace buffer defined by  the  config  argument's
39       begin and end fields will.
40
41       The  returned  query  decoder  needs  to be synchronized onto the trace
42       stream before it can be used.  To synchronize the  query  decoder,  use
43       pt_qry_sync_forward(3), pt_qry_sync_backward(3), or pt_qry_sync_set(3).
44
45       pt_qry_free_decoder()  frees  the  Intel PT query decoder pointed to by
46       decoder.  The decoder argument must be NULL or point to a decoder  that
47       has been allocated by a call to pt_qry_alloc_decoder().
48

RETURN VALUE

50       pt_qry_alloc_decoder()  returns  a pointer to a pt_query_decoder object
51       on success or NULL in case of an error.
52

EXAMPLE

54              int foo(const struct pt_config *config) {
55                  struct pt_query_decoder *decoder;
56                  errcode;
57
58                  decoder = pt_qry_alloc_decoder(config);
59                  if (!decoder)
60                      return pte_nomem;
61
62                  errcode = bar(decoder);
63
64                  pt_qry_free_decoder(decoder);
65                  return errcode;
66              }
67

SEE ALSO

69       pt_config(3),     pt_qry_sync_forward(3),      pt_qry_sync_backward(3),
70       pt_qry_sync_set(3),   pt_qry_get_offset(3),  pt_qry_get_sync_offset(3),
71       pt_qry_get_config(3), pt_qry_cond_branch(3), pt_qry_indirect_branch(3),
72       pt_qry_event(3), pt_qry_time(3), pt_qry_core_bus_ratio(3)
73
74
75
76                                                       PT_QRY_ALLOC_DECODER(3)
Impressum