i#4138 samples: clarify why instrace does not expand REP string instructions (#7789)

Document the rationale for not expanding REP-prefixed string instructions
in the instrace sample clients.

instrace is a simple instruction tracer focused on instruction fetches,
not per-iteration memory accesses. Expanding REP would emit multiple
consecutive instances of the same instruction, which is often confusing
in instrace output and differs from tools like perf that count only a
single instance.

Emulation-aware expansion of REP and scatter/gather instructions
requires consuming emulation metadata via drmgr_orig_app_instr_for_fetch() and
drmgr_orig_app_instr_for_operands(), as done in memtrace.
That complexity is intentionally avoided in instrace and left to emulation-aware
samples.

Fixes #4138.

Author: GandholiSarat

api/samples/instrace_simple.c

@@ -209,6 +209,20 @@ event_app_instruction(void *drcontext, void *tag, instrlist_t *bb, instr_t *inst
     if (!instr_is_app(instr))
         return DR_EMIT_DEFAULT;
 
+    /* We intentionally do not expand REP-prefixed string instructions here.
+     * instrace is a simple instruction tracer: it is concerned only with
+     * instruction fetches, not with per-iteration memory accesses.
+     *
+     * Expanding REP would emit multiple consecutive instances of the same
+     * instruction (one per iteration), which is often confusing in instrace
+     * output and differs from tools like perf that also count only a single
+     * instance.
+     *
+     * Users who want to observe per-iteration behavior of REP instructions
+     * should use emulation-aware samples such as memtrace, which consume the
+     * emulation metadata via drmgr_orig_app_instr_for_fetch() /
+     * drmgr_orig_app_instr_for_operands().
+     */
     /* insert code to add an entry to the buffer */
     instrument_instr(drcontext, bb, instr);
 

api/samples/instrace_x86.c

@@ -249,6 +249,21 @@ event_bb_insert(void *drcontext, void *tag, instrlist_t *bb, instr_t *instr,
 {
     if (instr_get_app_pc(instr) == NULL || !instr_is_app(instr))
         return DR_EMIT_DEFAULT;
+
+    /* We intentionally do not expand REP-prefixed string instructions here.
+     * instrace is a simple instruction tracer: it is concerned only with
+     * instruction fetches, not with per-iteration memory accesses.
+     *
+     * Expanding REP would emit multiple consecutive instances of the same
+     * instruction (one per iteration), which is often confusing in instrace
+     * output and differs from tools like perf that also count only a single
+     * instance.
+     *
+     * Users who want to observe per-iteration behavior of REP instructions
+     * should use emulation-aware samples such as memtrace, which consume the
+     * emulation metadata via drmgr_orig_app_instr_for_fetch() /
+     * drmgr_orig_app_instr_for_operands().
+     */
     instrument_instr(drcontext, bb, instr);
     return DR_EMIT_DEFAULT;
 }