update b59812e

.buildinfo

@@ -0,0 +1,4 @@
+# Sphinx build info version 1
+# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
+config: a33658b24e23c01ddcc34064eabd005b
+tags: 645f666f9bcd5a90fca523b33c5a78b7

_sources/arty.md.txt

@@ -0,0 +1,44 @@
+# Arty-A7 board
+
+The [Arty-A7 board](https://reference.digilentinc.com/reference/programmable-logic/arty-a7/start) allows testing its on-board DDR3 module.
+The board is designed around the Artix-7™ Field Programmable Gate Array (FPGA) from Xilinx.
+
+```{image} images/arty-a7.jpg
+```
+
+The following instructions explain how to set up the board.
+
+## Board configuration
+
+Connect the board USB and Ethernet cables to your computer and configure the network. The board's IP address will be `192.168.100.50` (so you could e.g. use `192.168.100.2/24`). The `IP_ADDRESS` environment variable can be used to modify the board's address.
+Next, generate the FPGA bitstream:
+
+```sh
+export TARGET=arty
+make build
+```
+
+```{note}
+This will by default target Arty A7 with the XC7A35TICSG324-1L FPGA. To build for XC7A100TCSG324-1,
+use `make build TARGET_ARGS="--variant a7-100"`
+```
+
+The results will be located in: `build/arty/gateware/digilent_arty.bit`. To upload it, use:
+
+```sh
+export TARGET=arty
+make upload
+```
+
+```{note}
+By typing `make` (without `build`) LiteX will generate build files without invoking Vivado.
+```
+
+To save bitstream in flash memory, use:
+
+```sh
+export TARGET=arty
+make flash
+```
+
+Bitstream will be loaded from flash memory upon device power-on or after a PROG button press.

_sources/ddr4_datacenter_dram_tester.md.txt

@@ -0,0 +1,46 @@
+# Data Center DRAM Tester
+
+```{image} images/ddr4_datacenter_dram_tester.jpg
+```
+
+The data center DRAM tester is an open source hardware test platform that enables testing and experimenting with various DDR4 RDIMMs (Registered Dual In-Line Memory Module).
+
+The hardware is open and can be found on GitHub:
+<https://github.com/antmicro/data-center-dram-tester/>
+
+The following instructions explain how to set up the board.
+
+## Board configuration
+
+First connect the board USB and Ethernet cables to your computer, plug the board to the socket and turn it on using power switch. Then configure the network. The board's IP address will be `192.168.100.50` (so you could e.g. use `192.168.100.2/24`). The `IP_ADDRESS` environment variable can be used to modify the board's address.
+Next, generate the FPGA bitstream:
+
+```sh
+export TARGET=ddr4_datacenter_test_board
+make build
+```
+
+```{note}
+By typing `make` (without `build`) LiteX will generate build files without invoking Vivado.
+```
+
+The results will be located in: `build/ddr4_datacenter_test_board/gateware/antmicro_datacenter_ddr4_test_board.bit`. To upload it, use:
+
+```sh
+export TARGET=ddr4_datacenter_test_board
+make upload
+```
+
+To save bitstream in flash memory, use:
+
+```sh
+export TARGET=ddr4_datacenter_test_board
+make flash
+```
+
+```{warning}
+There is a JTAG/SPI jumper named `MODE2` on the right side of the board.
+Unless it's set to the SPI setting, the FPGA will load the bitstream received via JTAG.
+```
+
+Bitstream will be loaded from flash memory upon device power-on or after a PROG button press.

_sources/ddr5_test_board.md.txt

@@ -0,0 +1,55 @@
+# DDR5 Test Board
+
+```{image} images/lpddr4-test-board.jpg
+```
+
+The DDR5 test board is an open source hardware test platform that enables testing and experimenting with
+various x4/x8 DDR5 modules embedded on DDR5 testbed.
+
+The hardware is open and can be found on GitHub:
+
+- Main board <https://github.com/antmicro/lpddr4-test-board/>
+- Testbed <https://github.com/antmicro/ddr5-testbed/>
+
+The following instructions explain how to set up the board.
+
+## Board configuration
+
+First connect the board USB and Ethernet cables to your computer, plug the board to the socket and turn it on using power switch. Then configure the network. The board's IP address will be `192.168.100.50` (so you could e.g. use `192.168.100.2/24`). The `IP_ADDRESS` environment variable can be used to modify the board's address.
+Next, generate the FPGA bitstream:
+
+```sh
+export TARGET=ddr5_test_board
+make build TARGET_ARGS="--l2-size 256 --build --iodelay-clk-freq 400e6 --bios-lto --rw-bios --no-sdram-hw-test"
+```
+
+```{note}
+--l2-size 256 sets L2 cache size to 256 bytes
+
+--no-sdram-hw-test disables hw accelerated memory test
+```
+
+```{note}
+By typing `make` (without `build`) LiteX will generate build files without invoking Vivado.
+```
+
+The results will be located in: `build/ddr5_test_board/gateware/antmicro_ddr5_test_board.bit`. To upload it, use:
+
+```sh
+export TARGET=ddr5_test_board
+make upload
+```
+
+To save bitstream in flash memory, use:
+
+```sh
+export TARGET=ddr5_test_board
+make flash
+```
+
+```{warning}
+There is a JTAG/SPI jumper named `MODE2` on the right side of the board.
+Unless it's set to the SPI setting, the FPGA will load the bitstream received via JTAG.
+```
+
+Bitstream will be loaded from flash memory upon device power-on or after a PROG button press.

_sources/ddr5_tester.md.txt

@@ -0,0 +1,52 @@
+# DDR5 Tester
+
+```{image} images/datacenter-rdimm-ddr5-tester.png
+```
+
+The DDR5 tester is an open source hardware test platform that enables testing and experimenting with various DDR5 RDIMMs (Registered Dual In-Line Memory Module).
+
+The hardware is open and can be found on GitHub:
+<https://github.com/antmicro/ddr5-tester/>
+
+The following instructions explain how to set up the board.
+
+## Board configuration
+
+First connect the board USB and Ethernet cables to your computer, plug the board to the socket and turn it on using power switch. Then configure the network. The board's IP address will be `192.168.100.50` (so you could e.g. use `192.168.100.2/24`). The `IP_ADDRESS` environment variable can be used to modify the board's address.
+Next, generate the FPGA bitstream:
+
+```sh
+export TARGET=ddr5_tester
+make build TARGET_ARGS="--l2-size 256 --build --iodelay-clk-freq 400e6 --bios-lto --rw-bios --module MTC10F1084S1RC --no-sdram-hw-test"
+```
+
+```{note}
+--l2-size 256 sets L2 cache size to 256 bytes
+
+--no-sdram-hw-test disables hw accelerated memory test
+```
+
+```{note}
+By typing `make` (without `build`) LiteX will generate build files without invoking Vivado.
+```
+
+The results will be located in: `build/ddr5_tester/gateware/antmicro_ddr5_tester.bit`. To upload it, use:
+
+```sh
+export TARGET=ddr5_tester
+make upload
+```
+
+To save bitstream in flash memory, use:
+
+```sh
+export TARGET=ddr5_tester
+make flash
+```
+
+```{warning}
+There is a JTAG/SPI jumper named `MODE` on the right side of the board.
+Unless it's set to the SPI setting, the FPGA will load the bitstream received via JTAG.
+```
+
+Bitstream will be loaded from flash memory upon device power-on or after a PROG button press.

_sources/dram_modules.md.txt

@@ -0,0 +1,57 @@
+# DRAM modules
+
+When building one of the targets in [rowhammer_tester/targets](https://github.com/antmicro/rowhammer-tester/tree/master/rowhammer_tester/targets), a custom DRAM module can be specified using the `--module` argument. To find the default modules for each target, check the output of `--help`.
+
+```{note}
+Specifying different DRAM module makes most sense on boards that allow to easily replace the DRAM module,
+such as on ZCU104. On other boards it would be necessary to desolder the DRAM chip and solder a new one.
+```
+
+(adding-new-modules)=
+
+## Adding new modules
+
+[LiteDRAM](https://github.com/enjoy-digital/litedram) controller provides out-of-the-box support for many DRAM modules.
+Supported modules can be found in [litedram/modules.py](https://github.com/enjoy-digital/litedram/blob/master/litedram/modules.py).
+If a module is not listed there, you can add a new definition.
+
+To make development more convenient, modules can be added in the rowhammer-tester repository directly in file [rowhammer_tester/targets/modules.py](https://github.com/antmicro/rowhammer-tester/blob/master/rowhammer_tester/targets/modules.py). These definitions will be used before definitions in LiteDRAM.
+
+```{note}
+After ensuring that the module works correctly, a Pull Request to LiteDRAM should be created to add support for the module.
+```
+
+To add a new module definition, use the existing ones as a reference. New module class should derive from `SDRAMModule` (or the helper classes, e.g. `DDR4Module`). Timing/geometry values for a module have to be obtained from the relevant DRAM module's datasheet. The timings in classes deriving from `SDRAMModule` are specified in nanoseconds. The timing value can also be specified as a 2-element tuple `(ck, ns)`, in which case `ck` is the number of clock cycles and `ns` is the number of nanoseconds (and can be `None`). The highest of the resulting timing values will be used.
+
+## SPD EEPROM
+
+On boards that use DIMM/SO-DIMM modules (e.g. ZCU104) it is possible to read the contents of the DRAM modules's [SPD EEPROM memory](https://en.wikipedia.org/wiki/Serial_presence_detect).
+SPD contains several essential module parameters that the memory controller needs in order to use the DRAM module.
+SPD EEPROM can be read over I2C bus.
+
+### Reading SPD EEPROM
+
+To read the SPD memory use the script `rowhammer_tester/scripts/spd_eeprom.py`.
+First prepare the environment as described in {ref}`controlling-the-board`.
+Then use the following command to read the contents of SPD EEPROM and save it to a file, for example:
+
+```sh
+python rowhammer_tester/scripts/spd_eeprom.py read MTA4ATF51264HZ-3G2J1.bin
+```
+
+The contents of the file can then be used to get DRAM module parameters.
+Use the following command to examine the parameters:
+
+```sh
+python rowhammer_tester/scripts/spd_eeprom.py show MTA4ATF51264HZ-3G2J1.bin 125e6
+```
+
+Note that system clock frequency must be passed as an argument to determine timing values in controller clock cycles.
+
+### Using SPD data
+
+The memory controller is able to set the timings read from an SPD EEPROM during system boot.
+The only requirement here is that the SoC is built with I2C controller, and I2C pins are routed to the (R)DIMM module.
+There is no additional action required from system user.
+The timings will be set automatically.
+

_sources/general.md.txt

@@ -0,0 +1,129 @@
+# General
+
+The aim of this project is to provide a platform for testing [DRAM vulnerability to rowhammer attacks](https://users.ece.cmu.edu/~yoonguk/papers/kim-isca14.pdf).
+
+(architecture)=
+## Architecture
+
+The setup consists of FPGA gateware and application side software.
+The following diagram illustrates the general system architecture.
+
+```{image} ./images/architecture.png
+:alt: Architecture diagram
+:target: ./images/architecture.png
+```
+
+The DRAM is connected to [LiteDRAM](https://github.com/enjoy-digital/litedram), which provides swappable PHYs and a DRAM controller implementation.
+
+In the default bulk transfer mode the LiteDRAM controller is connected to PHY and ensures correct DRAM traffic.
+Bulk transfers can be controlled using dedicated Control & Status Registers (CSRs) and use LiteDRAM DMA to ensure fast operation.
+
+The Payload Executor allows executing a user-provided sequence of commands.
+It temporarily disconnects the DRAM controller from PHY, executes the instructions stored in the SRAM memory,
+translating them into DFI commands and finally reconnects the DRAM controller.
+
+The application side consists of a set of Python scripts communicating with the FPGA using the LiteX EtherBone bridge.
+
+## Installing dependencies
+
+Make sure you have Python 3 installed with the `venv` module, and the dependencies required to build
+[verilator](https://github.com/verilator/verilator), [openFPGALoader](https://github.com/trabucayre/openFPGALoader)
+and [OpenOCD](https://github.com/openocd-org/openocd).
+To install the dependencies on Ubuntu 18.04 LTS, run:
+
+```sh
+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
+```
+
+````{note}
+On some Debian-based systems there's a problem with a broken dependency:
+
+  ```
+  libc6-dev : Breaks: libgcc-9-dev (< 9.3.0-5~) but 9.2.1-19 is to be installed
+  ```
+
+`gcc-9-base` package installation solves the problem.
+````
+
+On Ubuntu 22.04 LTS the following dependencies may also be required:
+
+```sh
+apt install libtool libusb-1.0-0-dev pkg-config
+```
+
+### Rowhammer tester
+
+Now clone the `rowhammer-tester` repository and install the rest of the required dependencies:
+
+```sh
+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 will set up a [Python virtual environment](https://docs.python.org/3/library/venv.html) 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`.
+This can be put in your `.bashrc` or other shell init script.
+
+To make the process automatic without hard-coding these things in shell init script,
+tools like [direnv](https://github.com/direnv/direnv) can be used. A sample `.envrc` file would then look like this:
+
+```sh
+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`.
+
+## Packaging the bitstream
+
+If you want to save the bitstream and use it later or share it with someone, there is an utility target `make pack`.
+It packs files necessary to load the bitstream and run rowhammer scripts on it.
+Those files are:
+ - `build/$TARGET/gateware/$TOP.bit`
+ - `build/$TARGET/csr.csv`
+ - `build/$TARGET/defs.csv`
+ - `build/$TARGET/sdram_init.py`
+ - `build/$TARGET/litedram_settings.json`
+
+After running `make pack`, you should have a zip file named like `$TARGET-$BRANCH-$COMMIT.zip`.
+
+Next time you want to use a bitstream packaged in such way, all you need to do is to run
+`unzip your-bitstream-file.zip` and you are all set.
+
+## Local documentation build
+
+The gateware part of the documentation is auto-generated from source files.
+Other files are static and are located in the `doc/` directory.
+To build the documentation, enter:
+
+```sh
+source venv/bin/activate
+pip install -r requirements.txt
+python -m sphinx -b html doc build/documentation/html
+```
+
+The documentation will be located in `build/documentation/index.html`.
+
+```{note}
+For easier development one can use [sphinx-autobuild](https://pypi.org/project/sphinx-autobuild)
+using command `sphinx-autobuild -b html doc build/documentation/html --re-ignore 'doc/build/.*'`.
+The documentation can be then viewed in a browser at `http://127.0.0.1:8000`.
+```
+
+## Tests
+
+To run project tests use:
+
+```sh
+make test
+```