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 ()=default
virtual scheduler_status_t	init (std::vector< input_workload_t > &workload_inputs, int output_count, scheduler_options_t options)
stream_t *	get_stream (output_ordinal_t ordinal)
int	get_input_stream_count () const
memtrace_stream_t *	get_input_stream_interface (input_ordinal_t input) const
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 ( )

default

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

Returns a string further describing an error code.

get_input_stream_count()

template<typename RecordType , typename ReaderType >

int dynamorio::drmemtrace::scheduler_tmpl_t< RecordType, ReaderType >::get_input_stream_count

(

)

const

Returns the number of input streams.

get_input_stream_interface()

template<typename RecordType , typename ReaderType >

memtrace_stream_t* dynamorio::drmemtrace::scheduler_tmpl_t< RecordType, ReaderType >::get_input_stream_interface

(

input_ordinal_t

input

)

const

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

get_input_stream_name()

template<typename RecordType , typename ReaderType >

std::string dynamorio::drmemtrace::scheduler_tmpl_t< RecordType, ReaderType >::get_input_stream_name

(

input_ordinal_t

input

)

const

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 >

stream_t* dynamorio::drmemtrace::scheduler_tmpl_t< RecordType, ReaderType >::get_stream

(

output_ordinal_t

ordinal

)

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