PT_QRY_SYNC_FORWARD(3)

✨ NAME ✨

okay bestie, welcome to the pt_qry_sync_forward(3) page 💖 — we're talking about pt_qry_sync_forward, pt_qry_sync_backward, and pt_qry_sync_set, the trio whose whole job is to synchronize an Intel(R) Processor Trace query decoder. no cap, that's literally the entire vibe: get the decoder in position and slay ✨

---

🌸 SYNOPSIS 🌸

#include <intel-pt.h>
int pt_qry_sync_forward(struct pt_query_decoder *decoder,
                        uint64_t *ip);
int pt_qry_sync_backward(struct pt_query_decoder *decoder,
                         uint64_t *ip);
int pt_qry_sync_set(struct pt_query_decoder *decoder,
                    uint64_t *ip, uint64_t offset);

Link with -lipt.

---

💅 DESCRIPTION 💅

so. these functions take an Intel Processor Trace (Intel PT) query decoder — the one pointed to by decoder — and synchronize it onto the trace stream living in decoder's trace buffer. it's giving "align the stars" energy, honestly 🔥

they go hunt for a Packet Stream Boundary (PSB) packet in the trace stream and, if that works out, they set decoder's current position and synchronization position to that packet, then start processing packets. for synchronization to be successfull (fr fr), there has to be a full PSB+ header in the trace stream. no PSB+ header, no sync. periodt.

if the ip argument is not NULL, these functions hand you the code memory address at which tracing starts, dropped into the variable pointed to by ip. and if tracing is disabled at the synchronization point? the lack of an IP gets indicated in the return value by setting the pts_ip_suppressed bit. she's telling you the tea via the return value 😌

• pt_qry_sync_forward() — searches in forward direction, from decoder's current position towards the end of the trace buffer. if decoder has been newly allocated and hasn't been synchronized yet, the search starts from the beginning of the trace. 🌱
• pt_qry_sync_backward() — searches in backward direction, from decoder's current position towards the beginning of the trace buffer. if decoder has been newly allocated and hasn't been synchronized yet, the search starts from the end of the trace. 🔙
• pt_qry_sync_set() — searches at offset bytes from the beginning of its trace buffer. pinpoint precision, main character behavior 👑

---

🎀 RETURN VALUE 🎀

all the synchronization functions return zero or a positive value on success, or a negative pt_error_code enumeration constant if something went wrong. (crying in error code 😭)

on success, you get back a bit-vector of pt_status_flag enumeration constants. the pt_status_flag enumeration is declared like this:

/** 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
};

look at her go. iconic enum ✨

---

🦋 ERRORS 🦋

• pte_invalid — the decoder argument is NULL. yeah. you passed nothing. 💀
• pte_eos — there is no (further) PSB+ header in the trace stream (pt_qry_sync_forward() and pt_qry_sync_backward()) or at offset bytes into the trace buffer (pt_qry_sync_set()).
• pte_nosync — there is no PSB packet at offset bytes from the beginning of the trace. (pt_qry_sync_set() only, bestie, don't @ the other two).
• pte_bad_opc — the decoder encountered an unsupported Intel PT packet opcode. 🚫
• pte_bad_packet — the decoder encountered an unsupported Intel PT packet payload. 🙈

none of these are a vibe. check your trace before you blame the decoder, okay? 🫶

---

🌈 EXAMPLE 🌈

the following example re-synchronizes an Intel PT query decoder after decode errors — she's a phoenix rising from the ashes, lowkey:

int foo(struct pt_query_decoder *decoder) {
    for (;;) {
        int errcode;

        errcode = pt_qry_sync_forward(decoder);
        if (errcode < 0)
            return errcode;

        do {
            errcode = decode(decoder);
        } while (errcode >= 0);
    }
}

---

💜 SEE ALSO 💜

• pt_qry_alloc_decoder(3)
• pt_qry_free_decoder(3)
• pt_qry_get_offset(3)
• pt_qry_get_sync_offset(3)
• pt_qry_get_config(3)
• pt_qry_cond_branch(3)
• pt_qry_indirect_branch(3)
• pt_qry_event(3)
• pt_qry_time(3)
• pt_qry_core_bus_ratio(3)

the whole friend group, go say hi 🧚

---

and that's the page, bestie — the header at the very top and the footer at the very bottom both just say PT_QRY_SYNC_FORWARD(3), that's the manual page name and the only thing down there, no extra version or date sprinkled in. so that's a wrap, go synchronize something and slay 👑💖⭐