i#6660 dr$sim aliases: Add -tool to replace -simulator_type (DynamoRI…

…O#6797)

Adds -tool as the preferred alias for the -simulator_type option for the
drmemtrace/drcachesim framework. This is long overdue as many analysis
tools are not "simulators" and the original option was solely to pick
between cache and TLB simulators.

Updates all uses in tests and documentation.

Adds a release note.

Changes the preferred cache and TLB simulator tool names to have
_simulator suffixes. Adds a "drcachesim" alias for the cache simulator
as well.

Manually tested the "cache" and "drcachesim" aliases.

Issue: DynamoRIO#6660

api/docs/release.dox

@@ -234,6 +234,8 @@ Further non-compatibility-affecting changes include:
    generate #DR_ISA_REGDEPS traces.
  - Added #dynamorio::drmemtrace::OFFLINE_FILE_TYPE_ARCH_REGDEPS file type for
    #DR_ISA_REGDEPS traces.
+ - Added -tool as the preferred alias for -simulator_type for the drmemtrace/drcachesim
+   trace analysis tool framework.
 
 **************************************************
 <hr>

clients/drcachesim/analyzer_multi.cpp

@@ -181,22 +181,22 @@ analyzer_multi_t::create_invariant_checker()
 
 template <>
 analysis_tool_t *
-analyzer_multi_t::create_analysis_tool_from_options(const std::string &simulator_type)
+analyzer_multi_t::create_analysis_tool_from_options(const std::string &tool)
 {
-    if (simulator_type == CPU_CACHE) {
+    if (tool == CPU_CACHE || tool == CPU_CACHE_ALT || tool == CPU_CACHE_LEGACY) {
         const std::string &config_file = op_config_file.get_value();
         if (!config_file.empty()) {
             return cache_simulator_create(config_file);
         } else {
             cache_simulator_knobs_t *knobs = get_cache_simulator_knobs();
             return cache_simulator_create(*knobs);
         }
-    } else if (simulator_type == MISS_ANALYZER) {
+    } else if (tool == MISS_ANALYZER) {
         cache_simulator_knobs_t *knobs = get_cache_simulator_knobs();
         return cache_miss_analyzer_create(*knobs, op_miss_count_threshold.get_value(),
                                           op_miss_frac_threshold.get_value(),
                                           op_confidence_threshold.get_value());
-    } else if (simulator_type == TLB) {
+    } else if (tool == TLB || tool == TLB_LEGACY) {
         tlb_simulator_knobs_t knobs;
         knobs.num_cores = op_num_cores.get_value();
         knobs.page_size = op_page_size.get_value();
@@ -215,10 +215,10 @@ analyzer_multi_t::create_analysis_tool_from_options(const std::string &simulator
         knobs.cpu_scheduling = op_cpu_scheduling.get_value();
         knobs.use_physical = op_use_physical.get_value();
         return tlb_simulator_create(knobs);
-    } else if (simulator_type == HISTOGRAM) {
+    } else if (tool == HISTOGRAM) {
         return histogram_tool_create(op_line_size.get_value(), op_report_top.get_value(),
                                      op_verbose.get_value());
-    } else if (simulator_type == REUSE_DIST) {
+    } else if (tool == REUSE_DIST) {
         reuse_distance_knobs_t knobs;
         knobs.line_size = op_line_size.get_value();
         knobs.report_histogram = op_reuse_distance_histogram.get_value();
@@ -234,11 +234,11 @@ analyzer_multi_t::create_analysis_tool_from_options(const std::string &simulator
         }
         knobs.verbose = op_verbose.get_value();
         return reuse_distance_tool_create(knobs);
-    } else if (simulator_type == REUSE_TIME) {
+    } else if (tool == REUSE_TIME) {
         return reuse_time_tool_create(op_line_size.get_value(), op_verbose.get_value());
-    } else if (simulator_type == BASIC_COUNTS) {
+    } else if (tool == BASIC_COUNTS) {
         return basic_counts_tool_create(op_verbose.get_value());
-    } else if (simulator_type == OPCODE_MIX) {
+    } else if (tool == OPCODE_MIX) {
         std::string module_file_path = get_module_file_path();
         if (module_file_path.empty() && op_indir.get_value().empty() &&
             op_infile.get_value().empty() && !op_instr_encodings.get_value()) {
@@ -248,15 +248,15 @@ analyzer_multi_t::create_analysis_tool_from_options(const std::string &simulator
         }
         return opcode_mix_tool_create(module_file_path, op_verbose.get_value(),
                                       op_alt_module_dir.get_value());
-    } else if (simulator_type == SYSCALL_MIX) {
+    } else if (tool == SYSCALL_MIX) {
         return syscall_mix_tool_create(op_verbose.get_value());
-    } else if (simulator_type == VIEW) {
+    } else if (tool == VIEW) {
         std::string module_file_path = get_module_file_path();
         // The module file is optional so we don't check for emptiness.
         return view_tool_create(module_file_path, op_skip_refs.get_value(),
                                 op_sim_refs.get_value(), op_view_syntax.get_value(),
                                 op_verbose.get_value(), op_alt_module_dir.get_value());
-    } else if (simulator_type == FUNC_VIEW) {
+    } else if (tool == FUNC_VIEW) {
         std::string funclist_file_path = get_aux_file_path(
             op_funclist_file.get_value(), DRMEMTRACE_FUNCTION_LIST_FILENAME);
         if (funclist_file_path.empty()) {
@@ -265,21 +265,21 @@ analyzer_multi_t::create_analysis_tool_from_options(const std::string &simulator
         }
         return func_view_tool_create(funclist_file_path, op_show_func_trace.get_value(),
                                      op_verbose.get_value());
-    } else if (simulator_type == INVARIANT_CHECKER) {
+    } else if (tool == INVARIANT_CHECKER) {
         return create_invariant_checker();
-    } else if (simulator_type == SCHEDULE_STATS) {
+    } else if (tool == SCHEDULE_STATS) {
         return schedule_stats_tool_create(op_schedule_stats_print_every.get_value(),
                                           op_verbose.get_value());
     } else {
-        auto tool = create_external_tool(simulator_type);
-        if (tool == nullptr) {
+        auto ext_tool = create_external_tool(tool);
+        if (ext_tool == nullptr) {
             ERRMSG("Usage error: unsupported analyzer type \"%s\". "
                    "Please choose " CPU_CACHE ", " MISS_ANALYZER ", " TLB ", " HISTOGRAM
                    ", " REUSE_DIST ", " BASIC_COUNTS ", " OPCODE_MIX ", " SYSCALL_MIX
                    ", " VIEW ", " FUNC_VIEW ", or some external analyzer.\n",
-                   simulator_type.c_str());
+                   tool.c_str());
         }
-        return tool;
+        return ext_tool;
     }
 }
 
@@ -326,10 +326,9 @@ record_analyzer_multi_t::create_invariant_checker()
 
 template <>
 record_analysis_tool_t *
-record_analyzer_multi_t::create_analysis_tool_from_options(
-    const std::string &simulator_type)
+record_analyzer_multi_t::create_analysis_tool_from_options(const std::string &tool)
 {
-    if (simulator_type == RECORD_FILTER) {
+    if (tool == RECORD_FILTER) {
         return record_filter_tool_create(
             op_outdir.get_value(), op_filter_stop_timestamp.get_value(),
             op_filter_cache_size.get_value(), op_filter_trace_types.get_value(),
@@ -339,7 +338,7 @@ record_analyzer_multi_t::create_analysis_tool_from_options(
     }
     ERRMSG("Usage error: unsupported record analyzer type \"%s\".  Only " RECORD_FILTER
            " is supported.\n",
-           simulator_type.c_str());
+           tool.c_str());
     return nullptr;
 }
 
@@ -536,8 +535,8 @@ bool
 analyzer_multi_tmpl_t<RecordType, ReaderType>::create_analysis_tools()
 {
     this->tools_ = new analysis_tool_tmpl_t<RecordType> *[this->max_num_tools_];
-    if (!op_simulator_type.get_value().empty()) {
-        std::stringstream stream(op_simulator_type.get_value());
+    if (!op_tool.get_value().empty()) {
+        std::stringstream stream(op_tool.get_value());
         std::string type;
         while (std::getline(stream, type, ':')) {
             if (this->num_tools_ >= this->max_num_tools_ - 1) {

clients/drcachesim/common/options.cpp

@@ -458,18 +458,18 @@ droption_t<std::string>
                           "Specifies the replacement policy for TLBs. "
                           "Supported policies: LFU (Least Frequently Used).");
 
-// TODO i#6660: Add "-tool" alias as these are not all "simulators".
 droption_t<std::string>
-    op_simulator_type(DROPTION_SCOPE_FRONTEND, "simulator_type", CPU_CACHE,
-                      "Specifies which trace analysis tool(s) to run.  Multiple tools "
-                      "can be specified, separated by a colon (\":\").",
-                      "Predefined types: " CPU_CACHE ", " MISS_ANALYZER ", " TLB
-                      ", " REUSE_DIST ", " REUSE_TIME ", " HISTOGRAM ", " BASIC_COUNTS
-                      ", " INVARIANT_CHECKER ", " SCHEDULE_STATS ", or " RECORD_FILTER
-                      ". The " RECORD_FILTER " tool cannot be combined with the others "
-                      "as it operates on raw disk records. "
-                      "To invoke an external tool: specify its name as identified by a "
-                      "name.drcachesim config file in the DR tools directory.");
+    op_tool(DROPTION_SCOPE_FRONTEND,
+            std::vector<std::string>({ "tool", "simulator_type" }), CPU_CACHE,
+            "Specifies which trace analysis tool(s) to run.  Multiple tools "
+            "can be specified, separated by a colon (\":\").",
+            "Predefined types: " CPU_CACHE ", " MISS_ANALYZER ", " TLB ", " REUSE_DIST
+            ", " REUSE_TIME ", " HISTOGRAM ", " BASIC_COUNTS ", " INVARIANT_CHECKER
+            ", " SCHEDULE_STATS ", or " RECORD_FILTER ". The " RECORD_FILTER
+            " tool cannot be combined with the others "
+            "as it operates on raw disk records. "
+            "To invoke an external tool: specify its name as identified by a "
+            "name.drcachesim config file in the DR tools directory.");
 
 droption_t<unsigned int> op_verbose(DROPTION_SCOPE_ALL, "verbose", 0, 0, 64,
                                     "Verbosity level",

clients/drcachesim/common/options.h

@@ -35,12 +35,13 @@
 #ifndef _OPTIONS_H_
 #define _OPTIONS_H_ 1
 
-// Tool names (for -simulator_type option).
-// TODO i#6660: When we add "-tool", add "cache_simulator" or "drcachesim"
-// instead of just "-tool cache".  Ditto for "TLB".
-#define CPU_CACHE "cache"
+// Tool names (for -tool option).
+#define CPU_CACHE_LEGACY "cache"
+#define CPU_CACHE "cache_simulator"
+#define CPU_CACHE_ALT "drcachesim"
 #define MISS_ANALYZER "miss_analyzer"
-#define TLB "TLB"
+#define TLB_LEGACY "TLB"
+#define TLB "TLB_simulator"
 #define HISTOGRAM "histogram"
 #define REUSE_DIST "reuse_distance"
 #define REUSE_TIME "reuse_time"
@@ -146,7 +147,7 @@ extern dynamorio::droption::droption_t<unsigned int> op_TLB_L1D_assoc;
 extern dynamorio::droption::droption_t<unsigned int> op_TLB_L2_entries;
 extern dynamorio::droption::droption_t<unsigned int> op_TLB_L2_assoc;
 extern dynamorio::droption::droption_t<std::string> op_TLB_replace_policy;
-extern dynamorio::droption::droption_t<std::string> op_simulator_type;
+extern dynamorio::droption::droption_t<std::string> op_tool;
 extern dynamorio::droption::droption_t<unsigned int> op_verbose;
 extern dynamorio::droption::droption_t<bool> op_show_func_trace;
 extern dynamorio::droption::droption_t<int> op_jobs;

clients/drcachesim/docs/drcachesim.dox.in

@@ -262,7 +262,7 @@ LL stats:
 
 In addition to a CPU cache simulator, other predefined analysis tools are
 available that operate on memory address traces.  Which set of tools is used
-can be selected with the \p -simulator_type parameter.  New, custom
+can be selected with the \p -tool parameter.  New, custom
 tools can also be created, as described in \ref sec_drcachesim_newtool.
 
 - \ref sec_tool_cache_sim
@@ -332,10 +332,10 @@ LL stats:
 
 \section sec_tool_TLB_sim TLB Simulator
 
-To simulate TLB devices instead of caches, pass \p TLB to \p -simulator_type:
+To simulate TLB devices instead of caches, pass \p TLB to \p -tool:
 
 \code
-$ bin64/drrun -t drcachesim -simulator_type TLB -- ~/test/pi_estimator
+$ bin64/drrun -t drcachesim -tool TLB -- ~/test/pi_estimator
 Estimation of pi is 3.142425985001098
 ---- <application exited with code 0> ----
 TLB simulation results:
@@ -392,7 +392,7 @@ Core #3 (0 thread(s))
 To compute reuse distance metrics:
 
 \code
-$ bin64/drrun -t drcachesim -simulator_type reuse_distance -reuse_distance_histogram -- ~/test/pi_estimator
+$ bin64/drrun -t drcachesim -tool reuse_distance -reuse_distance_histogram -- ~/test/pi_estimator
 Estimation of pi is 3.142425985001098
 ---- <application exited with code 0> ----
 Reuse distance tool aggregated results:
@@ -486,7 +486,7 @@ accesses (without considering uniqueness) between accesses to the same
 address:
 
 \code
-$ bin64/drrun -t drcachesim -simulator_type reuse_time -- ~/test/pi_estimator
+$ bin64/drrun -t drcachesim -tool reuse_time -- ~/test/pi_estimator
 Estimation of pi is 3.142425985001098
 ---- <application exited with code 0> ----
 Reuse time tool aggregated results:
@@ -528,7 +528,7 @@ To simply see the counts of instructions and memory references broken down
 by thread use the basic counts tool:
 
 \code
-$ bin64/drrun -t drcachesim -simulator_type basic_counts -- ~/test/pi_estimator
+$ bin64/drrun -t drcachesim -tool basic_counts -- ~/test/pi_estimator
 Estimation of pi is 3.142425985001098
 ---- <application exited with code 0> ----
 Basic counts tool results:
@@ -645,7 +645,7 @@ opcode for load and store but both have the same public string "mov":
 \code
 $ bin64/drrun -t drcachesim -offline -- ~/test/pi_estimator
 Estimation of pi is 3.142425985001098
-$ bin64/drrun -t drcachesim -simulator_type opcode_mix -indir drmemtrace.*.dir
+$ bin64/drrun -t drcachesim -tool opcode_mix -indir drmemtrace.*.dir
 Opcode mix tool results:
          267271 : total executed instructions
           36432 :       mov
@@ -695,7 +695,7 @@ In its first two columns, the tool displays the trace record ordinal
 and the instruction fetch ordinal.
 
 \code
-$ $ bin64/drrun -t drcachesim -simulator_type view -indir drmemtrace.*.dir -sim_refs 20
+$ $ bin64/drrun -t drcachesim -tool view -indir drmemtrace.*.dir -sim_refs 20
 Output format:
 <--record#-> <--instr#->: <---tid---> <record details>
 ------------------------------------------------------------
@@ -795,7 +795,7 @@ more information.
 \code
 $ bin64/drrun -t drcachesim -offline -record_function 'fib|1' -- ~/test/fib 5
 Estimation of pi is 3.142425985001098
-$ bin64/drrun -t drcachesim -simulator_type func_view -indir drmemtrace.*.dir
+$ bin64/drrun -t drcachesim -tool func_view -indir drmemtrace.*.dir
 0x7fc06d2288eb => common.fib!fib(0x5)
     0x7fc06d22888e => common.fib!fib(0x4)
         0x7fc06d22888e => common.fib!fib(0x3)
@@ -829,7 +829,7 @@ Function id=0: common.fib!fib
 The top referenced cache lines are displayed by the \p histogram tool:
 
 \code
-$ bin64/drrun -t drcachesim -simulator_type histogram -- ~/test/pi_estimator
+$ bin64/drrun -t drcachesim -tool histogram -- ~/test/pi_estimator
 Estimation of pi is 3.142425985001098
 ---- <application exited with code 0> ----
 Cache line histogram tool results:
@@ -877,7 +877,7 @@ number. This works only with traces that have these markers; that is, offline tr
 must have #dynamorio::drmemtrace::OFFLINE_FILE_TYPE_SYSCALL_NUMBERS in their file type.
 
 \code
-$ bin64/drrun -t drcachesim -indir drmemtrace.ls.*.dir -simulator_type syscall_mix
+$ bin64/drrun -t drcachesim -indir drmemtrace.ls.*.dir -tool syscall_mix
 Syscall mix tool results:
           count : syscall_num
              17 :         9
@@ -929,18 +929,18 @@ option.
 Example of removing function markers:
 
 \code
-$ bin64/drrun -t drcachesim -indir mytracedir -simulator_type basic_counts
+$ bin64/drrun -t drcachesim -indir mytracedir -tool basic_counts
 ...
         9009 total function id markers
         5006 total function return address markers
         6007 total function argument markers
         4003 total function return value markers
 ...
 
-$ bin64/drrun -t drcachesim -simulator_type record_filter -filter_marker_types 4,5,6,7 -indir mytracedir -outdir newdir
+$ bin64/drrun -t drcachesim -tool record_filter -filter_marker_types 4,5,6,7 -indir mytracedir -outdir newdir
 Output 1280800 entries from 1304825 entries.
 
-$ bin64/drrun -t drcachesim -indir newdir -simulator_type basic_counts
+$ bin64/drrun -t drcachesim -indir newdir -tool basic_counts
 ...
            0 total function id markers
            0 total function return address markers
@@ -1266,7 +1266,7 @@ burst_static test application</a>.
 Generally, the simulator is able to be extended to model a variety of
 caching devices.  Currently, CPU caches and TLBs are implemented.  The type of
 devices to simulate can be specified by the parameter
-"-simulator_type" (see \ref sec_drcachesim_ops).
+"-tool" (see \ref sec_drcachesim_ops).
 
 The CPU cache simulator models a configurable number of cores,
 each with an L1 data cache and an L1 instruction cache.
@@ -1393,15 +1393,15 @@ The cache simulator can be used to analyze the stream of last-level cache (LLC)
 miss addresses. This can be useful when looking for patterns that can be utilized
 in software prefetching. The current analyzer can only identify simple stride
 patterns, but it can be extended to search for more complex patterns.
-To invoke the miss analyzer, pass \p miss_analyzer to the \p -simulator_type
+To invoke the miss analyzer, pass \p miss_analyzer to the \p -tool
 parameter. To write the prefetching hints to a file use the \p -LL_miss_file
 parameter to specify the file's path and name.
 
 For example, to run the analyzer on a benchmark called "my_benchmark" and store
 the prefetching recommendations in a file called "rec.csv", run the following:
 
 \code
-$ bin64/drrun -t drcachesim -simulator_type miss_analyzer -LL_miss_file rec.csv -- my_benchmark
+$ bin64/drrun -t drcachesim -tool miss_analyzer -LL_miss_file rec.csv -- my_benchmark
 \endcode
 
 
@@ -1669,7 +1669,7 @@ functions.
 
 \p drcachesim \p drmemtrace analysis tool framework allows to load
 non-predefined separately-built external tools. This tool can be loaded by drcachesim
-using the \p -simulator_type option.
+using the \p -tool option.
 
 ## External tool package
 

clients/drcachesim/launcher.cpp

@@ -323,7 +323,7 @@ _tmain(int argc, const TCHAR *targv[])
             FATAL_ERROR("invalid -outdir %s", op_outdir.get_value().c_str());
         }
     } else {
-        if (op_simulator_type.get_value() == RECORD_FILTER) {
+        if (op_tool.get_value() == RECORD_FILTER) {
             record_analyzer = new record_analyzer_multi_t;
             if (!*record_analyzer) {
                 std::string error_string_ = record_analyzer->get_error_string();