DynamoRIO Documentation

Required Arguments

To execute DynamoRIO profilers, specific arguments are required based on the chosen action. The necessary arguments are defined in the code as follows:

@classmethod
def required_profiling_args(cls):
    """
    Return required arguments for the profiling method.
    """
    return ["executable"]

@classmethod
def required_extract_args(cls, action):
    """
    Return required arguments for the extract_metrics method.
    """
    if action == "extract_metrics":
        return ["report_file"]
    else:
        return []

Configuration File Support

The DynamoRIO memcount client supports runtime configuration through a text-based configuration file. This allows fine-grained control over profiling behavior without recompiling the instrumentation client.

enable_instruction_threshold=true
instruction_threshold=100000000

Example Usage

Below are examples of how to execute the profiling tool with different actions:

• Profiling the application:

  python3 main.py --profiler dynamorio --action profiling --executable ./executable
  

• Profiling with custom configuration:

  python3 main.py --profiler dynamorio --action profiling --config config/memcount_config.txt --executable ./executable
  

• Profiling with instruction threshold enabled:

  Edit config/memcount_config.txt to enable the threshold:

  enable_instruction_threshold=true
  instruction_threshold=100000000
  

  Then run:

  python3 main.py --profiler dynamorio --action profiling --config config/memcount_config.txt --executable ./executable
  

• Extracting metrics from an existing report:

  python3 main.py --profiler dynamorio --action extract_metrics --report_file ./report_file
  

• Performing both profiling and metric extraction:

  python3 main.py --profiler dynamorio --action both --executable ./executable
  

Sample Output

This profiler generates output traces that follow the standardized format defined by the MemSysExplorer Application Interface.

Output Files

The DynamoRIO profiler generates several output files during execution:

Time-Series Output

The time-series output (timeseries_<pid>.pb) captures windowed Working Set Size (WSS) samples throughout program execution.

What is Captured:

• WSS measurements at configurable intervals (controlled by sample_window_refs)

• Per-window read and write counts

• Both exact and approximate (HyperLogLog) WSS estimates

• Size histograms for memory accesses

Configuring Sampling Interval:

The sampling window size is controlled by the sample_window_refs parameter in the configuration file:

sample_window_refs=2000

This captures a WSS sample every 2000 memory references.

Fields in Time-Series Output:

Parsing Time-Series Output:

Use the timeseries_parser.py tool to convert protobuf output to readable formats:

# Get summary statistics
python3 tools/timeseries_parser.py output/timeseries_12345.pb

# Export to CSV
python3 tools/timeseries_parser.py output/timeseries_12345.pb --format csv --output wss_data.csv

# Visualize with plots
python3 tools/timeparser_plot.py output/timeseries_12345.pb --output wss_plot.png

See 4. Tools for complete documentation on parsing tools.

Memory Trace Output

The memory trace output (memtrace_<pid>.pb) captures per-access memory events when enable_trace=true.

What is Captured:

• Every memory read and write operation

• Memory addresses accessed

• Thread context for each access

• Cache hit/miss information (if available)

Fields in Trace Output:

Parsing Memory Trace Output:

Use the trace_parser.py tool to convert protobuf output:

# Get summary statistics
python3 tools/trace_parser.py output/memtrace_12345.pb

# Export to JSON
python3 tools/trace_parser.py output/memtrace_12345.pb --format json --output trace.json

# Export first 10000 events to CSV
python3 tools/trace_parser.py output/memtrace_12345.pb --format csv --limit 10000 --output trace.csv

# Filter by thread
python3 tools/trace_parser.py output/memtrace_12345.pb --thread 12345 --format csv

See 4. Tools for complete documentation on parsing tools.

Parsing Workflow

End-to-End Workflow for DynamoRIO Output:

Step 1: Run profiling with configuration

python3 main.py --profiler dynamorio --action profiling \
    --config config/memcount_config.txt --executable ./my_workload

Step 2: Parse time-series data for WSS trends

python3 tools/timeseries_parser.py output/timeseries_*.pb --format summary

Step 3: Visualize WSS over time

python3 tools/timeparser_plot.py output/timeseries_*.pb --output wss_analysis.png

Step 4: Parse memory trace for detailed analysis (if enabled)

python3 tools/trace_parser.py output/memtrace_*.pb --format csv --output detailed_trace.csv

Step 5: Calculate reuse distance (optional)

python3 tools/reuse_distance.py detailed_trace.csv --output reuse_analysis.txt

Additional Notes

• The DynamoRIO must be correctly installed and accessible via the system PATH variable.

Troubleshooting

If you encounter issues when building the DynamoRIO profiler:

• Ensure that the environment has been set up properly using:

  source setup/setup.csh dynamorio
  

  or

  source setup/setup.sh dynamorio
  

• Verify that the correct GCC version is installed and exported in your environment. The profiler expects a compatible GCC version as configured in your setup script (e.g., GCC 11.2.0).

• Check for missing compiler paths: Make sure PATH, LD_LIBRARY_PATH, LIBRARY_PATH, and C_INCLUDE_PATH are configured to include your GCC installation directories.

If problems persist, rebuild the profiler after re-sourcing your environment.