PT_QRY_ALLOC_DECODER(3)

✨ PT_QRY_ALLOC_DECODER(3) ✨

okay so bestie, welcome to the PT_QRY_ALLOC_DECODER(3) page 💖 this is where we learn how to birth a query decoder and then gently release it back into the wild. it's giving malloc but make it Intel PT.

---

🌸 NAME 🌸

pt_qry_alloc_decoder, pt_qry_free_decoder — allocate/free an Intel(R) Processor Trace query decoder 🦋

---

💅 SYNOPSIS 💅

#include <intel-pt.h>
struct pt_query_decoder *
pt_qry_alloc_decoder(const struct pt_config *config);
void pt_qry_free_decoder(struct pt_query_decoder *decoder);

Link with -lipt.

fr fr, do not forget the -lipt or the linker will simply not know you 💀

---

👑 DESCRIPTION 👑

A query decoder decodes raw Intel Processor Trace (Intel PT) and hands you functions so you can ask it stuff like:

• whether the next conditional branch was taken (or not taken) 🎀
• the destination of the next indirect branch 🌈

You can use this info to reconstruct the execution flow of the traced code. The rule is literally so simple: as long as the flow is clear, follow the flow. If the flow cannot be determined by examining the current instruction, that's when you go ask the query decoder. she knows. she always knows. ✨

On top of that, the query decoder signals asynchronous events through the return value of its query functions, and there's an extra function you can call to query for those asynchronous events. see pt_qry_cond_branch(3), pt_qry_indirect_branch(3), and pt_qry_event(3). 🫶

pt_qry_alloc_decoder() allocates a brand new query decoder and returns a pointer to it. the config argument points to a pt_config object. see pt_config(3). now listen — the config argument itself will not be referenced by the returned decoder, but the trace buffer defined by the config argument's begin and end fields absolutely will be. so keep that buffer alive, okay? 👀

the returned query decoder also needs to be synchronized onto the trace stream before it can be used, no cap. to synchronize the query decoder, use pt_qry_sync_forward(3), pt_qry_sync_backward(3), or pt_qry_sync_set(3). 🧚

pt_qry_free_decoder() frees the Intel PT query decoder pointed to by decoder. the decoder argument must be NULL or point to a decoder that has been allocated by a call to pt_qry_alloc_decoder(). like, it has to be yours, bestie. don't be out here freeing random pointers 💀

---

⭐ RETURN VALUE ⭐

pt_qry_alloc_decoder() returns a pointer to a pt_query_decoder object on success, or NULL in case of an error. that's it, that's the whole vibe check. 💜

---

🎀 EXAMPLE 🎀

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

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

           errcode = bar(decoder);

           pt_qry_free_decoder(decoder);
           return errcode;
       }

see how she allocates, checks for NULL, does the thing, and frees? that's the whole cycle. iconic behaviour, no notes. 👑

---

🌈 SEE ALSO 🌈

pt_config(3), pt_qry_sync_forward(3), pt_qry_sync_backward(3), pt_qry_sync_set(3), pt_qry_get_offset(3), pt_qry_get_sync_offset(3), pt_qry_get_config(3), pt_qry_cond_branch(3), pt_qry_indirect_branch(3), pt_qry_event(3), pt_qry_time(3), pt_qry_core_bus_ratio(3)

---

and that's the page!! 🦋 this was the PT_QRY_ALLOC_DECODER(3) manual, straight from the PT_QRY_ALLOC_DECODER(3) corner of the docs 💖 go forth and allocate responsibly, bestie. mwah. 💅✨