DynamoRIO · abhinav92003 · Jan 24, 2025 · Dec 9, 2024 · Dec 9, 2024 · Dec 10, 2024
diff --git a/api/docs/release.dox b/api/docs/release.dox
@@ -136,6 +136,11 @@ changes:
 Further non-compatibility-affecting changes include:
  - Added support for reading a single drmemtrace trace file from stdin
    via "-infile -".
+ - Added the #dynamorio::drmemtrace::decode_cache_t library to make it easier and more
+   efficient for drmemtrace analysis tools to obtain decoded information about
+   instructions in the trace. This works for traces that have embedded instruction
+   encodings in them, and also for legacy traces without embedded encodings where the
+   encodings are obtained from the application binaries instead.
 
 **************************************************
 <hr>

diff --git a/clients/drcachesim/CMakeLists.txt b/clients/drcachesim/CMakeLists.txt
@@ -163,19 +163,27 @@ add_exported_library(drmemtrace_reuse_distance STATIC tools/reuse_distance.cpp)
 add_exported_library(drmemtrace_histogram STATIC tools/histogram.cpp)
 add_exported_library(drmemtrace_reuse_time STATIC tools/reuse_time.cpp)
 add_exported_library(drmemtrace_basic_counts STATIC tools/basic_counts.cpp)
-add_exported_library(drmemtrace_opcode_mix STATIC
-                     tools/opcode_mix.cpp tracer/raw2trace_shared.cpp)
+add_exported_library(drmemtrace_opcode_mix STATIC tools/opcode_mix.cpp)
 add_exported_library(drmemtrace_syscall_mix STATIC tools/syscall_mix.cpp)
 add_exported_library(drmemtrace_view STATIC
                      tools/view.cpp tracer/raw2trace_shared.cpp)
 add_exported_library(drmemtrace_func_view STATIC tools/func_view.cpp)
 add_exported_library(drmemtrace_invariant_checker STATIC tools/invariant_checker.cpp)
 add_exported_library(drmemtrace_schedule_stats STATIC tools/schedule_stats.cpp)
+add_exported_library(drmemtrace_decode_cache STATIC
+                     tools/common/decode_cache.cpp
+                     # XXX: Possibly create a library for raw2trace_shared, to avoid
+                     # multiple build overhead.
+                     tracer/raw2trace_shared.cpp)
 add_exported_library(drmemtrace_schedule_file STATIC common/schedule_file.cpp)
 add_exported_library(drmemtrace_mutex_dbg_owned STATIC common/mutex_dbg_owned.cpp)
 
-target_link_libraries(drmemtrace_invariant_checker drdecode drmemtrace_schedule_file)
+target_link_libraries(drmemtrace_invariant_checker drdecode drmemtrace_schedule_file
+                      drmemtrace_decode_cache)
+target_link_libraries(drmemtrace_decode_cache drcovlib_static)
+target_link_libraries(drmemtrace_opcode_mix drmemtrace_decode_cache)
 
+configure_DynamoRIO_standalone(drmemtrace_decode_cache)
 configure_DynamoRIO_standalone(drmemtrace_opcode_mix)
 configure_DynamoRIO_standalone(drmemtrace_view)
 configure_DynamoRIO_standalone(drmemtrace_invariant_checker)
@@ -322,6 +330,7 @@ include_directories(${CMAKE_CURRENT_SOURCE_DIR}/reader)
 # so that we can more cleanly separate tracer and raw2trace code.
 include_directories(${CMAKE_CURRENT_SOURCE_DIR}/tracer)
 include_directories(${CMAKE_CURRENT_SOURCE_DIR}/scheduler)
+include_directories(${CMAKE_CURRENT_SOURCE_DIR}/tools/common)
 include_directories(${CMAKE_CURRENT_SOURCE_DIR})
 
 if (BUILD_PT_POST_PROCESSOR)
@@ -369,6 +378,7 @@ install_client_nonDR_header(drmemtrace reader/reader.h)
 install_client_nonDR_header(drmemtrace reader/record_file_reader.h)
 install_client_nonDR_header(drmemtrace analysis_tool.h)
 install_client_nonDR_header(drmemtrace analyzer.h)
+install_client_nonDR_header(drmemtrace tools/common/decode_cache.h)
 install_client_nonDR_header(drmemtrace tools/reuse_distance_create.h)
 install_client_nonDR_header(drmemtrace tools/histogram_create.h)
 install_client_nonDR_header(drmemtrace tools/reuse_time_create.h)
@@ -633,6 +643,7 @@ restore_nonclient_flags(drmemtrace_analyzer)
 restore_nonclient_flags(drmemtrace_invariant_checker)
 restore_nonclient_flags(drmemtrace_schedule_stats)
 restore_nonclient_flags(drmemtrace_schedule_file)
+restore_nonclient_flags(drmemtrace_decode_cache)
 
 # We need to pass /EHsc and we pull in libcmtd into drcachesim from a dep lib.
 # Thus we need to override the /MT with /MTd.
@@ -706,6 +717,7 @@ add_win32_flags(drmemtrace_analyzer)
 add_win32_flags(drmemtrace_invariant_checker)
 add_win32_flags(drmemtrace_schedule_stats)
 add_win32_flags(drmemtrace_schedule_file)
+add_win32_flags(drmemtrace_decode_cache)
 add_win32_flags(directory_iterator)
 add_win32_flags(test_helpers)
 add_win32_flags(drmemtrace_mutex_dbg_owned)
@@ -964,6 +976,26 @@ if (BUILD_TESTS)
     add_win32_flags(tool.drcacheoff.burst_aarch64_sys)
   endif ()
 
+  add_executable(tool.drcachesim.decode_cache_test tests/decode_cache_test.cpp)
+  configure_DynamoRIO_standalone(tool.drcachesim.decode_cache_test)
+  add_win32_flags(tool.drcachesim.decode_cache_test)
+  target_link_libraries(tool.drcachesim.decode_cache_test
+    drmemtrace_decode_cache test_helpers)
+  add_test(NAME tool.drcachesim.decode_cache_test
+           COMMAND tool.drcachesim.decode_cache_test)
+  set_tests_properties(tool.drcachesim.decode_cache_test PROPERTIES
+    TIMEOUT ${test_seconds})
+
+  add_executable(tool.drcacheoff.opcode_mix_test tests/opcode_mix_test.cpp)
+  configure_DynamoRIO_standalone(tool.drcacheoff.opcode_mix_test)
+  add_win32_flags(tool.drcacheoff.opcode_mix_test)
+  target_link_libraries(tool.drcacheoff.opcode_mix_test
+    drmemtrace_opcode_mix drmemtrace_decode_cache test_helpers)
+  add_test(NAME tool.drcacheoff.opcode_mix_test
+           COMMAND tool.drcacheoff.opcode_mix_test)
+  set_tests_properties(tool.drcacheoff.opcode_mix_test PROPERTIES
+    TIMEOUT ${test_seconds})
+
   # XXX i#1997: dynamorio_static is not supported on Mac yet
   # FIXME i#2949: gcc 7.3 fails to link certain configs
   # TODO i#3544: Port tests to RISC-V 64

diff --git a/clients/drcachesim/docs/drcachesim.dox.in b/clients/drcachesim/docs/drcachesim.dox.in
@@ -1,5 +1,5 @@
 /* **********************************************************
- * Copyright (c) 2015-2024 Google, Inc.  All rights reserved.
+ * Copyright (c) 2015-2025 Google, Inc.  All rights reserved.
  * **********************************************************/
 
 /*
@@ -142,6 +142,13 @@ copies of the binaries and reading the raw bytes for each instruction
 in order to obtain the opcode and full operand information.
 See also \ref sec_drcachesim_core.
 
+drmemtrace analysis tools may use the
+#dynamorio::drmemtrace::decode_cache_t library, which handles the
+heavy lifting of decoding the trace instructions using either the embedded
+encodings in the trace or the encodings from the app binaries, and manages
+caching their decode info (including invalidating stale decode info based on
+the `encoding_is_new` field for embedded encodings).
+
 Whether conditional branches are taken or untaken is indicated by the
 instruction types #dynamorio::drmemtrace::TRACE_TYPE_INSTR_TAKEN_JUMP
 and #dynamorio::drmemtrace::TRACE_TYPE_INSTR_UNTAKEN_JUMP.  The target