pt_packet(3)

1PT_PACKET(3)                                                      PT_PACKET(3)
2
3
4

NAME

6       pt_packet, pt_enc_next, pt_pkt_next - encode/decode an Intel(R) Proces‐
7       sor Trace packet
8

SYNOPSIS

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
17       Link with -lipt.
18

DESCRIPTION

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
25       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
29       The  caller is responsible for allocating and freeing the pt_packet ob‐
30       ject pointed to be the packet argument.
31
32       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
38       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
44       An Intel PT packet is described by the pt_packet  structure,  which  is
45       declared as:
46
47              /** 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
55                  /** The size of the packet including opcode and payload. */
56                  uint8_t size;
57
58                  /** Packet specific data. */
59                  union {
60                      /** Packets: pad, ovf, psb, psbend, stop - no payload. */
61
62                      /** Packet: tnt-8, tnt-64. */
63                      struct pt_packet_tnt tnt;
64
65                      /** Packet: tip, fup, tip.pge, tip.pgd. */
66                      struct pt_packet_ip ip;
67
68                      /** Packet: mode. */
69                      struct pt_packet_mode mode;
70
71                      /** Packet: pip. */
72                      struct pt_packet_pip pip;
73
74                      /** Packet: tsc. */
75                      struct pt_packet_tsc tsc;
76
77                      /** Packet: cbr. */
78                      struct pt_packet_cbr cbr;
79
80                      /** Packet: tma. */
81                      struct pt_packet_tma tma;
82
83                      /** Packet: mtc. */
84                      struct pt_packet_mtc mtc;
85
86                      /** Packet: cyc. */
87                      struct pt_packet_cyc cyc;
88
89                      /** Packet: vmcs. */
90                      struct pt_packet_vmcs vmcs;
91
92                      /** Packet: mnt. */
93                      struct pt_packet_mnt mnt;
94
95                      /** Packet: unknown. */
96                      struct pt_packet_unknown unknown;
97                  } payload;
98              };
99
100       See the intel-pt.h header file for more detail.
101

RETURN VALUE

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
106       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

ERRORS

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
114       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
120       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
126       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
131       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

EXAMPLE

137       The example shows a typical Intel PT packet decode loop.
138
139              int foo(struct pt_packet_decoder *decoder) {
140                  for (;;) {
141                      struct pt_packet packet;
142                      int errcode;
143
144                      errcode = pt_pkt_next(decoder, &packet, sizeof(packet));
145                      if (errcode < 0)
146                          return errcode;
147
148                      [...]
149                  }
150              }
151

NAME

SYNOPSIS

DESCRIPTION

RETURN VALUE

ERRORS

EXAMPLE

SEE ALSO