====== VHDL ======
<box blue right 38% | **Downloads**>
  * [[https://github.com/flink-project/flinkvhdl | flink VHDL Modules on Github]]
</box>

This is the user documentation for the flink VHDL modules. At the current state flink is available for Altera and Xilinx FPGAs.
\\
\\
\\

===== Overview =====
<box green right 38% | **Functions**>
  * [[.:subdevices|Available functions]] 
</box>
We currently support various functions which are implemented in subdevices. More functions will be developed in the near future.
===== Requirements =====
<box red right 38% | **Troubleshooting**>
  * [[.:Multiple subdevices with the same number of ports]] 
</box>
  * Quartus version 13.0.1 Service Pack 1 together with Qsys 13.0sp1 for Altera devices
  * Modelsim Altera 10.1d (only necessary for simulation of modules)
  * Vivado (Tested with Version 2016.1, 2017.3, 2017.4 and 2019.1) for Xilinx devices

===== Id and Unique_Id =====
Every subdevice has a parameter ''unique_id''. The user can assign any unique value to it. Please keep a list with these values.\\
When a flink device is later scanned and all its contained subdevices read out, every subdevice is numbered with numbers starting from 0. This number is the ''id''. A subdevice can now be selected either by its ''unique_id'' or its ''id''. \\
The ''unique_id'' is defined as a parameter when configuring the subdevice in the FPGA. On the other side, ''id'' is set at runtime when subdevices are scanned. ''id'' therefore depends on the arrangement of the subdevices in a device. ''unique_id'' can be kept constant in any arrangement. \\
An userland application should use ''unique_id'' when searching for a subdevice. This ensures that the application doesn't have to be recompiled when more subdevices are added to a FPGA design and the memory arrangement changes.

===== Info Subdevice =====
An info subdevice serves for information purposes only. It comprises the fields ''unique_id'', ''description'' and ''dev_size'' and has no channels. It can be included in any design if desired. ''dev_size'' is very handy if the interface to the FPGA doesn't allow for enumeration. In those cases the info subdevice can be queried for this field.
\\
The field ''description'' can be used to ascertain that a specific design is present in the FPGA. 
 

===== Building =====
==== Quartus ====
  - Start Quartus and create a new project. We use QuartusII Web Edition, though, newer versions work as well.
  - Choose your appropriate device.
  - Under //Device -> Device and Pin Options... -> Unused Pins// choose //As input tri-stated with weak pull-up//. Without this setting the system will not work later!
  - Start Platform Designer (formerly Qsys) and choose //Tools -> Options//. Press //Add// and choose the flink repository root path. After pressing //Finish// flink should be listed in the library section.
  - Add all your desired subdevices to your system by double clicking on the appropriate entry. Set all the necessary parameters, among them ''unique_id''. If the base clock has to be specified, you must make sure, that it reflects the actual system clock of your FPGA. Also add an interface module such as a PCI or SPI interface.
  - Add a //info subdevice// if necessary. An //info subdevice// can be very useful for reading the total memory size of the whole device as well as reading the description field. This can be used to cross check whether the right design is loaded in the FPGA.
  - Connect all the clock sinks as well as the reset sinks.
  - Connect the avalon master interface of the interface module with the avalon slave interfaces of all the other subdevices.
  - In the export column double click on the conduit part of every subdevice.
  - Choose //System->Assign Base Addresses//. Make sure that there are no empty spaces between subsequent subdevices. 
  - Select the tab //Generation Writer// on the top and choose VHDL in the Synthesis part. Save the system and click the //Generate// button.
  - Close Platform Designer and change to the //Files// tab in the project view in Quartus. Add the .qip file from the synthesis folder of the Qsys system.
  - Set the .qip file as //Top-Level-Entity//.
  - Select //Analyse and Synthesis//.
  - Open Pin Planer and designate all the necessary pins.
  - Compile the design and download it.

==== Vivado ====
  - Start Vivado and create a new project (RTL).
  - Choose your appropriate part. If you want a specific board as target, you can choose it from the tab //Boards//. If your board is not listed, you can download the Xilinx-Boards [[https://reference.digilentinc.com/reference/software/vivado/board-files?redirect=1 | here]].
  - Under //Project Manager// -> //Settings// -> //General// change target language to VHDL.
  - Under //Project Manager// -> //Settings// -> //IP// -> //Repository// add the flinkvhdl root directory.
  - In the //IP INTEGRATOR// click //Create Block Design//.
  - Add a ZYNQ7 processor system to the design and click //Run Block Automation//.
  - Double click on the processor system. In the //clock configuration// -> //PL fabric clocks// you can choose the frequency driving the AXI Interface. You should also later enter this value in your flink subdevices as baseclock. In the //PS-PL Configuration// add a //M AXI GP0 interface// if not already selected.
  - Add all desired subdevices. Add an //AXI Interconnect// device as well. 
  - Press //Run Connection Automation// to make necessary connections. If you forgot to add an //AXI Interconnect// the process will automatically add an //AXI SmartConnect//, which does not work with our components. 
  - Edit the subdevices, choose properties such as uniqueId, number of channels or base clock. If the base clock has to be specified, you must make sure, that it reflects the actual system clock of your FPGA.
  - Right click on the outputs of the subdevices and choose //Create Port//. Choose port type and vector size. Connect them to the outputs. The ports for a gpio device must be created with //create interface port// and be of type //xilinx.com:interface:gpio_rtl//.
  - Open the //Address Editor// tab and make sure that all devices have a range of 4k and that there are no gaps between two devices. Make sure that the infoDevice is on the first memory address. 
  - Add pin mapping. For specific boards you can get your .xdc-files [[https://reference.digilentinc.com/reference/programmable-logic/zybo/start | here ]].
  - Change the properties of the infoDevice as follows: //Dev Size// must be the total size of all subdevices combined. Set the description to a meaningful name.
  - Right click on your block design and select //Create HDL Wrapper// with //let Vivado manage ...//.
  - Under //PROGRAM AND DEBUG// select //Generate Bitstream//.
  - The resulting FPGA configuration file can be found under //project_name/project_name/runs/impl_1//.