PT_CONFIG(3)

🎀 PT_CONFIG(3) 🎀

okay so hi bestie 💖 you've landed on the manual page for pt_config, pt_config_init, and pt_cpu_errata — aka the Intel(R) Processor Trace encoder/decoder configuration situation. this is part 1, so don't go anywhere, there's more coming 👑

---

✨ NAME ✨

pt_config, pt_config_init, pt_cpu_errata — Intel(R) Processor Trace encoder/decoder configuration 🦋

---

🌸 SYNOPSIS 🌸

#include <intel-pt.h>
struct pt_config;
void pt_config_init(struct pt_config *config);
int pt_cpu_errata(struct pt_errata *errata, const struct pt_cpu *cpu);

Link with -lipt. 🔗

---

💅 DESCRIPTION 💅

so the pt_config struct is literally the whole vibe check for an Intel Processor Trace (Intel PT) encoder or decoder. you need it before you can allocate a trace packet encoder (peep pt_alloc_encoder(3)), a trace packet decoder (pt_pkt_alloc_decoder(3)), a query decoder (pt_qry_alloc_decoder(3)), or an instruction flow decoder (pt_insn_alloc_decoder(3)). no config, no decoder. periodt 💀

pt_config_init() zero-initializes its config argument and sets config's size field to sizeof(struct pt_config). it's giving "clean slate, fresh start, main character energy" ✨

pt_cpu_errata() enables workarounds for known errata in its errata argument, for the processor defined by its family/model/stepping in its cpu argument. basically: "tell me your chip, I'll tell you its lore" 🧚

The pt_config structure is declared as:

/** An Intel PT decoder configuration. */
struct pt_config {
    /** The size of the config structure in bytes. */
    size_t size;

    /** The trace buffer begin address. */
    uint8_t *begin;

    /** The trace buffer end address. */
    uint8_t *end;

    /** An optional callback for handling unknown packets.
     *
     * If @callback is not NULL, it is called for any unknown
     * opcode.
     */
    struct {
        /** The callback function.
         *
         * It shall decode the packet at @pos into @unknown.
         * It shall return the number of bytes read upon success.
         * It shall return a negative pt_error_code otherwise.
         * The below context is passed as @context.
         */
        int (*callback)(struct pt_packet_unknown *unknown,
                const struct pt_config *config,
                const uint8_t *pos, void *context);

        /** The user-defined context for this configuration. */
        void *context;
    } decode;

    /** The cpu on which Intel PT has been recorded. */
    struct pt_cpu cpu;

    /** The errata to apply when encoding or decoding Intel PT. */
    struct pt_errata errata;

    /** The CTC frequency.
     *
     * This is only required if MTC packets have been enabled in
     * IA32_RTIT_CTRL.MTCEn.
     */
    uint32_t cpuid_0x15_eax, cpuid_0x15_ebx;

    /** The MTC frequency as defined in IA32_RTIT_CTL.MTCFreq.
     *
     * This is only required if MTC packets have been enabled in
     * IA32_RTIT_CTRL.MTCEn.
     */
    uint8_t mtc_freq;

    /** The nominal frequency as defined in
     * MSR_PLATFORM_INFO[15:8].
     *
     * This is only required if CYC packets have been enabled in
     * IA32_RTIT_CTRL.CYCEn.
     *
     * If zero, timing calibration will only be able to use MTC
     * and CYC packets.
     *
     * If not zero, timing calibration will also be able to use
     * CBR packets.
     */
    uint8_t nom_freq;

    /** A collection of decoder-specific flags. */
    struct pt_conf_flags flags;

    /** The address filter configuration. */
    struct pt_conf_addr_filter addr_filter;
};

The fields of the pt_config structure are described in more detail below. buckle up 🎢

---

🌟 size 🌟

The size of the pt_config structure, for backward and forward compatibility. Set it to sizeof(struct pt_config). do not be quirky about this one bestie 🙈

🌟 begin, end 🌟

The begin and end of a user-allocated memory buffer; begin points to the first byte of the buffer, end points to one past the last byte in the buffer.

The packet encoder will generate Intel PT packets into the memory buffer. 🫶

The decoders expect the buffer to contain raw Intel PT packets. They decode directly from the buffer and expect the buffer to remain valid until the decoder has been freed. so like, don't free it early, that's not the move 💀

🌟 decode 🌟

An optional packet decode callback function. If decode.callback is not NULL, it will be called for any unknown packet, with the decoder configuration, the current decoder position, and a user-defined context provided in callback.context as arguments.

If the callback function is able to decode the packet, it shall return the size of the decoded packet and provide details in a pt_packet_unknown object. slay ✨

If the packet cannot be decoded, the callback function shall return a negative pt_error_code enumeration constant. rip 😭

The pt_packet_unknown object can be used to provide user-defined information back to the user when using the packet decoder to iterate over Intel PT packets. Other decoders ignore this information but will skip the packet if a non-zero size is returned by the callback function. iykyk 💅

🌟 cpu 🌟

The processor on which the trace has been collected, or for which the trace should be generated. The processor is identified by its family, model, and stepping.

/** A cpu vendor. */
enum pt_cpu_vendor {
    pcv_unknown,
    pcv_intel
};

/** A cpu identifier. */
struct pt_cpu {
    /** The cpu vendor. */
    enum pt_cpu_vendor vendor;

    /** The cpu family. */
    uint16_t family;

    /** The cpu model. */
    uint8_t model;

    /** The stepping. */
    uint8_t stepping;
};

🌟 errata 🌟

The errata workarounds to be applied by the trace encoder or decoder that is created using this configuration.

The pt_errata structure is a collection of one-bit-fields, one for each supported erratum. Duplicate errata are indicated by comments for the erratum for which the workaround was first implemented. Set the field of an erratum to enable the correspondig workaround. 👑

The pt_errata structure is declared as:

/** A collection of Intel PT errata. */
struct pt_errata {
    /** BDM70: Intel(R) Processor Trace PSB+ Packets May Contain
     *         Unexpected Packets.
     *
     * Same as: SKD024.
     *
     * Some Intel Processor Trace packets should be issued only
     * between TIP.PGE and TIP.PGD packets.  Due to this erratum,
     * when a TIP.PGE packet is generated it may be preceded by a
     * PSB+ that incorrectly includes FUP and MODE.Exec packets.
     */
    uint32_t bdm70:1;

    /** BDM64: An Incorrect LBR or Intel(R) Processor Trace Packet
     *         May Be Recorded Following a Transactional Abort.
     *
     * Use of Intel(R) Transactional Synchronization Extensions
     * (Intel(R) TSX) may result in a transactional abort.  If an
     * abort occurs immediately following a branch instruction,
     * an incorrect branch target may be logged in an LBR (Last
     * Branch Record) or in an Intel(R) Processor Trace (Intel(R)
     * PT) packet before the LBR or Intel PT packet produced by
     * the abort.
     */
    uint32_t bdm64:1;

    [...]
};

ngl the [...] up there is doing a lot of heavy lifting — the full erratum list keeps going, this is just where the page shows the shape of it 🍓

🌟 cpuid_0x15_eax, cpuid_0x15_ebx 🌟

The values of eax and ebx on a cpuid call for leaf 0x15.

The value ebx/eax gives the ratio of the Core Crystal Clock (CTC) to Timestamp Counter (TSC) frequency. math bestie 🤓

This field is ignored by the packet encoder and packet decoder. It is required for other decoders if Mini Time Counter (MTC) packets are enabled in the collected trace.

🌟 mtc_freq 🌟

The Mini Time Counter (MTC) frequency as defined in IA32_RTIT_CTL.MTCFreq.

This field is ignored by the packet encoder and packet decoder. It is required for other decoders if Mini Time Counter (MTC) packets are enabled in the collected trace.

🌟 nom_freq 🌟

The nominal or max non-turbo frequency.

This field is ignored by the packet encoder and packet decoder. It is used by other decoders if Cycle Count (CYC) packets are enabled to improve timing calibration for cycle-accurate tracing.

If the field is zero, the time tracking algorithm will use Mini Time Counter (MTC) and Cycle Count (CYC) packets for calibration.

If the field is non-zero, the time tracking algorithm will additionally be able to calibrate at Core:Bus Ratio (CBR) packets. ✨

🌟 flags 🌟

A collection of decoder-specific configuration flags. that's it, that's the field 🎀

🌟 addr_filter 🌟

The address filter configuration. It is declared as:

/** The address filter configuration. */
struct pt_conf_addr_filter {
    /** The address filter configuration.
     *
     * This corresponds to the respective fields in IA32_RTIT_CTL MSR.
     */
    union {
        uint64_t addr_cfg;

        struct {
            uint32_t addr0_cfg:4;
            uint32_t addr1_cfg:4;
            uint32_t addr2_cfg:4;
            uint32_t addr3_cfg:4;
        } ctl;
    } config;

    /** The address ranges configuration.
     *
     * This corresponds to the IA32_RTIT_ADDRn_A/B MSRs.
     */
    uint64_t addr0_a;
    uint64_t addr0_b;
    uint64_t addr1_a;
    uint64_t addr1_b;
    uint64_t addr2_a;
    uint64_t addr2_b;
    uint64_t addr3_a;
    uint64_t addr3_b;

    /* Reserve some space. */
    uint64_t reserved[8];
};

---

🌈 RETURN VALUE 🌈

pt_cpu_errata() returns zero on success, or a negative pt_error_code enumeration constant otherwise. zero = ate, negative = not ate 😭

---

🔥 ERRORS 🔥

pt_cpu_errata() may return the following errors:

• pte_invalid — The errata or cpu argument is NULL. you passed nothing bestie, and it noticed 🙈

🎀 EXAMPLE 🎀

ok bestie, here's the whole little ritual in one place — set up the config, point it at your buffer, tell it which cpu you're on, then let pt_cpu_errata() do its thing and bail if it's mad 💖

int foo(uint8_t *trace_buffer, size_t size, struct pt_cpu cpu) {
    struct pt_config config;
    int errcode;

    pt_config_init(&config);
    config.begin = trace_buffer;
    config.end = trace_buffer + size;
    config.cpu = cpu;

    errcode = pt_cpu_errata(&config.errata, &config.cpu);
    if (errcode < 0)
        return errcode;

    [...]
}

like… the [...] is where you go do your actual decoding thing, obviously 🙈 but everything before it is the vibe: init, fill in begin / end / cpu, check errata, done. no cap.

---

👀 SEE ALSO 👀

go read these next, they're the whole friend group fr fr:

• pt_alloc_encoder(3)
• pt_pkt_alloc_decoder(3)
• pt_qry_alloc_decoder(3)
• pt_insn_alloc_decoder(3)

---

and that's the page, bestie 🫶 this is PT_CONFIG(3) — the man page from the Intel(R) Processor Trace library, straight out of the libipt docs (which is also where the date/version in the footer comes from, iykyk). go forth and configure responsibly, you absolute icon 👑✨