pt_qry_cond_branch - Man Page

#include <intel-pt.h>

int pt_qry_cond_branch(struct pt_query_decoder *decoder,

                       int *taken);

int pt_qry_indirect_branch(struct pt_query_decoder *decoder,

                           **uint64_t *ip);

Link with -lipt.

pt_qry_cond_branch() uses Intel Processor Trace (Intel PT) to determine whether the next conditional branch in the traced code was taken or was not taken. The decoder argument must point to an Intel PT query decoder.

On success, sets the variable the taken argument points to a non-zero value if the next condition branch is taken and to zero if it is not taken.

pt_qry_indirect_branch() uses Intel Processor Trace (Intel PT) to determine the destination virtual address of the next indirect branch in the traced code.

On success, provides the destination address in the integer variable pointed to be the ip argument. If the destination address has been suppressed in the Intel PT trace, the lack of an IP is indicated in the return value by setting the pts_ip_suppressed bit.

Both functions return zero or a positive value on success or a negative pt_error_code enumeration constant in case of an error.

On success, a bit-vector of pt_status_flag enumeration constants is returned. The pt_status_flag enumeration is declared as:

/** Decoder status flags. */
enum pt_status_flag {
    /** There is an event pending. */
    pts_event_pending   = 1 << 0,

    /** The address has been suppressed. */
    pts_ip_suppressed   = 1 << 1,

    /** There is no more trace data available. */
    pts_eos             = 1 << 2
};

pte_invalid

The decoder argument or the taken (pt_qry_cond_branch()) or ip (pt_qry_indirect_branch()) argument is NULL.

pte_eos

Decode reached the end of the trace stream.

pte_nosync

The decoder has not been synchronized onto the trace stream. Use pt_qry_sync_forward(3), pt_qry_sync_backward(3), or pt_qry_sync_set(3) to synchronize decoder.

pte_bad_opc

The decoder encountered an unsupported Intel PT packet opcode.

pte_bad_packet

The decoder encountered an unsupported Intel PT packet payload.

pte_bad_query

The query does not match the data provided in the Intel PT stream. Based on the trace, the decoder expected a call to the other query function or a call to pt_qry_event(3). This usually means that execution flow reconstruction and trace got out of sync.

The following example sketches an execution flow reconstruction loop. Asynchronous events have been omitted.

int foo(struct pt_query_decoder *decoder, uint64_t ip) {
    for (;;) {
        if (insn_is_cond_branch(ip)) {
            int errcode, taken;

            errcode = pt_qry_cond_branch(decoder, &taken);
            if (errcode < 0)
                return errcode;

            if (taken)
                ip = insn_destination(ip);
            else
                ip = insn_next_ip(ip);
        } else if (insn_is_indirect_branch(ip)) {
            int errcode;

            errcode = pt_qry_indirect_branch(decoder, &ip);
            if (errcode < 0)
                return errcode;
        } else
            ip = insn_next_ip(ip);
    }
}

pt_qry_alloc_decoder(3), pt_qry_free_decoder(3), pt_qry_event(3), pt_qry_time(3), pt_qry_core_bus_ratio(3)

pt_evt_next(3), pt_qry_alloc_decoder(3), pt_qry_get_offset(3), pt_qry_sync_forward(3), pt_qry_time(3).

The man page pt_qry_indirect_branch(3) is an alias of pt_qry_cond_branch(3).