PT_EVT_NEXT(3)

✨ PT_EVT_NEXT ✨

bestie. sit down. we're reading pt_evt_next(3) together, and it's literally the page about asking an Intel(R) Processor Trace decoder for an (asynchronous) event. this is the PT_EVT_NEXT(3) page, manual section 3, and yes we are going to get through all of it 💖

---

🌸 NAME 🌸

pt_evt_next, pt_qry_event, pt_insn_event, pt_blk_event — query an Intel(R) Processor Trace decoder for an (asynchronous) event 🦋

---

🎀 SYNOPSIS 🎀

#include <intel-pt.h>
int pt_evt_next(struct pt_event_decoder *decoder,
                struct pt_event *event, size_t size);
int pt_qry_event(struct pt_query_decoder *decoder,
                 struct pt_event *event, size_t size);
int pt_insn_event(struct pt_insn_decoder *decoder,
                  struct pt_event *event, size_t size);
int pt_blk_event(struct pt_block_decoder *decoder,
                 struct pt_event *event, size_t size);

Link with -lipt.

---

🦋 DESCRIPTION 🦋

okay so pt_evt_next() hands you the next Intel Processor Trace (Intel PT) event from decoder's Intel PT decode, and it drops it into the pt_event object that the event argument is pointing at. and the tea? it gives you asynchronous events and synchronous control-flow events. both. iconic behavior 💅

meanwhile pt_qry_event(), pt_insn_event(), and pt_blk_event() only hand you the next pending asynchronous event in decoder's Intel PT decode, into the pt_event object the event argument points at. the synchronous control-flow events? nope, the decoder interprets those itself and they will not be provided through this interface. not up for discussion 🫶

the size argument must be set to sizeof(struct pt_event). the function will provide at most size bytes of the pt_event structure. and here's the part nobody tells you: a newer decoder library may provide event types that are not yet defined, and those events may be truncated 😭

on success, detailed info about the event lands in the pt_event object that event points to. the pt_event structure is declared as:

/** An event. */
struct pt_event {
    /** The type of the event. */
    enum pt_event_type type;

    /** A flag indicating that the event IP has been
     * suppressed.
     */
    uint32_t ip_suppressed:1;

    /** A flag indicating that the event is for status update. */
    uint32_t status_update:1;

    /** A flag indicating that the event has timing
     * information.
     */
    uint32_t has_tsc:1;

    /** The time stamp count of the event.
     *
     * This field is only valid if \@has_tsc is set.
     */
    uint64_t tsc;

    /** The number of lost mtc and cyc packets.
     *
     * This gives an idea about the quality of the \@tsc.  The
     * more packets were dropped, the less precise timing is.
     */
    uint32_t lost_mtc;
    uint32_t lost_cyc;

    /* Reserved space for future extensions. */
    uint64_t reserved[2];

    /** Event specific data. */
    union {
        /** Event: enabled. */
        struct {
            /** The address at which tracing resumes. */
            uint64_t ip;

            /** A flag indicating that tracing resumes from the IP
             * at which tracing had been disabled before.
             */
            uint32_t resumed:1;
        } enabled;

        /** Event: disabled. */
        struct {
            /** The destination of the first branch inside a
             * filtered area.
             *
             * This field is not valid if \@ip_suppressed is set.
             */
            uint64_t ip;

            /* The exact source ip needs to be determined using
             * disassembly and the filter configuration.
             */
        } disabled;

        [...]
    } variant;
};

see the intel-pt.h header file for more detail. the common fields of the pt_event structure are described in more detail below 👇

• type — the type of the event, as a pt_event_type enumeration, which is declared as:

/** Event types. */
enum pt_event_type {
    /* Tracing has been enabled/disabled. */
    ptev_enabled,
    ptev_disabled,

    /* Tracing has been disabled asynchronously. */
    ptev_async_disabled,

    /* An asynchronous branch, e.g. interrupt. */
    ptev_async_branch,

    /* A synchronous paging event. */
    ptev_paging,

    /* An asynchronous paging event. */
    ptev_async_paging,

    /* Trace overflow. */
    ptev_overflow,

    /* An execution mode change. */
    ptev_exec_mode,

    /* A transactional execution state change. */
    ptev_tsx,

    /* Trace Stop. */
    ptev_stop,

    /* A synchronous vmcs event. */
    ptev_vmcs,

    /* An asynchronous vmcs event. */
    ptev_async_vmcs,

    /* Execution has stopped. */
    ptev_exstop,

    /* An MWAIT operation completed. */
    ptev_mwait,

    /* A power state was entered. */
    ptev_pwre,

    /* A power state was exited. */
    ptev_pwrx,

    /* A PTWRITE event. */
    ptev_ptwrite,

    /* A timing event. */
    ptev_tick,

    /* A core:bus ratio event. */
    ptev_cbr,

    /* A maintenance event. */
    ptev_mnt,

    /* An indirect branch event. */
    ptev_tip,

    /* A conditional branch indicator event. */
    ptev_tnt
};

• ip_suppressed — a flag saying whether the ip field in the event-dependent part is not valid, because the value has been suppressed in the trace 🙈
• status_update — a flag saying whether the event is for updating the decoder's status. status update events originate from Intel PT packets in PSB+.
• has_tsc — a flag saying that the event's timing-related fields tsc, lost_mtc, and lost_cyc are valid.
• tsc — the last time stamp count before the event. depending on the timing configuration, the timestamp can be more or less precise. for cycle-accurate tracing, event packets are typically CYC-eligible so the timestamp should be cycle-accurate. slay ⭐
• lost_mtc, lost_cyc — the number of lost MTC and CYC updates. an update is lost if the decoder was not able to process an MTC or CYC packet due to missing information. that can be either missing calibration or missing configuration information. the number of lost MTC and CYC updates gives a rough idea about the quality of the tsc field. so like, the more that got dropped, the less precise your timing is 💀
• variant — this field contains event-specific information. see the intel-pt.h header file for details.

---

💜 RETURN VALUE 💜

pt_evt_next(), pt_qry_event(), pt_insn_event(), and pt_blk_event() return zero or a positive value on success, or a negative pt_error_code enumeration constant in case of an error.

on success, pt_qry_event(), pt_insn_event(), and pt_blk_event() return a bit-vector of pt_status_flag enumeration constants. the pt_status_flag enumeration is declared as:

/** Decoder status flags. */
enum pt_status_flag {
    /** There is an event pending. */
    pts_event_pending   = 1 << 0,

    /** The address has been suppressed. */
    pts_ip_suppressed   = 1 << 1,

    /** There is no more trace data available. */
    pts_eos             = 1 << 2
};

---

💀 ERRORS 💀

• pte_invalid — the decoder or event argument is NULL, or the size argument is too small.
• pte_eos — decode reached the end of the trace stream.
• pte_nosync — the decoder has not been synchronized onto the trace stream. use pt_evt_sync_forward(3), pt_evt_sync_backward(3), or pt_evt_sync_set(3) to synchronize decoder.
• pte_bad_opc — the decoder encountered an unsupported Intel PT packet opcode.
• pte_bad_packet — the decoder encountered an unsupported Intel PT packet payload.
• pte_bad_query — the query does not match the data provided in the Intel PT stream. based on the trace, the decoder expected a call to pt_qry_cond_branch(3) or pt_qry_indirect_branch(3). this usually means that execution flow reconstruction and trace got out of sync 😭

---

🌈 SEE ALSO 🌈

pt_evt_alloc_decoder(3), pt_evt_free_decoder(3), pt_qry_cond_branch(3), pt_qry_indirect_branch(3), pt_insn_next(3), pt_blk_next(3)

---

okay bestie that's the whole page, top to bottom, no skips 🫶 this was the PT_EVT_NEXT(3) page — same name up top and down at the bottom in the footer, section 3 of the manual, straight out of the Intel PT / -lipt family, and the date line in the original is just the page title with nothing else stamped on it. go forth and query your events, main character 🎀✨💅