PT_PKT_ALLOC_DECODER(3)

💖 PT_PKT_ALLOC_DECODER(3) 💖

okay bestie, gather round, because today we're talking about pt_pkt_alloc_decoder and pt_pkt_free_decoder — the lil duo that gives you an Intel(R) Processor Trace packet decoder and then gently takes it away when you're done. this is the PT_PKT_ALLOC_DECODER(3) page, and yes it's exactly as iconic as it sounds 💅

---

✨ NAME ✨

pt_pkt_alloc_decoder, pt_pkt_free_decoder — allocate/free an Intel(R) Processor Trace packet decoder 🎀

---

🌸 SYNOPSIS 🌸

#include <intel-pt.h>
struct pt_packet_decoder *
pt_pkt_alloc_decoder(const struct pt_config *config);
void pt_pkt_free_decoder(struct pt_packet_decoder *decoder);

and like, don't forget to link with -lipt or nothing's gonna happen, fr fr 🫶

---

🦋 DESCRIPTION 🦋

so pt_pkt_alloc_decoder() does the thing: it allocates a brand new Intel Processor Trace (Intel PT) packet decoder and hands you back a pointer to it. what does a packet decoder even do, you ask? it decodes raw Intel PT trace into a whole stream of pt_packet objects. literally turning chaos into structure, main character energy ✨ go peek at pt_pkt_next(3) for that part.

the config argument points to a pt_config object — check pt_config(3) for the deets. and here's a lil lowkey important detail: the returned decoder will not reference the config argument itself, BUT it absolutely will reference the trace buffer defined by the config argument's begin and end fields. so like, keep that buffer alive, okay? 😭

also, the decoder you get back needs to be synchronized onto the trace stream before you can actually use it. it's giving "new phone, who dis" — you gotta introduce it to the stream first. to sync it up, use pt_pkt_sync_forward(3), pt_pkt_sync_backward(3), or pt_pkt_sync_set(3). pick your fighter 💅

and then pt_pkt_free_decoder() frees the Intel PT packet decoder pointed to by decoder. one rule though, no cap: the decoder argument must be NULL or point to a decoder that was allocated by a call to pt_pkt_alloc_decoder(). anything else is not the vibe 🙈

---

⭐ RETURN VALUE ⭐

pt_pkt_alloc_decoder() returns a pointer to a pt_packet_decoder object on success, or NULL if something went wrong. that's it, that's the whole mood. NULL = error, pointer = slay 👑

---

🌈 EXAMPLE 🌈

int foo(const struct pt_config *config) {
    struct pt_packet_decoder *decoder;
    errcode;

    decoder = pt_pkt_alloc_decoder(config);
    if (!decoder)
        return pte_nomem;

    errcode = bar(decoder);

    pt_pkt_free_decoder(decoder);
    return errcode;
}

see how clean that is? allocate, check for NULL, do the thing, free, done. chef's kiss 🔥

---

👑 SEE ALSO 👑

• pt_config(3)
• pt_pkt_sync_forward(3)
• pt_pkt_sync_backward(3)
• pt_pkt_sync_set(3)
• pt_pkt_get_offset(3)
• pt_pkt_get_sync_offset(3)
• pt_pkt_get_config(3)
• pt_pkt_next(3)

---

okay that's the whole page, bestie 💜 go forth and decode some packets. this was the PT_PKT_ALLOC_DECODER(3) manual page from the libipt / Intel PT crew — no date on this one, so just know it's the PT_PKT_ALLOC_DECODER(3) era and it ate. periodt 🎀✨🦋