|
DynamoRIO
|
#include <scheduler.h>
Public Member Functions | |
| scheduler_options_t () | |
| scheduler_options_t (mapping_t mapping, inter_input_dependency_t deps, scheduler_flags_t flags=SCHEDULER_DEFAULTS, int verbosity=0) | |
Detailed Description
template<typename RecordType, typename ReaderType>
struct dynamorio::drmemtrace::scheduler_tmpl_t< RecordType, ReaderType >::scheduler_options_t
Collects the parameters specifying how the scheduler should behave, outside of the workload inputs and the output count.
Constructor & Destructor Documentation
◆ scheduler_options_t() [1/2]
|
inline |
Constructs a default set of options.
◆ scheduler_options_t() [2/2]
|
inline |
Constructs a set of options with the given type and strategy.
Field Documentation
◆ block_time_max
| uint64_t dynamorio::drmemtrace::scheduler_tmpl_t< RecordType, ReaderType >::scheduler_options_t::block_time_max = 0 |
Deprecated: use block_time_max_us and time_units_per_us instead. It is an error to set this to a non-zero value when struct_size includes block_time_max_us. When struct_size does not include block_time_max_us and this value is non-zero, the value in block_time_max_us is replaced with this value divided by the default value of time_units_per_us.
◆ block_time_max_us
| uint64_t dynamorio::drmemtrace::scheduler_tmpl_t< RecordType, ReaderType >::scheduler_options_t::block_time_max_us = 2500 |
The maximum time in microseconds for an input to be considered blocked for any one system call. This value is multiplied by time_units_per_us to produce a value that is compared to the "cur_time" parameter to next_record(). If any block time (see block_time_multiplier) exceeds this value, it is capped to this value. This value is also used as a fallback to avoid hangs when there are no scheduled inputs: if the only inputs left are "unscheduled" (see TRACE_MARKER_TYPE_SYSCALL_UNSCHEDULE), after this amount of time those inputs are all re-scheduled.
◆ block_time_multiplier
| double dynamorio::drmemtrace::scheduler_tmpl_t< RecordType, ReaderType >::scheduler_options_t::block_time_multiplier = 0.1 |
Controls the amount of time inputs are considered blocked at a syscall whose as-traced latency (recorded in timestamp records in the trace) exceeds syscall_switch_threshold or blocking_switch_threshold. The as-traced syscall latency (which is in traced microseconds) is multiplied by this field to produce the blocked time in simulated microseconds. Once that many simulated microseconds have passed according to the "cur_time" value passed to next_record() (multiplied by time_units_per_us), the input will be no longer considered blocked. The blocked time is clamped to a maximum value controlled by block_time_max.
While there is no direct overhead during tracing, indirect overhead does result in some inflation of recorded system call latencies. Thus, a value below 0 is typically used here. This value, in combination with block_time_max_us, can be tuned to achieve a desired idle rate. The default value errs on the side of less idle time.
◆ block_time_scale
| double dynamorio::drmemtrace::scheduler_tmpl_t< RecordType, ReaderType >::scheduler_options_t::block_time_scale = 0. |
Deprecated: use block_time_multiplier instead. It is an error to set this to a non-zero value when struct_size includes block_time_multiplier. When struct_size does not include block_time_multiplier and this value is non-zero, the value in block_time_multiplier is replaced with this value divided by the default value of time_units_per_us.
◆ blocking_switch_threshold
| uint64_t dynamorio::drmemtrace::scheduler_tmpl_t< RecordType, ReaderType >::scheduler_options_t::blocking_switch_threshold = 500 |
Determines the minimum latency in the unit of the trace's timestamps (microseconds) for which a maybe-blocking system call (one with a TRACE_MARKER_TYPE_MAYBE_BLOCKING_SYSCALL marker) will be treated as blocking and trigger a context switch.
◆ deps
| inter_input_dependency_t dynamorio::drmemtrace::scheduler_tmpl_t< RecordType, ReaderType >::scheduler_options_t::deps = DEPENDENCY_IGNORE |
How inter-input dependencies are handled.
◆ exit_if_fraction_inputs_left
| double dynamorio::drmemtrace::scheduler_tmpl_t< RecordType, ReaderType >::scheduler_options_t::exit_if_fraction_inputs_left = 0.1 |
For MAP_TO_ANY_OUTPUT, when an input reaches EOF, if the number of non-EOF inputs left as a fraction of the original inputs is equal to or less than this value then the scheduler exits (sets all outputs to EOF) rather than finishing off the final inputs. This helps avoid long sequences of idles during staggered endings with fewer inputs left than cores and only a small fraction of the total instructions left in those inputs. Since the remaining instruction count is not considered (as it is not available), use discretion when raising this value on uneven inputs.
◆ flags
| scheduler_flags_t dynamorio::drmemtrace::scheduler_tmpl_t< RecordType, ReaderType >::scheduler_options_t::flags = SCHEDULER_DEFAULTS |
Optional flags affecting scheduler behavior.
◆ honor_direct_switches
| bool dynamorio::drmemtrace::scheduler_tmpl_t< RecordType, ReaderType >::scheduler_options_t::honor_direct_switches = true |
If true, the scheduler will attempt to switch to the recorded targets of TRACE_MARKER_TYPE_DIRECT_THREAD_SWITCH system call metadata markers regardless of system call latency. Furthermore, the scheduler will model "unscheduled" semantics and honor the TRACE_MARKER_TYPE_SYSCALL_UNSCHEDULE and TRACE_MARKER_TYPE_SYSCALL_SCHEDULE markers. If false, these markers are ignored and only system call latency thresholds are used to determine switches (these markers remain: they are not removed from the trace).
◆ honor_infinite_timeouts
| bool dynamorio::drmemtrace::scheduler_tmpl_t< RecordType, ReaderType >::scheduler_options_t::honor_infinite_timeouts = false |
Determines whether an unscheduled-indefinitely input really is unscheduled for an infinite time, or instead is treated as blocked for the maxiumim time (block_time_max_us) scaled by block_time_multiplier.
◆ kernel_switch_reader
| std::unique_ptr<ReaderType> dynamorio::drmemtrace::scheduler_tmpl_t< RecordType, ReaderType >::scheduler_options_t::kernel_switch_reader |
An alternative to kernel_switch_trace_path is to pass a reader and kernel_switch_reader_end. See the description of kernel_switch_trace_path. This field is only examined if kernel_switch_trace_path is empty. The scheduler will call the init() function for the reader.
◆ kernel_switch_reader_end
| std::unique_ptr<ReaderType> dynamorio::drmemtrace::scheduler_tmpl_t< RecordType, ReaderType >::scheduler_options_t::kernel_switch_reader_end |
The end reader for kernel_switch_reader.
◆ kernel_switch_trace_path
| std::string dynamorio::drmemtrace::scheduler_tmpl_t< RecordType, ReaderType >::scheduler_options_t::kernel_switch_trace_path |
Input file containing template sequences of kernel context switch code. Each sequence must start with a TRACE_MARKER_TYPE_CONTEXT_SWITCH_START marker and end with TRACE_MARKER_TYPE_CONTEXT_SWITCH_END. The values of each marker must hold a switch_type_t enum value indicating which type of switch it corresponds to. Each sequence can be stored as a separate subfile of an archive file, or concatenated into a single file. Each sequence should be in the regular offline drmemtrace format. The sequence is inserted into the output stream on each context switch of the indicated type. The same file (or reader) must be passed when replaying as this kernel code is not stored when recording. An alternative to passing the file path is to pass kernel_switch_reader and kernel_switch_reader_end.
◆ mapping
| mapping_t dynamorio::drmemtrace::scheduler_tmpl_t< RecordType, ReaderType >::scheduler_options_t::mapping = MAP_TO_ANY_OUTPUT |
The mapping of inputs to outputs.
◆ migration_threshold_us
| uint64_t dynamorio::drmemtrace::scheduler_tmpl_t< RecordType, ReaderType >::scheduler_options_t::migration_threshold_us = 500 |
The minimum time in microseconds that must have elapsed after an input last ran on an output before that input is allowed to be migrated to a different output. This value is multiplied by time_units_per_us to produce a value that is compared to the "cur_time" parameter to next_record().
◆ quantum_duration
| uint64_t dynamorio::drmemtrace::scheduler_tmpl_t< RecordType, ReaderType >::scheduler_options_t::quantum_duration = 0 |
Deprecated: use quantum_duration_us and time_units_per_us for QUANTUM_TIME, or quantum_duration_instrs for QUANTUM_INSTRUCTIONS, instead. It is an error to set this to a non-zero value when struct_size includes quantum_duration_us. When struct_size does not include quantum_duration_us and this value is non-zero, the value in quantum_duration_us is replaced with this value divided by the default value of time_units_per_us.
◆ quantum_duration_instrs
| uint64_t dynamorio::drmemtrace::scheduler_tmpl_t< RecordType, ReaderType >::scheduler_options_t::quantum_duration_instrs = 10 * 1000 * 1000 |
The scheduling quantum duration for preemption, in instruction count, for QUANTUM_INSTRUCTIONS. The time passed to next_record() is ignored for purposes of quantum preempts.
Instructions executed in a quantum may end up higher than the specified value to avoid interruption of the kernel system call sequence.
◆ quantum_duration_us
| uint64_t dynamorio::drmemtrace::scheduler_tmpl_t< RecordType, ReaderType >::scheduler_options_t::quantum_duration_us = 5000 |
The scheduling quantum duration for preemption, in simulated microseconds, for QUANTUM_TIME. This value is multiplied by time_units_per_us to produce a value that is compared to the "cur_time" parameter to next_record() to determine when to force a quantum switch.
◆ quantum_unit
| quantum_unit_t dynamorio::drmemtrace::scheduler_tmpl_t< RecordType, ReaderType >::scheduler_options_t::quantum_unit = QUANTUM_INSTRUCTIONS |
The unit of the schedule time quantum.
◆ randomize_next_input
| bool dynamorio::drmemtrace::scheduler_tmpl_t< RecordType, ReaderType >::scheduler_options_t::randomize_next_input = false |
If true, enables a mode where the normal methods of choosing the next input based on priority, timestamps (if -sched_order_time is set), and FIFO order are disabled. Instead, the scheduler selects the next input randomly. Output bindings are still honored. This is intended for experimental use in sensitivity studies.
◆ read_inputs_in_init
| bool dynamorio::drmemtrace::scheduler_tmpl_t< RecordType, ReaderType >::scheduler_options_t::read_inputs_in_init = true |
If true, the scheduler will read from each input to determine its filetype during initialization. If false, the filetype will not be available prior to explicit record retrieval by the user, but this may be required for inputs whose sources are not yet set up at scheduler init time (e.g., inputs over blocking pipes with data only becoming available after initializing the scheduler, as happens with online trace analyzers). This must be true for DEPENDENCY_TIMESTAMPS as it also requires reading ahead.
◆ rebalance_period_us
| uint64_t dynamorio::drmemtrace::scheduler_tmpl_t< RecordType, ReaderType >::scheduler_options_t::rebalance_period_us = 50000 |
The period in microseconds at which rebalancing is performed to keep output run queues from becoming uneven. This value is multiplied by time_units_per_us to produce a value that is compared to the "cur_time" parameter to next_record().
◆ replay_as_traced_istream
| archive_istream_t* dynamorio::drmemtrace::scheduler_tmpl_t< RecordType, ReaderType >::scheduler_options_t::replay_as_traced_istream = nullptr |
Input stream for replaying the traced schedule when MAP_TO_RECORDED_OUTPUT is specified for more than one output stream (whose count must match the number of traced cores). Alternatively, if dynamorio::drmemtrace::scheduler_tmpl_t::input_workload_t.times_of_interest is non-empty, this stream is required for obtaining the mappings between timestamps and instruction ordinals.
◆ schedule_record_ostream
| archive_ostream_t* dynamorio::drmemtrace::scheduler_tmpl_t< RecordType, ReaderType >::scheduler_options_t::schedule_record_ostream = nullptr |
Output stream for recording the schedule for later replay. write_recorded_schedule() must be called when finished to write the in-memory data out to this stream.
◆ schedule_replay_istream
| archive_istream_t* dynamorio::drmemtrace::scheduler_tmpl_t< RecordType, ReaderType >::scheduler_options_t::schedule_replay_istream = nullptr |
Input stream for replaying a previously recorded schedule when MAP_AS_PREVIOUSLY is specified. If this is non-nullptr and MAP_AS_PREVIOUSLY is specified, schedule_record_ostream must be nullptr, and most other fields in this struct controlling scheduling are ignored.
◆ single_lockstep_output
| bool dynamorio::drmemtrace::scheduler_tmpl_t< RecordType, ReaderType >::scheduler_options_t::single_lockstep_output = false |
If true, enables a mode where all outputs are serialized into one global outer layer output. The single global output stream alternates in round-robin lockstep among each core output. The core outputs operate just like they would with no serialization, other than timing differences relative to other core outputs.
◆ struct_size
| size_t dynamorio::drmemtrace::scheduler_tmpl_t< RecordType, ReaderType >::scheduler_options_t::struct_size = sizeof(scheduler_options_t) |
Size of the struct for binary-compatible additions.
◆ syscall_switch_threshold
| uint64_t dynamorio::drmemtrace::scheduler_tmpl_t< RecordType, ReaderType >::scheduler_options_t::syscall_switch_threshold = 30000000 |
Determines the minimum latency in the unit of the trace's timestamps (microseconds) for which a non-maybe-blocking system call (one without a TRACE_MARKER_TYPE_MAYBE_BLOCKING_SYSCALL marker) will be treated as blocking and trigger a context switch.
◆ time_units_per_us
| double dynamorio::drmemtrace::scheduler_tmpl_t< RecordType, ReaderType >::scheduler_options_t::time_units_per_us = 1000. |
How many time units for the "cur_time" value passed to next_record() are equivalent to one simulated microsecond. E.g., if the time units are in picoseconds, pass one million here. This is used to scale all of the other parameters that are in microseconds (they all end in "_us": e.g., quantum_duration_us) so that they operate on the right time scale for the passed-in simulator time (or wall-clock microseconds if no time is passed). The default value is a rough estimate when no accurate simulated time is available: the instruction count is used in that case, and we use the instructions per microsecond for a 2GHz clock at 0.5 IPC as our default.
◆ verbosity
| int dynamorio::drmemtrace::scheduler_tmpl_t< RecordType, ReaderType >::scheduler_options_t::verbosity = 0 |
If > 0, diagnostic messages are printed to stderr. Higher values produce more frequent diagnostics.
The documentation for this struct was generated from the following file:
- /home/runner/work/dynamorio/dynamorio/build_release-64/clients/include/drmemtrace/scheduler.h
DynamoRIO version 11.2.0 --- Fri Dec 20 2024 17:44:43