1PT_QRY_COND_BRANCH(3)                                    PT_QRY_COND_BRANCH(3)
2
3
4

NAME

6       pt_qry_cond_branch,  pt_qry_indirect_branch - query an Intel(R) Proces‐
7       sor Trace query decoder
8

SYNOPSIS

10       #include <intel-pt.h>
11       int pt_qry_cond_branch(struct pt_query_decoder *decoder,
12                              int *taken);
13       int pt_qry_indirect_branch(struct pt_query_decoder *decoder,
14                                  **uint64_t *ip);
15
16       Link with -lipt.
17

DESCRIPTION

19       pt_qry_cond_branch() uses Intel Processor Trace (Intel PT) to determine
20       whether the next conditional branch in the traced code was taken or was
21       not taken.  The decoder argument must point to an Intel  PT  query  de‐
22       coder.
23
24       On  success,  sets the variable the taken argument points to a non-zero
25       value if the next condition branch is taken and to zero if  it  is  not
26       taken.
27
28       pt_qry_indirect_branch()  uses  Intel Processor Trace (Intel PT) to de‐
29       termine the destination virtual address of the next indirect branch  in
30       the traced code.
31
32       On  success,  provides  the destination address in the integer variable
33       pointed to be the ip argument.  If the  destination  address  has  been
34       suppressed in the Intel PT trace, the lack of an IP is indicated in the
35       return value by setting the pts_ip_suppressed bit.
36

RETURN VALUE

38       Both functions return zero or a positive value on success or a negative
39       pt_error_code enumeration constant in case of an error.
40
41       On success, a bit-vector of pt_status_flag enumeration constants is re‐
42       turned.  The pt_status_flag enumeration is declared as:
43
44              /** Decoder status flags. */
45              enum pt_status_flag {
46                  /** There is an event pending. */
47                  pts_event_pending   = 1 << 0,
48
49                  /** The address has been suppressed. */
50                  pts_ip_suppressed   = 1 << 1,
51
52                  /** There is no more trace data available. */
53                  pts_eos             = 1 << 2
54              };
55

ERRORS

57       pte_invalid
58              The decoder argument or the taken (pt_qry_cond_branch())  or  ip
59              (pt_qry_indirect_branch()) argument is NULL.
60
61       pte_eos
62              Decode reached the end of the trace stream.
63
64       pte_nosync
65              The  decoder  has  not  been synchronized onto the trace stream.
66              Use    pt_qry_sync_forward(3),    pt_qry_sync_backward(3),    or
67              pt_qry_sync_set(3) to synchronize decoder.
68
69       pte_bad_opc
70              The decoder encountered an unsupported Intel PT packet opcode.
71
72       pte_bad_packet
73              The decoder encountered an unsupported Intel PT packet payload.
74
75       pte_bad_query
76              The  query  does  not  match  the  data provided in the Intel PT
77              stream.  Based on the trace, the decoder expected a call to  the
78              other query function or a call to pt_qry_event(3).  This usually
79              means that execution flow reconstruction and trace  got  out  of
80              sync.
81

EXAMPLE

83       The  following  example sketches an execution flow reconstruction loop.
84       Asynchronous events have been omitted.
85
86              int foo(struct pt_query_decoder *decoder, uint64_t ip) {
87                  for (;;) {
88                      if (insn_is_cond_branch(ip)) {
89                          int errcode, taken;
90
91                          errcode = pt_qry_cond_branch(decoder, &taken);
92                          if (errcode < 0)
93                              return errcode;
94
95                          if (taken)
96                              ip = insn_destination(ip);
97                          else
98                              ip = insn_next_ip(ip);
99                      } else if (insn_is_indirect_branch(ip)) {
100                          int errcode;
101
102                          errcode = pt_qry_indirect_branch(decoder, &ip);
103                          if (errcode < 0)
104                              return errcode;
105                      } else
106                          ip = insn_next_ip(ip);
107                  }
108              }
109

SEE ALSO

111       pt_qry_alloc_decoder(3),    pt_qry_free_decoder(3),    pt_qry_event(3),
112       pt_qry_time(3), pt_qry_core_bus_ratio(3)
113
114
115
116                                                         PT_QRY_COND_BRANCH(3)
Impressum