1. The Hardware Repository

All relevant hardware files can be found in the hw folder in the THANNA repository. The following subsections help to navigate and operate within the hardware part of the project.

Be aware: This is not supposed to be a detailed

1.1. Make System

With the Makefile one has several command line options to build and simulate the hardware. The most important make targets are listed here. The more specific ones are explained in the corresponding hardware sections.

Make targets:

  • make sim_thanna_ip_core : creates the THANNA_IP_CORE in a simulation environment to simulate

  • make thanna_ip_core : creates the THANNA IP CORE and packages it to be used in a block design

  • make system : creates the block design for the board on the system level and loads the THANNA_IP_CORE

  • make update_system : For debugging: Opens the system vivado project and regenerates the output products

  • make clean : Cleanup the output out folder

  • make : shortcut for targets execution: clean -> sim_thanna_ip_core -> thanna_ip_core -> system

1.2. TCL

One can interact with Vivado over the GUI or TCL commands. The TCL scripts automatize every step, from building the project to programming the FPGA device. The TCL scripts are automatically launched via the Makefile and can be found. The TCL scripts only need to be adapted if new functionality is added, such as new hardware modules.

The TCL files include:

  • Parameter passing from the Makefile

  • Creating, opening and closing projects

  • Adding the board files, vhdl files, vivado library files, driver files

  • Elaboration, Synthesis, Simulation and Implementation

  • Generating the bitstream and programming the FPGA device

Active TCL Scripts:

  • vivado.tcl : A flexible script that contains all the functionality above. For info how to use it take the Makefile as reference.

1.3. The Output Directory

The out/ directory contains the generated output projects.

  • *_sim/ simulation project folder

  • *_ip_core/ deployment project folder containing the IP CORE vivado

  • system/ deployment project folder containing the board design with the IP cores

All underlying .xpr files can opened, edited and inspected with vivado. When creating new modules it is required to copy or save the modules outside of the output directory next to the other hardware description modules, since the output directory is not tracked via git and is cleaned up during builds. If persistent changes to block design file are made in vivado, copy the file from out/system/design_1.bd to board_files/<<name_of_fpga_device>>/design_1.bd.

1.4. Hardware Description

The hardwaremodules are currently written and tested in vhdl.

Structure of the vhdl directory:

  • vhdl/pkg : All custom vhdl libraries

  • vhdl/src : All vhdl modules that are supposed to be deployed on the FPGA device

  • vhdl/sim/modules : All vhdl modules that are integrated to run the simulation

  • vhdl/sim/testbenches : All vhdl modules that are simulation testbenches

When creating new modules it is required to copy or save the modules outside of the output directory next to the other hardware description modules, since the output directory is not tracked via git and is cleaned up during builds.

1.5. Board Files

In the board files directory each subfolder corresponds to one FPGA device. Each folder contains a block design file with the ending .bd and a constraint file with the ending .xdc. If persistent changes to block design file are made in vivado, copy the file from out/system/design_1.bd to board_files/<<name_of_fpga_device>>/design_1.bd. The constraint file defines hardware parameters and connects hardware components listed in the board design to board components. It can be edited in any text editor.

1.6. Wavewindow Files

The wavefile folder contains all saved waveconfigs. Every wavefile contains the vhdl module as prefix and “_behave.wcfg” as suffix. Wavefiles can be loaded and stored after simulation in the vivado editor.

1.7. Python Testbench Scripts

The sim folder contains the python script sim_interface.py that generates text files for the simulated DDR. Each line in the text file contains 8-Bit in binary form. During simulation every line is transfered to the Memory. The line number that corresponds to the byte in the text file represents the address in the simulated DDR.