PT_QRY_EVENT(3)

NAME

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_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

pt_qry_event(), pt_insn_event(), and pt_blk_event() provide the next pending asynchronous event in decoder’s Intel Processor Trace (Intel PT) decode in the pt_event object pointed to by the event argument.

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

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.

RETURN VALUE

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, a bit-vector of pt_status_flag enumeration constants is returned. 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_qry_sync_forward(3), pt_qry_sync_backward(3), or pt_qry_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_qry_alloc_decoder(3), pt_qry_free_decoder(3), pt_qry_cond_branch(3), pt_qry_indirect_branch(3), pt_qry_time(3), pt_qry_core_bus_ratio(3), pt_insn_next(3), pt_blk_next(3)