|
Packit |
b1f7ae |
% PT_QRY_EVENT(3)
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
! Copyright (c) 2015-2017, Intel Corporation
|
|
Packit |
b1f7ae |
!
|
|
Packit |
b1f7ae |
! Redistribution and use in source and binary forms, with or without
|
|
Packit |
b1f7ae |
! modification, are permitted provided that the following conditions are met:
|
|
Packit |
b1f7ae |
!
|
|
Packit |
b1f7ae |
! * Redistributions of source code must retain the above copyright notice,
|
|
Packit |
b1f7ae |
! this list of conditions and the following disclaimer.
|
|
Packit |
b1f7ae |
! * Redistributions in binary form must reproduce the above copyright notice,
|
|
Packit |
b1f7ae |
! this list of conditions and the following disclaimer in the documentation
|
|
Packit |
b1f7ae |
! and/or other materials provided with the distribution.
|
|
Packit |
b1f7ae |
! * Neither the name of Intel Corporation nor the names of its contributors
|
|
Packit |
b1f7ae |
! may be used to endorse or promote products derived from this software
|
|
Packit |
b1f7ae |
! without specific prior written permission.
|
|
Packit |
b1f7ae |
!
|
|
Packit |
b1f7ae |
! THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
|
|
Packit |
b1f7ae |
! AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
Packit |
b1f7ae |
! IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
|
Packit |
b1f7ae |
! ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
|
|
Packit |
b1f7ae |
! LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
|
|
Packit |
b1f7ae |
! CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
|
|
Packit |
b1f7ae |
! SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
|
|
Packit |
b1f7ae |
! INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
|
|
Packit |
b1f7ae |
! CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
|
|
Packit |
b1f7ae |
! ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
|
|
Packit |
b1f7ae |
! POSSIBILITY OF SUCH DAMAGE.
|
|
Packit |
b1f7ae |
!-->
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
# NAME
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
pt_qry_event - query an Intel(R) Processor Trace query decoder for an asynchronous event
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
# SYNOPSIS
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
| **\#include `<intel-pt.h>`**
|
|
Packit |
b1f7ae |
|
|
|
Packit |
b1f7ae |
| **int pt_qry_event(struct pt_query_decoder \**decoder*,**
|
|
Packit |
b1f7ae |
| **struct pt_event \**event*, size_t *size*);**
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
Link with *-lipt*.
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
# DESCRIPTION
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
**pt_qry_event**() provides the next pending asynchronous event in *decoder*'s
|
|
Packit |
b1f7ae |
Intel Processor Trace (Intel PT) decode in the *pt_event* object pointed to by
|
|
Packit |
b1f7ae |
the *event* argument.
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
The *size* argument must be set to *sizeof(struct pt_event)*. The function will
|
|
Packit |
b1f7ae |
provide at most *size* bytes of the *pt_event* structure. A newer decoder
|
|
Packit |
b1f7ae |
library may provide event types that are not yet defined. Those events may be
|
|
Packit |
b1f7ae |
truncated.
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
On success, detailed information about the event is provided in the *pt_event*
|
|
Packit |
b1f7ae |
object pointed to by the *event* argument. The *pt_event* structure is declared
|
|
Packit |
b1f7ae |
as:
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
~~~{.c}
|
|
Packit |
b1f7ae |
/** An event. */
|
|
Packit |
b1f7ae |
struct pt_event {
|
|
Packit |
b1f7ae |
/** The type of the event. */
|
|
Packit |
b1f7ae |
enum pt_event_type type;
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
/** A flag indicating that the event IP has been
|
|
Packit |
b1f7ae |
* suppressed.
|
|
Packit |
b1f7ae |
*/
|
|
Packit |
b1f7ae |
uint32_t ip_suppressed:1;
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
/** A flag indicating that the event is for status update. */
|
|
Packit |
b1f7ae |
uint32_t status_update:1;
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
/** A flag indicating that the event has timing
|
|
Packit |
b1f7ae |
* information.
|
|
Packit |
b1f7ae |
*/
|
|
Packit |
b1f7ae |
uint32_t has_tsc:1;
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
/** The time stamp count of the event.
|
|
Packit |
b1f7ae |
*
|
|
Packit |
b1f7ae |
* This field is only valid if \@has_tsc is set.
|
|
Packit |
b1f7ae |
*/
|
|
Packit |
b1f7ae |
uint64_t tsc;
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
/** The number of lost mtc and cyc packets.
|
|
Packit |
b1f7ae |
*
|
|
Packit |
b1f7ae |
* This gives an idea about the quality of the \@tsc. The
|
|
Packit |
b1f7ae |
* more packets were dropped, the less precise timing is.
|
|
Packit |
b1f7ae |
*/
|
|
Packit |
b1f7ae |
uint32_t lost_mtc;
|
|
Packit |
b1f7ae |
uint32_t lost_cyc;
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
/* Reserved space for future extensions. */
|
|
Packit |
b1f7ae |
uint64_t reserved[2];
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
/** Event specific data. */
|
|
Packit |
b1f7ae |
union {
|
|
Packit |
b1f7ae |
/** Event: enabled. */
|
|
Packit |
b1f7ae |
struct {
|
|
Packit |
b1f7ae |
/** The address at which tracing resumes. */
|
|
Packit |
b1f7ae |
uint64_t ip;
|
|
Packit |
b1f7ae |
} enabled;
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
/** Event: disabled. */
|
|
Packit |
b1f7ae |
struct {
|
|
Packit |
b1f7ae |
/** The destination of the first branch inside a
|
|
Packit |
b1f7ae |
* filtered area.
|
|
Packit |
b1f7ae |
*
|
|
Packit |
b1f7ae |
* This field is not valid if \@ip_suppressed is set.
|
|
Packit |
b1f7ae |
*/
|
|
Packit |
b1f7ae |
uint64_t ip;
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
/* The exact source ip needs to be determined using
|
|
Packit |
b1f7ae |
* disassembly and the filter configuration.
|
|
Packit |
b1f7ae |
*/
|
|
Packit |
b1f7ae |
} disabled;
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
[...]
|
|
Packit |
b1f7ae |
} variant;
|
|
Packit |
b1f7ae |
};
|
|
Packit |
b1f7ae |
~~~
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
See the *intel-pt.h* header file for more detail. The common fields of the
|
|
Packit |
b1f7ae |
*pt_event* structure are described in more detail below:
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
type
|
|
Packit |
b1f7ae |
: The type of the event as a *pt_event_type* enumeration, which is declared
|
|
Packit |
b1f7ae |
as:
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
~~~{.c}
|
|
Packit |
b1f7ae |
/** Event types. */
|
|
Packit |
b1f7ae |
enum pt_event_type {
|
|
Packit |
b1f7ae |
/* Tracing has been enabled/disabled. */
|
|
Packit |
b1f7ae |
ptev_enabled,
|
|
Packit |
b1f7ae |
ptev_disabled,
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
/* Tracing has been disabled asynchronously. */
|
|
Packit |
b1f7ae |
ptev_async_disabled,
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
/* An asynchronous branch, e.g. interrupt. */
|
|
Packit |
b1f7ae |
ptev_async_branch,
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
/* A synchronous paging event. */
|
|
Packit |
b1f7ae |
ptev_paging,
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
/* An asynchronous paging event. */
|
|
Packit |
b1f7ae |
ptev_async_paging,
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
/* Trace overflow. */
|
|
Packit |
b1f7ae |
ptev_overflow,
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
/* An execution mode change. */
|
|
Packit |
b1f7ae |
ptev_exec_mode,
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
/* A transactional execution state change. */
|
|
Packit |
b1f7ae |
ptev_tsx,
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
/* Trace Stop. */
|
|
Packit |
b1f7ae |
ptev_stop,
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
/* A synchronous vmcs event. */
|
|
Packit |
b1f7ae |
ptev_vmcs,
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
/* An asynchronous vmcs event. */
|
|
Packit |
b1f7ae |
ptev_async_vmcs
|
|
Packit |
b1f7ae |
};
|
|
Packit |
b1f7ae |
~~~
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
ip_suppressed
|
|
Packit |
b1f7ae |
: A flag indicating whether the *ip* field in the event-dependent part is not
|
|
Packit |
b1f7ae |
valid because the value has been suppressed in the trace.
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
status_update
|
|
Packit |
b1f7ae |
: A flag indicating whether the event is for updating the decoder's status.
|
|
Packit |
b1f7ae |
Status update events originate from Intel PT packets in PSB+.
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
has_tsc
|
|
Packit |
b1f7ae |
: A flag indicating that the event's timing-related fields *tsc*, *lost_mtc*,
|
|
Packit |
b1f7ae |
and *lost_cyc* are valid.
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
tsc
|
|
Packit |
b1f7ae |
: The last time stamp count before the event. Depending on the timing
|
|
Packit |
b1f7ae |
configuration, the timestamp can be more or less precise. For
|
|
Packit |
b1f7ae |
cycle-accurate tracing, event packets are typically CYC-eligible so the
|
|
Packit |
b1f7ae |
timestamp should be cycle-accurate.
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
lost_mtc, lost_cyc
|
|
Packit |
b1f7ae |
: The number of lost MTC and CYC updates. An update is lost if the decoder
|
|
Packit |
b1f7ae |
was not able to process an MTC or CYC packet due to missing information.
|
|
Packit |
b1f7ae |
This can be either missing calibration or missing configuration information.
|
|
Packit |
b1f7ae |
The number of lost MTC and CYC updates gives a rough idea about the quality
|
|
Packit |
b1f7ae |
of the *tsc* field.
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
variant
|
|
Packit |
b1f7ae |
: This field contains event-specific information. See the *intel-pt.h* header
|
|
Packit |
b1f7ae |
file for details.
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
# RETURN VALUE
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
**pt_qry_event**() returns zero or a positive value on success or a negative
|
|
Packit |
b1f7ae |
*pt_error_code* enumeration constant in case of an error.
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
On success, a bit-vector of *pt_status_flag* enumeration constants is returned.
|
|
Packit |
b1f7ae |
The *pt_status_flag* enumeration is declared as:
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
~~~{.c}
|
|
Packit |
b1f7ae |
/** Decoder status flags. */
|
|
Packit |
b1f7ae |
enum pt_status_flag {
|
|
Packit |
b1f7ae |
/** There is an event pending. */
|
|
Packit |
b1f7ae |
pts_event_pending = 1 << 0,
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
/** The address has been suppressed. */
|
|
Packit |
b1f7ae |
pts_ip_suppressed = 1 << 1,
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
/** There is no more trace data available. */
|
|
Packit |
b1f7ae |
pts_eos = 1 << 2
|
|
Packit |
b1f7ae |
};
|
|
Packit |
b1f7ae |
~~~
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
# ERRORS
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
pte_invalid
|
|
Packit |
b1f7ae |
: The *decoder* or *event* argument is NULL or the *size* argument is too
|
|
Packit |
b1f7ae |
small.
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
pte_eos
|
|
Packit |
b1f7ae |
: Decode reached the end of the trace stream.
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
pte_nosync
|
|
Packit |
b1f7ae |
: The decoder has not been synchronized onto the trace stream. Use
|
|
Packit |
b1f7ae |
**pt_qry_sync_forward**(3), **pt_qry_sync_backward**(3), or
|
|
Packit |
b1f7ae |
**pt_qry_sync_set**(3) to synchronize *decoder*.
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
pte_bad_opc
|
|
Packit |
b1f7ae |
: The decoder encountered an unsupported Intel PT packet opcode.
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
pte_bad_packet
|
|
Packit |
b1f7ae |
: The decoder encountered an unsupported Intel PT packet payload.
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
pte_bad_query
|
|
Packit |
b1f7ae |
: The query does not match the data provided in the Intel PT stream. Based on
|
|
Packit |
b1f7ae |
the trace, the decoder expected a call to **pt_qry_cond_branch**(3) or
|
|
Packit |
b1f7ae |
**pt_qry_indirect_branch**(3). This usually means that execution flow
|
|
Packit |
b1f7ae |
reconstruction and trace got out of sync.
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
# SEE ALSO
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
**pt_qry_alloc_decoder**(3), **pt_qry_free_decoder**(3),
|
|
Packit |
b1f7ae |
**pt_qry_cond_branch**(3), **pt_qry_indirect_branch**(3), **pt_qry_time**(3),
|
|
Packit |
b1f7ae |
**pt_qry_core_bus_ratio**(3)
|