% PT_EVT_NEXT(3)

<!---
 ! Copyright (c) 2015-2025, Intel Corporation
 ! SPDX-License-Identifier: BSD-3-Clause
 !
 ! Redistribution and use in source and binary forms, with or without
 ! modification, are permitted provided that the following conditions are met:
 !
 !  * Redistributions of source code must retain the above copyright notice,
 !    this list of conditions and the following disclaimer.
 !  * Redistributions in binary form must reproduce the above copyright notice,
 !    this list of conditions and the following disclaimer in the documentation
 !    and/or other materials provided with the distribution.
 !  * Neither the name of Intel Corporation nor the names of its contributors
 !    may be used to endorse or promote products derived from this software
 !    without specific prior written permission.
 !
 ! THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 ! AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 ! IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 ! ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
 ! LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
 ! CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
 ! SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
 ! INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
 ! CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
 ! ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 ! POSSIBILITY OF SUCH DAMAGE.
 !-->

# 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

**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:

~~~{.c}
/** 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:

~~~{.c}
/** 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.


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

~~~{.c}
/** 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)