From 1afe5eb00f27e7747042d7f5ca4acbd18784c5fe Mon Sep 17 00:00:00 2001 From: Derek Bruening Date: Wed, 16 Oct 2024 19:32:16 -0400 Subject: [PATCH] i#7028 mod markers: Document scheduler-modified markers (#7041) Updates the documentation to explain that dynamic scheduling modifies timestamp and cpu id markers. Issue: #7028 --- clients/drcachesim/docs/drcachesim.dox.in | 20 +++++++++++++------- 1 file changed, 13 insertions(+), 7 deletions(-) diff --git a/clients/drcachesim/docs/drcachesim.dox.in b/clients/drcachesim/docs/drcachesim.dox.in index 406e3293530..5cc2818c7bd 100644 --- a/clients/drcachesim/docs/drcachesim.dox.in +++ b/clients/drcachesim/docs/drcachesim.dox.in @@ -179,9 +179,9 @@ Some of the more important markers are: - #dynamorio::drmemtrace::TRACE_MARKER_TYPE_KERNEL_XFER - This identifies a system call that changes control flow, such as a signal return. -- #dynamorio::drmemtrace::TRACE_MARKER_TYPE_TIMESTAMP - The marker value provides a timestamp for this point of the trace (in units of microseconds since Jan 1, 1601 UTC). This value can be used to synchronize records from different threads as well as analyze latencies (however, tracing overhead inflates time unevenly, so time deltas should not be considered perfectly representative). It is used in the sequential analysis of a multi-threaded trace. +- #dynamorio::drmemtrace::TRACE_MARKER_TYPE_TIMESTAMP - The marker value provides a timestamp for this point of the trace (in units of microseconds since Jan 1, 1601 UTC). This value can be used to synchronize records from different threads as well as analyze latencies (however, tracing overhead inflates time unevenly, so time deltas should not be considered perfectly representative). It is used in the sequential analysis of a multi-threaded trace. When dynamic scheduling is performed (see \ref sec_drcachesim_sched_dynamic), the original timestamp value is replaced with a synthetic value in order to maintain relative ordering (though the new values should not be relied upon to indicate accurate durations between events). -- #dynamorio::drmemtrace::TRACE_MARKER_TYPE_CPU_ID - The marker value contains the CPU identifier on which the subsequent records were collected. It can be used to identify the "as traced" schedule, indicating which threads were on which cores at which times. However, this schedule is not representative and should not be treated as indicating how the application behaves without tracing. See \ref sec_drcachesim_as_traced for further information. +- #dynamorio::drmemtrace::TRACE_MARKER_TYPE_CPU_ID - The marker value contains the CPU identifier on which the subsequent records were collected. It can be used to identify the "as traced" schedule, indicating which threads were on which cores at which times. However, this schedule is not representative and should not be treated as indicating how the application behaves without tracing. See \ref sec_drcachesim_as_traced for further information. When dynamic scheduling is performed (see \ref sec_drcachesim_sched_dynamic), the original value of this marker is replaced with the new virtual core identifier. - #dynamorio::drmemtrace::TRACE_MARKER_TYPE_FUNC_ID, #dynamorio::drmemtrace::TRACE_MARKER_TYPE_FUNC_RETADDR, #dynamorio::drmemtrace::TRACE_MARKER_TYPE_FUNC_ARG, #dynamorio::drmemtrace::TRACE_MARKER_TYPE_FUNC_RETVAL - These markers are used to capture information about function calls. Which functions to capture must be explicitly selected at tracing time. Typical candiates are heap allocation and freeing functions. See \ref sec_drcachesim_funcs. @@ -1469,8 +1469,10 @@ While we suggest keeping traces stored as thread-sharded and using the dynamic s in each run, there is support for running the scheduler once and creating a new set of stored traces in core-sharded format: essentially switching to hardware-thread-oriented traces. This is done using the \ref sec_tool_record_filter tool in `-core_sharded` mode. -The #dynamorio::drmemtrace::TRACE_MARKER_TYPE_CPU_ID markers are not modified by the -dynamic scheduler, and should be ignored in a newly created core-sharded trace. +The #dynamorio::drmemtrace::TRACE_MARKER_TYPE_TIMESTAMP and +#dynamorio::drmemtrace::TRACE_MARKER_TYPE_CPU_ID markers are modified by the dynamic +scheduler to reflect the new schedule. The new timestamps maintain relative ordering +but should not be relied upon to indicate accurate durations between events. Traces also include markers indicating disruptions in user mode control flow such as signal handler entry and exit. @@ -1535,7 +1537,9 @@ through the -cpu_schedule_file option. \section sec_drcachesim_sched_dynamic Dynamic Scheduling Instead of using the as-traced schedule, we recommend re-scheduling the traced software -threads using our trace scheduler. Our scheduler essentially serves as an operating +threads using our trace scheduler in +#dynamorio::drmemtrace::scheduler_t::MAP_TO_ANY_OUTPUT mode. +Our scheduler essentially serves as an operating system scheduler for this purpose, though using simpler schemes. It models separate runqueues per core with support for binding inputs to certain cores, priorities, idle time from blocking system calls, migration thresholds, rebalancing runqueues, etc. It @@ -1564,8 +1568,10 @@ The downsides include: thus, timestamp ordering will be followed at context switch points for picking the next input, but timestamps will not preempt an input. -The #dynamorio::drmemtrace::TRACE_MARKER_TYPE_CPU_ID markers are not modified by the -dynamic scheduler, and should be ignored in a dynamic rescheduling. +The #dynamorio::drmemtrace::TRACE_MARKER_TYPE_TIMESTAMP and +#dynamorio::drmemtrace::TRACE_MARKER_TYPE_CPU_ID markers are modified by the dynamic +scheduler to reflect the new schedule. The new timestamps maintain relative ordering +but should not be relied upon to indicate accurate durations between events. ******************** \section sec_drcachesim_sched_time Simulated Time