pt_evt_next - Man Page

#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.

pt_evt_next() provides the next Intel Processor Trace (Intel PT) event in decoder’s Intel PT decode in the pt_event object pointed to by the event argument. This function provides asynchronous events as well as synchronous control-flow events.

pt_qry_event(), pt_insn_event(), and pt_blk_event() provide the next pending asynchronous event in decoder’s Intel PT decode in the pt_event object pointed to by the event argument. Synchronous control-flow events are interpreted by the decoder and will not be provided through this interface.

The size argument must be set to sizeof(struct pt_event). The function will provide at most size bytes of the pt_event structure. A newer decoder library may provide event types that are not yet defined. Those events may be truncated.

On success, detailed information about the event is provided in the pt_event object pointed to by the event argument. 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 indicating 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 indicating whether the event is for updating the decoder’s status. Status update events originate from Intel PT packets in PSB+.

has_tsc

A flag indicating 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.

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. This 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.

variant

This field contains event-specific information. See the intel-pt.h header file for details.

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
};

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.

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)

pt_blk_next(3), pt_blk_sync_forward(3), pt_insn_next(3), pt_insn_sync_forward(3), pt_qry_alloc_decoder(3), pt_qry_cond_branch(3), pt_qry_get_offset(3), pt_qry_sync_forward(3), pt_qry_time(3).

The man pages pt_blk_event(3), pt_insn_event(3) and pt_qry_event(3) are aliases of pt_evt_next(3).