|
Packit |
b1f7ae |
% PT_PACKET(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_packet, pt_enc_next, pt_pkt_next - encode/decode an Intel(R) Processor Trace
|
|
Packit |
b1f7ae |
packet
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
# SYNOPSIS
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
| **\#include `<intel-pt.h>`**
|
|
Packit |
b1f7ae |
|
|
|
Packit |
b1f7ae |
| **struct pt_packet;**
|
|
Packit |
b1f7ae |
|
|
|
Packit |
b1f7ae |
| **int pt_enc_next(struct pt_packet_encoder \**encoder*,**
|
|
Packit |
b1f7ae |
| **const struct pt_packet \**packet*);**
|
|
Packit |
b1f7ae |
|
|
|
Packit |
b1f7ae |
| **int pt_pkt_next(struct pt_packet_decoder \**decoder*,**
|
|
Packit |
b1f7ae |
| **struct pt_packet \**packet*, size_t *size*);**
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
Link with *-lipt*.
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
# DESCRIPTION
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
**pt_enc_next**() encodes its *packet* argument as Intel Processor Trace (Intel
|
|
Packit |
b1f7ae |
PT) packet at *encoder*'s current position. On success, sets *encoder*'s
|
|
Packit |
b1f7ae |
current position to point to the first byte after the encoded packet.
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
**pt_pkt_next**() decodes the Intel PT packet at decoder*'s current position
|
|
Packit |
b1f7ae |
into *packet*. On success, sets *decoder*'s current position to point to the
|
|
Packit |
b1f7ae |
first byte after the decoded packet.
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
The caller is responsible for allocating and freeing the *pt_packet* object
|
|
Packit |
b1f7ae |
pointed to be the *packet* argument.
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
The *size* argument of **pt_pkt_next**() must be set to *sizeof(struct
|
|
Packit |
b1f7ae |
pt_packet)*. The function will provide at most *size* bytes of packet data. A
|
|
Packit |
b1f7ae |
newer decoder library may provide packet types that are not yet defined. Those
|
|
Packit |
b1f7ae |
packets may be truncated. Unknown packet types should be ignored.
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
If the packet decoder does not know the packet opcode at *decoder*'s current
|
|
Packit |
b1f7ae |
position and if *decoder*'s configuration contains a packet decode callback
|
|
Packit |
b1f7ae |
function, **pt_pkt_next**() will call that callback function to decode the
|
|
Packit |
b1f7ae |
unknown packet. On success, a *ppt_unknown* packet type is provided with the
|
|
Packit |
b1f7ae |
information provided by the decode callback function.
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
An Intel PT packet is described by the *pt_packet* structure, which is declared
|
|
Packit |
b1f7ae |
as:
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
~~~{.c}
|
|
Packit |
b1f7ae |
/** An Intel PT packet. */
|
|
Packit |
b1f7ae |
struct pt_packet {
|
|
Packit |
b1f7ae |
/** The type of the packet.
|
|
Packit |
b1f7ae |
*
|
|
Packit |
b1f7ae |
* This also determines the \@variant field.
|
|
Packit |
b1f7ae |
*/
|
|
Packit |
b1f7ae |
enum pt_packet_type type;
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
/** The size of the packet including opcode and payload. */
|
|
Packit |
b1f7ae |
uint8_t size;
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
/** Packet specific data. */
|
|
Packit |
b1f7ae |
union {
|
|
Packit |
b1f7ae |
/** Packets: pad, ovf, psb, psbend, stop - no payload. */
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
/** Packet: tnt-8, tnt-64. */
|
|
Packit |
b1f7ae |
struct pt_packet_tnt tnt;
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
/** Packet: tip, fup, tip.pge, tip.pgd. */
|
|
Packit |
b1f7ae |
struct pt_packet_ip ip;
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
/** Packet: mode. */
|
|
Packit |
b1f7ae |
struct pt_packet_mode mode;
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
/** Packet: pip. */
|
|
Packit |
b1f7ae |
struct pt_packet_pip pip;
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
/** Packet: tsc. */
|
|
Packit |
b1f7ae |
struct pt_packet_tsc tsc;
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
/** Packet: cbr. */
|
|
Packit |
b1f7ae |
struct pt_packet_cbr cbr;
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
/** Packet: tma. */
|
|
Packit |
b1f7ae |
struct pt_packet_tma tma;
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
/** Packet: mtc. */
|
|
Packit |
b1f7ae |
struct pt_packet_mtc mtc;
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
/** Packet: cyc. */
|
|
Packit |
b1f7ae |
struct pt_packet_cyc cyc;
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
/** Packet: vmcs. */
|
|
Packit |
b1f7ae |
struct pt_packet_vmcs vmcs;
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
/** Packet: mnt. */
|
|
Packit |
b1f7ae |
struct pt_packet_mnt mnt;
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
/** Packet: unknown. */
|
|
Packit |
b1f7ae |
struct pt_packet_unknown unknown;
|
|
Packit |
b1f7ae |
} payload;
|
|
Packit |
b1f7ae |
};
|
|
Packit |
b1f7ae |
~~~
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
See the *intel-pt.h* header file for more detail.
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
# RETURN VALUE
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
**pt_enc_next**() returns the number of bytes written on success or a negative
|
|
Packit |
b1f7ae |
*pt_error_code* enumeration constant in case of an error.
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
**pt_pkt_next**() returns the number of bytes consumed on success or a negative
|
|
Packit |
b1f7ae |
*pt_error_code* enumeration constant in case of an error.
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
# ERRORS
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
pte_invalid
|
|
Packit |
b1f7ae |
: The *encoder*/*decoder* or *packet* argument is NULL or the *size* argument
|
|
Packit |
b1f7ae |
is zero (**pt_pkt_next**() only).
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
pte_nosync
|
|
Packit |
b1f7ae |
: *decoder* has not been synchronized onto the trace stream (**pt_pkt_next**()
|
|
Packit |
b1f7ae |
only). Use **pt_pkt_sync_forward**(3), **pt_pkt_sync_backward**(3), or
|
|
Packit |
b1f7ae |
**pt_pkt_sync_set**(3) to synchronize *decoder*.
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
pte_eos
|
|
Packit |
b1f7ae |
: Encode/decode has reached the end of the trace buffer. There is not enough
|
|
Packit |
b1f7ae |
space in the trace buffer to generate *packet* (**pt_enc_next**()) or the
|
|
Packit |
b1f7ae |
trace buffer does not contain a full Intel PT packet (**pt_pkt_next**()).
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
pte_bad_opc
|
|
Packit |
b1f7ae |
: The type of the *packet* argument is not supported (**pt_enc_next**()) or
|
|
Packit |
b1f7ae |
the packet at *decoder*'s current position is not supported
|
|
Packit |
b1f7ae |
(**pt_pkt_next**()).
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
pte_bad_packet
|
|
Packit |
b1f7ae |
: The payload or parts of the payload of the *packet* argument is not
|
|
Packit |
b1f7ae |
supported (**pt_enc_next**()) or the packet at *decoder*'s current position
|
|
Packit |
b1f7ae |
contains unsupported payload (**pt_pkt_next**()).
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
# EXAMPLE
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
The example shows a typical Intel PT packet decode loop.
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
~~~{.c}
|
|
Packit |
b1f7ae |
int foo(struct pt_packet_decoder *decoder) {
|
|
Packit |
b1f7ae |
for (;;) {
|
|
Packit |
b1f7ae |
struct pt_packet packet;
|
|
Packit |
b1f7ae |
int errcode;
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
errcode = pt_pkt_next(decoder, &packet, sizeof(packet));
|
|
Packit |
b1f7ae |
if (errcode < 0)
|
|
Packit |
b1f7ae |
return errcode;
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
[...]
|
|
Packit |
b1f7ae |
}
|
|
Packit |
b1f7ae |
}
|
|
Packit |
b1f7ae |
~~~
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
# SEE ALSO
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
**pt_alloc_encoder**(3), **pt_pkt_alloc_decoder**(3),
|
|
Packit |
b1f7ae |
**pt_pkt_sync_forward**(3), **pt_pkt_sync_backward**(3), **pt_pkt_sync_set**(3)
|