PT_ALLOC_ENCODER(3)

💖 PT_ALLOC_ENCODER(3) — bestie's guide to alloc'ing & free'ing an Intel(R) Processor Trace packet encoder 💖

okay so you found your way into section 3 of the manual, bestie, and honestly? iconic of you. this is the page for the alloc/free duo of the Intel(R) Processor Trace packet encoder world. let's get into it 🫶

---

✨ NAME ✨

pt_alloc_encoder</p>, pt_free_encoder</p> — allocate/free an Intel(R) Processor Trace packet encoder. that's the whole vibe. one of them gives you an encoder, the other one takes it away. yin and yang fr fr 🦋

---

✨ SYNOPSIS ✨

#include <intel-pt.h>
struct pt_packet_encoder *
pt_alloc_encoder(const struct pt_config *config);
void pt_free_encoder(struct pt_packet_encoder *encoder);

and listen, you gotta link with -lipt. no -lipt, no encoder. that's just the rules 💅

---

✨ DESCRIPTION ✨

pt_alloc_encoder() allocates a brand new Intel Processor Trace (Intel PT) packet encoder and hands you back a pointer to it. main character behaviour honestly. and what does this packet encoder do? it generates Intel PT trace from pt_packet objects. like, that's its whole job. if you wanna know more about that, go read pt_enc_next(3).

the config argument points to a pt_config object. see pt_config(3) for the tea on that. here's the little detail that lowkey matters a lot: the config argument itself will not be referenced by the returned encoder — but the trace buffer defined by the config argument's begin and end fields will be. so like, keep that buffer alive, okay?? the encoder is still holding onto it 😭

the returned packet encoder starts out initially synchronized onto the beginning of the trace buffer specified in its config argument. wanna move it somewhere else inside the trace buffer? go use pt_enc_sync_set(3). easy.

pt_free_encoder() frees the Intel PT packet encoder pointed to by encoder. and this is the part where you need to be careful, bestie, because:

the encoder argument must be NULL or point to an encoder that has been allocated by a call to pt_alloc_encoder(). that's it. those are the options. don't be out here freeing random pointers, i'm begging 🙈

---

✨ RETURN VALUE ✨

pt_alloc_encoder() returns a pointer to a pt_packet_encoder object on success ✨ or NULL in case of an error 💀. that's the whole thing. check your pointers, bestie.

---

✨ EXAMPLE ✨

here's the lil example, copy it exactly bestie, character for character, no notes:

       int foo(const struct pt_config *config) {
           struct pt_packet_encoder *encoder;
           errcode;

           encoder = pt_alloc_encoder(config);
           if (!encoder)
               return pte_nomem;

           errcode = bar(encoder);

           pt_free_encoder(encoder);
           return errcode;
       }

see how it allocs, checks for NULL, does the thing, then frees? that's the whole cycle. that's the rhythm. ate and left no crumbs 👑

---

✨ SEE ALSO ✨

• pt_config(3)
• pt_enc_sync_set(3)
• pt_enc_get_offset(3)
• pt_enc_get_config(3)
• pt_enc_next(3)

go read them, they're all part of the same little friend group 🎀

---

and that's the page!! 💜 this was PT_ALLOC_ENCODER(3), from the manual, and the footer is out here repping that same name — so yeah, PT_ALLOC_ENCODER(3), same energy top and bottom, periodt. no cap, you're now officially an encoder allocator. slay 🌸💅✨