PT_INSN_ALLOC_DECODER(3)

💖 PT_INSN_ALLOC_DECODER(3) 💖

okay bestie, so this is a page from the libipt manual, section 3, and the whole vibe is: allocating and freeing an Intel® Processor Trace instruction flow decoder. two functions, one page, let's go 🦋

---

✨ NAME ✨

pt_insn_alloc_decoder, pt_insn_free_decoder — allocate/free an Intel(R) Processor Trace instruction flow decoder. that's it, that's the duo 💅

---

🌸 SYNOPSIS 🌸

#include <intel-pt.h>
struct pt_insn_decoder *
pt_insn_alloc_decoder(const struct pt_config *config);
void pt_insn_free_decoder(struct pt_insn_decoder *decoder);

and bestie, you gotta link with -lipt. no -lipt, no decoder, no nothing. periodt 🔥

---

🎀 DESCRIPTION 🎀

so an instruction flow decoder takes raw Intel Processor Trace (Intel PT) and decodes it into a sequence of instructions, and those instructions are described by the pt_insn structure. like, that's the whole glow-up. see pt_insn_next(3) for the next chapter of the story ✨

pt_insn_alloc_decoder() allocates a brand new instruction flow decoder and hands you back a pointer to it. the config argument points to a pt_config object — see pt_config(3). now here's the tea: the returned decoder will not reference the config argument itself, BUT it will reference the trace buffer defined by the config argument's begin and end fields. so like, keep that buffer alive, mkay? 👀

lowkey important: the decoder you get back needs to be synchronized onto the trace stream before it can be used. it does not arrive ready to serve, bestie. to sync it up, use pt_insn_sync_forward(3), pt_insn_sync_backward(3), or pt_insn_sync_set(3). then you're iconic 💅

pt_insn_free_decoder() frees the Intel PT instruction flow decoder pointed to by decoder. and the decoder argument must be NULL or point to a decoder that has been allocated by a call to pt_insn_alloc_decoder(). no random pointers, we don't do that here 🙈

---

⭐ RETURN VALUE ⭐

pt_insn_alloc_decoder() returns a pointer to a pt_insn_decoder object on success, or NULL in case of an error. that's the whole vibe check: pointer = slay, NULL = 😭

---

🌈 EXAMPLE 🌈

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

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

    errcode = bar(decoder);

    pt_insn_free_decoder(decoder);
    return errcode;
}

allocate, use, free, return. the classic three-step, no notes 👑

---

🫶 SEE ALSO 🫶

• pt_config(3)
• pt_insn_sync_forward(3)
• pt_insn_sync_backward(3)
• pt_insn_sync_set(3)
• pt_insn_get_offset(3)
• pt_insn_get_sync_offset(3)
• pt_insn_get_image(3)
• pt_insn_set_image(3)
• pt_insn_get_config(3)
• pt_insn_time(3)
• pt_insn_core_bus_ratio(3)
• pt_insn_next(3)

---

and that's the page!! 💖 the footer down there just signs off with PT_INSN_ALLOC_DECODER(3) all over again in the libipt manual, section 3 — no date, no version number, just the title echoing itself like the main character it is. stay synchronized, bestie, and go free your decoders 🦋✨💜