PT_BLK_ALLOC_DECODER(3)

💖 pt_blk_alloc_decoder — allocate/free an Intel(R) Processor Trace block decoder 💖

okay bestie, welcome to PT_BLK_ALLOC_DECODER(3), the manual page that's literally just here to hand you a block decoder and then let you yeet it back when you're done. two functions, one header, zero drama. let's get into it 🎀

---

✨ SYNOPSIS ✨

#include <intel-pt.h>
struct pt_block_decoder *
pt_blk_alloc_decoder(const struct pt_config *config);
void pt_blk_free_decoder(struct pt_block_decoder *decoder);

Link with -lipt.

like… that's it. that's the whole API. two lines and a linker flag, we love a minimal moment 💅

---

🌸 DESCRIPTION 🌸

So a block decoder takes raw Intel Processor Trace (Intel PT) and decodes it into a sequence of blocks of instructions, and those blocks are described by the pt_block structure. wanna know more about the block structure itself? go read pt_blk_next(3), it's the main character of that story 🦋

💜 pt_blk_alloc_decoder()

pt_blk_alloc_decoder() allocates a brand-new block decoder and returns a pointer to it. slay.

The config argument points to a pt_config object — peep pt_config(3) for the deets. Now here's the ✨ important ✨ part, bestie, don't skip this:

The config argument will not be referenced by the returned decoder — but the trace buffer defined by the config argument's begin and end fields will be. so like, the config struct itself can dip, but that buffer? it's staying. keep it alive. 🔥

Also, heads up: the returned block decoder needs to be synchronized onto the trace stream before you can actually use it. it's giving "new phone, who dis" until you sync it. to do that, use one of these:

• pt_blk_sync_forward(3)
• pt_blk_sync_backward(3)
• pt_blk_sync_set(3)

🫶 pt_blk_free_decoder()

pt_blk_free_decoder() frees the Intel PT block decoder pointed to by decoder.

⚠️ the decoder argument must be NULL, or it must point to a decoder that was allocated by a call to pt_blk_alloc_decoder(). no random pointers, no impostors, okay? we do not free things we didn't allocate. periodt. 💀

---

⭐ RETURN VALUE ⭐

pt_blk_alloc_decoder() returns a pointer to a pt_block_decoder object on success, or NULL if something went wrong. that's the whole vibe check: pointer = good, NULL = error. 😭

---

🌈 EXAMPLE 🌈

here's the glow-up, a full little lifecycle in code:

struct pt_block_decoder *decoder;
int errcode;

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

errcode = decode(decoder);

pt_blk_free_decoder(decoder);
return errcode;

alloc → check → decode → free → return. the circle of life, but make it Intel PT 🧚

---

👑 SEE ALSO 👑

your reading list, bestie, all the cross-references:

• pt_config(3)
• pt_blk_sync_forward(3)
• pt_blk_sync_backward(3)
• pt_blk_sync_set(3)
• pt_blk_get_offset(3)
• pt_blk_get_sync_offset(3)
• pt_blk_get_image(3)
• pt_blk_set_image(3)
• pt_blk_get_config(3)
• pt_blk_time(3)
• pt_blk_core_bus_ratio(3)
• pt_blk_next(3)

---

okay and for the lil sign-off moment: this page is filed under PT_BLK_ALLOC_DECODER(3) — that's the manual name at the top and the footer stamp at the very bottom, same string twice because the manpage gods love symmetry. no extra version or date tea on this one, just the section-3 tag itself. mwah, go alloc some decoders responsibly 💖✨🎀