DynamoRIO
dynamorio::drmemtrace::scheduler_tmpl_t< RecordType, ReaderType > Class Template Reference

#include <scheduler.h>

Data Structures

struct  input_reader_t
 
struct  input_thread_info_t
 
struct  input_workload_t
 
struct  range_t
 
struct  scheduler_options_t
 
class  stream_t
 
struct  timestamp_range_t
 

Public Types

enum  scheduler_status_t {
  STATUS_SUCCESS,
  STATUS_ERROR_INVALID_PARAMETER,
  STATUS_ERROR_FILE_OPEN_FAILED,
  STATUS_ERROR_FILE_READ_FAILED,
  STATUS_ERROR_NOT_IMPLEMENTED,
  STATUS_ERROR_FILE_WRITE_FAILED,
  STATUS_ERROR_RANGE_INVALID
}
 
enum  stream_status_t {
  STATUS_OK,
  STATUS_EOF,
  STATUS_WAIT,
  STATUS_INVALID,
  STATUS_REGION_INVALID,
  STATUS_NOT_IMPLEMENTED,
  STATUS_SKIPPED,
  STATUS_RECORD_FAILED,
  STATUS_IDLE,
  STATUS_IMPOSSIBLE_BINDING,
  STATUS_STOLE
}
 
enum  mapping_t {
  MAP_TO_CONSISTENT_OUTPUT,
  MAP_TO_RECORDED_OUTPUT,
  MAP_TO_ANY_OUTPUT,
  MAP_AS_PREVIOUSLY
}
 
enum  inter_input_dependency_t {
  DEPENDENCY_IGNORE = 0x00,
  DEPENDENCY_TIMESTAMPS_BITFIELD = 0x01,
  DEPENDENCY_DIRECT_SWITCH_BITFIELD = 0x02,
  DEPENDENCY_TIMESTAMPS
}
 
enum  quantum_unit_t {
  QUANTUM_INSTRUCTIONS,
  QUANTUM_TIME
}
 
enum  scheduler_flags_t {
  SCHEDULER_DEFAULTS = 0,
  SCHEDULER_PROVIDE_PHYSICAL_ADDRESSES = 0x1,
  SCHEDULER_SPECULATE_NOPS = 0x2,
  SCHEDULER_USE_INPUT_ORDINALS = 0x4,
  SCHEDULER_USE_SINGLE_INPUT_ORDINALS = 0x8
}
 
enum  switch_type_t {
  SWITCH_INVALID = 0,
  SWITCH_THREAD,
  SWITCH_PROCESS
}
 
typedef int input_ordinal_t
 
typedef int output_ordinal_t
 

Public Member Functions

 scheduler_tmpl_t ()
 
virtual scheduler_status_t init (std::vector< input_workload_t > &workload_inputs, int output_count, scheduler_options_t options)
 
virtual stream_tget_stream (output_ordinal_t ordinal)
 
virtual int get_input_stream_count () const
 
virtual memtrace_stream_tget_input_stream_interface (input_ordinal_t input) const
 
virtual std::string get_input_stream_name (input_ordinal_t input) const
 
int64_t get_output_cpuid (output_ordinal_t output) const
 
std::string get_error_string () const
 
scheduler_status_t write_recorded_schedule ()
 

Static Public Member Functions

static scheduler_options_t make_scheduler_parallel_options (int verbosity=0)
 
static scheduler_options_t make_scheduler_serial_options (int verbosity=0)
 

Static Public Attributes

static constexpr input_ordinal_t INVALID_INPUT_ORDINAL = -1
 
static constexpr output_ordinal_t INVALID_OUTPUT_ORDINAL = -1
 

Detailed Description

template<typename RecordType, typename ReaderType>
class dynamorio::drmemtrace::scheduler_tmpl_t< RecordType, ReaderType >

Schedules traced software threads onto simulated cpus. Takes in a set of recorded traces and maps them onto a new set of output streams, typically representing simulated cpus.

This is a templated class to support not just operating over dynamorio::drmemtrace::memref_t inputs read by dynamorio::drmemtrace::reader_t, but also over dynamorio::drmemtrace::trace_entry_t records read by dynamorio::drmemtrace::record_reader_t.

Member Typedef Documentation

◆ input_ordinal_t

template<typename RecordType , typename ReaderType >
typedef int dynamorio::drmemtrace::scheduler_tmpl_t< RecordType, ReaderType >::input_ordinal_t

Identifies an input stream by its index.

◆ output_ordinal_t

template<typename RecordType , typename ReaderType >
typedef int dynamorio::drmemtrace::scheduler_tmpl_t< RecordType, ReaderType >::output_ordinal_t

Identifies an output stream by its index.

Member Enumeration Documentation

◆ inter_input_dependency_t

template<typename RecordType , typename ReaderType >
enum dynamorio::drmemtrace::scheduler_tmpl_t::inter_input_dependency_t

Flags specifying how inter-input-stream dependencies are handled. The _BITFIELD values can be combined. Typical combinations are provided so the enum type can be used directly.

Enumerator
DEPENDENCY_IGNORE 

Ignores all inter-input dependencies.

DEPENDENCY_TIMESTAMPS_BITFIELD 

Ensures timestamps in the inputs arrive at the outputs in timestamp order. For MAP_TO_ANY_OUTPUT, enforcing asked-for context switch rates is more important that honoring precise trace-buffer-based timestamp inter-input dependencies: thus, timestamp ordering will be followed at context switch points for picking the next input, but timestamps will not preempt an input. To precisely follow the recorded timestamps, use MAP_TO_RECORDED_OUTPUT. If this flag is on, dynamorio::drmemtrace::scheduler_tmpl_t:: scheduler_options_t.read_inputs_in_init must be set to true.

DEPENDENCY_DIRECT_SWITCH_BITFIELD 

Ensures timestamps in the inputs arrive at the outputs in timestamp order. For MAP_TO_ANY_OUTPUT, enforcing asked-for context switch rates is more important that honoring precise trace-buffer-based timestamp inter-input dependencies: thus, timestamp ordering will be followed at context switch points for picking the next input, but timestamps will not preempt an input. To precisely follow the recorded timestamps, use MAP_TO_RECORDED_OUTPUT.

DEPENDENCY_TIMESTAMPS 

Combines DEPENDENCY_TIMESTAMPS_BITFIELD and DEPENDENCY_DIRECT_SWITCH_BITFIELD. This is the recommended setting for most schedules.

◆ mapping_t

template<typename RecordType , typename ReaderType >
enum dynamorio::drmemtrace::scheduler_tmpl_t::mapping_t

Controls how inputs are mapped to outputs.

Enumerator
MAP_TO_CONSISTENT_OUTPUT 

Each input stream is mapped to a single output stream (i.e., no input will appear on more than one output), supporting lock-free parallel analysis when combined with DEPENDENCY_IGNORE.

MAP_TO_RECORDED_OUTPUT 

Each input stream is assumed to contain markers indicating how it was originally scheduled. Those markers are honored with respect to which core number (considered to correspond to output stream ordinal) an input is scheduled into. This requires an output stream count equal to the number of cores occupied by the input stream set. When combined with DEPENDENCY_TIMESTAMPS, this will precisely replay the recorded schedule; for this mode, dynamorio::drmemtrace::scheduler_tmpl_t:: scheduler_options_t.replay_as_traced_istream must be specified. The original as-traced cpuid that is mapped to each output stream can be obtained by calling the get_output_cpuid() function on each stream.

An alternative use of this mapping is with a single output to interleave inputs in a strict timestamp order, as with make_scheduler_serial_options(), without specifying a schedule file and without recreating core mappings: only timestamps are honored.

MAP_TO_ANY_OUTPUT 

The input streams are scheduled using a new dynamic sequence onto the output streams. Any input markers indicating how the software threads were originally mapped to cores during tracing are ignored. Instead, inputs run until either a quantum expires (see dynamorio::drmemtrace::scheduler_tmpl_t::scheduler_options_t::quantum_unit) or a (potentially) blocking system call is identified. At this point, a new input is selected, taking into consideration other options such as priorities, core bindings, and inter-input dependencies.

MAP_AS_PREVIOUSLY 

A schedule recorded previously by this scheduler is to be replayed. The input schedule data is specified in dynamorio::drmemtrace::scheduler_tmpl_t:: scheduler_options_t.schedule_replay_istream. The same output count and input stream order and count must be re-specified; scheduling details such as regions of interest and core bindings do not need to be re-specified and are in fact ignored.

◆ quantum_unit_t

template<typename RecordType , typename ReaderType >
enum dynamorio::drmemtrace::scheduler_tmpl_t::quantum_unit_t

Quantum units used for replacing one input with another pre-emptively.

Enumerator
QUANTUM_INSTRUCTIONS 

Uses the instruction count as the quantum.

QUANTUM_TIME 

Uses the user's notion of time as the quantum. This must be supplied by the user by calling the next_record() variant that takes in the current time.

◆ scheduler_flags_t

template<typename RecordType , typename ReaderType >
enum dynamorio::drmemtrace::scheduler_tmpl_t::scheduler_flags_t

Flags controlling aspects of the scheduler beyond the core scheduling.

Enumerator
SCHEDULER_DEFAULTS 

Default behavior.

SCHEDULER_PROVIDE_PHYSICAL_ADDRESSES 

Whether physical addresses should be provided in addition to virtual addresses.

SCHEDULER_SPECULATE_NOPS 

Specifies that speculation should supply just NOP instructions.

SCHEDULER_USE_INPUT_ORDINALS 

Causes the get_record_ordinal() and get_instruction_ordinal() results for an output stream to equal those values for the current input stream for that output, rather than accumulating across inputs. This also changes the behavior of get_shard_index() as documented under that function.

SCHEDULER_USE_SINGLE_INPUT_ORDINALS 

If there is just one input and just one output stream, this sets SCHEDULER_USE_INPUT_ORDINALS. In all cases, this changes the behavior of get_shard_index() as documented under that function.

◆ scheduler_status_t

template<typename RecordType , typename ReaderType >
enum dynamorio::drmemtrace::scheduler_tmpl_t::scheduler_status_t

Status codes used by non-stream member functions. get_error_string() provides additional information such as which input file path failed.

Enumerator
STATUS_SUCCESS 

Success.

STATUS_ERROR_INVALID_PARAMETER 

Error: invalid parameter.

STATUS_ERROR_FILE_OPEN_FAILED 

Error: file open failed.

STATUS_ERROR_FILE_READ_FAILED 

Error: file read failed.

STATUS_ERROR_NOT_IMPLEMENTED 

Error: not implemented.

STATUS_ERROR_FILE_WRITE_FAILED 

Error: file write failed.

STATUS_ERROR_RANGE_INVALID 

Error: region of interest invalid.

◆ stream_status_t

template<typename RecordType , typename ReaderType >
enum dynamorio::drmemtrace::scheduler_tmpl_t::stream_status_t

Status codes used by stream member functions. get_error_string() provides additional information such as which input file path failed.

Enumerator
STATUS_OK 

Stream is healthy and can continue to advance.

STATUS_EOF 

Stream is at its end.

STATUS_WAIT 

For dynamic scheduling with cross-stream dependencies, the scheduler may pause a stream if it gets ahead of another stream it should have a dependence on. This value is also used for schedules following the recorded timestamps (DEPENDENCY_TIMESTAMPS) to avoid one stream getting ahead of another. STATUS_WAIT should be treated as artificial, an artifact of enforcing a recorded schedule on concurrent differently-timed output streams. Simulators are suggested to not advance simulated time for STATUS_WAIT while they should advance time for STATUS_IDLE as the latter indicates a true lack of work.

STATUS_INVALID 

Error condition.

STATUS_REGION_INVALID 

Input region is out of bounds.

STATUS_NOT_IMPLEMENTED 

Feature not implemented.

STATUS_SKIPPED 

Used for internal scheduler purposes.

STATUS_RECORD_FAILED 

Failed to record schedule for future replay.

STATUS_IDLE 

This code indicates that all inputs are blocked waiting for kernel resources (such as i/o). This is similar to STATUS_WAIT, but STATUS_WAIT indicates an artificial pause due to imposing the original ordering while STATUS_IDLE indicates actual idle time in the application. Simulators are suggested to not advance simulated time for STATUS_WAIT while they should advance time for STATUS_IDLE.

STATUS_IMPOSSIBLE_BINDING 

Indicates an input has a binding whose outputs are all marked inactive.

STATUS_STOLE 

Used for internal scheduler purposes.

◆ switch_type_t

template<typename RecordType , typename ReaderType >
enum dynamorio::drmemtrace::scheduler_tmpl_t::switch_type_t

Types of context switches for dynamorio::drmemtrace::scheduler_tmpl_t::scheduler_options_t:: kernel_switch_trace_path and kernel_switch_reader. The enum value is the subfile component name in the archive_istream_t.

Enumerator
SWITCH_INVALID 

Invalid value.

SWITCH_THREAD 

Generic thread context switch.

SWITCH_PROCESS 

Generic process context switch. A workload is considered a process.

Constructor & Destructor Documentation

◆ scheduler_tmpl_t()

template<typename RecordType , typename ReaderType >
dynamorio::drmemtrace::scheduler_tmpl_t< RecordType, ReaderType >::scheduler_tmpl_t ( )
inline

Default constructor.

Member Function Documentation

◆ get_error_string()

template<typename RecordType , typename ReaderType >
std::string dynamorio::drmemtrace::scheduler_tmpl_t< RecordType, ReaderType >::get_error_string ( ) const
inline

Returns a string further describing an error code.

◆ get_input_stream_count()

template<typename RecordType , typename ReaderType >
virtual int dynamorio::drmemtrace::scheduler_tmpl_t< RecordType, ReaderType >::get_input_stream_count ( ) const
inlinevirtual

Returns the number of input streams.

◆ get_input_stream_interface()

template<typename RecordType , typename ReaderType >
virtual memtrace_stream_t* dynamorio::drmemtrace::scheduler_tmpl_t< RecordType, ReaderType >::get_input_stream_interface ( input_ordinal_t  input) const
inlinevirtual

Returns the dynamorio::drmemtrace::memtrace_stream_t interface for the 'ordinal'-th input stream.

◆ get_input_stream_name()

template<typename RecordType , typename ReaderType >
virtual std::string dynamorio::drmemtrace::scheduler_tmpl_t< RecordType, ReaderType >::get_input_stream_name ( input_ordinal_t  input) const
inlinevirtual

Returns the name (from get_stream_name()) of the 'ordinal'-th input stream.

◆ get_output_cpuid()

template<typename RecordType , typename ReaderType >
int64_t dynamorio::drmemtrace::scheduler_tmpl_t< RecordType, ReaderType >::get_output_cpuid ( output_ordinal_t  output) const

Returns the get_output_cpuid() value for the given output. This interface is exported so that a user can get the cpuids at initialization time when using single_lockstep_output where there is just one output stream even with multiple output cpus.

◆ get_stream()

template<typename RecordType , typename ReaderType >
virtual stream_t* dynamorio::drmemtrace::scheduler_tmpl_t< RecordType, ReaderType >::get_stream ( output_ordinal_t  ordinal)
inlinevirtual

Returns the 'ordinal'-th output stream.

◆ init()

template<typename RecordType , typename ReaderType >
virtual scheduler_status_t dynamorio::drmemtrace::scheduler_tmpl_t< RecordType, ReaderType >::init ( std::vector< input_workload_t > &  workload_inputs,
int  output_count,
scheduler_options_t  options 
)
virtual

Initializes the scheduler for the given inputs, count of output streams, and options.

◆ make_scheduler_parallel_options()

template<typename RecordType , typename ReaderType >
static scheduler_options_t dynamorio::drmemtrace::scheduler_tmpl_t< RecordType, ReaderType >::make_scheduler_parallel_options ( int  verbosity = 0)
inlinestatic

Constructs options for a parallel no-inter-input-dependencies schedule where the output stream's get_record_ordinal() and get_instruction_ordinal() reflect just the current input rather than all past inputs on that output.

◆ make_scheduler_serial_options()

template<typename RecordType , typename ReaderType >
static scheduler_options_t dynamorio::drmemtrace::scheduler_tmpl_t< RecordType, ReaderType >::make_scheduler_serial_options ( int  verbosity = 0)
inlinestatic

Constructs options for a serial as-recorded schedule where the output stream's get_record_ordinal() and get_instruction_ordinal() honor skipped records in the input if, and only if, there is a single input and a single output.

◆ write_recorded_schedule()

template<typename RecordType , typename ReaderType >
scheduler_status_t dynamorio::drmemtrace::scheduler_tmpl_t< RecordType, ReaderType >::write_recorded_schedule ( )

Writes out the recorded schedule. Requires that dynamorio::drmemtrace::scheduler_tmpl_t:: scheduler_options_t::schedule_record_ostream was non-nullptr at init time.

Field Documentation

◆ INVALID_INPUT_ORDINAL

template<typename RecordType , typename ReaderType >
constexpr input_ordinal_t dynamorio::drmemtrace::scheduler_tmpl_t< RecordType, ReaderType >::INVALID_INPUT_ORDINAL = -1
staticconstexpr

Sentinel value indicating that no input stream is specified.

◆ INVALID_OUTPUT_ORDINAL

template<typename RecordType , typename ReaderType >
constexpr output_ordinal_t dynamorio::drmemtrace::scheduler_tmpl_t< RecordType, ReaderType >::INVALID_OUTPUT_ORDINAL = -1
staticconstexpr

Sentinel value indicating that no input stream is specified.


The documentation for this class was generated from the following file:
  • /home/runner/work/dynamorio/dynamorio/build_release-64/clients/include/drmemtrace/scheduler.h