|
Packit |
b1f7ae |
% PT_QRY_COND_BRANCH(3)
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
! Copyright (c) 2015-2017, Intel Corporation
|
|
Packit |
b1f7ae |
!
|
|
Packit |
b1f7ae |
! Redistribution and use in source and binary forms, with or without
|
|
Packit |
b1f7ae |
! modification, are permitted provided that the following conditions are met:
|
|
Packit |
b1f7ae |
!
|
|
Packit |
b1f7ae |
! * Redistributions of source code must retain the above copyright notice,
|
|
Packit |
b1f7ae |
! this list of conditions and the following disclaimer.
|
|
Packit |
b1f7ae |
! * Redistributions in binary form must reproduce the above copyright notice,
|
|
Packit |
b1f7ae |
! this list of conditions and the following disclaimer in the documentation
|
|
Packit |
b1f7ae |
! and/or other materials provided with the distribution.
|
|
Packit |
b1f7ae |
! * Neither the name of Intel Corporation nor the names of its contributors
|
|
Packit |
b1f7ae |
! may be used to endorse or promote products derived from this software
|
|
Packit |
b1f7ae |
! without specific prior written permission.
|
|
Packit |
b1f7ae |
!
|
|
Packit |
b1f7ae |
! THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
|
|
Packit |
b1f7ae |
! AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
Packit |
b1f7ae |
! IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
|
Packit |
b1f7ae |
! ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
|
|
Packit |
b1f7ae |
! LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
|
|
Packit |
b1f7ae |
! CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
|
|
Packit |
b1f7ae |
! SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
|
|
Packit |
b1f7ae |
! INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
|
|
Packit |
b1f7ae |
! CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
|
|
Packit |
b1f7ae |
! ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
|
|
Packit |
b1f7ae |
! POSSIBILITY OF SUCH DAMAGE.
|
|
Packit |
b1f7ae |
!-->
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
# NAME
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
pt_qry_cond_branch, pt_qry_indirect_branch - query an Intel(R) Processor Trace
|
|
Packit |
b1f7ae |
query decoder
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
# SYNOPSIS
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
| **\#include `<intel-pt.h>`**
|
|
Packit |
b1f7ae |
|
|
|
Packit |
b1f7ae |
| **int pt_qry_cond_branch(struct pt_query_decoder \**decoder*,**
|
|
Packit |
b1f7ae |
| **int \**taken*);**
|
|
Packit |
b1f7ae |
| **int pt_qry_indirect_branch(struct pt_query_decoder \**decoder*,**
|
|
Packit |
b1f7ae |
| **uint64_t \**ip*);
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
Link with *-lipt*.
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
# DESCRIPTION
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
**pt_qry_cond_branch**() uses Intel Processor Trace (Intel PT) to determine
|
|
Packit |
b1f7ae |
whether the next conditional branch in the traced code was taken or was not
|
|
Packit |
b1f7ae |
taken. The *decoder* argument must point to an Intel PT query decoder.
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
On success, sets the variable the *taken* argument points to a non-zero value
|
|
Packit |
b1f7ae |
if the next condition branch is taken and to zero if it is not taken.
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
**pt_qry_indirect_branch**() uses Intel Processor Trace (Intel PT) to determine
|
|
Packit |
b1f7ae |
the destination virtual address of the next indirect branch in the traced code.
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
On success, provides the destination address in the integer variable pointed to
|
|
Packit |
b1f7ae |
be the *ip* argument. If the destination address has been suppressed in the
|
|
Packit |
b1f7ae |
Intel PT trace, the lack of an IP is indicated in the return value by setting
|
|
Packit |
b1f7ae |
the *pts_ip_suppressed* bit.
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
# RETURN VALUE
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
Both functions return zero or a positive value on success or a negative
|
|
Packit |
b1f7ae |
*pt_error_code* enumeration constant in case of an error.
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
On success, a bit-vector of *pt_status_flag* enumeration constants is returned.
|
|
Packit |
b1f7ae |
The *pt_status_flag* enumeration is declared as:
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
~~~{.c}
|
|
Packit |
b1f7ae |
/** Decoder status flags. */
|
|
Packit |
b1f7ae |
enum pt_status_flag {
|
|
Packit |
b1f7ae |
/** There is an event pending. */
|
|
Packit |
b1f7ae |
pts_event_pending = 1 << 0,
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
/** The address has been suppressed. */
|
|
Packit |
b1f7ae |
pts_ip_suppressed = 1 << 1,
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
/** There is no more trace data available. */
|
|
Packit |
b1f7ae |
pts_eos = 1 << 2
|
|
Packit |
b1f7ae |
};
|
|
Packit |
b1f7ae |
~~~
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
# ERRORS
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
pte_invalid
|
|
Packit |
b1f7ae |
: The *decoder* argument or the *taken* (**pt_qry_cond_branch**()) or *ip*
|
|
Packit |
b1f7ae |
(**pt_qry_indirect_branch**()) argument is NULL.
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
pte_eos
|
|
Packit |
b1f7ae |
: Decode reached the end of the trace stream.
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
pte_nosync
|
|
Packit |
b1f7ae |
: The decoder has not been synchronized onto the trace stream. Use
|
|
Packit |
b1f7ae |
**pt_qry_sync_forward**(3), **pt_qry_sync_backward**(3), or
|
|
Packit |
b1f7ae |
**pt_qry_sync_set**(3) to synchronize *decoder*.
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
pte_bad_opc
|
|
Packit |
b1f7ae |
: The decoder encountered an unsupported Intel PT packet opcode.
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
pte_bad_packet
|
|
Packit |
b1f7ae |
: The decoder encountered an unsupported Intel PT packet payload.
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
pte_bad_query
|
|
Packit |
b1f7ae |
: The query does not match the data provided in the Intel PT stream. Based on
|
|
Packit |
b1f7ae |
the trace, the decoder expected a call to the other query function or a call
|
|
Packit |
b1f7ae |
to **pt_qry_event**(3). This usually means that execution flow
|
|
Packit |
b1f7ae |
reconstruction and trace got out of sync.
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
# EXAMPLE
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
The following example sketches an execution flow reconstruction loop.
|
|
Packit |
b1f7ae |
Asynchronous events have been omitted.
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
~~~{.c}
|
|
Packit |
b1f7ae |
int foo(struct pt_query_decoder *decoder, uint64_t ip) {
|
|
Packit |
b1f7ae |
for (;;) {
|
|
Packit |
b1f7ae |
if (insn_is_cond_branch(ip)) {
|
|
Packit |
b1f7ae |
int errcode, taken;
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
errcode = pt_qry_cond_branch(decoder, &taken);
|
|
Packit |
b1f7ae |
if (errcode < 0)
|
|
Packit |
b1f7ae |
return errcode;
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
if (taken)
|
|
Packit |
b1f7ae |
ip = insn_destination(ip);
|
|
Packit |
b1f7ae |
else
|
|
Packit |
b1f7ae |
ip = insn_next_ip(ip);
|
|
Packit |
b1f7ae |
} else if (insn_is_indirect_branch(ip)) {
|
|
Packit |
b1f7ae |
int errcode;
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
errcode = pt_qry_indirect_branch(decoder, &ip);
|
|
Packit |
b1f7ae |
if (errcode < 0)
|
|
Packit |
b1f7ae |
return errcode;
|
|
Packit |
b1f7ae |
} else
|
|
Packit |
b1f7ae |
ip = insn_next_ip(ip);
|
|
Packit |
b1f7ae |
}
|
|
Packit |
b1f7ae |
}
|
|
Packit |
b1f7ae |
~~~
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
# SEE ALSO
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
**pt_qry_alloc_decoder**(3), **pt_qry_free_decoder**(3),
|
|
Packit |
b1f7ae |
**pt_qry_event**(3), **pt_qry_time**(3), **pt_qry_core_bus_ratio**(3)
|