pt_packet - Man Page

#include <intel-pt.h>

struct pt_packet;

int pt_enc_next(struct pt_packet_encoder *encoder,

                const struct pt_packet *packet);

int pt_pkt_next(struct pt_packet_decoder *decoder,

                struct pt_packet *packet, size_t size);

Link with -lipt.

pt_enc_next() encodes its packet argument as Intel Processor Trace (Intel PT) packet at encoder’s current position. On success, sets encoder’s current position to point to the first byte after the encoded packet.

pt_pkt_next() decodes the Intel PT packet at decoder’s current position into packet. On success, sets decoder*’s current position to point to the first byte after the decoded packet.

The caller is responsible for allocating and freeing the pt_packet object pointed to be the packet argument.

The size argument of pt_pkt_next() must be set to sizeof(struct pt_packet). The function will provide at most size bytes of packet data. A newer decoder library may provide packet types that are not yet defined. Those packets may be truncated. Unknown packet types should be ignored.

If the packet decoder does not know the packet opcode at decoder’s current position and if decoder’s configuration contains a packet decode callback function, pt_pkt_next() will call that callback function to decode the unknown packet. On success, a ppt_unknown packet type is provided with the information provided by the decode callback function.

An Intel PT packet is described by the pt_packet structure, which is declared as:

/** An Intel PT packet. */
struct pt_packet {
    /** The type of the packet.
     *
     * This also determines the \@variant field.
     */
    enum pt_packet_type type;

    /** The size of the packet including opcode and payload. */
    uint8_t size;

    /** Packet specific data. */
    union {
        /** Packets: pad, ovf, psb, psbend, stop - no payload. */

        /** Packet: tnt-8, tnt-64. */
        struct pt_packet_tnt tnt;

        /** Packet: tip, fup, tip.pge, tip.pgd. */
        struct pt_packet_ip ip;

        /** Packet: mode. */
        struct pt_packet_mode mode;

        /** Packet: pip. */
        struct pt_packet_pip pip;

        /** Packet: tsc. */
        struct pt_packet_tsc tsc;

        /** Packet: cbr. */
        struct pt_packet_cbr cbr;

        /** Packet: tma. */
        struct pt_packet_tma tma;

        /** Packet: mtc. */
        struct pt_packet_mtc mtc;

        /** Packet: cyc. */
        struct pt_packet_cyc cyc;

        /** Packet: vmcs. */
        struct pt_packet_vmcs vmcs;

        /** Packet: mnt. */
        struct pt_packet_mnt mnt;

        /** Packet: unknown. */
        struct pt_packet_unknown unknown;
    } payload;
};

See the intel-pt.h header file for more detail.

pt_enc_next() returns the number of bytes written on success or a negative pt_error_code enumeration constant in case of an error.

pt_pkt_next() returns the number of bytes consumed on success or a negative pt_error_code enumeration constant in case of an error.

pte_invalid

The encoder/decoder or packet argument is NULL or the size argument is zero (pt_pkt_next() only).

pte_nosync

decoder has not been synchronized onto the trace stream (pt_pkt_next() only). Use pt_pkt_sync_forward(3), pt_pkt_sync_backward(3), or pt_pkt_sync_set(3) to synchronize decoder.

pte_eos

Encode/decode has reached the end of the trace buffer. There is not enough space in the trace buffer to generate packet (pt_enc_next()) or the trace buffer does not contain a full Intel PT packet (pt_pkt_next()).

pte_bad_opc

The type of the packet argument is not supported (pt_enc_next()) or the packet at decoder’s current position is not supported (pt_pkt_next()).

pte_bad_packet

The payload or parts of the payload of the packet argument is not supported (pt_enc_next()) or the packet at decoder’s current position contains unsupported payload (pt_pkt_next()).

The example shows a typical Intel PT packet decode loop.

int foo(struct pt_packet_decoder *decoder) {
    for (;;) {
        struct pt_packet packet;
        int errcode;

        errcode = pt_pkt_next(decoder, &packet, sizeof(packet));
        if (errcode < 0)
            return errcode;

        [...]
    }
}

pt_alloc_encoder(3), pt_pkt_alloc_decoder(3), pt_pkt_sync_forward(3), pt_pkt_sync_backward(3), pt_pkt_sync_set(3)

pt_alloc_encoder(3), pt_enc_get_offset(3), pt_pkt_alloc_decoder(3), pt_pkt_get_offset(3), pt_pkt_sync_forward(3).

The man pages pt_enc_next(3) and pt_pkt_next(3) are aliases of pt_packet(3).