libipt: resync

Add

    pt_insn_resync()
    pt_blk_resync()

for re-synchronizing onto the trace stream inside the current PSB segment
after a decode error.

The safe way to re-synchronize is via

    pt_insn_sync_forward()
    pt_blk_sync_forward()

at the next PSB to guarantee that the decoder is properly initialized.  In
particular, deferred TIP packets are guaranteed to not span across PSB+,
and IP compression is reset at PSB.  This may, unfortunately, lose a fair
amount of trace.

Instead of searching for the next PSB, pt_*_resync() scans ahead for the
next packet that provides a full or compressed IP.  It applies packets
that affect the decoder state like MODE, PIP, or timing packets, and it
ignores TNT, assuming no deferred TIP.

Signed-off-by: Markus Metzger <[email protected]>

Author: markus-metzger

doc/howto_libipt.md

@@ -237,6 +237,57 @@ Intel PT shall be generated (for encoders).  This allows implementing
 processor-specific behavior such as erratum workarounds.
 
 
+### Resync
+
+In case of errors, re-synchronizing at the next PSB is the safest option
+and should be the default.  This may lose a fair amount of trace, though,
+as PSB are infrequent.  To avoid that, one may attempt to synchronize at a
+subsequent IP packet using:
+
+  * `pt_<lyr>_resync()`     Synchronize at the next IP packet while keeping
+                            track of the execution state.
+
+
+It only skips packets that do not provide an IP, such as TNT.  Decoders
+still keep track of the execution state via MODE, PIP, and VMCS packets.
+Since TNT are skipped, deferred TIPs may not get placed correctly, and may
+lead to subsequent errors when synchronizing at the TIP IP assuming the
+TIP has not been deferred.
+
+An example of such an extended decode loop is given below:
+
+~~~{.c}
+    for (;;) {
+        int errcode;
+
+        errcode = <use decoder>(decoder);
+        if (errcode >= 0)
+            continue;
+
+        if (errcode == -pte_eos)
+            return;
+
+        <report error>(errcode);
+
+        errcode = pt_<lyr>_resync(decoder);
+        if (errcode >= 0)
+            continue;
+
+        if (errcode == -pte_eos)
+            return;
+
+        do {
+            errcode = pt_<lyr>_sync_forward(decoder);
+
+            if (errcode == -pte_eos)
+                return;
+        } while (errcode < 0);
+    }
+~~~
+
+This option is only supported for the block and instruction flow decoders.
+
+
 ## The Packet Layer
 
 This layer deals with Intel PT packet encoding and decoding.  It can further be

doc/man/CMakeLists.txt

@@ -133,6 +133,7 @@ add_man_page_alias(3 pt_image_remove_by_filename pt_image_remove_by_asid)
 add_man_page_alias(3 pt_insn_alloc_decoder pt_insn_free_decoder)
 add_man_page_alias(3 pt_insn_sync_forward pt_insn_sync_backward)
 add_man_page_alias(3 pt_insn_sync_forward pt_insn_sync_set)
+add_man_page_alias(3 pt_insn_sync_forward pt_insn_resync)
 add_man_page_alias(3 pt_insn_get_offset pt_insn_get_sync_offset)
 add_man_page_alias(3 pt_insn_get_image pt_insn_set_image)
 add_man_page_alias(3 pt_insn_get_image pt_blk_get_image)
@@ -143,6 +144,7 @@ add_man_page_alias(3 pt_iscache_alloc pt_iscache_name)
 add_man_page_alias(3 pt_blk_alloc_decoder pt_blk_free_decoder)
 add_man_page_alias(3 pt_blk_sync_forward pt_blk_sync_backward)
 add_man_page_alias(3 pt_blk_sync_forward pt_blk_sync_set)
+add_man_page_alias(3 pt_blk_sync_forward pt_blk_resync)
 add_man_page_alias(3 pt_blk_get_offset pt_blk_get_sync_offset)
 add_man_page_alias(3 pt_blk_next pt_block)
 

doc/man/pt_blk_next.3.md

@@ -283,5 +283,5 @@ pte_bad_query
 
 **pt_blk_alloc_decoder**(3), **pt_blk_free_decoder**(3),
 **pt_blk_sync_forward**(3), **pt_blk_sync_backward**(3),
-**pt_blk_sync_set**(3), **pt_blk_time**(3), **pt_blk_core_bus_ratio**(3),
-**pt_blk_event**(3)
+**pt_blk_sync_set**(3), **pt_blk_resync**(3), **pt_blk_time**(3),
+**pt_blk_core_bus_ratio**(3), **pt_blk_event**(3)

doc/man/pt_blk_sync_forward.3.md

@@ -34,6 +34,8 @@
 pt_blk_sync_forward, pt_blk_sync_backward, pt_blk_sync_set - synchronize an
 Intel(R) Processor Trace block decoder
 
+pt_blk_resync - resynchronize at the next IP
+
 
 # SYNOPSIS
 
@@ -43,14 +45,18 @@ Intel(R) Processor Trace block decoder
 | **int pt_blk_sync_backward(struct pt_block_decoder \**decoder*);**
 | **int pt_blk_sync_set(struct pt_block_decoder \**decoder*,**
 |                     **uint64_t *offset*);**
+|
+| **int pt_blk_resync(struct pt_block_decoder \**decoder*);**
 
 Link with *-lipt*.
 
 
 # DESCRIPTION
 
-These functions synchronize an Intel Processor Trace (Intel PT) block decoder
-pointed to by *decoder* onto the trace stream in *decoder*'s trace buffer.
+**pt_blk_sync_forward**(), **pt_blk_sync_backward**() and
+**pt_blk_sync_set**() synchronize an Intel Processor Trace (Intel PT)
+block decoder pointed to by *decoder* onto the trace stream in *decoder*'s
+trace buffer.
 
 They search for a Packet Stream Boundary (PSB) packet in the trace stream and,
 if successful, set *decoder*'s current position and synchronization position to
@@ -70,6 +76,10 @@ the end of the trace.
 **pt_blk_sync_set**() searches at *offset* bytes from the beginning of its
 trace buffer.
 
+**pt_blk_resync**() resynchronizes *decoder* at the next IP packet,
+skipping packets that do not provide an IP, such as TNT.  This may lead to
+subsequent errors when synchronizing at a deferred TIP.
+
 
 # RETURN VALUE
 
@@ -138,7 +148,11 @@ int foo(struct pt_block_decoder *decoder) {
             return errcode;
 
         do {
-            errcode = decode(decoder);
+            do {
+                errcode = decode(decoder);
+            } while (errcode >= 0);
+
+            errcode = pt_blk_resync(decoder);
         } while (errcode >= 0);
     }
 }

doc/man/pt_insn_next.3.md

@@ -267,5 +267,5 @@ pte_bad_query
 
 **pt_insn_alloc_decoder**(3), **pt_insn_free_decoder**(3),
 **pt_insn_sync_forward**(3), **pt_insn_sync_backward**(3),
-**pt_insn_sync_set**(3), **pt_insn_time**(3), **pt_insn_core_bus_ratio**(3),
-**pt_insn_event**(3)
+**pt_insn_sync_set**(3), **pt_insn_resync**(3), **pt_insn_time**(3),
+**pt_insn_core_bus_ratio**(3), **pt_insn_event**(3)

doc/man/pt_insn_sync_forward.3.md

@@ -34,6 +34,8 @@
 pt_insn_sync_forward, pt_insn_sync_backward, pt_insn_sync_set - synchronize an
 Intel(R) Processor Trace instruction flow decoder
 
+pt_insn_resync - resynchronize at the next IP
+
 
 # SYNOPSIS
 
@@ -43,15 +45,18 @@ Intel(R) Processor Trace instruction flow decoder
 | **int pt_insn_sync_backward(struct pt_insn_decoder \**decoder*);**
 | **int pt_insn_sync_set(struct pt_insn_decoder \**decoder*,**
 |                      **uint64_t *offset*);**
+|
+| **int pt_insn_resync(struct pt_insn_decoder \**decoder*);**
 
 Link with *-lipt*.
 
 
 # DESCRIPTION
 
-These functions synchronize an Intel Processor Trace (Intel PT) instruction flow
-decoder pointed to by *decoder* onto the trace stream in *decoder*'s trace
-buffer.
+**pt_insn_sync_forward**(), **pt_insn_sync_backward**() and
+**pt_insn_sync_set**() synchronize an Intel Processor Trace (Intel PT)
+instruction flow decoder pointed to by *decoder* onto the trace stream in
+*decoder*'s trace buffer.
 
 They search for a Packet Stream Boundary (PSB) packet in the trace stream and,
 if successful, set *decoder*'s current position and synchronization position to
@@ -71,6 +76,9 @@ the end of the trace.
 **pt_insn_sync_set**() searches at *offset* bytes from the beginning of its
 trace buffer.
 
+**pt_insn_resync**() resynchronizes *decoder* at the next IP packet,
+skipping packets that do not provide an IP, such as TNT.  This may lead to
+subsequent errors when synchronizing at a deferred TIP.
 
 # RETURN VALUE
 
@@ -139,7 +147,11 @@ int foo(struct pt_insn_decoder *decoder) {
 			return status;
 
 		do {
-			status = decode(decoder, status);
+			do {
+				status = decode(decoder, status);
+			} while (status >= 0);
+
+			status = pt_insn_resync(decoder);
 		} while (status >= 0);
 	}
 }

libipt/include/intel-pt.h.in

@@ -2652,6 +2652,30 @@ extern pt_export int pt_insn_sync_backward(struct pt_insn_decoder *decoder);
 extern pt_export int pt_insn_sync_set(struct pt_insn_decoder *decoder,
 				      uint64_t offset);
 
+#if (LIBIPT_VERSION >= 0x202)
+/** Re-synchronize an Intel PT instruction flow decoder.
+ *
+ * Scan ahead for the next IP providing packet.  Apply state changing packets
+ * along the way, including timing packets, but ignore everything else.
+ *
+ * Returns a non-negative pt_status_flag bit-vector on success, a negative
+ * error code otherwise.
+ *
+ * Returns pts_ip_suppressed if re-synchronization succeeded with tracing
+ * disabled.
+ *
+ * Returns -pte_event_ignored if an event cannot safely be skipped
+ * (e.g. ptwrite).  Use pt_insn_event() to read the event, then continue with
+ * pt_insn_resync() until re-synchronization completes or fails with an error.
+ *
+ * Returns -pte_bad_opc if an unknown packet is encountered.
+ * Returns -pte_bad_packet if an unknown packet payload is encountered.
+ * Returns -pte_eos if no further synchronization point is found.
+ * Returns -pte_invalid if \@decoder is NULL.
+ */
+extern pt_export int pt_insn_resync(struct pt_insn_decoder *decoder);
+#endif
+
 /** Get the current decoder position.
  *
  * Fills the current \@decoder position into \@offset.
@@ -2936,6 +2960,30 @@ extern pt_export int pt_blk_sync_backward(struct pt_block_decoder *decoder);
 extern pt_export int pt_blk_sync_set(struct pt_block_decoder *decoder,
 				     uint64_t offset);
 
+#if (LIBIPT_VERSION >= 0x202)
+/** Re-synchronize an Intel PT block decoder.
+ *
+ * Scan ahead for the next IP providing packet.  Apply state changing packets
+ * along the way, including timing packets, but ignore everything else.
+ *
+ * Returns a non-negative pt_status_flag bit-vector on success, a negative
+ * error code otherwise.
+ *
+ * Returns pts_ip_suppressed if re-synchronization succeeded with tracing
+ * disabled.
+ *
+ * Returns -pte_event_ignored if an event cannot safely be skipped
+ * (e.g. ptwrite).  Use pt_blk_event() to read the event, then continue with
+ * pt_blk_resync() until re-synchronization completes or fails with an error.
+ *
+ * Returns -pte_bad_opc if an unknown packet is encountered.
+ * Returns -pte_bad_packet if an unknown packet payload is encountered.
+ * Returns -pte_eos if no further synchronization point is found.
+ * Returns -pte_invalid if \@decoder is NULL.
+ */
+extern pt_export int pt_blk_resync(struct pt_block_decoder *decoder);
+#endif
+
 /** Get the current decoder position.
  *
  * Fills the current \@decoder position into \@offset.