1PT_PACKET(3) PT_PACKET(3)
2
6 pt_packet, pt_enc_next, pt_pkt_next - encode/decode an Intel(R) Proces‐
7 sor Trace packet
8
10 #include <intel-pt.h>
11 struct pt_packet;
12 int pt_enc_next(struct pt_packet_encoder *encoder,
13 const struct pt_packet *packet);
14 int pt_pkt_next(struct pt_packet_decoder *decoder,
15 struct pt_packet *packet, size_t size);
16 Link with -lipt.
18
20 pt_enc_next() encodes its packet argument as Intel Processor Trace (In‐
21 tel PT) packet at encoder's current position. On success, sets en‐
22 coder's current position to point to the first byte after the encoded
23 packet.
24 pt_pkt_next() decodes the Intel PT packet at decoder's current position
26 into packet. On success, sets decoder*'s current position to point to
27 the first byte after the decoded packet.
28 The caller is responsible for allocating and freeing the pt_packet ob‐
30 ject pointed to be the packet argument.
31 The size argument of pt_pkt_next() must be set to sizeof(struct
33 pt_packet). The function will provide at most size bytes of packet da‐
34 ta. A newer decoder library may provide packet types that are not yet
35 defined. Those packets may be truncated. Unknown packet types should
36 be ignored.
37 If the packet decoder does not know the packet opcode at decoder's cur‐
39 rent position and if decoder's configuration contains a packet decode
40 callback function, pt_pkt_next() will call that callback function to
41 decode the unknown packet. On success, a ppt_unknown packet type is
42 provided with the information provided by the decode callback function.
43 An Intel PT packet is described by the pt_packet structure, which is
45 declared as:
46 /** An Intel PT packet. */
48 struct pt_packet {
49 /** The type of the packet.
50 *
51 * This also determines the \@variant field.
52 */
53 enum pt_packet_type type;
54 /** The size of the packet including opcode and payload. */
56 uint8_t size;
57 /** Packet specific data. */
59 union {
60 /** Packets: pad, ovf, psb, psbend, stop - no payload. */
61 /** Packet: tnt-8, tnt-64. */
63 struct pt_packet_tnt tnt;
64 /** Packet: tip, fup, tip.pge, tip.pgd. */
66 struct pt_packet_ip ip;
67 /** Packet: mode. */
69 struct pt_packet_mode mode;
70 /** Packet: pip. */
72 struct pt_packet_pip pip;
73 /** Packet: tsc. */
75 struct pt_packet_tsc tsc;
76 /** Packet: cbr. */
78 struct pt_packet_cbr cbr;
79 /** Packet: tma. */
81 struct pt_packet_tma tma;
82 /** Packet: mtc. */
84 struct pt_packet_mtc mtc;
85 /** Packet: cyc. */
87 struct pt_packet_cyc cyc;
88 /** Packet: vmcs. */
90 struct pt_packet_vmcs vmcs;
91 /** Packet: mnt. */
93 struct pt_packet_mnt mnt;
94 /** Packet: unknown. */
96 struct pt_packet_unknown unknown;
97 } payload;
98 };
99 See the intel-pt.h header file for more detail.
101
103 pt_enc_next() returns the number of bytes written on success or a nega‐
104 tive pt_error_code enumeration constant in case of an error.
105 pt_pkt_next() returns the number of bytes consumed on success or a neg‐
107 ative pt_error_code enumeration constant in case of an error.
108
110 pte_invalid
111 The encoder/decoder or packet argument is NULL or the size argu‐
112 ment is zero (pt_pkt_next() only).
113 pte_nosync
115 decoder has not been synchronized onto the trace stream
116 (pt_pkt_next() only). Use pt_pkt_sync_forward(3),
117 pt_pkt_sync_backward(3), or pt_pkt_sync_set(3) to synchronize
118 decoder.
119 pte_eos
121 Encode/decode has reached the end of the trace buffer. There is
122 not enough space in the trace buffer to generate packet
123 (pt_enc_next()) or the trace buffer does not contain a full In‐
124 tel PT packet (pt_pkt_next()).
125 pte_bad_opc
127 The type of the packet argument is not supported (pt_enc_next())
128 or the packet at decoder's current position is not supported
129 (pt_pkt_next()).
130 pte_bad_packet
132 The payload or parts of the payload of the packet argument is
133 not supported (pt_enc_next()) or the packet at decoder's current
134 position contains unsupported payload (pt_pkt_next()).
135
137 The example shows a typical Intel PT packet decode loop.
138 int foo(struct pt_packet_decoder *decoder) {
140 for (;;) {
141 struct pt_packet packet;
142 int errcode;
143 errcode = pt_pkt_next(decoder, &packet, sizeof(packet));
145 if (errcode < 0)
146 return errcode;
147 [...]
149 }
150 }
151
153 pt_alloc_encoder(3), pt_pkt_alloc_decoder(3), pt_pkt_sync_forward(3),
154 pt_pkt_sync_backward(3), pt_pkt_sync_set(3)
155 PT_PACKET(3)