1 files changed, 197 insertions, 0 deletions
diff --git a/doc/man/pt_packet.3.md b/doc/man/pt_packet.3.md
new file mode 100644
index 0000000000000..c8d1c806da1b4
--- /dev/null
+++ b/doc/man/pt_packet.3.md
@@ -0,0 +1,197 @@
+% PT_PACKET(3)
+
+<!---
+ ! Copyright (c) 2015-2019, Intel Corporation
+ !
+ ! Redistribution and use in source and binary forms, with or without
+ ! modification, are permitted provided that the following conditions are met:
+ !
+ !  * Redistributions of source code must retain the above copyright notice,
+ !    this list of conditions and the following disclaimer.
+ !  * Redistributions in binary form must reproduce the above copyright notice,
+ !    this list of conditions and the following disclaimer in the documentation
+ !    and/or other materials provided with the distribution.
+ !  * Neither the name of Intel Corporation nor the names of its contributors
+ !    may be used to endorse or promote products derived from this software
+ !    without specific prior written permission.
+ !
+ ! THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ ! AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ ! IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ ! ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
+ ! LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ ! CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ ! SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ ! INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ ! CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ ! ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ ! POSSIBILITY OF SUCH DAMAGE.
+ !-->
+
+# NAME
+
+pt_packet, pt_enc_next, pt_pkt_next - encode/decode an Intel(R) Processor Trace
+packet
+
+
+# SYNOPSIS
+
+| **\#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*.
+
+
+# DESCRIPTION
+
+**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:
+
+~~~{.c}
+/** 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.
+
+
+# RETURN VALUE
+
+**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.
+
+
+# ERRORS
+
+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**()).
+
+
+# EXAMPLE
+
+The example shows a typical Intel PT packet decode loop.
+
+~~~{.c}
+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;
+
+		[...]
+	}
+}
+~~~
+
+
+# SEE ALSO
+
+**pt_alloc_encoder**(3), **pt_pkt_alloc_decoder**(3),
+**pt_pkt_sync_forward**(3), **pt_pkt_sync_backward**(3), **pt_pkt_sync_set**(3)