PT_PKT_SYNC_FORWARD(3)

✨ PT_PKT_SYNC_FORWARD(3) ✨

okay bestie, sit down, hydrate, and let me tell you about pt_pkt_sync_forward, pt_pkt_sync_backward, and pt_pkt_sync_set — the trio that gets your Intel(R) Processor Trace packet decoder back in sync with the trace stream. this is the PT_PKT_SYNC_FORWARD(3) manual page, and it's lowkey iconic. 💅

---

🌸 NAME 🌸

pt_pkt_sync_forward, pt_pkt_sync_backward, pt_pkt_sync_set — synchronize an Intel(R) Processor Trace packet decoder

🦋 SYNOPSIS 🦋

#include <intel-pt.h>
int pt_pkt_sync_forward(struct pt_packet_decoder *decoder);
int pt_pkt_sync_backward(struct pt_packet_decoder *decoder);
int pt_pkt_sync_set(struct pt_packet_decoder *decoder,
                    uint64_t offset);

Link with -lipt. (yes, that's the whole vibe, don't forget it 🎀)

💖 DESCRIPTION 💖

so, pt_pkt_sync_forward() and pt_pkt_sync_backward() do the main character move: they take an Intel Processor Trace (Intel PT) packet decoder — the one pointed to by decoder — and synchronize it onto the trace stream inside decoder's trace buffer. the way they do it? they go looking for a Packet Stream Boundary (PSB) packet in that trace stream, and if they find one, they set decoder's current position to that packet. slay. ✨

• pt_pkt_sync_forward() — searches in the forward direction, starting from decoder's current position and heading toward the end of the trace buffer. but if decoder is freshly allocated and hasn't been synchronized yet? the search starts from the beginning of the trace. new decoder, fresh start, we love that. 🌱
• pt_pkt_sync_backward() — searches in the backward direction, from decoder's current position toward the beginning of the trace buffer. and again, if decoder is brand new and never synced, the search starts from the end of the trace. backwards bestie behavior, but make it functional. 🦋
• pt_pkt_sync_set() — no searching, no drama, it just sets decoder's current position to offset bytes from the beginning of its trace buffer. direct. decisive. periodt. 👑

⭐ RETURN VALUE ⭐

all three synchronization functions return zero or a positive value when they ate 💅, or a negative pt_error_code enumeration constant if something went wrong. 😭

💀 ERRORS 💀

• pte_invalid — the decoder argument is NULL. (bestie. you gave it nothing. it cannot work with nothing.) 🙈
• pte_eos — there is no (further) PSB packet in the trace stream, which applies to pt_pkt_sync_forward() and pt_pkt_sync_backward(). OR the offset argument is too big and the resulting position would land outside of decoder's trace buffer, which is the pt_pkt_sync_set() case. either way: end of stream, no more crumbs. 🍓

🌈 EXAMPLE 🌈

here's the moment you've been waiting for — this example re-synchronizes an Intel PT packet decoder after decode errors, and it's giving "keep going until the universe stops you":

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

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

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

look at that loop. resilient. unbothered. re-syncing every time life (the trace) throws a decode error at it. 🔥

🎀 SEE ALSO 🎀

• pt_pkt_alloc_decoder(3)
• pt_pkt_free_decoder(3)
• pt_pkt_get_offset(3)
• pt_pkt_get_sync_offset(3)
• pt_pkt_get_config(3)
• pt_pkt_next(3)

---

and that's the whole page, bestie 🫶 this was PT_PKT_SYNC_FORWARD(3), footer and all — go forth, synchronize, and stay on your PSB. iykyk. 💜🧚‍♀️