i#7050: Bump the TRACE_ENTRY_VERSION and rename OFFLINE_FILE_VERSION_…

…RETIRED_INSTRUCTIONS_ONLY. (#7156)

Add a new trace version TRACE_ENTRY_VERSION_RETIRED_INSTRUCTIONS_ONLY
for #7050 and bump the TRACE_ENTRY_VERSION.

Rename OFFLINE_FILE_VERSION_RETIRED_INSTRUCTIONS_ONLY to
OFFLINE_FILE_VERSION_NO_OP since there were no changes in the raw trace
by #7050.

#7058 incorrectly changed the OFFLINE_FILE_VERSION, it should have
changed TRACE_ENTRY_VERSION instead.

Issue: #7050

api/docs/release.dox

@@ -126,7 +126,8 @@ clients.
 
 The changes between version \DR_VERSION and 11.1.0 include the following compatibility
 changes:
- - No compatibility changes yet.
+ - Added #dynamorio::drmemtrace::TRACE_ENTRY_VERSION_RETIRED_INSTRUCTIONS_ONLY to increase the
+   trace version for drmemtraces with uncompleted instructions removed.
 
 Further non-compatibility-affecting changes include:
  - Added instr_get_operation_size() and instr_set_operation_size() APIs for
@@ -142,9 +143,10 @@ changes:
    fault are removed. A new marker
    #dynamorio::drmemtrace::TRACE_MARKER_TYPE_UNCOMPLETED_INSTRUCTION was added
    to indicate an uncompleted instruction was removed. The value of the marker
-   is the encoding of the removed instruction up to a pointer's length. Added
-   #OFFLINE_FILE_VERSION_RETIRED_INSTRUCTIONS_ONLY to increase the trace version
-   for drmemtraces with uncompleted instructions removed.
+   is the encoding of the removed instruction up to a pointer's length.
+   OFFLINE_FILE_VERSION_RETIRED_INSTRUCTIONS_ONLY was added by mistake and it was changed to
+   #OFFLINE_FILE_VERSION_NO_OP.
+
  - Moved module file read logic into read_module_file() in raw2trace_shared, and
    removed raw2trace_directory_t::initialize_module_file() since the
    read_module_file() can be directly used without having to pull in the whole

clients/drcachesim/common/trace_entry.h

@@ -102,8 +102,23 @@ typedef enum {
      * post-syscall timestamp actually containing the pre-syscall time.
      */
     TRACE_ENTRY_VERSION_FREQUENT_TIMESTAMPS = 6,
+    /*
+     * The trace supports #TRACE_MARKER_TYPE_UNCOMPLETED_INSTRUCTION. The marker is used
+     * to indicate an instruction started to execute but didn't retire. The instruction
+     * was either preempted by an asynchronous signal or caused a fault. The instruction
+     * and corresponding memrefs are removed from the trace.
+     *
+     * The marker value is the raw encoding bytes of the instruction up to the
+     * length of a pointer. The encoding will be incomplete for instructions
+     * with long encodings. It is best-effort to help understand the sequence of
+     * generated code where encodings are not available offline. The PC of this
+     * instruction is available in a subsequent
+     * #dynamorio::drmemtrace::TRACE_MARKER_TYPE_KERNEL_EVENT marker.
+     */
+    TRACE_ENTRY_VERSION_RETIRED_INSTRUCTIONS_ONLY =
+        7, /**< Trace version which has only retired instructions in drmemtraces.*/
     /** The latest version of the trace format. */
-    TRACE_ENTRY_VERSION = TRACE_ENTRY_VERSION_FREQUENT_TIMESTAMPS,
+    TRACE_ENTRY_VERSION = TRACE_ENTRY_VERSION_RETIRED_INSTRUCTIONS_ONLY,
 } trace_version_t;
 
 /** The type of a trace entry in a #memref_t structure. */
@@ -963,9 +978,8 @@ typedef enum {
 #define OFFLINE_FILE_VERSION_ENCODINGS 6
 #define OFFLINE_FILE_VERSION_XFER_ABS_PC \
     7 /**< Use the absolute PC for kernel interruption PC for 64-bit mode.*/
-#define OFFLINE_FILE_VERSION_RETIRED_INSTRUCTIONS_ONLY \
-    8 /**< Trace version which has only retired instructions in drmemtraces.*/
-#define OFFLINE_FILE_VERSION OFFLINE_FILE_VERSION_RETIRED_INSTRUCTIONS_ONLY
+#define OFFLINE_FILE_VERSION_NO_OP 8 /**< There are no changes in this version.*/
+#define OFFLINE_FILE_VERSION OFFLINE_FILE_VERSION_NO_OP
 
 /**
  * Bitfields used to describe the high-level characteristics of both an

clients/drcachesim/tests/offline-phys.templatex

@@ -11,7 +11,7 @@ Adios world!
 Output format:
 <--record#-> <--instr#->: <---tid---> <record details>
 ------------------------------------------------------------
-           1           0: +[0-9]+ <marker: version 6>
+           1           0: +[0-9]+ <marker: version 7>
            2           0: +[0-9]+ <marker: filetype 0xe42>
            3           0: +[0-9]+ <marker: cache line size [0-9]+>
            4           0: +[0-9]+ <marker: chunk instruction count [0-9]+>