DDR4 DRAM Command Decoder

This repository contains an open-source DDR4 DRAM command decoder, as introduced in § 4 of our McSee paper (USENIX Security 2025). The decoder is designed to parse and analyze DRAM command traces extracted from high-speed oscilloscope captures.

Overview

The decoder processes signal captures acquired from a Teledyne oscilloscope and implements the following steps:

1. Conversion: The XMLdig file containing base64-encoded waveform data is converted to a CSV format. For this, the decoder invokes the external xmldig2csv converter.
2. Decoding: The DRAM bus signals (e.g., CA, CS, CK) are decoded into DDR4 command-level semantics.
3. Analysis: The decoded DRAM commands are analyzed by implementing experiment-specific analyses. For example, statistics are generated to understand the system behavior (e.g., command frequency, row activation patterns).

Requirements

1. Python ≥3.10.4 If python3 -v returns a version lower than 3.10.4, install it via pyenv:

   #### Instructions for Bash on Ubuntu/Debian #################################
   # Install the required build dependencies
   sudo apt install -y make build-essential libssl-dev zlib1g-dev \
   libbz2-dev libreadline-dev libsqlite3-dev wget curl llvm \
   libncursesw5-dev xz-utils tk-dev libxml2-dev libxmlsec1-dev libffi-dev liblzma-dev
   
   # Install pyenv (requires curl, git, build dependencies)
   curl -fsSL https://pyenv.run | bash
   
   # Add pyenv to shell startup (append to ~/.bashrc)
   echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.bashrc
   echo 'export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.bashrc
   echo 'eval "$(pyenv init --path)"' >> ~/.bashrc
   echo 'eval "$(pyenv init -)"' >> ~/.bashrc
   
   # Reload .bashrc to activate pyenv
   source ~/.bashrc
   
   # Install and set Python version
   pyenv install 3.10.4
   pyenv global 3.10.4

2. Python packages Install the required packages listed in requirements.txt, in a new virtual environment:

   cd decoder
   python3 -m venv venv
   source venv/bin/activate
   pip install -r requirements.txt

3. XMLdig-to-CSV converter Ensure that the xmldig2csv converter is accessible in the environment by building the converter based on its accompanying README and setting the XMLDIG2CSV_PATH environment variable:

   export XMLDIG2CSV_PATH="$HOME/git/xmldig2csv-converter/build/xmldig2csv" 

Usage

To use the decoder on a directory containing a Teledyne XMLdig file, you can run the provided decode_one.sh script as follows:

./scripts/decode_one.sh <path_to_xmldig_directory>

This script sets up the environment, activates the Python virtual environment, and runs the decoder on the specified directory.

Decoder Arguments

The main decoder script decode.py that is called by decode_one.sh accepts several arguments to control decoding behavior:

• -d, --directory <str>
  Specifies a suffix for the output directory

• -s, --setup-file <path>
  Path to a .lss file (scope setup file) used for configuring the oscilloscope.

• --dimm-config-dir <path>
  Path to the directory containing DIMM metadata (e.g., timing parameters) in JSON format, generated by spd-decoder.

Oscilloscope Communication

The repository includes two utility scripts that communicate directly with the Teledyne oscilloscope using the VXI-11 protocol over TCP/IP. This protocol is commonly used for LAN-based communication with laboratory instruments, allowing remote control via RPC.

Important

Before using these scripts, the scope_setup.py script must be updated. In particular, the scope's IP address (SCOPE_IP) and the digitizer port-to-signal mapping (input2signalname).

configure.py

This script configures the Teledyne oscilloscope for signal capture. It can set up vertical channel settings, acquisition depth, sample rate, trigger conditions, memory settings, and digital channel layout. However, as we figured out that configuring the device in this way is very slow, we just load a setup file (.lss) that we generated before directly on the oscilloscope.

Usage:

To load an existing setup file and set a specific output folder, run:

python3 configure.py -d <output_dir> -s <setup_file.lss>

Arguments:

• <output_dir>: Directory where saved traces will be saved
• <setup_file.lss>: Path to scope setup file on oscilloscope; if provided, it will be loaded before applying custom settings

acquire.py

This script communicates with a Teledyne oscilloscope using the VXI-11 protocol to control the acquisition process. It allows starting and stopping digital data capture and selecting the trigger mode.

Usage:

python3 acquire.py [--start] [--stop] [--trigger-mode {auto,normal,single,stopped}]

Arguments:

• --start: Starts capturing digital waveform data on the scope
• --stop: Stops data acquisition
• --trigger-mode <mode>: Sets the trigger mode. Must be one of:
  • auto: Triggering occurs automatically
  • normal: Waits for a valid trigger condition
  • single: Captures one acquisition and stops
  • stopped: Disables triggering

Example:

Start a capture in single trigger mode:

python3 acquire.py --start --trigger-mode single

Stop an ongoing acquisition:

python3 acquire.py --stop

This script is typically used in conjunction with configure.py to prepare the scope before starting a capture. It enables automated acquisition control for DRAM bus analysis.

Extensibility

The DDR4 decoder is designed to be modular and easily extensible. Its architecture separates signal decoding logic from data processing and analysis, making it straightforward to adapt the tool to new DRAM protocols or extend its functionality.

Adding or Modifying DRAM Protocols

The logic that maps raw signal patterns to high-level DRAM commands is defined in ddr4.py. This file contains the decoding rules for DDR4 bus commands based on combinations of signal line values (e.g., CS#, RAS#, CAS#, WE#, bank, address).

License

This project is open source and available under the GPLv3 License. See the LICENSE file for details.