Installation and setup¶

Installing dependencies¶

Make sure you have Python 3 installed with the venv module, and the dependencies required to build verilator, openFPGALoader and OpenOCD. To install the dependencies on Ubuntu 18.04 LTS, run:

apt install git build-essential autoconf cmake flex bison libftdi-dev libjson-c-dev libevent-dev libtinfo-dev uml-utilities python3 python3-venv python3-wheel protobuf-compiler libcairo2 libftdi1-2 libftdi1-dev libhidapi-hidraw0 libhidapi-dev libudev-dev pkg-config tree zlib1g-dev zip unzip help2man curl ethtool

libc6-dev : Breaks: libgcc-9-dev (< 9.3.0-5~) but 9.2.1-19 is to be installed

On Ubuntu 22.04 LTS the following dependencies may also be required:

apt install libtool libusb-1.0-0-dev pkg-config

Install Rowhammer tester¶

Clone the rowhammer-tester repository and install the rest of the required dependencies:

git clone --recursive https://github.com/antmicro/rowhammer-tester.git
cd rowhammer-tester
make deps

The last command will download and build all the dependencies (including a RISC-V GCC toolchain) and set up a Python virtual environment under the ./venv directory with all the required packages installed.

The virtual environment allows you to use Python without installing the packages system-wide. To enter the environment, you have to run source venv/bin/activate in each new shell. You can also use the provided make env target, which will start a new Bash shell with the virtualenv already sourced. You can install packages inside the virtual environment by entering the environment and then using pip.

To build the bitstream, you will also need to have Vivado (version 2020.2 or newer) installed and the vivado command available in your PATH. To configure Vivado in the current shell, you need to source /PATH/TO/Vivado/VERSION/settings64.sh. Then include it in your .bashrc or other shell init script.

To make the process automatic without hard-coding in the shell init script, you can use tools like direnv. A sample .envrc file looks like so:

source venv/bin/activate
source /PATH/TO/Vivado/VERSION/settings64.sh

All other commands assume that you run Python from the virtual environment with vivado in your PATH.

Local documentation build¶

The part of the documentation related to the digital design is auto-generated from source files. Other files are static and are located in the docs/ directory.

To build the documentation locally you may need to install additional requirements in your virtual Python environment. Those requirements are listed in `docs/requirements.txt’

You can install them with:

pip install ./docs/requirements.txt

Then you can build the local HTML documentation using:

cd docs
make html

Once the building process finishes, you can open ./build/html/index.html in your web browser.

Unit tests¶

To run unit tests for rowhammer tester modules, use:

make test

Network USB adapter setup¶

In order to control the Rowhammer platform, an Ethernet connection is necessary. In case you want to use an USB Ethernet adapter for this purpose, follow the instructions below.

1. Make sure you use a 1GbE USB network adapter.

2. Determine the MAC address for the USB network adapter:

   • Run sudo lshw -class network -short to get the list of all network interfaces

   • Check which of the devices uses the r8152 driver by running sudo ethtool -i <device>

   • Display the link information for the device running sudo ip link show <device> and look for the mac address next to the link/ether field

3. Configure the USB network adapter to appear as network device fpga0 using systemd

   • Create /etc/systemd/network/10-fpga0.link with the following contents:

   • Display the link information for the device running sudo ip link show <device> and look for the mac address next to the link/ether field

   [Match]
   # Set this to the MAC address of the USB network adapter
   MACAddress=XX:XX:XX:XX:XX
   
   [Link]
   Name=fpga0
   

4. Configure the fpga0 network device with a static IP address, always up (even when disconnected) and ignored by the network manager.

   • Run the following command, assuming your system uses NetworkManager:

     nmcli con add type ethernet con-name 'Rowhammer Tester' ifname fpga0 ipv4.method manual ipv4.addresses 192.168.100.100/24
     

   • Alternatively, if your system supports the legacy interfaces configuration file:

     1. Make sure your /etc/network/interfaces file contains the following line:

        source /etc/network/interfaces.d/*
        

     2. Create /etc/network/interfaces.d/fpga0 with the following contents:

        auto fpga0
        allow-hotplug fpga0
        iface fpga0 inet static
                address 192.168.100.100/24
        

     3. Check that nmcli device says the state is connected (externally) otherwise run sudo systemctl restart NetworkManager

   • Run ifup fpga0

5. Run sudo udevadm control --reload and then unplug the USB Ethernet device and plug it back in

6. Check whether an fpga0 interface is present with the correct IP address by running networkctl status