OpenCores
URL https://opencores.org/ocsvn/radiohdl/radiohdl/trunk

Subversion Repositories radiohdl

Compare Revisions

  • This comparison shows the changes necessary to convert path
    /radiohdl
    from Rev 6 to Rev 7
    Reverse comparison

Rev 6 → Rev 7

/trunk/core/common_radiohdl.py
1,3 → 1,21
###############################################################################
#
# Copyright 2018 Stichting Nederlandse Wetenschappelijk Onderzoek Instituten
# ASTRON Netherlands Institute for Radio Astronomy
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
#
###############################################################################
 
import os
import inspect
/trunk/core/generate_ip_libs
55,7 → 55,7
script += 'exit $exit_code\n'
# execute script
print("compiling {} ... ".format(vhdl_file))
return_code = call(script, stdout=None, stderr=STDOUT, shell=True)
return_code = call(script, stdout=None, stderr=STDOUT, shell=True, exectuable="/bin/bash")
# qmegawiz is very sloppy with it's exitcodes. We assume 0 is OK although this not always the case. :-(
if return_code == 0:
print("*** Generation (probably) OK\n")
89,7 → 89,7
script += 'exit $exit_code\n'
# execute script
print("compiling {} ... , output-dir = {}".format(vhdl_file, outputdir))
return_code = call(script, stdout=None, stderr=STDOUT, shell=True)
return_code = call(script, stdout=None, stderr=STDOUT, shell=True, executable="/bin/bash")
if return_code == 0:
print("*** Generation OK\n")
else:
119,7 → 119,7
script += 'exit $exit_code\n'
# execute script
print("compiling {} ... ".format(tcl_file))
return_code = call(script, stdout=None, stderr=STDOUT, shell=True)
return_code = call(script, stdout=None, stderr=STDOUT, shell=True, executable="/bin/bash")
if return_code == 0:
print("*** Generation OK\n")
else:
/trunk/core/hdl_libraries_wizard.py
553,15 → 553,18
destinations = key_values[1::2]
file_io = list(zip(sources, destinations))
for fpn_io in file_io:
sourcePathName = cm.expand_file_path_name(fpn_io[0], lib_path)
destinationPath = cm.expand_file_path_name(fpn_io[1], build_dir_path)
# print("Copy '{}'' to '{}'".format(sourcePathName, destinationPath))
if isfile(sourcePathName):
file_count += 1
shutil.copy(sourcePathName, destinationPath) # copy file
else:
dir_count += 1
copy_tree(sourcePathName, destinationPath) # copy directory tree (will create new destinationPath directory)
try:
sourcePathName = cm.expand_file_path_name(fpn_io[0], lib_path)
destinationPath = cm.expand_file_path_name(fpn_io[1], build_dir_path)
# print("Copy '{}'' to '{}'".format(sourcePathName, destinationPath))
if isfile(sourcePathName):
shutil.copy(sourcePathName, destinationPath) # copy file
file_count += 1
else:
copy_tree(sourcePathName, destinationPath) # copy directory tree (will create new destinationPath directory)
dir_count += 1
except:
print("Could not copy source {} to desination {}".format(sourcePathName,destinationPath))
print("Copied {} files and {} directories for {} libraries".format(file_count, dir_count, lib_count))
 
 
/trunk/doc/HDL programmers manual.docx Cannot display: file marked as a binary type. svn:mime-type = application/octet-stream
trunk/doc/HDL programmers manual.docx Property changes : Deleted: svn:mime-type ## -1 +0,0 ## -application/octet-stream \ No newline at end of property Index: trunk/doc/HDL programmers manual.pdf =================================================================== Cannot display: file marked as a binary type. svn:mime-type = application/octet-stream Index: trunk/doc/HDL programmers manual.pdf =================================================================== --- trunk/doc/HDL programmers manual.pdf (revision 6) +++ trunk/doc/HDL programmers manual.pdf (nonexistent)
trunk/doc/HDL programmers manual.pdf Property changes : Deleted: svn:mime-type ## -1 +0,0 ## -application/octet-stream \ No newline at end of property Index: trunk/doc/HDLgear.eap =================================================================== Cannot display: file marked as a binary type. svn:mime-type = application/octet-stream Index: trunk/doc/HDLgear.eap =================================================================== --- trunk/doc/HDLgear.eap (revision 6) +++ trunk/doc/HDLgear.eap (nonexistent)
trunk/doc/HDLgear.eap Property changes : Deleted: svn:mime-type ## -1 +0,0 ## -application/octet-stream \ No newline at end of property Index: trunk/doc/HDLgear overview.pptx =================================================================== Cannot display: file marked as a binary type. svn:mime-type = application/octet-stream Index: trunk/doc/HDLgear overview.pptx =================================================================== --- trunk/doc/HDLgear overview.pptx (revision 6) +++ trunk/doc/HDLgear overview.pptx (nonexistent)
trunk/doc/HDLgear overview.pptx Property changes : Deleted: svn:mime-type ## -1 +0,0 ## -application/octet-stream \ No newline at end of property Index: trunk/doc/HDL User manual.docx =================================================================== Cannot display: file marked as a binary type. svn:mime-type = application/octet-stream Index: trunk/doc/HDL User manual.docx =================================================================== --- trunk/doc/HDL User manual.docx (revision 6) +++ trunk/doc/HDL User manual.docx (nonexistent)
trunk/doc/HDL User manual.docx Property changes : Deleted: svn:mime-type ## -1 +0,0 ## -application/octet-stream \ No newline at end of property Index: trunk/doc/HDL User manual.pdf =================================================================== Cannot display: file marked as a binary type. svn:mime-type = application/octet-stream Index: trunk/doc/HDL User manual.pdf =================================================================== --- trunk/doc/HDL User manual.pdf (revision 6) +++ trunk/doc/HDL User manual.pdf (nonexistent)
trunk/doc/HDL User manual.pdf Property changes : Deleted: svn:mime-type ## -1 +0,0 ## -application/octet-stream \ No newline at end of property Index: trunk/doc/configuration_file_classes.jpg =================================================================== Cannot display: file marked as a binary type. svn:mime-type = application/octet-stream Index: trunk/doc/configuration_file_classes.jpg =================================================================== --- trunk/doc/configuration_file_classes.jpg (nonexistent) +++ trunk/doc/configuration_file_classes.jpg (revision 7)
trunk/doc/configuration_file_classes.jpg Property changes : Added: svn:mime-type ## -0,0 +1 ## +application/octet-stream \ No newline at end of property Index: trunk/doc/hdltool_readme.txt =================================================================== --- trunk/doc/hdltool_readme.txt (revision 6) +++ trunk/doc/hdltool_readme.txt (revision 7) @@ -1,250 +1,357 @@ +Author E. Kooistra, ASTRON: +This hdltool_readme.txt is a stripped down with left over content. All removed +content is now moved and restructured in the RadioHDL markdown (*.md) +documentation. -g) Tool start scripts +Contents: -The definitions for actually running Modelsim and Quartus are not kept in the ~/.bashrc file or the setup script but are -set in a tool start script: +1) Introduction - ${RADIOHDL_GEAR}/modelsim/run_modelsim # calls set_quartus and starts the Modelsim GUI for simulation - ${RADIOHDL_GEAR}/quartus/run_quartus # calls set_quartus and starts the Quartus GUI for synthesis +2) Tool environment setup + l) UniBoard2 device family + m) Upgrading the IP for new version of Quartus or for another device family + +3) HDL environment configuration files + b) Target configuration scripts + c) hdl_buildset_.cfg key sections + +9) RadioHDL directory structure + a) applications + b) boards + c) libraries + d) software + e) tools + f) sub directories + +100) To do + b) Generate Quartus IP key + f) Improve support IP for multiple FPGA device types and Quartus tool versions + g) Improve buildset_name scheme + h) Declare IP libraries to ensure default binding in simulation. + +101) More ideas + a) zip scripts + b) support dynamic generation of IP + c) Link RadioHDL developments with the OneClick MyHDL developments. + +102) Know errors -The paths to these tool start scripts are defined in setup_radiohdl.sh. In addition to the advantages mentioned above for the environment setup scripts, -the advantages of using a seperate tool start script is: - - different versions of the tool can be started in parallel on the same machine, because the tool start script settings - only apply to the started tool environment +2) Tool environment setup +l) UniBoard2 device family +The device family of the Arria10 on UniBoard2 v0 is 10AX115U4F45I3SGES as can be seen at the photo of the FPGA: - -i) How to start Quartus for RadioHDL + $RADIOHDL/boards/uniboard2/libraries/unb2_board/quartus/unb2_board_v0_device_family.JPG -For building a SOPC system use: - > run_sopc unb1 unb1_minimal_sopc - > run_app unb1 unb1_minimal_sopc # calls: run_bsp, run_reg, run_mif - > run_app_clean unb1 unb1_minimal_sopc app=unb_osy - > run_qcomp unb1 unb1_minimal_sopc - > run_all_sopc unb1 unb1_minimal_sopc # sequentially running: run_sopc + run_app + run_qcomp - > run_rbf unb1 unb1_minimal_sopc - > run_sof unb1 unb1_minimal_sopc 0 - -For building a QSYS system use: - > run_qsys unb1 unb1_minimal_qsys - > run_sopc unb1 unb1_minimal_sopc # (normally not needed but the unb1_minimal_qsys revision has a GENERATE sopc-OR-qsys section) - > run_app unb1 unb1_minimal_qsys use=qsys - > run_qcomp unb1 unb1_minimal_qsys - > run_all_qsys unb1 unb1_minimal_qsys # sequentially running: run_qsys + run_app + run_qcomp - > run_rbf unb1 unb1_minimal_qsys - > run_sof unb1 unb1_minimal_qsys 0 +The device family is used in: +- $RADIOHDL/boards/uniboard2/libraries/unb2_board/quartus/unb2_board.qsf +- QSYS IP component files +- QSYS system design file -j) How to start Modelsim for UNB +m) Upgrading the IP for new version of Quartus or for another device family -GUI: +On 20 May 2015 Eric manually upgraded all current Arria10 IP to Quartus 15.0 and used the Qsys GUI menu view->device family to set the FPGA that is on UniBoard2 v0. +These are the current Qsys IP components for ip_arria10: - > unb_msim & # for UNB - > aaf_msim & # for AARTFAAC - > paasar_msim & # for PAASAR + kooistra@dop233 ip_arria10 $ svn status -q + M ddio/ip_arria10_ddio_in_1.qsys + M ddio/ip_arria10_ddio_out_1.qsys + M ddr4_4g_1600/ip_arria10_ddr4_4g_1600.qsys + M ddr4_8g_2400/ip_arria10_ddr4_8g_2400.qsys + M fifo/ip_arria10_fifo_dc.qsys + M fifo/ip_arria10_fifo_dc_mixed_widths.qsys + M fifo/ip_arria10_fifo_sc.qsys + M flash/asmi_parallel/ip_arria10_asmi_parallel.qsys + M flash/remote_update/ip_arria10_remote_update.qsys + M mac_10g/ip_arria10_mac_10g.qsys + M phy_10gbase_r/ip_arria10_phy_10gbase_r.qsys + M phy_10gbase_r_24/ip_arria10_phy_10gbase_r_24.qsys + M pll_clk125/ip_arria10_pll_clk125.qsys + M pll_clk200/ip_arria10_pll_clk200.qsys + M pll_clk25/ip_arria10_pll_clk25.qsys + M pll_xgmii_mac_clocks/ip_arria10_pll_xgmii_mac_clocks.qsys + M pll_xgmii_mac_clocks/pll_xgmii_mac_clocks.qsys + M ram/ip_arria10_ram_cr_cw.qsys + M ram/ip_arria10_ram_crw_crw.qsys + M ram/ip_arria10_ram_crwk_crw.qsys + M ram/ip_arria10_ram_r_w.qsys + M transceiver_phy_1/transceiver_phy_1.qsys + M transceiver_phy_48/transceiver_phy_48.qsys + M transceiver_pll/transceiver_pll.qsys + M transceiver_pll_10g/ip_arria10_transceiver_pll_10g.qsys + M transceiver_reset_controller_1/ip_arria10_transceiver_reset_controller_1.qsys + M transceiver_reset_controller_1/transceiver_reset_controller_1.qsys + M transceiver_reset_controller_24/ip_arria10_transceiver_reset_controller_24.qsys + M transceiver_reset_controller_48/ip_arria10_transceiver_reset_controller_48.qsys + M transceiver_reset_controller_48/transceiver_reset_controller_48.qsys + M tse_sgmii_gx/ip_arria10_tse_sgmii_gx.qsys + M tse_sgmii_lvds/ip_arria10_tse_sgmii_lvds.qsys -See the setup_unb.sh environment script and ASTRON_RP_1354_unb_minimal.pdf for more description. +In addition several other files need to be modified to be able to simulate the IP: + - the tech_*.vhd files that instantiate the IP component need to have the LIBRARY clause for binding + - the compile_ip.tcl files need to be updated according to the generated/sim/mentor/msim_setup.tcl + because the IP library name and file names may have changed + . the copy_hex_files.tcl files need to be updated + . the IP library name in the hdllib.cfg of the IP needs to be changed -n) How to use RadioHDL for Lofar RSP +This concerned these files: -* The Lofar Station firmware is kept in a separate SVN repository at: - - https://svn.astron.nl/Station + kooistra@dop233 trunk $ svn status -q + M libraries/technology/10gbase_r/tech_10gbase_r_arria10.vhd + M libraries/technology/ddr/tech_ddr_arria10.vhd + M libraries/technology/flash/tech_flash_asmi_parallel.vhd + M libraries/technology/flash/tech_flash_remote_update.vhd + M libraries/technology/ip_arria10/ddio/compile_ip.tcl + M libraries/technology/ip_arria10/ddr4_4g_1600/compile_ip.tcl + M libraries/technology/ip_arria10/ddr4_4g_1600/copy_hex_files.tcl + M libraries/technology/ip_arria10/ddr4_4g_1600/hdllib.cfg + M libraries/technology/ip_arria10/ddr4_8g_2400/compile_ip.tcl + M libraries/technology/ip_arria10/ddr4_8g_2400/copy_hex_files.tcl + M libraries/technology/ip_arria10/ddr4_8g_2400/hdllib.cfg + M libraries/technology/ip_arria10/flash/asmi_parallel/compile_ip.tcl + M libraries/technology/ip_arria10/flash/asmi_parallel/hdllib.cfg + M libraries/technology/ip_arria10/flash/remote_update/compile_ip.tcl + M libraries/technology/ip_arria10/flash/remote_update/hdllib.cfg + M libraries/technology/ip_arria10/mac_10g/compile_ip.tcl + M libraries/technology/ip_arria10/mac_10g/hdllib.cfg + M libraries/technology/ip_arria10/phy_10gbase_r/compile_ip.tcl + M libraries/technology/ip_arria10/phy_10gbase_r/hdllib.cfg + M libraries/technology/ip_arria10/phy_10gbase_r_24/compile_ip.tcl + M libraries/technology/ip_arria10/phy_10gbase_r_24/hdllib.cfg + M libraries/technology/ip_arria10/pll_clk125/compile_ip.tcl + M libraries/technology/ip_arria10/pll_clk125/hdllib.cfg + M libraries/technology/ip_arria10/pll_clk200/compile_ip.tcl + M libraries/technology/ip_arria10/pll_clk200/hdllib.cfg + M libraries/technology/ip_arria10/pll_clk25/compile_ip.tcl + M libraries/technology/ip_arria10/pll_clk25/hdllib.cfg + M libraries/technology/ip_arria10/pll_xgmii_mac_clocks/compile_ip.tcl + M libraries/technology/ip_arria10/pll_xgmii_mac_clocks/hdllib.cfg + M libraries/technology/ip_arria10/transceiver_pll_10g/compile_ip.tcl + M libraries/technology/ip_arria10/transceiver_pll_10g/hdllib.cfg + M libraries/technology/ip_arria10/transceiver_reset_controller_1/compile_ip.tcl + M libraries/technology/ip_arria10/transceiver_reset_controller_1/hdllib.cfg + M libraries/technology/ip_arria10/transceiver_reset_controller_24/compile_ip.tcl + M libraries/technology/ip_arria10/transceiver_reset_controller_24/hdllib.cfg + M libraries/technology/ip_arria10/tse_sgmii_gx/compile_ip.tcl + M libraries/technology/ip_arria10/tse_sgmii_gx/hdllib.cfg + M libraries/technology/ip_arria10/tse_sgmii_lvds/compile_ip.tcl + M libraries/technology/ip_arria10/tse_sgmii_lvds/hdllib.cfg + M libraries/technology/mac_10g/tech_mac_10g_arria10.vhd + M libraries/technology/pll/tech_pll_clk125.vhd + M libraries/technology/pll/tech_pll_clk200.vhd + M libraries/technology/pll/tech_pll_clk25.vhd + M libraries/technology/pll/tech_pll_xgmii_mac_clocks.vhd + M libraries/technology/technology_select_pkg.vhd + M libraries/technology/tse/tech_tse_arria10.vhd - The firmware for the RSP board is kept in: - - https://svn.astron.nl/Station/trunk/RSP - - In setup_radiohdl.sh add the path to the local SVN checkout of the Station - firmware: - - export RSP=${SVN}/../Station/trunk/RSP +Then run generate-all-ip.sh and try to simulate the test benches that verify the IP: - and add ${RADIOHDL_GEAR}/ise to the PATH environment variable. - -* To compile the Xilinx ISE10.1.03 models with Modelsim 6.6c under linux do: + - tb_eth + - tb_tr_10GbE + - tb_io_ddr - The compxlib adds the Xilinx libraries to the [libraries] section in the - /home/software/Mentor/6.6c/modeltech/modelsim.ini file. Therefore make - sure to first copy this original installation modelsim.ini file, so that - we can restore it. - - cd /home/software/modelsim_xilinx_libs/ise/10.1.03 - sudo mkdir vhdl - sudo mkdir verilog - sudo /home/software/Xilinx/ISE/10.1/ISE/bin/lin/compxlib -s mti_se -f all -l vhdl -dir vhdl -p /home/software/Mentor/6.6c/modeltech/linux_x86_64 - sudo /home/software/Xilinx/ISE/10.1/ISE/bin/lin/compxlib -s mti_se -f all -l verilog -dir verilog -p /home/software/Mentor/6.6c/modeltech/linux_x86_64 +and the try to simulate a design, eg.: - Use the library mappings in the modelsim.ini that was modified by compxlib - to create: + - unb2_minimal - tools/ise/create hdl_libraries_ip_virtex4.txt - - The modelsim_config.py using hdl_libraries_ip_virtex4.txt to map the Xilinx - library files in each HDL library project files. Therefore the central - mapping in the Modelsim installation modelsim.ini file is unwanted and not - needed. -* Create tools/hdl_buildset_rsp.cfg HDL tool configuration dictionary file for buildset 'rsp' -* Create bash scripts to start up ISE based on the buildset 'rsp' in tools/ise: - run_ise - \--> set_ise - \--> ise_version.sh - \--> ise_generic.sh - - This is similar as for other tools like Modelsim, Quartus. The advantage of - this approach is that the tool settings are only made when the tool is ran - and not in the .bashrc file. These bash scripts are kept in SVN and thus the - same tool settings are used by all engineers. +3) HDL environment configuration files -* Add 'rsp' buildset for Modelsim and ISE versions to tools/modelsim/set_modelsim. - -* To start the ISE GUI do: - > run_ise rsp & - -* To start the Modelsim GUI do: - > run_modelsim rsp & +b) Target configuration scripts + t3. verify VHDL test benches in simulation - modelsim_regression_test_vhdl.py -3) HDL environment configuration files +c) Replace SOPC avs2_eth_coe instance + +Replace in SOPC instance avs_eth_0 with avs_eth_coe by avs2_eth_coe. The eth now uses eth_pkg.vhd from +$RADIOHDL. The avs_eth_coe still uses the eth_pkg.vhd from $UNB and this causes duplicate source file +error in synthesis. Therefore open the SOPC GUI and replace the instance avs_eth_0 with avs_eth_coe by +the avs2_eth_coe component. + +Make sure that the user_component.ipx is set up oke (see point 2e), because that is needed for SOPC to +find the new avs2_eth_coe in $RADIOHDL. -d) hdl_buildset_.cfg key descriptions + +9) RadioHDL directory structure -- project_dir_depth_sim = - The project file will be located in the build dir or at some levels deeper in the build dir. - These optional extra subdirectory levels allow for relative file reference from project file - location. This is useful to be able to keep memory initialisation files in the library build - directory that are referred to using some fixed ../../ path in the HDL code. - . project_deeper_subdir = '' when project_dir_depth_ = 0 or not in tool_dict - . project_deeper_subdir = 'p/' when project_dir_depth_ = 1 - . project_deeper_subdir = 'p/p/' when project_dir_depth_ = 2, - . project_deeper_subdir = 'p/p/p/' when project_dir_depth_ = 3, etc +Currently, the RadioHDL SVN repository is contained within the UniBoard_FP7 SVN repository, at the following URL: -- project_dir_depth_synth = - Same purpose as project_dir_depth_sim, but for synthesis project file location in build tree. +https://svn.astron.nl/UniBoard_FP7/RadioHDL/trunk - +The above location might change in the future. -5) Build directory location +The following sections describe the subdirectories that exist. -The Modelsim and Quartus build location central outside the $HDL sources directory tree, whereby the -subdirectory names are defined by the corresponding keysin the hdl_buildset_.cfg: +a) applications//designs//revisions/ + /quartus + /src + /tb + libraries/ + + . Contains firmware applications designs, categorized by project. - ${RADIOHDL_BUILD_DIR}// - -eg. +b) boards/ + /uniboard2a/designs/unb2a_led/quartus + src + tb + /libraries/unb2a_board/quartus + src + tb - ${RADIOHDL_BUILD_DIR}/unb1/modelsim/common - -The advantage of the central directory build tree is that it can easily be removed (using rm -rf) and -recreated (using modelsim_config.py and quartus_config.py). For synthesis recreation of targets like sof files can take much -time though. + . Contains board-specific support files and reference/testing designs + . /designs/ + . Contains application designs that can be run on that board to test board-specific features. + . /libraries/ + . Contains board-specific support files, such as firmware modules to communicate with board-specific ICs, + constraint files, pinning files, board settings template files - +c) libraries// + base + dsp + external + io + technology/... + ip_arria10_e3sge3 + . See libraries_hierarchy_and_structure.jpg and readme_libraries.txt + . Library of reusable firmware blocks, categorized by function and in which generic functionality is separated + from technology. Within technology another seperation exists between generic technology and hardware-specific IP. + . The library_category external/ contains HDL code that was obtained from external parties (e.g. open source). + . //designs/ + . Contains reference designs to synthesize the library block for specific boards. +d) software/ + . Intended for software that runs on a PC, such as control/monitoring of boards and programs to capture and process + board output, e.g. sent via Ethernet to the processing machine. + +e) tools/ + . Contains the RadioHDL tools that are described in this readme file. + +f) sub directories +The subdirectories that reoccur contain: + + - src/vhdl : contains vhdl source code that can be synthesised + - tb/vhdl : contains vhdl source code that can is only for simulation (e.g. test benches, models, stubs) + - quartus : synthesis specific settings for design that uses Quartus and an Altera FPGA + - vivado : synthesis specific settings for design that uses Vivado and an Xilinx FPGA + - revisions : contains revisions of a design that only differ in generic settign + +The separation of src/vhdl and tb/vhdl VHDL files is not mandatory, but can be convenient. An alternative +would be to keep all VHDL in one vhdl/ sub directory. The hdl_lib_uses_synth key in hdllib.cfg typically +contains the files from src/vhdl and the hdl_lib_uses_sim key typically contains the files from tb/vhdl. +The synthesis will only see the VHDL files that are listed at the hdl_lib_uses_synth key, because the files +at the hdl_lib_uses_sim key are not needed for synthesis and could even confuse synthesis (e.g. warnings that +file IO ignored because it is not possible to synthesize). + + + 100) To do - -a) quartus_* keys and synth_top_level_entity - . The quartus_* keys are now source oriented. Instead it may be better to redefine them as target oriented. Eg. a - quartus_create_qsf key that defines to create a qsf file using the information listed in the values. - Whether a key is source oriented or target oriented depends on whether its files are used for one or more targets. - In general if a file is used for more targets then source oriented is preferred to avoid having to list the file - name twice. If a file is used only for one target then target oriented is preferred to be more clear about the - purpose of the key. - . The synth_top_level_entity enforces the creation of a qpf and qsf. This kind of hidden behavior is not so nice. - Instead it is more clear to have an explicit quartus_create_qpf and quartus_create_qsf key to define this. b) Generate Quartus IP key The generate_ip.sh scripts for generating the MegaWizard or QSYS IP components in fact are merely a wrapper script - around the qsys-generate command. The generate_ip.sh may seem an unnecessary intermediate step if the IP is - generated automatically. The IP could be generated automatically based on a megawizard key or a qsys key that - has the description file as value. However the advantage of a generate_ip.sh script is that it can hide whether the - MegaWizard or QSYS needs to be used to generate the IP, so in that way a 'quartus_generate_ip' key can fit both: + around the 'qmegawiz' and 'qsys-generate' commands. The generate_ip.sh may seem an unnecessary intermediate step if + the IP is generated automatically. The IP could be generated automatically based on a megawizard key or a qsys key + that has the description file as value. - quartus_copy_files = - generate_ip.sh - _.qsys - quartus_generate_ip = generate_ip.sh + A disadvantage of the generate_ip.sh is that currently they use a fixed selection of the buildset_name, so they do not use + the -t argument. An advantage of a generate_ip.sh script is that it can hide whether the MegaWizard or QSYS needs + to be used to generate the IP, so in that way a 'quartus_generate_ip' key can fit both. Another advantage is that + the generate_ip.sh can call 'qmegawiz' or 'qsys-generate' multiple time and with lots of arguments. Without + generate_ip.sh this would become: + + quartus_generate_ip = + qmegawiz filename and arguments + qmegawiz filename and arguments + + Which is difficult to parse, because arguments can contain spaces and all arguments then have to be on one line. + Within the cfg files only lists of values and lists of value pairs without spaces are supported. + Therefore it is better to define a *_generate_ip key per generate IP tool. This is also more clear, because it shows + in the cfg file which IP generation tool is used. + + The key values are the IP config files that need to be generated. First these IP config files need to be copied + to the build dir using quartus_copy_files. The IP generate command options are then defined by the method that + processes the qmegawiz_generate_ip or qsys_generate_ip key. The options can be complicated, but it appears that they + are the same for all IP, so it is fine to define the options hard coded in the method or by some options txt file: + + qmegawiz_generate_ip = + filename + filename + qsys_generate_ip = filename + The 'quartus_copy_files' key is used to copy the IP generation source file and the generation script to the - build directory. The 'quartus_generate_ip' key identifies the script that needs to be ran when the IP has to be - generated. Eg. a --generate_ip command line argument for quartus_config.py (rather than a separate - quartus_generate_ip.py script) can then generate the IP for all libraries that have such a key. The IP can then - be generated outside the SVN tree. The $IP_DIR path compile_ip.tcl needs to be adjusted to generated/ and the - IP then gets generated in: + build directory. - $RADIOHDL_BUILD_DIR//quartus//generated + The '*_generate_ip' key identifies the tool script that needs to be ran when the IP has to be generated. The toolscript + can be a dedicated tool script per key, e.g.: + qmegawiz_generate_ip --> qmegawiz_generate_ip.py + qsys_generate_ip --> qsys_generate_ip.py + + Eg. a + --generate_ip command line argument for quartus_config.py (rather than a separate quartus_generate_ip.py script) + can then generate the IP for all libraries that have such a key. The IP can then be generated outside the SVN tree. + The $IP_DIR path compile_ip.tcl needs to be adjusted to generated/ and the IP then gets generated in: + + $RADIOHDL_BUILD_DIR//quartus//generated + For generated IP that is kept in SVN that IP could still remain there. - The hdllib.cfg should then also define a IP toolname subdirectory in build dir, eg.: + The hdllib.cfg should then also define a IP tool name subdirectory in build dir, eg.: - // = $RADIOHDL_BUILD_DIR/qsys or - $RADIOHDL_BUILD_DIR/megawizard + $RADIOHDL_BUILD_DIR// = $HDL_BUILD_DIR/qsys or + $HDL_BUILD_DIR/megawizard or more general $RADIOHDL_BUILD_DIR/ip? The $RADIOHDL_BUILD_DIR now has a modelsim and quartus subdir: - $RADIOHDL_BUILD_DIR//modelsim -- made by modelsim_config.py using sim_tool_name from hdl_buildset_.cfg - $RADIOHDL_BUILD_DIR//quartus -- made by quartus_config.py using synth_tool_name from hdl_buildset_.cfg + $RADIOHDL_BUILD_DIR//modelsim -- made by modelsim_config.py using sim_tool_name from hdl_buildset_.cfg + $RADIOHDL_BUILD_DIR//quartus -- made by quartus_config.py using synth_tool_name from hdl_buildset_.cfg - The IP can be put in a subdir using eg 'ip_tool_name' = quartus_ip: + The IP can be put in a subdir using eg 'tool_name_ip' = quartus_ip: - $RADIOHDL_BUILD_DIR//quartus_ip -- made by quartus_config.py using a new ip_tool_name from hdl_buildset_.cfg + $RADIOHDL_BUILD_DIR//quartus_ip -- made by quartus_config.py using a new tool_name_ip from hdl_buildset_.cfg or can it be put in the synth_tool_name directory: - $RADIOHDL_BUILD_DIR//quartus + $RADIOHDL_BUILD_DIR//quartus or do we need tool_name_megawizard and tool_name_qsys to be able to create: - // + $RADIOHDL_BUILD_DIR// $RADIOHDL_BUILD_DIR/unb1/megawizard -- Altera MegaWizard $RADIOHDL_BUILD_DIR/unb1/qsys -- Altera QSYS $RADIOHDL_BUILD_DIR/unb1/coregen -- Xilinx Probably it is not so important whether the IP is generated by MegaWizard or Qsys, because that selection is - already covered by the generate_ip.sh scripts. In the hdl_buildset_.cfg both MegaWizard and Qsys can be regarded as - being part of the Quartus tool. Therefore using ip_tool_name provides sufficient distinction in IP build - sub directory. However the IP could also be generated into the synth_tool_name build directory and then even - the ip_tool_name key is not needed, because the synth_tool_name sub directory also suits the Quartus IP + already covered by the generate_ip.sh scripts. In the hdl_buildset_.cfg both MegaWizard and Qsys can be regarded as + being part of the Quartus tool. Therefore using tool_name_ip provides sufficient distinction in IP build + sub directory. However the IP could also be generated into the tool_name_synth build directory and then even + the tool_name_ip key is not needed, because the tool_name_synth sub directory also suits the Quartus IP generation. + + Assume that per IP HDL library there can only be one IP tool that generates the IP. This then implies that + it is not necessary to distinghuis between megawizard and qsys per HDL library. Conclusion: - Using synth_tool_name = quartus is also sufficient/suitable to define the build subdirectory for IP generation. - Having a dedicate ip_tool_name could be nice, to more clearly see in the build tree which libraries have IP. + - Use dedicated key per IP generation tool: + . qmegawiz_generate_ip --> generate in // + . qsys_generate_ip --> generate in // + so assume that multiple generated IP they can share the generated directory, this is defined as an + option in the method that treats the *_generate_ip key, so it could be different per IP generation tool. + - Use --generate_ip option with quartus_config.py to generate the IP. This option looks for the *_generate_ip keys + and then executes them. Default this option is not used, because it the IP only needs t obe generated once. + - Generated IP that is kept in SVN could be copied to the build dir, and then treated as if it was generated. + - The sim files of the generated IP are used by Modelsim as well, via compile_ip.tcl, it is oke that these + generated IP sim files are in the synth_tool_name dir. + - Having a dedicate tool_name_ip could be nice, to more clearly see in the build tree which libraries have IP and + to bring them at a the same level as sim_tool_name and synth_tool_name. + -c) regression test script - * For pure HDL tests the modelsim_regression_test.py script can simulate VHDL test benches that are listed at - the 'regression_test_vhdl' key and report the result. - * For Python test cases another key can be defined 'regression_test_py_hdl'. The values they may contain the entire command - to run the Python test case with the HDL test bench. Note that the pure VHDL test benches could be perphaps also be - regarded as a special case of the Python MM - VHDL tests, ie. as a test without MM. - * Another bash or Python script that synthesises a set of designs to check that they still run through synthesis ok. - -d) multiple libRootDirs for finding hdllib.cfg files - The libRootDir is now defined via a the 'lib_root_dir' key in the hdl_buildset_.cfg. - Currently hdlib.cfg files are search from one rootDir by find_all_dict_file_paths() in common_dict_file.py. It - would be usefule to be able to specify multiple rootDirs for the search path. This allows finding eg. all - hdllib.cfg in two different directory trees without having to specifiy their common higher directory root which - could be a very large tree to search through. Furthermore by being able to specify the rootDirs more precisely - avoids finding unintended hdllib.cfg files. Support for multiple rootdirs needs to be implemented in - common_dict_file.py because the results from all root dirs need to be in a common object. - -e) Python peripherals - The Python peripherals are still in the $UNB/Software/python/peripherals directory. At some time we need to move - these also to RadioHDL. The peripherals could be located central again or local in a src/python directory. A first - step can be to svn copy the $UNB/Software/python dir to ${RADIOHDL_WORK}/software/python to become independent of the - $UNB tree. An intermediate scheme is also possible whereby the periperal is kept local but copied to a central - build/python directory by means of a python_config.py script. The advantage of a central directory is that the periperals - are grouped so that only a single Python search path is needed. The disadvantage of having a fixed central - location in SVN is that peripherals that are application specific also need to be located there. Another option - may be to use a synbolic link from a central directory to each local Python peripheral. - - f) Improve support IP for multiple FPGA device types and Quartus tool versions The IP is FPGA type specific (because it needs to be defined in the Qsys source file) and tool version specific @@ -256,11 +363,11 @@ treat the both the FPGA device version id and the Quartus tool version as a new technology. For example for Arria10 we now use Quartus 15.0 and device family of UniBoard2 v0 and the IP for that is kept in: - ${RADIOHDL_WORK}/libraries/technology/ip_arria10/ + $RADIOHDL/libraries/technology/ip_arria10/ This can be renamed in: - ${RADIOHDL_WORK}/libraries/technology/ip_arria10_device_10AX115U4F45I3SGES_quartus_15.0/ + $RADIOHDL/libraries/technology/ip_arria10_device_10AX115U4F45I3SGES_quartus_15.0/ For a directory name it is allowed to use a '.' instead of a '_'. The directory name is not mandatory, but the name convention is to define the FPGA technology as a triplet: @@ -269,7 +376,7 @@ A future version of the IP can be kept in: - ${RADIOHDL_WORK}/libraries/technology/ip_arria10_device_10AX115U4F45I3SGES_quartus_16.0/ + $RADIOHDL/libraries/technology/ip_arria10_device_10AX115U4F45I3SGES_quartus_16.0/ The technology_pkg.vhd then gets; @@ -281,7 +388,7 @@ hdl_lib_technology = ip_arria10_device_10AX115U4F45I3SGES_quartus_15_0 -The hdl_buildset_.cfg can support multiple technologies eg. to be able to simulate a system with more than one FPGA that are +The hdl_buildset_.cfg can support multiple technologies eg. to be able to simulate a system with more than one FPGA that are of different technology (eg. an application with Uniboard1 and Uniboard2): technology_names = ip_stratixiv @@ -292,7 +399,7 @@ The build directory currently contains: - // + $RADIOHDL_BUILD_DIR/// This scheme is probably still sufficent to also support the FPGA technology as a triplet. However it may be necessary to rename the library key values in the IP hdllib.cfg to contain the full triplet information, so eg. @@ -305,7 +412,7 @@ hdl_lib_name = ip_arria10_device_10AX115U4F45I3SGES_quartus_15_0_fifo hdl_library_clause_name = ip_arria10_device_10AX115U4F45I3SGES_quartus_15_0_fifo_lib -this is a bit awkward. If only one Quartus version and only one device type are supported per buildset, then all these versions can keep +this is a bit awkward. If only one Quartus version and only one device type are supported per buildset_name, then all these versions can keep the same basic hdl_lib_name and hdl_library_clause_name because the IP libraries that are not used can be removed from the build. Alternatively the hdllib_config.py could support multiple technology version IP libraries that use the same logical library name and use clause. @@ -315,17 +422,14 @@ that are actually used on our board. If we make a new board with another FPGA, then we add the technology triplet for that FPGA. -g) Improve buildset scheme +g) Improve buildset_name scheme -The buildset defines the combination of Modelsim version and Quartus version. Currently there are buildsets 'unb1', 'unb2' and 'unb2a'. This -buildset scheme can be improved because: +The buildset_name defines the combination of Modelsim version and Quartus version. Currently there are buildset_names 'unb1', 'unb2' and 'unb2a'. This +buildset_name scheme can be improved because: -- for python they are defined by the hdl_buildset_.cfg, but for the run_* bash scripts they are defined in set_quartus, - can they be defined in a common source (eg. base on hdl_buildset_.cfg set an environment variable and uses that for bash). The bash - script must then be ran from the same terminal as where the python config script was used to set the environment variable, because otherwise - the environment variable is not set or may not be correct. -- the buildsets are tight to a board name 'unb1' (is that oke?) or should we use more general buildset names, or do we need a symbolic buildset names at all? -- there is also a 'site' level in the bash scripts set_quartus (is that still needed?) +- the buildset_names are tight to a board name 'unb1' (is that oke?) or should we use more general buildset_name names, or do we need a symbolic + buildset_name names at all? +- there is also a 'site' level in the bash scripts set_modelsim and set quartus (is that still needed?) h) Declare IP libraries to ensure default binding in simulation. @@ -338,9 +442,7 @@ then that if the IP library is not mapped to a directory then Modelsim will issue an error when it tries to search it. --> For now keep the 'hdl_lib_include_ip' but only use it for synthesis. For simulation the 'hdl_lib_include_ip' is ignored. Which is fine because for simulation there is no need to exclude IP libraries. - - - + 101) More ideas a) zip scripts @@ -377,4 +479,5 @@ # Time: 0 fs Iteration: 0 Instance: /tb_<...>//ip_stratixiv_phy_xaui_0_inst////// File: nofile # FATAL ERROR while loading design - Make sure that the StratixIV IP search libraries are defined by modelsim_search_libraries in the hdl_buildset_.cfg. + Make sure that the StratixIV IP search libraries are defined by modelsim_search_libraries in the hdl_buildset_.cfg. +
/trunk/doc/radiohdl_hdl_buildset_key_descriptions.md
0,0 → 1,75
# RadioHDL buildset keys
 
---
#### Document history:
|Revision|Date|Author|Affiliation|Modification|
|:---|:---|:---|:---|:---|
|1.0|27 jan 2020|E. Kooistra|ASTRON|Created, using text from hdltool_readme.txt.|
 
---
#### Contents:
1 Introduction
2 hdl_buildset keys
2.1 modelsim
2.2 quartus
 
---
#### References:
[1] radiohdl_user_guide.md
[2] radiohdl_hdl_tool_modelsim.md
[3] radiohdl_hdl_tool_quartus.md
 
---
## 1 Introduction
Each HDL project in RadioHDL has a hdl_buildset_<buildset_name>.cfg configuration file [1]. This document describes the keys that are used in the hdl_buildset_<buildset_name> configuration files.
 
The hdl_buildset configuration file can be divided into sections to group the keys that are used with a specific tool. The sections headers are identified by a [tool_name] that is defined by the *sim_tool_name* key or the *synth_tool_name* key. The [tool_name] refers to a HDL tool configuration file e.g. [2], [3].
 
---
## 2 hdl_buildset keys
 
***buildset_name***
Free to choose name that identifies this buildset. The name is used in the directory structure that is created during the several build/compile stages. It turns out the be handy to make this value equal to the name you use in the name of your hdl_buildset_<buildset_name>.cfg file.
 
***technology_names***
The technology_names key lists the IP technologies that are supported within this buildset_name, eg. ip_stratixiv, ip_arria10. It is possible to define multiple technologies. As long as your tool (e.g. Modelsim) supports these technolgies (i.e. the technology libraries are available in Modelsim) then unused technologies are not disturbing and then they also do not cause simulation load errors with the 'modelsim_search_libraries' key. RadioHDL will only build libs that are based on the technologies you define in this key. Hence the HDL libraries with a hdl_lib_technology key value that is not in the list of technology_names will not be in the build.
 
***family_names***
Lists the family(s) your FPGA belongs to. For simulation only the libs for these families are compiled.
 
***block_design_names***
Names of tools that can be used for creating block designs, e.g. for Altera this can be 'sopc', 'qsys'.
 
***project_dir_depth_sim***
The project file will be located in the build dir or at some levels deeper in the build dir. These optional extra subdirectory levels allow for relative file reference from project file location. This can be useful to be able to keep memory initialisation files in the library build directory that are referred to using some fixed ../../ path in the HDL code. This was used to support a Xilinx ISE project in hdl_buildset_rsp.cfg, which used a binary project file that contained fixed relative paths to higher directories.
- project_deeper_subdir = '' when project_dir_depth_sim = 0 (default),
- project_deeper_subdir = 'p/' when project_dir_depth_sim = 1,
- project_deeper_subdir = 'p/p/' when project_dir_depth_sim = 2,
- project_deeper_subdir = 'p/p/p/' when project_dir_depth_sim = 3, etc
 
***project_dir_depth_synth***
Same purpose as project_dir_depth_sim, but for synthesis project file location in build tree.
 
***sim_tool_name*** and ***sim_tool_version***
Name and version of simulation tool to use with this buildset. Used as subdirectory name in the build directory, e.g. modelsim, 6.6c, 10.4.Note: RadioHDL will look for a key in this config file that has the name of the value of sim_tool_name extended with '_dir'. So in this example file RadioHDL expects a key with the name modelsim_dir.
***synth_tool_name*** and ***synth_tool_version***
Name and version of synthesis tool to use with this buildset. Used as subdirectory name in the build directory, e.g. quartus, 11.1. Note: RadioHDL will look for a key in this config file that has the name of the value of sim_tool_name extended with '_dir'. So in this example file RadioHDL expects a key with the name quartus_dir.
 
***lib_root_dirs***
List of one or more root directories from where all HDL library configuration files (hdllib.cfg) are searched. There is only a single root directory for the build tree, that is defined by $RADIOHDL_BUILD_DIR.
 
### 2.1 [modelsim]
***modelsim_dir***
Path to installed version of Modelsim. Used to get the location of the modelsim.ini file, e.g. ${MENTOR_DIR}/<sim_tool_version>/modeltech. The modelsim.ini needs to be included in the mpf, because without the IEEE and STD libraries are not known anymore after the mpf is loaded.
 
***modelsim_platform***
Targeted platform subdirectory name for Modelsim. Executables like vsim, vlog and other are located here.
 
***modelsim_search_libraries***
List of IP technology search libraries that will be put in the -L {} option of a Modelsim simulation configuration in the mpf. This avoids that all IP technology needs to be compiled into the work library. The -L {} option is needed for simulations in libraries that use generated IP like ip_stratixiv_phy_xaui which do not recognize the IP technology libraries mapping in [libraries] section in the mpf. The -L {} option is added to all simulation configurations in all mpf even if they do not need it, which is fine because it does not harm and avoids the need for having to decide whether to include it or not per individual library or even per individual simulation configuration.
 
### 2.2 [quartus]
***quartus_dir***
Path to installated version of Quartus, e.g. ${ALTERA_DIR}/<synth_tool_version>.
 
/trunk/doc/radiohdl_hdl_buildset_uniboard1.md
0,0 → 1,245
# RadioHDL buildset for UniBoard1
 
---
#### Document history:
|Revision|Date|Author|Affiliation|Modification|
|:---|:---|:---|:---|:---|
|1.0|27 jan 2020|E. Kooistra|ASTRON|Created.|
 
---
#### Contents:
1 Introduction
1.1 Scope
1.2 RadioHDL commands
2 Workflow
2.1 Preconditions
2.2 Setup RadioHDL
2.2.1 Source project settings
2.2.2 Source RadioHDL settings
2.3 Check the RadioHDL configuration
2.4 Create intermediate product files and project files
2.4.1 Compile standard Altera component libraries for Modelsim simulation
2.4.2 Pre-generate custom Altera IP blocks for simulation and synthesis
2.4.3 Create project files for simulation
2.4.4 Create project files for synthesis
2.4.5 Create an IP block design for a design library in your project
2.5 Simulate the HDL project
2.6 Synthesize the HDL project
3 Appendix: hdl_buildset_unb1.cfg
 
#### References:
[1] radiohdl_user_guide.md
[2] A. Gunst, A. Szomoru, G. Schoonderbeek, E. Kooistra, D. van der Schuur, H. Pepping, "The application of UniBoard as a beam former for APERTIF", Experimental Astronomy, Volume 37, Issue 1, pp 55-67, February 2014, doi:10.1007/s10686-013-9366-x.
[3] radiohdl_hdl_tool_modelsim.md
[4] radiohdl_hdl_tool_quartus.md
[5] radiohdl_hdl_buildset_key_descriptions.md
 
---
# 1 Introduction
 
## 1.1 Scope
The RadioHDL package offers scripts to ease and speed up HDL code development. The RadioHDL User Guide describes the general concept s of RadioHDL [1]. This RadioHDL for UniBoard1 user guide describes how to use RadioHDL for developing HDL applications on UniBoard1. The UniBoard1 [2] is an electronic board with 8 Altera Stratix IV FPGAs, that was developed by ASTRON and JIVE within the RadioNET FP7 program,
 
This user guide serves as an advanced start example for other projects. It describes how RadioHDL is used for the UniBoard1 at ASTRON (2019) to develop HDL firmware from source code to working FPGA image. There is too much HDL code involved and too much dependency on vendor tools to make this example publicly available as a working example. For a publicly working example please try the quick start example from [1].
 
## 1.2 RadioHDL commands
The HDL development for UniBoard1 involves vendor tools from Mentor/Modelsim for simulation and Intel/Altera for synthesis. For this RadioHDL offers the following command line commands:
 
* **check_config** to verify dependencies between hdl_buildset and hdl_tool configuration files
* **compile_altera_simlibs** to compile standard Altera component libraries for simulation with Modelsim
* **generate_ip_libs** to pre-generate customized IP components using Altera MegaWizard or Altera QSYS
* **modelsim_config** to create project files for Modelsim simulation
* **quartus_config** to create project files for Quartus synthesis
* **run_sopc** to generate a Altera SOPC memory mapped bus with NiosII
* **run_qsys** to generate a Altera QSYS memory mapped bus with NiosII
* **run_modelsim** to start Mentor Modelsim GUI for simulation
* **run_quartus** to start Altera Quartus GUI for synthesis
* **run_qcomp** to synthesize a top level design from the command line
* **run_rbf** to create an Altera FPGA rbf file from an FPGA sof file
 
The scripts that start with 'run_' typically are bash scripts that invoke tools. The other scripts are typically Python3 scripts that manage the build directory tree and e.g. tool project files. Please see [3] and [4] for more information on how to use Modelsim and Quartus with RadioHDL. Please see [5] for hdllib.cfg configuration file examples that are used by **generate_ip_libs**, **modelsim_config** and **quartus_config**.
 
---
## 2 Workflow
 
### 2.1 Preconditions
 
RadioHDL uses Python3 and bash. Python3 is used to interpret the configuration files and to create target files, bash is used to setup and invoke tools. Install a version of:
 
- Modelsim in $MENTOR_DIR/<version id> (Modelsim version 6.6c or higher)
- Quartus in $ALTERA_DIR (version 11.1 for UniBoard1)
 
and take care of all vendor specific environment variables in your own .bashrc or local .profile file. For example Altera and Modelsim needs the key LM_LICENSE_FILE to be defined. So the .bashrc file contains the lines:
 
> export MENTOR_DIR=<path to where Mentor tool versions are installed>
> export ALTERA_DIR=<path to where Altera tool versions are installed>
> export MODELSIM_ALTERA_LIBS_DIR=<path to where Altera simulation libraries compiled with Modelsim are stored per Altera tool version>
> export LM_LICENSE_FILE=<license@our_company>
 
 
### 2.2 Setup RadioHDL
 
#### 2.2.1 Source Project settings
The UniBoard1 HDL source code is available in a source directory tree at hdl/. Setup RadioHDL development environment for a project at hdl/ using a corresponding init_hdl.sh.
 
> \> cd <path to>/hdl
> \> . ./init_hdl.sh
 
The init_hdl.sh defines:
 
- RADIOHDL_WORK directory for where the source code resides
- RADIOHDL_BUILD_DIR directory for where the targets will be build
The init_hdl.sh copies version controlled ${RADIOHDL_WORK}/hdl_user_components.ipx into the Altera dir's at $ALTERA_DIR/<tool version>/ip/altera/user_components.ipx. This Altera user_components.ipx contains the search paths that Altera SOPC builder and Altera QSYS use.
 
> **NOTE:** Altera says that you can use your personal user_components.ipx file in ~/.altera.quartus/ip/<quartus_version>/ip_search_path for this kind of additional paths but tests show that this does not work for all tools of Altera. Therefore the user_components.ipx file is copied to the Altera installation directory.
 
#### 2.2.2 Source RadioHDL settings
 
The init_hdl.sh can automatically also source init_radiohdl.sh, or source these RadioHDL settings separately:
 
> \> . <path to RadioHDL installation>/init_radiohdl.sh
 
The init_radiohdl.sh from the RadioHDL package defines:
 
- RADIOHDL_GEAR directory of where the init_radiohdl.sh is located
- RADIOHDL_BUILD_DIR = ${RADIOHDL_BUILD_DIR}/build if not already defined
- RADIOHDL_CONFIG = ${RADIOHDL_GEAR}/config if not already defined
The init_radiohdl.sh extends:
 
- PATH with ${RADIOHDL_GEAR}/core, ${RADIOHDL_GEAR}/quartus, ${RADIOHDL_GEAR}/modelsim
- PYTHONPATH with ${RADIOHDL_GEAR}/core, ${RADIOHDL_GEAR}/components
 
### 2.3 Check the RadioHDL configuration
 
The hdl_buildset_unb1.cfg defines the buildset 'unb1' for build target files for UniBoard1. Since there are some dependencies between the hdl_buildset configuration file and the hdl_tool configuration files there is a utility that checks (most) values in these files. To check the content of the file hdl_buildset_unb1.cfg and the hdl_tool_modelsim.cfg and hdl_tool_quartus.cfg files it refers to do
 
> \> check_config unb1
 
Once the configuration files are correct you can start using the RadioHDL utilities.
 
 
### 2.4 Create intermediate product files and project files
 
#### 2.4.1 Compile standard Altera component libraries for Modelsim simulation
 
This only needs to be done once when a new version of Modelsim or new version of Quartus is used.
 
> \> compile_altera_simlibs unb1
- creates build/unb1/hdl_libraries_ip_stratixiv.txt
- creates build/quartus/<tool version> simulation models of Altera components that need to be moved manually using 'mv' or 'sudo mv' to $MODELSIM_ALTERA_LIBS_DIR/<tool version>, because that is where Modelsim expects them.
 
> **NOTE:** For Modelsim versions newer than about version10 this compile_altera_simlibs script must be used and not the tools/Launch simulation library compiler in the Quartus GUI, because the libraries have to be compiled with the 'vlib -type directory' option to be able to use 'mk all' in Modelsim.
 
#### 2.4.2 Pre-generate custom Altera IP blocks for simulation and synthesis
 
The custom IP needs to be generated before it can be simulated or synthesized. To make all custom IP libraries for the 'unb1' buildset do:
 
> \> generate_ip_libs unb1
- creates build/unb1/qmegawiz/
 
> **NOTE:** The Altera tools make use of the /tmp directory intensively. Unfortunately these tools do not cleanup the files they created there. We ran into major problems when working with more than one user on the same machine:
> 1. /tmp/compute_pll_temp and /tmp must have write-access for anyone (rwxrwxrwx)
> 2. run 'rm -rf /tmp/alt* /tmp/public*' before running generate_ip_libs
 
 
#### 2.4.3 Create project files for simulation
> \> modelsim_config unb1
- creates build/unb1/modelsim/<hdllib libraries> with Modelsim project files (mpf) for simulation
- creates build/unb1/modelsim/modelsim_project_files.txt for Modelsim commands.do, that lists all HDL libraries in their hierarchical order for compilation.
- creates build/unb1/modelsim/technology_select_pkg.vhd to select stratixiv technology for UniBoard1
 
 
#### 2.4.4 Create project files for synthesis
> \> quartus_config unb1
- creates build/unb1/quartus/<hdllib libraries> with Quartus files for synthesis
- creates build/unb1/quartus/technology_select_pkg.vhd to select stratixiv technology for UniBoard1
 
The quartus_config creates the Quartus qpf, qsf for a top level design library and Quartus qip files all libraries. If a new VHDL file is added to a library or if a filename is changed, then it is necessary to rerun the quartus_config. Typically it is not necessary to do delete the entire $RADIOHDL_BUILD_DIR library of the design directory, but it can be necessary to make sure that Quartus is not 'confused' by obsolete files in that build directory. Make sure that any image files that needs to be kept are saved elsewhere, before deleting the build directory of the design library.
 
 
#### 2.4.5 Create an IP block design for a design library in your project
 
Dependent of which tool you like to use you can run run_sopc (older) or run_qsys (newer) to generate the control interface of your design.
> \> run_sopc unb1 unb1_minimal_sopc
- creates memory mapped bus block with NiosII master using Altera SOPC
 
> \> run_qsys unb1 unb1_minimal_qsys
- creates memory mapped bus block with NiosII master using Altera QSYS
 
Syntax:
 
> run_qsys <buildset> <project> [<qsysfile>]
> run_sopc <buildset> <project> [<sopcfile>]
 
Both utilities only differ in name not in functionality. The <project> is a HDL library directory that needs to exist under $RADIOHDL_BUILD_DIR/${buildset}/quartus. If no <qsysfile> respectively <sopcfile> is specified during the invocation, then the utility will look for a file with the name <project>.qsys or <project>.sopc in the project directory.
 
After generating all necessary files the utility will also build the software for the NiosII application using the RadioHDL run_app script. This run_app calls run_bsp and run_reg. The run_reg calls run_mif. For the FPGA designs on UniBoard the NiosII software application is fixed, because it implements the monitoring and control protocol interface between the 1GbE port and the memory mapped bus that is generated by SOPC or QSYS. The NiosII is the master on the memory mapped bus, and the slaves are configurable dependent on the design.
 
> **NOTE:** The sopc_builder from Altera uses Java and Java expects that it is started from an Xterm (environment DISPLAY must be set) otherwise it stops with an error.
 
 
### 2.5 Simulate the HDL project
 
To simulate test benches within the hdl project for UniBoard using the Modelsim GUI do:
 
> \> run_modelsim unb1 &
 
In simulation the entire unb1_minimal design can be simulated. The NiosII and memory mapped bus are not simulated. Instead the access to the memory mapped slaves is simulated using file IO.
 
### 2.6 Synthesize the HDL project
 
The way to start quartus is using the script **run_quartus**. This script sets up the environment variables that match the buildset and then start quartus itself. To synthesize a top level design within the hdl project for UniBoard using the Quartus GUI do:
 
> \> run_quartus unb1 &
 
To synthesize the unb1_minimal_sopc top level design from the command line do:
 
> \> run_qcomp unb1 unb1_minimal_sopc
 
To synthesize the unb1_minimal_qsys top level design from the command line do:
 
> \> run_qcomp unb1 unb1_minimal_qsys
 
The run_qcomp script can also rerun the synthesis for multiple seeds by using its --seed option. To translate the FPGA image sof file into an rbf file for use in a flash on UniBoard do:
 
> \> run_rbf unb1 unb1_minimal_sopc
> \> run_rbf unb1 unb1_minimal_qsys
 
---
## 3 Appendix: hdl_buildset_unb1.cfg
 
Buildset configuration file for Uniboard1 from $RADIOHDL_GEAR/config.
```
buildset_name = unb1
technology_names = ip_stratixiv
family_names = stratixiv
block_design_names = sopc
synth_tool_name = quartus
synth_tool_version = 11.1
sim_tool_name = modelsim
sim_tool_version = 6.6c
lib_root_dirs = ${RADIOHDL_WORK}/libraries
${RADIOHDL_WORK}/applications
${RADIOHDL_WORK}/boards
[quartus]
quartus_dir = ${ALTERA_DIR}/<synth_tool_version>
[modelsim]
modelsim_dir = ${MENTOR_DIR}/<sim_tool_version>/modeltech
modelsim_platform = linux_x86_64
modelsim_search_libraries =
# stratixiv only
altera_ver lpm_ver sgate_ver altera_mf_ver altera_lnsim_ver
stratixiv_ver stratixiv_hssi_ver stratixiv_pcie_hip_ver
altera lpm sgate altera_mf altera_lnsim stratixiv stratixiv_hssi
stratixiv_pcie_hip
```
 
/trunk/doc/radiohdl_hdl_library_key_descriptions.md
0,0 → 1,402
# RadioHDL library keys
 
---
#### Document history:
|Revision|Date|Author|Affiliation|Modification|
|:---|:---|:---|:---|:---|
|1.0|27 jan 2020|E. Kooistra|ASTRON |Created, using text from hdltool_readme.txt..|
 
---
#### Contents:
1 Introduction
2 General hdllib,cfg keys
3 Examples of hdllib.cfg configuration files
3.1 Example for a simple HDL library
3.2 Example for a HDL library that uses copies files
3.3 Example for a technology wrapper HDL library
3.4 Example for a board HDL library
3.5 Example for a board HDL top level design library
3.6 Example for a board HDL top level revision design library
3.7 Example for a HDL library for pre-generating and simulating IP
 
---
#### References:
[1] radiohdl_user_guide.md
[2] radiohdl_hdl_buildset_key_descriptions.md
[3] radiohdl_with_modelsim.md
[4] radiohdl_with_quartus.md
[5] radiohdl_hdl_buildset_uniboard1.md
 
---
## 1 Introduction
Each HDL library inRadioHDL has a hdllib.cfg file [1]. This document describes the keys that are used in the hdllib.cfg configuration files.
 
The hdllib.cfg can be divided into sections to group the keys that are used for a specific target. The sections headers are identified by a [section_name]. The first part of the hdllib.cfg has no section header and these general keys are available for all target scripts. The keys within in a section are used by a corresponding target script, for example:
 
* [modelsim_project_file] used by **modelsim_config**, described in [3]
* [quartus_project_file] used by **quartus_config**, described in [4]
 
A target script can use keys from more than one section. Future target scripts will have their own [section name] header in the hdllib.cfg. In this way the hdllib.cfg remains more organised and the keys per target are independent.
 
Keys in the hdllib.cfg can use key values from the hdl_buildset_<buildset_name>.cfg configuration file [2].
 
---
## 2 General hdllib.cfg keys
The general hdllib keys are described here.
 
***hdl_lib_name***
The name of the HDL library, e.g. unb1_minimal.
 
***hdl_library_clause_name***
The name of the HDL library as it is used in the VHDL LIBRARY clause, e.g. unb1_minimal_lib.
 
***hdl_lib_uses_synth*** (see also the other 'hdl_lib_include_*' descriptions)
List of HDL library names that are used in this HDL library for the 'synth_files', only the libraries that appear in VHDL LIBRARY clauses need to be mentioned, all lower level libraries are found automatically. The following libraries have to be declared at the 'hdl_lib_uses_synth' key:
 
- Libraries with packages that are used
- Libraries with components that are instantiated as VHDL entities
 
Libraries that are instantiated as VHDL components can be specified at the 'hdl_lib_uses_synth' key, but instead it may also be specified at the 'hdl_lib_uses_ip' key. If there are different source variants of the component and if these source libraries can be missing in the 'lib_root_dirs' tree, then the library must be specified at the 'hdl_lib_uses_ip' key.
 
***hdl_lib_uses_ip*** (See also the other 'hdl_lib_include_*' descriptions)
The 'hdl_lib_uses_ip' typically defines IP libraries that have multiple variants even within a specific technology (as specified by hdl_buildset key 'technology_names'). However typically only one technology variant of the IP is used in a design. The 'hdl_lib_include_ip' key therefore defines the library that must be included in the list of library dependencies that are derived from 'hdl_lib_uses_ip'. Hence the 'hdl_lib_uses_ip' key defines the multiple choice IP libraries that are available in this library and the 'hdl_lib_include_ip' select which one (or more) are used by a higher level component (design). For technology libraries with only one IP library variant the IP libraries should be listed at the 'hdl_lib_uses_synth' key or at both the 'hdl_lib_uses_ip' and 'hdl_lib_include_ip' key. If a multiple choice IP library can be included always, then it may also be specified at the 'hdl_lib_uses_synth'.
Typically present, but unused IP is no problem. However for synthesis the constraint files of unused IP can cause problems. Therefore then use 'hdl_lib_include_ip' to only include this IP library from the IP variants in 'hdl_lib_uses_ip'. An example is to only include ip_stratixiv_ddr3_uphy_4g_800_master in unb1_ddr3 / io_ddr / tech_ddr by setting hdl_lib_include_ip = ip_stratixiv_ddr3_uphy_4g_800_master in the hdllib.cfg of unb1_ddr3. Another example is ip_stratixiv_tse_sgmii_lvds for tech_tse which is included by the board specific library unb1_board to avoid that the other ip_stratixiv_tse_sgmii_gx variant is also included when it is not actually used. This example also shows that a 'hdl_lib_include_ip' can also occur at some intermediate hierarchical component level in a design. The advantage is that the include of ip_stratixiv_tse_sgmii_lvds in the unb1_board hdlib.cfg now automatically applies to all designs that instantiate unb1_board. The exclusion can only be done when the component is instantiated as a VHDL component and not as a VHDL entity. Therefore the exclusion is done at the IP level, because the IP is instantiated as component. Hence the exclusion works because for a component instance that is not used, only the component declaration (in the component package) needs to be known by the tools. Hence the exclusion makes use of the same VHDL component mechanism as the technology independence.The exclusion is only done for synthesis, so not for simulation. The reason is that for simulation it is oke to keep the library included.
The difference between this 'hdl_lib_uses_ip' key and the 'hdl_lib_technology' key is that the HDL libraries with 'hdl_lib_technology' key value that does not match the specified technologies are not build. Whereas HDL libraries that are excluded via the combination of 'hdl_lib_include_ip' and 'hdl_lib_uses_ip' are still created in the build directory, but they are not used for that HDL library so they are excluded dynamically.
 
***hdl_lib_uses_sim*** (see also the other 'hdl_lib_include_*' descriptions)
List of HDL library names that are used in this HDL library for the 'test_bench_files', only the libraries that appear in VHDL LIBRARY clauses need to be mentioned, all lower level libraries are found automatically.
The 'hdl_lib_uses_synth' and 'hdl_lib_uses_ip' keys and 'hdl_lib_uses_sim' key separate the dependencies due to the 'synth_files' from the extra dependencies that come from the 'test_bench_files'. Quartus can exit with error if IP is included in the 'hdl_lib_uses_ip' list of libraries, but not actually used in the design, e.g. due to an sdc constraints file that is then sourced but that cannot find some IP signals. Having a seperate 'hdl_lib_uses_ip' and 'hdl_lib_uses_sim' key solves this issue, by avoiding that libraries that are only needed for test bench simulation get included in the list for synthesis. Often the 'test_bench_files' do not depend on other libraries then those that are already mentioned at the 'hdl_lib_uses_synth' key, so then the 'hdl_lib_uses_sim' remains empty.
 
***hdl_lib_include_ip*** (see also the 'hdl_lib_include_*' descriptions)
The 'hdl_lib_uses_*' keys identify which libraries are available for that particular HDL library. For simulation they are all included. The 'hdl_lib_include_ip' identifies which IP libraries from 'hdl_lib_uses_ip' will actually be included for synthesis. The 'hdl_lib_include_ip' typically appears in another higher layer HDL library. IP libraries can be included in the following ways:
 
- by listing the IP library name at the 'hdl_lib_uses_synth' key, then it is always included
- by listing the IP library name at the 'hdl_lib_uses_ip' key, and including it explicitly with the 'hdl_lib_include_ip' key.
 
The 'hdl_lib_include_ip' is typically set at:
 
- the design library that actually uses that IP library, this then has to be done per design revision.
- for IP in unb*_board that is used in all designs it is set in these unb*_board libraries so that it is then automatically included for all designs that use the unb*_board library (i.e. via ctrl_unb*_board.vhd).
- Note that specifying an IP library at the 'hdl_lib_uses_ip' key and then including it via 'hdl_lib_include_ip' in the same hdllib.cfg, is equivalent to specifying the IP library at the 'hdl_lib_uses_synth' key.
 
***hdl_lib_disclose_library_clause_names*** (see also the 'hdl_lib_include_*' descriptions)
If a component from a library is instantiated as a VHDL component (instead of as an VHDL entity) then that means that this library may be unavailable and then it has to be listed as a pair of lib_name and library_clause_name at this 'hdl_lib_disclose_library_clause_names' key. For components that are instantiated as components the actual source library may have been removed (via the 'hdl_lib_technology' key) or it may even not be present at all. The library clause name of instantiated components is used in the VHDL code at the LIBRARY statement in e.g. a tech_*.vhd file to ensure default component binding in simulation. The 'hdl_lib_disclose_library_clause_names' key is then used in the hdllib.cfg file of that (technology) wrapper library to disclose the library clause name of the component library that is listed at the hdl_lib_uses_* key. The disclosed library will be available as an empty library, to avoid a missing library error in Modelsim.
 
***hdl_lib_technology***
The IP technology that this library is using or targets, e.g. ip_stratixiv for UniBoard1, ip_arria10 for UniBoard2. For generic HDL libraries use empty ''. For simulating systems with multiple FPGA technologies it is also possible to list multiple IP technology names.
 
***synth_files***
Lists all HDL files that are needed for synthesis. For Modelsim they need to be in compile order and they are placed in the 'synth_files' project folder. For Quartus synthesis these files get included in the HDL library qip file. Both Verilog and VHDL files are supported.
 
***test_bench_files***
List all HDL files that are needed only for simulation. These are typically test bench files, but also HDL models. For Modelsim they need to be in compile order and they are placed in the 'test_bench_files' project folder. Both Verilog and VHDL files are supported. A synthesis tool should ignore this key.
 
***regression_test_vhdl***
List of pure VHDL testbenches that need to be included in the regression simulation test. For Modelsim this key is used by modelsim_regression_test_vhdl.py to simulate all testbenches and report their result in a log. The VDHL test benches must be self-checking and self-stopping.
 
### 2.1 [section_name]
***<tool_name>_copy_files***
The copy_files key can copy one file or a directory. The first value denotes the source file or directory and the second value denotes the destination directory. The paths may use environment variables. The file path or directory can be an absolute path or a relative path. The relative path can be from hdllib.cfg location or from the build dir location. Whether the source directory is the hdllib.cfg location or the build location depends on the <tool_name>. For modelsim_copy_files [3] and quartus_copy_files [4[] the relative source directory is the hdllib.cfg location and the relative destination directory is the build location. The direction can be from build dir to hdllib.cfg location or vice versa, or to any directory location in case absolute paths are used. The destination directory will be removed if it already exists, but only if it is within in the build location. If the destination directory is not in the build location, then it first needs to be removed manually to avoid accidentally removing a directory tree that should remain.
 
---
## 3 Examples of hdllib.cfg configuration files
 
### 3.1 Example for a simple HDL library
This shows a HDL library that contains firmware code for reading out sensors via I2C. The HDL library is called 'sens' at the ***hdl_lib_name*** key and from the ***hdl_lib_uses_synth*** key it follows that it dependents on the HDL libraries 'common' and 'i2c'. In VHDL the library 'sens' is declared by 'sens_lib', as defined by the ***hdl_library_clause_name*** key. The part of the 'sens' library that can be synthesized is listed at the ***synth_files*** key. The 'sens' library has a test bench for simulation listed at the ***test_bench_files*** key. The test bench is also listed at the ***regression_test_vhdl*** key, because it is suitable for a regression test, because it is self-checking and self-stopping.
 
```
hdl_lib_name = sens
hdl_library_clause_name = sens_lib
hdl_lib_uses_synth = common i2c
hdl_lib_uses_sim =
hdl_lib_technology =
 
synth_files =
src/vhdl/sens_ctrl.vhd
src/vhdl/sens.vhd
test_bench_files =
tb/vhdl/tb_sens.vhd
regression_test_vhdl =
tb/vhdl/tb_sens.vhd
[modelsim_project_file]
 
[quartus_project_file]
 
```
 
### 3.2 Example for a HDL library that copies files
 
This fft library contains reference data that is used in the test bench to verify the HDL in simulation. This reference data is copied from the source directory tree relative to where this hdllib.cfg is located, to the modelsim/fft sub directory in the build tree. The modelsim_config will create the data/ subdirectory in the build tree if it did not exist. If the data/ directory already exists, then it will just copy the files to it. Note that it is possible to list multiple copy from-to location pairs at the ***modelsim_copy_files*** key.
 
```
hdl_lib_name = fft
hdl_library_clause_name = fft_lib
hdl_lib_uses_synth = common mm dp diag rTwoSDF st
hdl_lib_uses_sim =
hdl_lib_technology =
 
synth_files =
src/vhdl/fft_pkg.vhd
src/vhdl/fft_sepa.vhd
src/vhdl/fft_reorder_sepa_pipe.vhd
src/vhdl/fft_sepa_wide.vhd
src/vhdl/fft_r2_bf_par.vhd
src/vhdl/fft_r2_pipe.vhd
src/vhdl/fft_r2_par.vhd
src/vhdl/fft_r2_wide.vhd
src/vhdl/fft_wide_unit_control.vhd
src/vhdl/fft_wide_unit.vhd
test_bench_files =
tb/vhdl/tb_fft_pkg.vhd
tb/vhdl/tb_fft_functions.vhd
tb/vhdl/tb_fft_sepa.vhd
tb/vhdl/tb_fft_reorder_sepa_pipe.vhd
tb/vhdl/tb_fft_r2_bf_par.vhd
tb/vhdl/tb_fft_r2_pipe.vhd
tb/vhdl/tb_fft_r2_par.vhd
tb/vhdl/tb_fft_r2_wide.vhd
tb/vhdl/tb_fft_wide_unit.vhd
tb/vhdl/tb_mmf_fft_r2.vhd
tb/vhdl/tb_mmf_fft_wide_unit.vhd
tb/vhdl/tb_tb_fft_r2_pipe.vhd
tb/vhdl/tb_tb_fft_r2_par.vhd
tb/vhdl/tb_tb_fft_r2_wide.vhd
 
regression_test_vhdl =
tb/vhdl/tb_tb_fft_r2_pipe.vhd
tb/vhdl/tb_tb_fft_r2_par.vhd
tb/vhdl/tb_tb_fft_r2_wide.vhd
[modelsim_project_file]
modelsim_copy_files =
../rTwoSDF/tb/data data
tb/data data
[quartus_project_file]
```
 
### 3.3 Example for a technology wrapper HDL library
 
This tech_fifo is a HDL library that VHDL files that wrap IP generated for a FIFO. The FIFO IP for different FPGA types is kept in dedicated HDL libraries. The tech_fifo provides a technology independent interface to these IP FIFOs. Dependent on a technology selection parameter only one IP FIFO will be used. The tech_fifo.vhd does declare all IP HDL libraries at the VHDL LIBRARY clause, to ensure default binding in simulation. The LIBRARY clause is ignored by synthesis. The ***hdl_lib_disclose_library_clause_names*** is used avoid a simulation error for the IP FIFO libraries that are not selected, when the tech_fifo is used in a particular application.
 
```
hdl_lib_name = tech_fifo
hdl_library_clause_name = tech_fifo_lib
hdl_lib_uses_synth = technology ip_stratixiv_fifo ip_arria10_fifo ip_arria10_e3sge3_fifo ip_arria10_e1sg_fifo
hdl_lib_uses_sim =
hdl_lib_technology =
hdl_lib_disclose_library_clause_names =
ip_stratixiv_fifo ip_stratixiv_fifo_lib
ip_arria10_fifo ip_arria10_fifo_lib
ip_arria10_e3sge3_fifo ip_arria10_e3sge3_fifo_lib
ip_arria10_e1sg_fifo ip_arria10_e1sg_fifo_lib
synth_files =
tech_fifo_component_pkg.vhd
tech_fifo_sc.vhd
tech_fifo_dc.vhd
tech_fifo_dc_mixed_widths.vhd
test_bench_files =
regression_test_vhdl =
# no self checking tb available yet
[modelsim_project_file]
[quartus_project_file]
```
 
### 3.4 Example for a board HDL library
 
This board HDL library serves as a board support package (BSP) that can be used for all applications that run on the FPGA. Hence a top level design with only this BSP servers as a minimal design for that FPGA board. The unb1_board library shows how the ***hdl_lib_include_ip*** key is used to for example only include the ip_stratixiv_tse_sgmii_lvds IP library for the Tripple Speed Ethernet IP and not the other IP that also exists in the technology wrapper for the 1GbE IP.
 
```
hdl_lib_name = unb1_board
hdl_library_clause_name = unb1_board_lib
hdl_lib_uses_synth = common dp diag uth ppsh i2c tr_nonbonded eth remu technology tech_pll epcs
hdl_lib_uses_sim =
hdl_lib_technology = ip_stratixiv
hdl_lib_include_ip = ip_stratixiv_tse_sgmii_lvds
ip_stratixiv_pll
ip_stratixiv_pll_clk25
 
synth_files =
src/vhdl/unb1_board_pkg.vhd
src/vhdl/unb1_board_system_info.vhd
src/vhdl/unb1_board_system_info_reg.vhd
src/vhdl/mms_unb1_board_system_info.vhd
src/vhdl/unb1_board_clk_rst.vhd
src/vhdl/unb1_board_clk200_pll.vhd
src/vhdl/unb1_board_clk25_pll.vhd
src/vhdl/unb1_board_wdi_extend.vhd
src/vhdl/unb1_board_node_ctrl.vhd
src/vhdl/unb1_board_sens_ctrl.vhd
src/vhdl/unb1_board_sens.vhd
src/vhdl/unb1_board_sens_reg.vhd
src/vhdl/mms_unb1_board_sens.vhd
src/vhdl/unb1_board_wdi_reg.vhd
src/vhdl/ctrl_unb1_board.vhd
src/vhdl/unb1_board_front_io.vhd
src/vhdl/unb1_board_mesh_io.vhd
src/vhdl/unb1_board_mesh_reorder_tx.vhd
src/vhdl/unb1_board_mesh_reorder_rx.vhd
src/vhdl/unb1_board_mesh_reorder_bidir.vhd
src/vhdl/unb1_board_mesh_uth_terminals_bidir.vhd
src/vhdl/unb1_board_back_io.vhd
src/vhdl/unb1_board_back_select.vhd
src/vhdl/unb1_board_back_reorder.vhd
src/vhdl/unb1_board_back_uth_terminals_bidir.vhd
src/vhdl/unb1_board_terminals_mesh.vhd
src/vhdl/unb1_board_terminals_back.vhd
src/vhdl/unb1_board_peripherals_pkg.vhd
 
# For BN the $RADIOHDL/boards/uniboard1/designs/unb1_bn_terminal_bg/src/vhdl/node_unb1_bn_terminal_bg.vhd is referred to directly in the apertif_unb1_bn_filterbank library. For FN a copy of $RADIOHDL/boards/uniboard1/designs/unb1_fn_terminal_db/src/vhdl/node_unb1_fn_terminal_db.vhd is taken via this unb1_board library:
src/vhdl/node_unb1_fn_terminal_db.vhd
test_bench_files =
tb/vhdl/tb_unb1_board_pkg.vhd
tb/vhdl/tb_mms_unb1_board_sens.vhd
tb/vhdl/tb_unb1_board_clk200_pll.vhd
tb/vhdl/tb_unb1_board_node_ctrl.vhd
tb/vhdl/unb1_board_mesh_model_sosi.vhd
tb/vhdl/unb1_board_mesh_model_siso.vhd
tb/vhdl/unb1_board_mesh_model_sl.vhd
tb/vhdl/unb1_board_back_model_sosi.vhd
tb/vhdl/unb1_board_back_model_sl.vhd
tb/vhdl/tb_unb1_board_mesh_reorder_bidir.vhd
tb/vhdl/tb_tb_tb_unb1_board_regression.vhd
 
regression_test_vhdl =
tb/vhdl/tb_mms_unb1_board_sens.vhd
tb/vhdl/tb_unb1_board_mesh_reorder_bidir.vhd
[modelsim_project_file]
[quartus_project_file]
```
 
### 3.5 Example for a board HDL top level 'mother' design library
 
This top level 'mother' design library uses the 'unb1_board' board library to construct a design with only the Board Support Package functionality, that can serve as a minimal design that can run on the FPGA board. However this unb1_board library is not used directly, instead it is used as a 'mother' design libnrary that is used in revisions.
 
```
hdl_lib_name = unb1_minimal
hdl_library_clause_name = unb1_minimal_lib
hdl_lib_uses_synth = common mm unb1_board
hdl_lib_uses_sim =
hdl_lib_technology = ip_stratixiv
 
synth_files =
$RADIOHDL_BUILD_DIR/unb1/quartus/unb1_minimal_sopc/sopc_unb1_minimal.vhd
src/vhdl/qsys_unb1_minimal_pkg.vhd
src/vhdl/mmm_unb1_minimal.vhd
src/vhdl/unb1_minimal.vhd
test_bench_files =
tb/vhdl/tb_unb1_minimal.vhd
 
[modelsim_project_file]
modelsim_copy_files =
 
[quartus_project_file]
quartus_copy_files =
```
 
### 3.6 Example for a board HDL top level revision design library
 
This top level revision design library 'unb1_minimal_qsys' uses the 'mother' design library 'unb1_minimal' to construct a design that can be synthesized and run an FPGA of the UniBoard1 [5]. Therefore this 'unb1_minimal_qsys' HDL design library uses the [quartus_project_file] section to declare the keys that are needed to configure the synthesis.
 
```
hdl_lib_name = unb1_minimal_qsys
hdl_library_clause_name = unb1_minimal_qsys_lib
hdl_lib_uses_synth = unb1_board unb1_minimal
hdl_lib_uses_sim =
hdl_lib_technology = ip_stratixiv
synth_files =
unb1_minimal_qsys.vhd
test_bench_files =
tb_unb1_minimal_qsys.vhd
tb_unb1_minimal_qsys_stimuli.vhd
regression_test_vhdl =
tb_unb1_minimal_qsys_stimuli.vhd
[modelsim_project_file]
 
[quartus_project_file]
synth_top_level_entity =
quartus_copy_files =
../../quartus/qsys_unb1_minimal.qsys .
quartus_qsf_files =
$RADIOHDL/boards/uniboard1/libraries/unb1_board/quartus/unb1_board.qsf
quartus_sdc_files =
$RADIOHDL/boards/uniboard1/libraries/unb1_board/quartus/unb1_board.sdc
quartus_tcl_files =
../../quartus/unb1_minimal_pins.tcl
quartus_vhdl_files =
quartus_qip_files =
$HDL_BUILD_DIR/unb1/quartus/unb1_minimal_qsys/qsys_unb1_minimal/synthesis/qsys_unb1_minimal.qip
```
 
Note: With another top level revision design library called 'unb1_minimal_sopc' it is possible to synthesize the same functionality, but than using the SOPC tool instead of QSYS tool from Altera to created the IP block for the memory mapped bus with NiosII master.
 
### 3.7 Example for a HDL library for pre-generating and simulating IP
 
The ***qmegawiz_ip_files*** key in this 'ip_stratixiv_mac_10g' IP library is used by **generate_ip_libs** to know that it can pre-generate a 10GbE MAC for the strativiv FPGA. The ***modelsim_compile_ip_files*** will be used by **modelsim_config*** to include the compile_ip.tcl script when this library is compiled in Modelsim. The compile_ip.tcl refers to simualtion models for the 10GbE MAC.
 
```
hdl_lib_name = ip_stratixiv_mac_10g
hdl_library_clause_name = ip_stratixiv_mac_10g_lib
hdl_lib_uses_synth = common
hdl_lib_uses_sim =
hdl_lib_technology = ip_stratixiv
synth_files =
test_bench_files =
[modelsim_project_file]
modelsim_copy_files =
modelsim_compile_ip_files =
$RADIOHDL_WORK/libraries/technology/ip_stratixiv/mac_10g/compile_ip.tcl
[quartus_project_file]
quartus_copy_files =
quartus_vhdl_files =
ip_stratixiv_mac_10g.vhd
quartus_sdc_files =
quartus_qip_files =
ip_stratixiv_mac_10g.qip
[generate_ip_libs]
qmegawiz_ip_files =
ip_stratixiv_mac_10g.vhd
```
/trunk/doc/radiohdl_hdl_tool_modelsim.md
0,0 → 1,224
# RadioHDL tool settings for Modelsim
 
---
#### Document history:
|Revision|Date|Author|Affiliation|Modification|
|:---|:---|:---|:---|:---|
|1.0|27 jan 2020|E. Kooistra|ASTRON |Created.|
 
---
#### Contents:
1 Introduction
1.1 Preconditions
2 Creating Modelsim project files
3 Using Modelsim
3.1 Starting the Modelsim GUI
3.2 Compiling the HDL
3.3 Simulating the HDL
3.4 Developing the HDL
4 Appendix: Configuration files
4.1 hdl_tool_modelsim.cfg
4.2 hdllib.cfg keys for Modelsim
5 Appendix: hdl_tool_modelsim.cfg
 
---
#### Terminology:
 
- FPGA = Field Programmable Gate Array
- GUI = Graphical User Interface
- HDL = Hardware Description Language
- IP = Intellectual Property
- MPF = Modelsim Project File
 
---
#### References:
[1] radiohdl_user_guide.md
[2] radiohdl_hdl_library_key_descriptions.md
 
---
## 1 Introduction
The RadioHDL package consists of a set of scripts that interpret configuration files and that setup or run other tools for HDL code development [1]. This document describes how to use the following RadioHDL tools for compiling and simulating HDL code with Mentor/Modelsim:
 
* **modelsim_config** : to create Modelsim project files (mpf) for simulation of HDL code
* **run_modelsim** : to start the Modelsim GUI and make and compile HDL code in Modelsim and hierarchically add signals to the Modelsim wave window
### 1.1 Preconditions
Setup the RadioHDL environment as explained in [1].
 
The RadioHDL for Modelsim is configured using a hdl_tool_<tool_name>.cfg = hdl_tool_modelsim.cfg configuration file (see appendix), where the tool_name = modelsim is defined in a hdl_buildset_<buildset_name>.cfg configuration file. Here assume we use the quick start example from [1], so with hdl_buildset_qs.cfg and hdl_tool_modelsim.cfg. The HDL source is grouped into one or more HDL libraries that are described by hdllib.cfg configuration files.
---
## 2 Creating Modelsim project files
The binaries for Modelsim are built in a separate directory tree under $RADIOHDL_BUILD_DIR.
Use modelsim_config to create the Modelsim project files (mpf) for all your HDL libraries. In this example the quick start buildset 'qs' is used:
 
> \> modelsim_config -h
> \> modelsim_config qs
 
The modelsim_config script puts the created files and copied files in the build directory, at:
 
$RADIOHDL_BUILD_DIR/<buildset_name>/<sim_tool_name>/<hdl_lib_name>
> For 'buildset_name = qs' and 'sim_tool_name = modelsim' defined in hdl_buildset_qs.cfg this is at:
 
> $RADIOHDL_BUILD_DIR/qs/modelsim
The <hdl_lib_name> sub directories follow from the 'hdl_lib_name' key that is defined in the hdllib.cfg configuration files per HDL library. The modelsim_config script finds all hdllib.cfg files within 'lib_root_dirs = ${RADIOHDL_WORK}' that is defined in hdl_buildset_qs.cfg. The lib_root_dirs can list one or more search trees.
 
Optionally you can clear this directory before running modelsim_config because everything is recreated:
 
> \> rm -rf $RADIOHDL_BUILD_DIR/qs/modelsim
 
If the HDL library dependencies change, e.g. because a new VHDL file is added to a library, or if a filename is changed, then it is necessary to rerun the modelsim_config.
 
In addition to the Modelsim project files the modelsim_config also generates some auxiliary files that are used by commands.do in run_modelsim as quick reference to all HDL libraries. The central modelsim_project_files.txt at $RADIOHDL_BUILD_DIR/qs/modelsim/ contains a list of the paths to all HDL libraries. Per HDL library there is a <lib_name>_lib_order.txt file that contains a list of all HDL libraries that this HDL library depends on in order.
 
---
## 3 Using Modelsim
 
### 3.1 Starting the Modelsim GUI
 
To support your work inside Modelsim, RadioHDL comes with a **command.do** file that adds the following useful commands to the Modelsim Transcript command line window:
 
* lp = load project
* mk = make project
* as = add signals to the wave window
* ds = delete signals from wave window
 
To use these commands with your buildset start the Modelsim GUI with your buildset_name using run_modelsim:
 
> \> run_modelsim qs &
 
### 3.2 Compiling the HDL
First compile the dp_repack_data library and the libraries that it depends on.In the Modelsim Transcript window load Modelsim project file for HDL library dp_repack_data:
> ModelSim> lp dp_repack_data
 
Report current library:
> ModelSim> lp
 
Report all libraries in order that dp_repack_data depends on:
> ModelSim> lp all
 
Compile all libraries in order that dp_repack_data depends on:
> ModelSim> mk compile all
 
Compile only this dp_repack_data library:
> ModelSim> mk compile
 
To load another HDL library project e.g. common_pkg, do:
> ModelSim> lp common_pkg
 
Report all libraries in order that common_pkg depends on:
> ModelSim> lp all
 
Instead of 'mk compile' one can use GNU 'make' for Unix (or make.exe on Windows) and Modelsim 'vmake' via the 'mk' command from **commands.do**. The advantage is that after an initial successful compile of all, any subsequent recompiles after editing a HDL source file only will require recompilation of the HDL source files that depend on it.
 
Load Modelsim project file for HDL library dp_repack_data:
> ModelSim> lp dp_repack_data
 
Clean build directories and makefiles in $RADIOHDL_BUILD_DIR that were made for dp_repack_data:
> ModelSim> mk clean all
 
Make all libraries in order that dp_repack_data depends on and create the makefiles for those libraries:
> ModelSim> mk all
 
To make only this dp_repack_data library do:
> ModelSim> mk
 
To make only the specific common_pkg library do:
> ModelSim> mk common_pkg
 
The first time 'mk all' is called the libraries are compiled and the library makefiles are made. The library makefiles are stored in the library build directories in $RADIOHDL_BUILD_DIR. It is important that all libraries compile OK, because otherwise the library makefiles are not created properly. Therefore if a library fails to compile, then load that library project with 'lp' and keep on doing 'mk compile' until the library compiles OK. Then when it compiles OK do 'mk clean' to clear the library build directory at $RADIOHDL_BUILD_DIR, and then do 'mk' or 'mk all' to compile the library again and create a proper makefile. Repeat this process until also the top level HDL library compiles OK.
 
With the proper makefiles for all HDL libraries it is sufficient to use 'mk' to automatically recompile only the HDL source files that changed or that depend on the changed file. Similar with 'mk all' a change in some lower level library HDL file will only cause that the HDL files that depend on it will be recompiled. For a big project with many libraries using 'mk all' is much easier and faster to use than 'mk compile all'. Doing 'mk all' and again 'mk all' should show that the second 'mk all' did not need to recompile any HDL again.
 
Note that the dp_repack_data library also depends on the common_pkg library. Therefore when doing the following:
 
> ModelSim> lp common_pkg
> ModelSim> mk clean all
> ModelSim> mk all
> ModelSim> lp dp_repack_data
> ModelSim> mk all
 
Then the 'mk all' in the dp_repack_data library will not recompile the libraries that were already compiled by the 'mk all' in the common_pkg library. Similar if you clean the common_pkg library while the dp_repack_data library project is loaded:
 
> ModelSim> lp dp_repack_data
> ModelSim> mk clean common_pkg
> ModelSim> mk all
 
Then the 'mk all' in the dp_repack_data library will recompile and recreate the makefile for the common_pkg library, and then reompile the HDL files in the higher libraries (up to dp_repack_data) that directly or indirectly depend on a HDL file in the common_pkg library.
 
If a new VHDL file is added to a library or if a filename is changed, then it is necessary to rerun the modelsim_config and to do 'mk clean' on that library. It is important that Modelsim does not have that library open already, so either quit Modelsim first or 'lp' to another library first, before running modelsim_config. Typically it is not necessary to do 'mk clean all', nor is it necessary to delete the entire $RADIOHDL_BUILD_DIR library subdirectories.
 
### 3.3 Simulating the HDL
 
The simulation is done using a VHDL test bench (tb). These test bench files are made more recognizable by using the 'tb_' prefix. All HDL files that are listed at the test_bench_files key in the hdllib configuration file will have a simulation configuration icon in the Modelsim GUI. To simulate the tb_repack_data.vhd test bench in the dp_repack_data library do e.g.:
 
> ModelSim> lp dp_repack_data
> Manually load simulation by double clicking the tb_repack_data icon in the Modelsim Project window
 
Add all signals of 10 levels deep into of test bench hierarchy to the Wave Window:
> ModelSim> as 10
 
Run all until the test bench is done:
> ModelSim> run -a
 
This tb_dp_repack_data.vhd test bench is self checking and self stopping. In the Wave window the signals can be observed visually, see Figure 1.
 
 
![Figure 1](./wave_tb_dp_repack_data.jpg "wave_tb_dp_repack_data.jpg")
Figure 1: Modelsim wave window with hierarchical signals view using 'as' command
 
### 3.4 Developing the HDL
 
Edit one of the VHDL source files or for example do:
 
> \> touch $QS_DIR/cores/dp/dp_pkg/dp_stream_stimuli.vhd
 
Then in Modelsim GUI:
 
> ModelSim> mk all
> ModelSim> restart -f
> ModelSim> run -a
 
The 'mk all' will only compile the touched files and the files that depend on it. The 'restart -f' cleans the wave window but preserves the viewed signal. The 'run -a' runs the simulation.
 
The tb in the dp_repack_data library run as long as needed to apply the stimuli, and they are self checking. The tb_repack_data is instantiated into a multi test bench tb_tb_repack_data. By running this tb_tb_repack_data the entire dp_repack_data library gets verified in one simulation.
 
To change project library using 'lp <lib name>' first the current active simulation needs to be closed using 'quit -sim'. To quit Modelsim entirely, without having to acknowledge the pop up do 'quit -f'.
 
---
## 4 Appendix: configuration files
 
### 4.1 hdl_tool_modelsim.cfg
 
This appendix describes the keys that are used in the hdl_tool_modelsim configuration file that is located in $RADIOHDL_GEAR/config.
 
***model_tech_altera_lib***
Defines the path to where the compiled component libraries of a certain Quartus version are stored.
 
 
### 4.2 hdllib.cfg keys for Modelsim
 
This appendix describes the keys that are used in the [modelsim_project_file] section of the hdllib.cfg configuration file. Please see [2] for hdllib.cfg configuration file examples that use these Modelsim specific keys.
 
***modelsim_copy_files***
Copy listed all directories and files for simulation with Modelsim, used when tool_name_sim = modelsim in hdltool_<toolset>.cfg. Can be used to eg. copy wave.do or data files from the source directory to the build directory where the Modelsim project file is. For data files that are read in VHDL the path within the build directory then becomes e.g. data/<file_name>.
 
***modelsim_compile_ip_files***
This key lists one or more TCL scripts that are executed by the Modelsim mpf before it compiles the rest of the source code. E.g.:
 
- compile_ip.tcl : a TCL script that contains external IP sources that are fixed and need to be compiled before the synth_files. For the Altera IP the compile_ip.tcl is derived from the msim_setup.tcl that is generated by the MegaWizard or Qsys [2].
- copy_hex_files.tcl : a TCL script that is derived fromt yhe msim_setup.tcl and is used to copy ROM/RAM files initialization files from the generated IP directory to the simulation work directory.
- map_ip.tcl : a TCL script that maps a VHDL library name to another location (not use so far).
 
---
## 5 Appendix: hdl_tool_modelsim.cfg
 
Tool configuration file for Mentor/Modelsim from $RADIOHDL_GEAR/config.
```
# configuration file for defining the model installation on this system
model_tech_altera_lib = ${MODELSIM_ALTERA_LIBS_DIR}/${SYNTH_TOOL_VERSION}
```
 
 
/trunk/doc/radiohdl_hdl_tool_quartus.md
0,0 → 1,175
# RadioHDL tool settings for Quartus
 
---
#### Document history:
|Revision|Date|Author|Affiliation|Modification|
|:---|:---|:---|:---|:---|
|1.0|27 jan 2020|E. Kooistra|ASTRON |Created.|
 
---
#### Contents:
1 Introduction
1.1 Preconditions
1.2 Overview
2 Appendix:configuration files
2.1 hdl_tool_quartus.cfg
2.2 hdllib.cfg keys for Quartus
3 Appendix: hdl_tool_quartus.cfg
 
---
#### Terminology:
- FPGA = Field Programmable Gate Array
- HDL = Hardware Description Language
- IP = Intellectual Property
- QIP = Quartus Intellectual Property (file)
- QPF = Quartus Project File
- QSF = Quartus Setting File
 
---
#### References:
 
[1] radiohdl_user_guide.md
[2] radiohdl_hdl_buildset_uniboard1.md
[3] radiohdl_hdl_library_key_descriptions.md
 
---
## 1 Introduction
 
The RadioHDL package consists of a set of scripts that interpret configuration files and that setup or run other tools for HDL code development. This document describes how to use the RadioHDL command line tools [1] with the vendor tools from Intel/Altera.
 
### 1.1 Preconditions
 
Install a version of Quartus in $ALTERA_DIR/<version id> (version 11.1 is used for UniBoard1, but for newer boards newer Intel/.Altera tool versions have been used too).
 
Setup the RadioHDL environment as explained in [1]. The RadioHDL for Quartus is configured using a hdl_tool_<tool_name>.cfg configuration = hdl_tool_quartus.cfg file, where the tool_name = quartus is defined in a hdl_buildset_<buildset_name>.cfg configuration file. The hdl_tool_quartus.cfg is described in appendix 2.
 
### 1.2 Overview
 
The following RadioHDL tools are about preparing intermediate targets like project files and compiled or pre-generated IP:
 
* **compile_altera_simlibs** to compile fixed, standard Altera component libraries for simulation with Modelsim. For example PLL, block RAM, FIFO components.
* **generate_ip_libs** to pre-generate customized, parameterizable IP components for simulation and synthesis, using Altera MegaWizard or Altera QSYS. For example a 10GbE MAC, a DDR4 PHY controller. The custom IP is generated for HDL libraries that have a [generate_ip_libs] section with one or more <ip_tool>_ip_files keys. The supported IP tools are defined at the ip_tools key in the hdl_tool_quartus.cfg
* **quartus_config** to create Quartus project files (qpf, qsf, qip) for all HDL libraries with a hdllib.cfg. All HDL libraries withsource code that can be synthesized will get a Quartus qip file. The HDL libraries with top level design will also get a Quartus qfp and qsf file.
* **run_sopc** to generate a Altera SOPC memory mapped (MM) bus with NiosII, for an HDL library that has an sopc file
* **run_qsys** to generate a Altera QSYS memory mapped (MM) bus with NiosII, for an HDL library that has an qsys file
 
Internally **run_sopc** and **run_qsys** can also build the software that runs on the NiosII softcore processor. For this they use **run_app**, which calls **run_bsp** and **run_reg**. The **run_reg** calls **run_mif**.
 
The following tools are about synthesis and to build an image that can run on an FPGA:
 
* **run_quartus** to start Altera Quartus GUI for synthesis of an HDL library with a top level design
* **run_qcomp** to synthesize a top level design from the command line. Use option --seed to rerun the synthesis for different seeds, which can make a difference to achieve timing closure.
* **run_rbf** to create an Altera FPGA rbf file from an FPGA sof file, to boot the FPGA from flash
 
For an example of how to use these RadioHDL scripts please see how they are used for HDL firmware development for UniBoard1 [2].
 
For hdllib.cfg configuration file examples that are used by **generate_ip_libs** and **quartus_config** please see [3].
 
---
## 2 Appendix: configuration files
 
### 2.1 hdl_tool_quartus.cfg
 
This appendix describes the keys that are used in the hdl_tool_quartus configuration file that is located in $RADIOHDL_GEAR/config.
 
***quartus_rootdir***, ***quartus_rootdir_override*** and ***niosdir***
Quartus needs these three environment variables in order to operate properly. Note that you can refer to environment variables that you have defined in your buildset file.
 
***quartus_paths***
List of paths that are needed to run Quartus programs. Sometimes paths differ slightly between several versions of a tool. Just mention all paths here because paths that do not exist (for your <buildset> version) are not added to your PATH variable.
 
#### 2.1.1 [<block_design_name>]
For the tools you mentioned in the key 'block_design_names' of your hdl_buildset file you can define two keys that are automatically recognized by RadioHDL. These keys are:
 
- <block_design_name>_paths: the paths to add to your PATH variable.
- <block_design_name>_environment_variables: the environment variables this tool need. Note that the name of environment variable and de value of the environment variable are separated by a space.
 
#### 2.1.2 [ip generation]
This section defines the tools and their options that will be used for the generation of the IP libraries. Currently the generate_ip_libs executable from RadioHDL supports three generation tools: qmegawiz, qsys-generate and quartus_sh. For each of these tools you can define a key <block_design_name>_default_options that contains the default options to add to the commandline when running this tool. Options that are lib-specific are defined in the hdllib.cfg file. In those files the key <block_design_name>_extra_options can be used to add other flags/arguments to the IP compilation.
 
#### 2.1.3 [user settings]
Finally you can define paths and environment variables that are specific for you own need. The keys user_paths and user_environment_variables are recognized by RadioHDL.
 
 
### 2.2 hdllib.cfg keys for Quartus
 
This appendix describes the keys that are used in the [quartus_project_files] section of the hdllib.cfg configuration file. Please see [2] and [3] for hdllib.cfg configuration file examples that use these Quartus specific keys.
 
***quartus_copy_files***
Copy listed all directories and files for synthesis with Quartus, used when tool_name_synth = quartus in hdl_buildset_<buildset_name>.cfg. Can be used to e.g. copy SOPC or QSYS file from the hdllib.cfg location directory to the build directory where the Quartus project file is and that is where the run_* bash commands expect them to be.
 
***synth_top_level_entity***
When this key exists then a Quartus project file (QPF) and Quartus settings file (QSF) will be created for this HDL library. If this key does not exist then no QPF and QSF are created. The 'synth_top_level_entity' key specifies the top level entity in the HDL library that will be the top level for synthesis. If the key value is empty '' then the 'hdl_lib_name' is taken as top level entity name. The 'synth_top_level_entity' key in a library indicates that the library is a design library that can be synthesized to yield an FPGA image. A design library should not depend on another design library with a 'synth_top_level_entity' key, because then there may occur conflicting or double design constraints for Quartus.
 
* Created QPF:
- It only states that there is one revision that has the name of the 'synth_top_level_entity'. The Quartus scheme for revisions is not used. Instead the RadioHDL scheme of defining design revisions as separate HDL libraries is used [1].
* Created QSF:
- Defines the top level entity name using 'synth_top_level_entity'
- It sources the files listed by the 'quartus_qsf_files' key, this is typically a board qsf that defines settings that are common to all designs that target that board, eg. unb1_board.qsf.
- It sources all library QIP files <lib_name>_lib.qip that are needed by the design. The library QIP files are sourced in dependency order so that the top level design <lib_name>_lib.qip is sourced last. In this way the top level design constraints are at the end.
* Created <lib_name>_lib.qip files:
The <lib_name>_lib.qip files are created for each library using the following keys in this order:
- hdl_lib_uses_synth -- used for all HDL libraries
- quartus_vhdl_files -- used for IP libraries that have different HDL file for sim and for synth (typically not needed for most IP)
- quartus_qip_files -- used for IP libraries (constraints for the IP), top level design libraries (SOPC or QSYS MMM-bus, e.g. sopc_unb1_minimal.qip)
- quartus_tcl_files -- used for top level design libraries (pinning definitions, e.g. unb1_minimal_pins.tcl)
- quartus_sdc_files -- used for top level design libraries (timing constraints, e.g. unb1_board.sdc)
 
***quartus_qsf_files*** (see also 'synth_top_level_entity' description)
One or more .qsf files that need to be included in the HDL library qsf file for Quartus synthesis of a 'synth_top_level_entity' VHDL file.
***quartus_vhdl_files*** (see also 'synth_top_level_entity' description)
One or more .vhdl files that need to be included in the HDL library qip file for Quartus synthesis. These are VHDL files that must not be simulated, so they are not listed at the 'synth_files' key. This can typically occur for technology IP libraries where e.g. a .vhd file is used for synthesis and a .vho file for simulation like in the tse_sqmii_lvds HDL library.
 
***quartus_qip_files*** (see also 'synth_top_level_entity' description)
One or more .qip files that need to be included in the HDL library qip file for Quartus synthesis.
***quartus_tcl_files*** (see also 'synth_top_level_entity' description)
One or more .tcl files that need to be included in the HDL library qip file for Quartus synthesis.
 
***quartus_sdc_files*** (see also 'synth_top_level_entity' description)
One or more .sdc files that need to be included in the HDL library qip file for Quartus synthesis.
 
---
## 3 Appendix: hdl_tool_quartus.cfg
 
Tool configuration file for Intel/Altera Quartus from $RADIOHDL_GEAR/config.
```
# configuration file for defining the quartus installation on this system
quartus_rootdir = ${QUARTUS_DIR}/quartus
quartus_rootdir_override = ${QUARTUS_DIR}/quartus
niosdir = ${QUARTUS_DIR}/nios2eds
 
# extension to the PATH variable
quartus_paths =
<quartus_rootdir>/bin
<niosdir>/bin
<niosdir>/bin/gnu/H-i686-pc-linux-gnu/bin
<niosdir>/bin/gnu/H-x86_64-pc-linux-gnu/bin
<niosdir>/sdk2/bin
 
[sopc]
sopc_paths =
<quartus_rootdir>/sopc_builder/bin
sopc_environment_variables =
sopc_kit_nios2 <niosdir>
 
[qsys]
qsys_paths =
<quartus_rootdir>/../qsys/bin
 
[ip generation]
ip_tools = qmegawiz qsys-generate quartus_sh
qmegawiz_default_options = -silent
qsys-generate_default_options = --synthesis=VHDL --simulation=VHDL --allow-mixed-language-simulation --block-symbol-file
quartus_sh_default_options =
 
[user settings]
user_paths =
user_environment_variables =
altera_hw_tcl_keep_temp_files 1
 
#unb_compile_stamps 1
```
 
 
/trunk/doc/radiohdl_programmer_guide.md
0,0 → 1,429
# RadioHDL Gear Programmer Guide
 
### *Speed up HDL development*
 
---
#### Document history:
|Revision|Date|Author|Affiliation|Modification|
|:---|:---|:---|:---|:---|
| 0.9|18 sep 2018|R. Overeem |ASTRON|HDL programmers manual, created after refactoring the Python3 and bash code.|
| 1.0|27 jan 2020|E. Kooistra|ASTRON|Converted HDL programmers manual docx into this md file|
 
---
#### Contents:
1 Introduction
1.1 Purpose
1.2 Design principles
1.2.1 Rules for scripts and configuration files
1.2.2 Rules for keys and values
2 Handling configuration files
2.1 Base classes
2.1.1 ConfigFile
2.1.2 ConfigTree
2.2 Related classes
2.3 Unit tests
2.4 Utility modify_configfiles
2.5 Relation with old CommonDictFile
3 Initialisation of the environment
3.1 Usage of configuration file settings in a shell
3.2 set_quartus.sh and set_modelsim.sh
4 Programming principles
4.1 Shell scripts
4.1.1 Shell options
4.1.2 generic.sh
4.1.3 Parsing arguments
4.2 Python
4.2.1 Importing packages
4.2.2 Limiting export
4.2.3 Parsing arguments
 
---
#### References:
[1] radiohdl_user_guide.md
[2] radiohdl_hdl_buildset_key_descriptions.md
[3] radiohdl_hdl_buildset_uniboard1.md
[4] radiohdl_hdl_tool_modelsim.md
[5] radiohdl_hdl_tool_quartus.md
[6] radiohdl_hdl_library_key_descriptions.md
 
---
## 1 Introduction
### 1.1 Purpose
This document describes the inside gear of the RadioHDL package [1].
 
### 1.2 Design principles
Originally the RadioHDL gear consisted of Python2 and bash. The conversion to Python3 was taken as an opportunity to refactor the RadioHDL code. These design principles also apply to future updates and extensions of the RadioHDL package, see also section 4.
 
#### 1.2.1 Rules for scripts and configuration files
* Keep the shell environment as clean as possible
Therefore RadioHDL uses **init_radiohdl.sh**, to (manually) start RadioHDL in a terminal.
 
* Store all 'user tuneable' variables in configuration files instead of in scripts
This avoids too much tool knowledge in scripts and eases the maintenance of the scripts.
 
* The scripts must clearly report if they fail
For example the Python scripts give a hint of what causes the failure. Bash scripts report if they fail, instead of finishing silently.
 
* Avoid classes that can do too much
Instead Use classes that 'embed/guard' some data(structure) and provide a few functions for manipulating this data in a controlled way. This normally means that a class is very good in only one or two things. The maintenance of multiple dedicated classes is much easier, since it is very clear what each class does. This rule is applied in section 2.
 
#### 1.2.2 Rules for keys and values
* Source or target oriented keys
Whether a key is source oriented or target oriented depends on whether its files are used for one or more targets. In general if a file is used for more targets then source oriented is preferred to avoid having to list the file name twice. If a file is used only for one target then target oriented is preferred to be more clear about the purpose of the key. For example the quartus_* keys in the hdllib.cfg [5], [6] are now source oriented. Instead it may be better to redefine them as target oriented. E.g. a 'quartus_create_qsf' key that defines to create a qsf file using the information listed in the values.
 
* Avoid hidden behaviour of keys
The 'synth_top_level_entity' key in the hdllib.cfg [6] enforces the creation of a qpf and qsf. This kind of hidden behaviour is not so nice. Instead it is more clear to have an explicit 'quartus_create_qpf' and 'quartus_create_qsf' key to define this.
 
* Support new key names
Unknown key names are ignored, such that multiple tool scripts can use the same cfg file. Each tool only handles the keys that it knowns. Hence a key name will only cause an action if it is known by a tool script. Therefore key names must be predefined and can be described in a tool configuration file specification document.
 
* Support more value definitions for keys
Currently keys can have one value, a list of values or a list of pairs [1]. More value definitions could be added to the RadioHDL configuration file schema, e.g. a list of value tuples, whereby a tuple can contain more than a pair.
 
* Executing key values
An issue can be that it can be dangerous to blindly execute a key value, because it is user defined and could be a script that contains e.g. 'rm -rf ~/*'. E.g. 'quartus_tcl_files' sources a tcl script, it is left to the user to ensure that this tcl script is a legal tcl script. For shell commands blind execution of commands can be prevented by defining a dedicated key per command, such that it is impossible to execute a key value, so instead of e.g. 'ls *' the key value then become '*' and the key name itself invokes 'ls'.
 
* Section headers
Support for new tools may be added by using a dedicated [section header] in the configuration file.
 
---
## 2 Handling configuration files
The handling of the configuration files involves e.g.:
 
- represent the content of one configuration file
- represent the content of a whole hierarchical tree of configuration files
- a bulk modification tool to modify keys and/or values
 
This diverse functionality has resulted in eight classes and one interactive command line tool. Figure 1 shows the class diagram.
 
![Figure 1](./configuration_file_classes.jpg "configuration_file_classes.jpg")
Figure 1: Class diagram of the configuration file classes.
 
### 2.1 Base clases
The main functionality located in two base classes *ConfigFile* and *ConfigTree*.
 
#### 2.1.1 ConfigFile
The ConfigFile base class can read in one configuration file and store that content to an OrderedDict inside the class. This is done during the construction of the class. If the read in fails a ConfigFileException is thrown.
 
* Arguments:
- filename : full filename including the absolute path of the file
- sections : optional argument to limit the sections that are read in.
- required_keys : optional list of key names that must exist in the configuration file.
* Variables:
- filename : name of the file read in without the path.
- location : path to the file
- sections : user argument which sections should be stored.
- content : property that gives you the stored OrderedDict
- ID : unique identification of this file (defaults to location+filename)
* Functions:
- resolve_key_references()
- get_value(key, must_exist=False)
 
#### 2.1.2 ConfigTree
The ConfigTree base class implements the 'tree'-aspect of the set of configuration files. On construction it reads in a collection of ConfigFiles.
 
* Arguments:
- rootdirs : list of top directories where to search for files
- filename : name of the files to search for. Use '*' as wild-char, e.g. 'hdl_buildset_*.cfg' matches all buildset files.
- sections : optional argument to limit the sections that are read in.
* Variables:
- The three arguments are stored as class variables.
- configfiles : returns a dict containing all read in ConfigFile objects.
* Functions:
- remove_files_from_tree(files_to_remove)
- limit_tree_to(files_to_keep)
- get_key_values(key, configfiles=None, must_exist=False)
- get_configfiles(key, values=None, user_configfiles=None)
 
Note: A function ```_factory_constructor``` is used in the main loop to read in each file that matches the filename(mask) argument. The default implementation calls the ConfigFile constructor. Inhereted classes should implement their own ```_factory_constructor```.
 
### 2.2 Related classes
Three kinds of configuration files are currently used in RadioHDL [1].
 
- hdl_buildset_<buildset_name>.cfg
- hdl_tool_<tool_name>.cfg
- hdlib.cfg
 
The keys inside these files decide for which flavour a file qualifies. To implement this we created three derived classes that only implement the ID property and they call the base class constructor with their own set of required keys. In a similar way three flavour of configuration trees are implemented with three derived classes from ConfigTree that only implement their own _factory_constructor function.
 
An HDL project can have many hdllib configuration files. Therefore it is useful to be able to modify collections of files. When modifying files we like the preserve as much of the original file as possible, this includes comments and spatial layout of the file. Since ConfigFile (the only class that reads in the files) discards this kind of information this class cannot be used. Therefore there is a separate class that can read a configuration file: RawConfigFile. Together with RawConfigTree (derived from ConfigTree) it forms the base for bulk modifying configuration files, see Figure 2.
 
![Figure 2](./raw_config_classes.jpg "raw_config_classes.jpg")
Figure 2: Classes that provide access to the raw content of the configuration file to support modifications.
 
### 2.3 Unit tests
The $RADIOHDL_GEAR/core/tests directory contains unit tests to verify the working of the classes.
 
### 2.4 Utility modify_configfiles
As small interactive python program **modify_configfiles** implements a tiny menu system that enables you to execute the modification functions that the RawConfigFile class provides.
 
### 2.5 Relation with old CommonDictFile
In the initial Python2 code of RadioHDL there one large class called CommonDictFile. This class is now obsolete and replaced by the eight classes. For those who were used to work with CommonDictFile: the next table shows the new function names.
 
|Old CommonDictFile|New ConfigFile, ConfigTree, **modify_configfiles**|
|:---|:---|
|dicts() |ConfigTree.configfiles|
|nof_dicts() |len(ConfigTree.configfiles)|
|filePathNames() |ConfigTree.configfiles.keys()|
|filePaths() |iterate over ConfigTree.configfiles, useConfigFile.location|
|remove_dict_from_list(dict_to_remove) |ConfigTree.remove_files_from_tree(files_to_remove)|
|remove_all_but_the_dict_from_list(dict_to_keep) |ConfigTree.limit_tree_to(files_to_keep)|
|find_all_dict_file_paths(rootDir=None) |obsolete|
|read_all_dict_files(filePathNames=None) |obsolete|
|read_dict_file(filePathName=None) |ConfigFile(fullFileName)|
|write_dict_file(...) |interactive modify_configfiles program|
|append_key_to_dict_file(...) |interactive modify_configfiles program|
|insert_key_in_dict_file_at_line_number(...) |interactive modify_configfiles program|
|insert_key_in_dict_file_before_another_key(...) |interactive modify_configfiles program|
|remove_key_from_dict_file(...) |interactive modify_configfiles program|
|rename_key_in_dict_file(...) |interactive modify_configfiles program|
|change_key_value_in_dict_file(...) |interactive modify_configfiles program|
|resolve_key_references() |ConfigFile.resolve_key_references()|
|get_filePath(the_dict) |ConfigFile.location|
|get_filePathName(the_dict) |ConfigFile.location + '/' + ConfigFile.filename|
|get_key_values(key, dicts=None, must_exist=False)|ConfigTree.get_key_values(key, configfiles=None, must_exist=False)|
|get_key_value(key, the_dict, must_exist=False) |ConfigFile.get_value(key, must_exist=False)|
|get_dicts(key, values=None, dicts=None) |ConfigTree.get_configfiles(key, values=None, user_configfiles=None)|
 
---
## 3 Initialisation of the environment
The RadioHDL package is setup using **init_radiohdl.sh**. This **init_radiohdl.sh** keeps the shell environment as clean as possible. By not cluttering your environment with many functions (actually everything in **generic.sh**) **init_radiohdl.sh** defines only three environment variables and extends your path with the necessary paths.
 
### 3.1 Usage of configuration file settings in a shell
Using the configuration files is easy since they can be accessed through ConfigFile and ConfigTree. But the content of the configuration files should also be available for shell. The cleanest way to do this is to reuse/wrap the python code so that we don't have to reimplement the file interpretation. So we made two small python programs that read in a configuration file and print the requested information. Two other small shell scripts invoke those python scripts and execute the information that was printed by the python script.
 
![Figure 3](./sd_export_variable.jpg "sd_export_variable.jpg")
Figure 3: Example how configuration file information is made available in shell.
 
### 3.2 set_quartus.sh and set_modelsim.sh
Both scripts only use information from the hdl_buildset- and hdl_tool- configuration files.
 
---
## 4 Programming principles
This chapter describes some principles that were used for designing and writing the scripts. In general we can state that:
 
- scripts must give a syntax help message when they are invoked the wrong way or when '-h' or '--help' is given as an argument
- invocation arguments are strictly checked. Unknown arguments result in an error (and the help
message)
- the order of the invocation arguments is trivial
- everything is assumed to be fault/wrong/undefined until the opposite is proven.
 
### 4.1 Shell scripts
#### 4.1.1 Shell options
Each shell scripts starts with the line:
 
```bash
#!/bin/bash -eu
```
where
```
-e option: exit immediate on error
-u option: treat undefined variables and parameters as an error
```
The -u option helps us to find uninitialized variables but also makes it harder to use the invocation arguments: MY_VAR=$1 exits the script with an ugly error message if no arguments were used. Also trying to test the arguments like if [ "$1" == "something" ] will exit the script. However you can access a probably-undefined variable, say VARNAME with ${VARNAME:-} with triggering the -u option.
All scripts nowadays expect the buildset name to be the first argument so the following code snippet catches the undefined first argument is a proper way.
 
```bash
BUILDSET=${1:-}
if [ "${BUILDSET}" = "" ]; then
hdl_error $0 "Please specify all arguments\nUsage: $0 <buildset>"
fi
```
 
#### 4.1.2 generic.sh
One of the first lines in each script is:
```
#read generic functions
. ${RADIOHDL_GEAR}/generic.sh
```
This imports some generic functions like path_add, hdl_exec, hdl_exit, and so on. By importing this in each script the environment of the user stays clean and we import the functions only when we need them.
 
#### 4.1.3 Parsing arguments
Unlike Python, there is no out of the box argument parser for shell programming that works well. There are two flavours: **```getopts```** and **```getopt```**.
 
##### 4.1.3.1 getopts
The ```getopts``` argument parser only accepts short options like ```-e something``` or ```-v```. The major flaw of ```getopts``` however is that *options should always precede the arguments*. For example if we have a script **getopts_test.sh** like:
 
```
EXT=
VERBOSE=false
while getopts e:v option
do
case "$option" in
e) EXT=${OPTARG} ;;
v) VERBOSE=true ;;
\?) echo "OOPS"; exit 1 ;;
esac
done
shift $(($OPTIND - 1))
echo "EXT="$EXT
echo "VERBOSE="$VERBOSE
echo "POSITIONALS=$@"
```
then
```
getopts_test.sh -v -e something cats and dogs
```
will give you the correct output:
```
EXT=something
VERBOSE=true
POSITIONALS=cats and dogs
```
But
```
getopts_test.sh -v cats and dogs -e something
```
*silently* treats the -e as positional argument:
```
EXT=
VERBOSE=true
POSITIONALS=cats and dogs -e something
```
 
###### 4.1.3.2 getopt
The ```getopt``` argument parser is not picky about order of options and arguments and even also excepts long options like ```--extension=something``` or ```--verbose```. Short and long options can be mixed and are recognized by the number is minus signs. This is where it goes wrong! When the user makes a type like ```-extension=something``` (one minus instead of two) it sees short option ```-e``` with the value ```xtension=something```. With a test script **getopt_test.sh**:
 
```
EXT=
VERBOSE=false
eval set -- `getopt -o e:v --long extension:,verbose -n $0 -- "$@"`
while true ; do
case "$1" in
-e|--extension)
EXT="${2:+$2}"
shift 2
;;
-v|--verbose)
VERBOSE=true
shift
;;
--) shift ; break ;;
\?) echo "OOPS"; exit 1 ;;
*) echo "Internal error!"; exit 1 ;;
esac
done
echo "EXT="$EXT
echo "VERBOSE="$VERBOSE
echo "POSITIONALS=$@"
```
then
```
getopt_test.sh -v -e something cats and dogs
```
will give you the correct output:
```
EXT=something
VERBOSE=true
POSITIONALS=cats and dogs
```
also invocations like
```
getopt_test.sh --verbose -e something cats and dogs
getopt_test.sh -v --extension=something cats and dogs
getopt_test.sh -v cats and dogs -e something
getopt_test.sh --verbose cats and dogs --extension=something
```
will all give the correct result.
But
```
getopt_test.sh --verbose cats and dogs -extension=something
```
*silently* treats the typo of ```-extension``` and give the following result:
```
EXT=xtension=something
VERBOSE=true
POSITIONALS=cats and dogs
```
 
##### 4.1.3.3 Chosen solution
Since the two out of the box tools both have major flaws we have to make a do-it-yourself (DIY) parser. After extensive research on the internet the following solution was made that is fully correct and is as tiny as possible.
```
missing_option_argument() {
exit_with_error "Option $1 expects an argument"
}
 
exit_with_error() {
echo "$@"
cat <<@EndOfHelp@
Usage: $(basename $0) [options] arguments
Options
-e | --extension= <explain>
-v | --verbose <explain>
Arguments
<explain>
@EndOfHelp@
exit 1
}
 
POSITIONAL=()
EXT=
VERBOSE=false
while [[ $# -gt 0 ]] do
case $1 in
-e)
[ $# -lt 2 ] && missing_option_argument $1
EXT="$2" ; shift ;;
--extension=*)
EXT=${1#*=} ;;
-v|--verbose)
VERBOSE=true ;;
-h|--help)
exit_with_error "Information about the options and arguments" ;;
-*|--*)
exit_with_error "Unknown option: "$1 ;;
*)
POSITIONAL+=("$1") ;;
esac
shift
done
if [ ${#POSITIONAL[@]} -gt 0 ]; then
set -- "${POSITIONAL[@]}"
fi
echo "EXT="$EXT
echo "VERBOSE="$VERBOSE
echo "POSITIONALS=$@"
```
To give neat responses to the user when something goes wrong we defined two small functions:
 
- ```missing_option_argument()``` tells the user that a value is expected for the option and then calls the exit_with_error function.
- ```exit_with_error()``` shows the user the correct syntax of the command and exits the script with exitcode 1. Please provide useful information to the user.
 
The main loop of the parser is only slightly larger than with the out-of-the-box-with-major-flaws parsers. The main idea behind the parser loop is:
1. handle all defined options. Options without an argument can be combine in one 'case' match. For options that do need an argument we have to treat the short and the long version separate as the short version covers two arguments (no connecting '=' sign) and the long version includes the value of the option.
2. catch 'help' options
3. reject all other options
4. gather the arguments that may be anywhere in the invocation order.
 
Finally assign the collected positional arguments to $1, $2, and so on.
 
This DIY parser meets all programming principles we defined in the beginning of this chapter.
 
### 4.2 Python
#### 4.2.1 Importing packages
When you need only a few functions from a package you can better limit the import to these few functions. This keeps the 'lookup tables' of python smaller, makes the code cleaner and give insight in what you use from the packages. So instead of writing:
```
import os.path
dir_name=os.path.expandvars('RADIOHDL_GEAR')
```
write:
```
from os.path import expandvars
dir_name=expandvars('RADIOHDL_GEAR')
```
 
#### 4.2.2 Limiting export
If a source file contains both public functions/classes as well as private ones you can limit what a user will see if it imports your file by defining the __all__ variable. E.g. by adding the line:
```
__all__ = [ 'public_function_1', 'public_class_1', 'public_constant' ]
```
to your source file limits the exposure the these three entities when someone imports your file.
 
#### 4.2.3 Parsing arguments
Fortunately python has an excellent parser for arguments: ```ArgumentParser``` from the argparse package. Look on internet for the manual or look e.g. in **export_config_variables.py** how to use this parser. In short:
 
1. create an ```ArgumentParser``` instance.
2. for each argument and for each option call ```add_argument```
3. finally call ```parse_args()```
/trunk/doc/radiohdl_user_guide.md
0,0 → 1,324
# RadioHDL User Guide
 
### *Speed up HDL development*
 
---
#### Document history:
|Revision|Date|Author|Affiliation|Modification|
|:---|:---|:---|:---|:---|
|0.5|11 dec 2018|R. Overeem |ASTRON|Initial HDL user manual docx.|
|1.0|27 jan 2020|E. Kooistra|ASTRON|Created, based on HDL user manual docx and hdltool_readme.txt.|
 
---
#### Contents:
1 Introduction
2 Quick start using simulation in Modelsim
2.1 Preconditions
2.2 Setup RadioHDL
2.3 Create Modelsim Project files
2.4 Simulate the HDL test bench in Modelsim
2.5 Utilities
2.5.1 check_config
2.5.2 modify_configfiles
3 Setting up the RadioHDL environment
3.1 Environment variables
3.2 Configuration files kinds
3.2.1 hdl_buildset_<buildset_name>.cfg
3.2.2 hdl_tool_<tool_name>.cfg
3.2.3 hdllib.cfg
4 RadioHDL concepts and features
4.1 Clean enviroment
4.2 Copy files
4.3 Top level design library
4.4 Design revisions
5 Adding your own tools
5.1 New hdl_tool_<tool_name>.cfg file
5.2 New <tool_name> directory
5.3 Extend generate_ip_libs
6 Appendix: RadioHDL configuration file schema basics
 
---
#### Terminology:
 
- FPGA = Field Programmable Gate Array
- GUI = Graphical User Interface
- HDL = Hardware Description Language
- IP = Intellectual Property
- MPF = Modelsim Project File
 
---
#### References:
[1] radiohdl_hdl_buildset_key_descriptions.md
[2] radiohdl_hdl_buildset_uniboard1.md
[3] radiohdl_hdl_tool_modelsim.md
[4] radiohdl_hdl_tool_quartus.md
[5] radiohdl_hdl_library_key_descriptions.md
[6] radiohdl_programmer_guide.md
 
---
## 1 Introduction
The RadioHDL package offers tools for setting up, automating and maintaining the HDL source code, IP code and tools for programming FPGAs. The RadioHDL package consists of a set of scripts that interpret configuration files and that setup or run other tools. Currently RadioHDL supports vendor tools like Modelsim and Quartus, but other vendor tools can be added easily to the package.
 
The parameters for the HDL source libraries, the vendor IP blocks, the build tools and the target FPGA are kept in configuration files. The configuration files and source files are the inputs for the RadioHDL tools. The output is a build target that depends on which build tool is used. The build target can e.g. be a project file for Modelsim to simulate the HDL, a project file for Quartus to synthesize the HDL, a report log from a regression test that simulated the HDL. Figure 1 shows how RadioHDL fits in the build flow from source to target. The configuration files and source files are kept in one or more source directory trees that can be under version control, while the target files are built in a separate build directory tree. The RadioHDL is configured using three different kinds of configuration files:
 
- one central hdl_buildset_<buildset name>.cfg configuration file per set of FPGA technology and tools and tool versions,
- one central hdl_tool_<tool name>.cfg configuration file per vendor tool,
- multiple local hdllib.cfg configuration files, one per HDL library.
 
After setting up the configuration files for the tools and the source files, RadioHDL can create for the selected buildset all libraries for simulation, create all IP libraries, find out dependencies, generate project files and do a lot more of these labour-intensive tasks automatically.
 
![Figure 1](./radiohdl_work_flow.jpg "radiohdl_work_flow.jpg")
Figure 1: RadioHDL flow from source to target
 
The main benefit of RadioHDL is that it speeds up HDL development by providing a uniform and automated way of using tools and building code. The disadvantage of using RadioHDL is that it requires an initial effort to support a vendor tool and to maintain this support with changes in vendor tool versions. However in practice it has appeared worth the effort to use and maintain RadioHDL.
 
RadioHDL is open source, see [LICENSE.md](../LICENSE.md). The name RadioHDL reflects that it was first used for HDL development in FPGA projects for radio astronomy, see [NOTICE.md](../NOTICE.md) and [CREDITS.md](../CREDITS.md), but it can be applied for any HDL development project. This user guide focusses on how to use RadioHDL. The internal working of the RadioHDL scripts is described in the RadioHDL gear programmer guide [6].
 
---
## 2 Quick start using simulation in Modelsim
 
This quick start uses the following RadioHDL tools for Mentor/Modelsim:
 
* **modelsim_config** : to create Modelsim project files (mpf) for simulation of HDL code
* **run_modelsim** : to start the Modelsim GUI and make and compile HDL code in Modelsim and hierarchically add signals to the Modelsim wave window
 
See [1] for more detailed information on using RadioHDL with Modelsim.
See [2] for more a more advanced example of using RadioHDL with Modelsim and Quartus, so including synthesis
 
 
### 2.1 Preconditions
 
RadioHDL uses Python3 and bash. Python3 is used to interpret the configuration files nad to create target files, bash is used to setup and invoke tools.
 
Install a version of Modelsim in $MENTOR_DIR/<version id> (version 6.6c and 10.4 and Questasim have been used) and take care of all vendor specific environment variables in your own .bashrc or local .profile file. For example Altera and Modelsim needs the key LM_LICENSE_FILE to be defined. So the .bashrc file contains the lines:
 
> export MENTOR_DIR=<path to where Mentor tool versions are installed>
> export LM_LICENSE_FILE=<license1@our_company>:<license2@our_company>
 
### 2.2 Set up RadioHDL
 
Create a directory at some location $QS_DIR to store the quick start (QS) example. Copy the example init_qs.sh from the RadioHDL installation directory to $QS_DIR and download the common_pkg, dp_pkg and dp_repack_data HDL libraries from OpenCores and put them in $QS_DIR.
 
> ls
$QS_DIR/init_qs.sh
$QS_DIR/cores/common/common_pkg
$QS_DIR/cores/dp/dp_pkg
$QS_DIR/cores/dp/dp_repack_data
 
Source init_qs.sh from within $QS_DIR to set the RadioHDL environment variables RADIOHDL_WORK and RADIOHDL_BUILD_DIR for the quick start (qs) project.
 
> \> . ./init_qs.sh
 
The example hdl_buildset_qs.cfg in the RADIOHDL_GEAR/config directory of RadioHDL installation directory defines which Modelsim version should be used. The sim_tool_version key in the hdl_buildset_qs.cfg defines the subdirectory of the installation of the Modelsim simulation tool in $MENTOR_DIR. In the example hdl_buildset_qs.cfg the sim_tool_version = 6.6c, indicating that the Modelsim tool version is installed at $MENTOR_DIR/6.6c/. If necessary change this to your sim_tool_version = <version id> and $MENTOR_DIR/<version id>.
 
Source init_radiohdl.sh to create $RADIOHDL_GEAR that points to <path to where RadioHDL is installed> and to add search paths within $RADIOHDL_GEAR to $PATH and to $PYTHONPATH
 
> \> . ./<path to where RadioHDL is installed>/init_radiohdl.sh
 
Now the environment variables that are important for using RadioHDL and that are also depicted in Figure 1) have been defined.
 
### 2.3 Create Modelsim project files
 
Use RadioHDL to build Modelsim simulation project files (*.mpf) for the quick start HDL libraries
 
> \> modelsim_config qs
 
The modelsim_config script puts the created files and copied files in the build directory, at:
 
> $RADIOHDL_BUILD_DIR/qs/modelsim
 
### 2.4 Simulate the HDL test bench in Modelsim
 
Start the Modelsim simulation GUI using:
 
> \> run_modelsim qs &
 
The run_modelsim also sources a commands.do script in Modelsim that adds the following
useful Modelsim Transcript command line commands:
 
* lp = load project
* mk = make project
* as = add signals hierarchically to the wave window
* ds = delete signals from wave window
 
To compile the HDL code do in the Modelsim Transcript window:
 
> ModelSim> lp dp_repack_data
> ModelSim> mk all
 
To simulate the HDL code first double click tb_dp_repack_data icon in the Modelsim Project window to load the test bench (tb) into the simulator and then in the Modelsim Transcript window do.
 
> ModelSim> as 10
> ModelSim> run -a
 
The signals in this tb_dp_repack_data.vhd test bench can be observed visually in Modelsim Wave window, see Figure 2.
 
![Figure 2](./wave_tb_dp_repack_data.jpg "wave_tb_dp_repack_data.jpg")
Figure 2: Modelsim wave window with hierarchical signals view using 'as' command
 
### 2.5 Utilities
 
### 2.5.1 check_config
The utility **check_config** checks key-value dependencies between the hdl_buildset configuration file and the hdl_tool configuration files.
 
### 2.5.2 modify_configfiles
The utility **modify_configfiles** implements a tiny menu system that enables you to add, remove or change keys in all hdllib.cfg files of a certain buildset.
 
---
## 3 Setting up RadioHDL environment
 
### 3.1 Environment variables
 
The following environment variables are important for RadioHDL:
 
* RADIOHDL_GEAR : Points to the main directory where your checked out the RadioHDL package. This is the location where this init_radiohdl.sh file is located. Do not change this variable.
* RADIOHDL_BUILD_DIR : Points to the directory where RadioHDL will store all its result files. If this variable is not already set when init_radiohdl.sh is run, then it will be set to point to $RADIOHDL_WORK/build.
* RADIOHDL_CONFIG : Points to the directory where RadioHDL expects the hdl_buildset and hdl_tool configuration files. If this variable is not already set when init_radiohdl.sh is run, then it will be set to point to $RADIOHDL_GEAR/config.
* RADIOHDL_WORK : Points to the root directory of the your project that will use RadioHDL.
 
 
### 3.2 Configuration files kinds
 
The configuration files define key-value pairs, see the appendix for the details of the schema. There are three different kinds of configuration files in RadioHDL. The hdl_buildset configurations file and hdl_tool configuration file are central and define the global keys that hold for the whole HDL project. The hdllib configuration files define keys that apply per HDL library. The key values from the hdl_buildset configuration file can be used in the hdllib configuration files by referring to the hdl_build set key as <key name>. An HDL project in RadioHDL typically targets a certain FPGA board and has an hdl_buildset configuration file for that board. The hdl_buildset configuration file identifies the hdl_tool configuration files for the tools that are needed to build HDL and it points to the directory tree(s) that contain the HDL libraries that are needed for the HDL application(s) that can run on the FPGA board.
 
 
#### 3.2.1 hdl_buildset_<buildset_name>.cfg
 
An hdl_buildset_<buildset_name>.cfg configuration file defines the combination of FPGA type, tools, IP libraries and versions that are needed to build a target. The buildset_name is used as command line option in RadioHDL scripts to identify the buildset. The buildset_name is typically an abbreviation that identifies the target FPGA board hardware and a version, e.g. 'unb1' for a version 1 of an FPGA board called 'UniBoard'. If the same board is used, but with another set of tool versions, then that could be identified by e.g. 'unb1_a' and have a buildset file called hdl_buildset_unb1_a.cfg. The hdl_buildset configuration files are kept centrally at $RADIOHDL_CONFIG. To structure the hdl_buildset configuration file it can be divided into sections that group keys per included tool. The section headers are identified between square brackets [tool_name]
#### 3.2.2 hdl_tool_<tool_name>.cfg
 
RadioHDL looks for '*_tool_name' keys in the hdl_buildset configuration file to find the tool names that the buildset uses for e.g. simulation and synthesis. In this way RadioHDL knows which hdl_tool_<tool_name> configuration file it needs to use to setup these tools. Typically there is one tool configuration file that covers multiple versions of that tool. The hdl_tool configuration files are kept centrally at $RADIOHDL_CONFIG.
 
Although most keys in a hdl_tool configuration file are tool specific, there are some keys RadioHDL will always search for in a hdl_tool configuration file. RadioHDL will always search for keys ending in '_paths' and '_environment_variables' for keys that begin with:
 
- the tool_name of that hdl_tool configuration file (e.g. quartus_paths and quartus_environment_variables)
- the block_design_names you mentioned in your hdl_buildset configuration file (e.g. sopc, qsys)
- the word 'user', so you can always add your own paths and environment variables with the keys user_paths and user_environment_variables.
#### 3.2.3 hdllib.cfg
 
The HDL code is organised in one or more (can be many) HDL libraries. Each HDL Library has a local hdllib.cfg configuration file that defines the sources and supported tools. All HDL files are grouped into libraries. The rule is that each HDL file is compiled in only one HDL library. If a component is used in another library, then it is instantiated in VHDL using <hdl_library_clause_name>.<entity name>, where the hdl_library_clause_name is defined in the hdllib.cfg. Although the creation of these hdllib.cfg files may take some time, you will definitely save time on the long run. An HDL library can define a:
 
* module library with HDL that is reused in other libraries
* top level library with a top level entity that maps on the IO of the FPGA.
 
For RadioHDL there is no difference in HDL libraries. A top level library that is used for synthesis has a synth_top_level_entity key. RadioHDL search for all hdllib.cfg files in the directory tree(s) that are specified by the lib_root_dirs key in the hdl_buildset configuration file. Typically the hdllib configuration points to sources that are located in the same directory as where the hdllib.cfg is located or in its sub directories, however relative or absolute paths to sources elsewhere are also allowed.
 
The hdllib can distinguish between source HDL that can be synthesized (at synth_files key), HDL code that is used only in test benches for simulation (at test_bench_files key) and test benches that are selected to be part of a simulation regression test (at regression_test_vhdl key)..
 
The hdllib.cfg files are used by many utilities from the RadioHDL package. To structure the hdllib.cfg file, it can be divided into sections that group keys that are used for a specific target. The section headers are identified between square brackets [target_name]. The first part of an hdllib.cfg file has no section header as these keys are available for all target scripts. The keys within a section are applicable to the corresponding tool script. For example:
 
- section [modelsim_project_file] contains key-value pairs for modelsim_config
- section [quartus_project_file] contains key-value pairs for quartus_config
- section [generate_ip_libs] contains key-value pairs for generate_ip_libs
 
Future target scripts can have their own [target_name] header in the hdllib.cfg to keep the files more organised.
 
---
## 4 RadioHDL concepts and features
 
### 4.1 Clean environment
 
The RadioHDL settings are only active in the terminal where RadioHDL was started. Therefore it is possible to run different buildsets in different terminals on the same machine. When the terminal is closed, then also all RadioHDL settings vanish as well.
 
### 4.2 Copy files
 
RadioHDL has <tool_name>_copy_files keys that can be used to copy files from the source directory tree to anywhere in the build directory tree. The file may also be copied to multiple locations in the build tree. This can be useful if different tools need the same source file, but at different locations.
 
A file may also be copied to another file. This can be useful to keep several variants of a file in the source tree, but only use one variant with a fixed filename in the build tree. The hdllib.cfg configuration can then refer to the file in the build tree.
 
### 4.3 Top level design library
 
A synth_top_level_entity key in the hdllib.cfg of an HDL library indicates that the HDL library is a design library that can be synthesized to yield an FPGA image. A design library should not depend on another design library, because then there may occur conflicting or double design constraints for Quartus. Therefore it is not advised to directly use VHDL from a design library in other libraries. A proper solution is to put these VHDL files in a separate library and then use them from that library. Another solution (i.e. work around) is to break the rule that an HDL file should only be compiled once in one library and then also compile it in the design library that needs to reuse it.
 
### 4.4 Design revisions
 
A design in this context is a top level entity in a HDL library that can be synthesized to create a FPGA image that can run on an FPGA. Within a design, several design revisions can be made that all use the same HDL source code from the base design, but with different generic settings at the top level entity. To keep these design revisions separate, add a directory 'revisions/' in the base design directory, which contains a list of subdirectories. Each subdirectory is a revision. The base design 'unb1_minimal' can be uses as an example:
 
> designs/unb1_minimal/hdllib.cfg
> designs/unb1_minimal/revisions/unb1_minimal_sopc/hdllib.cfg
> designs/unb1_minimal/revisions/unb1_minimal_qsys/hdllib.cfg
 
The base design library unb1_minimal/hdllib.cfg contains the source code. Each design revision library also has a hdllib.cfg file and a top level VHDL file that wraps the top level VHDL file from unb1_minimal. The wrapper file makes the generic settings for the specific revision. In addition it is useful to specify a 'g_design_name' generic that can be used to store a string in the FPGA that can be read out to know which design revision runs on the FPGA. In this example for UniBoard1 the 'g_design_name' for the revisions is 'unb1_minimal_qsys' or 'unb1_minimal_qsys'.
 
When a design library has revisions, then the base library should not include keys for synthesis. Instead the synthesis is only done for the revisions. The base library contains all the VHDL source files. The revision hdllib.cfg should not refer to these base library VHDL files (i.e. using a relative path via ../../), but instead it should instantiate the top level base entity using the base design library name. This to follow the rule that a HDL file is only compiled in one HDL library.
 
---
## 5 Adding your own tools
 
The RadioHDL package as described in this user guide is based on the tools Modelsim and Quartus. If you are using the same tools, then everything should work in your environment after you checked/modified the configuration files in $RADIOHDL_CONFIG. But what if you are using others tool like e.g. Xilinx Vivado? In that case you have to create some new configuration files, some directories and (unfortunately) extend one script. This chapter guides you through this process.
 
### 5.1 New hdl_tool_<tool_name>.cfg file
 
Assume you want to add Vivado to RadioHDL, then create in $RADIOHDL_CONFIG a file named hdl_tool_vivado.cfg and put in that file Vivado specific paths and environment variables. There are no required keys in configuration files of the type hdl_tool, so you are free to choose your own key names. Note: the script you create in the following section uses the definitions you create in the hdl_tool file.
 
### 5.2 New <tool_name> directory
 
Every tool has its own directory in $RADIOHDL_GEAR. In this directory we expect a script named set_<tool_name> to be present, that accepts the buildset_name as an argument. That script sets up the whole environment, so that the tool can be used, e.g. extend paths, setup environment variables, etc. Look in e.g. set_modelsim and set_quartus how to get access to the information that is stored in your configuration files in the $RADIOHDL_CONFIG. So to add e.g. to add Vivado:
 
- create a directory $RADIOHDL_GEAR/vivado
- inside this directory make a script set_vivado that sets up the Vivado environment using the information that is configured in the hdl_buildset and hdl_tool files.
 
### 5.3 Extend generate_ip_libs
 
Currently generate_ip_libs supports three IP generation tools from Altera: qmegawiz, qsys-generate and quartus_sh. These IP tools are configured in the hdl_tool_quartus.cfg file (key ip_tools) and implemented as special functions in generate_ip_libs. If you need different IP generation tools you should add them to the ip_tools key and add an extra function in generate_ip_libs. This generate_ip_libs script is the one place (left) where tool specific code is part of a RadioHDL script. In a future release of RadioHDL this should be solved in a more generic way, but for now you have to add a function to generate_ip_libs, when you are using a tool other than qmegawiz, qsys-generate or quartus_sh for creating your IP libraries.
 
The main flow of generate_ip_libs is:
 
- read the hdl_buildset file of the buildset you started the program with.
- search for hdllib.cfg files in all directories mentioned in the key lib_root_dirs
- read the hdl_tool_<tool_name>.cfg file where tool_name is the value of the key synth_tool_name in your buildset file.
- read the value of the key ip_tools in this hdl_tool file which is a list of tools you use for creating the IP libraries. Each of these ip_tools have their own <ip_tool>_default_options key to configure the default options of that command.
- finally it loops over all buildset.technology_names, all tool.ip_tools and all hdllibs that where read in, to see if there is a match in technology and ip_tool with the information in the hdllibs.
- for each match found in these nested loops it calls a function called run_<ip_tool_name> that is part of the generate_ip_libs program.
 
So if you are using other ip_tools then the three mentioned above you have to add a run_<your_ip_tool> function to generate_ip_libs and extend the if-then-else construction in the main loop with a call to that function. And you have to setup your configuration files in the right way of course. Take a look at the other run_ functions in generate_ip_libs for what to implement. Basically it constructs a shell script that runs the IP tool and analyses the exit-code of the execution. No rocket science.
 
---
## 6 Appendix: RadioHDL configuration file schema basics
 
A RadioHDL configuration file is a collection of key-value pairs. Key and value are separated with the assignment char '='. Everything after (and including) a '#' char till the end of the line is treated as comment and is skipped in the interpretation of the files.
```
this_is_a_key = and this is the value # except for this comment.
```
The files can be divided into sections. A section marker is a line that starts with '[', contains a string and ends with ']'. Sections can be used to group keys that are only used by certain tool scripts and may be ignored by other tool scripts. Key names in different sections must still be unique in the entire configuration file.
```
[start of a new section]
key = value
```
To make the files easier to read and maintain for humans each value can be defined in more than one line where spacing is trivial. This makes is easy to define values that consist of more than one item. Actually, the concept of 'value' is implemented as 'being everything between the assignment char and the start of the next key or the start of a section. Newline characters are translated into a single space.
```
invitationlist = John & Marry,
Robert,
Sandra and Naomi,
```
This is equivalent with:
```
invitationlist = John & Marry, Robert, Sandra and Naomi,
```
You can use environment variables in values:
```
lib_root_dirs = ${RADIOHDL_WORK}
```
Keys are always in lowercase even when the name of the key will be used as environment variable. RadioHDL takes care that the key names are converted to uppercase in these cases.
 
You can refer to a value of another key by placing the name of that key between '<' and '>'. Key word substitution can happen local within a file or global between files:
 
- Local: A key name can be used for key value substitution in other key values within the same cfg file at <key name>.
- Global: A key name in the hdl_buildset cfg file can be used to substitute in key values in hdllib cfg files: e.g. <buildset_name>
 
For example:
```
tool_name = quartus
tool_version = 12.3
tool_location = /home/software/\<tool_name\>/\<tool_version\>/bin
```
 
Key values can be e.g.:
 
* Single value : e.g 'hdl_lib_name' key
* List of values : e.g. 'synth_files' key
* List of value pairs : e.g '*_copy_files' key
 
The pairs in '*_copy_files' are separated by a space and therfore the values can not contain a space.
/trunk/doc/radiohdl_user_guide.vsdx Cannot display: file marked as a binary type. svn:mime-type = application/octet-stream
trunk/doc/radiohdl_user_guide.vsdx Property changes : Added: svn:executable ## -0,0 +1 ## +* \ No newline at end of property Added: svn:mime-type ## -0,0 +1 ## +application/octet-stream \ No newline at end of property Index: trunk/doc/radiohdl_work_flow.jpg =================================================================== Cannot display: file marked as a binary type. svn:mime-type = application/octet-stream Index: trunk/doc/radiohdl_work_flow.jpg =================================================================== --- trunk/doc/radiohdl_work_flow.jpg (nonexistent) +++ trunk/doc/radiohdl_work_flow.jpg (revision 7)
trunk/doc/radiohdl_work_flow.jpg Property changes : Added: svn:mime-type ## -0,0 +1 ## +application/octet-stream \ No newline at end of property Index: trunk/doc/raw_config_classes.jpg =================================================================== Cannot display: file marked as a binary type. svn:mime-type = application/octet-stream Index: trunk/doc/raw_config_classes.jpg =================================================================== --- trunk/doc/raw_config_classes.jpg (nonexistent) +++ trunk/doc/raw_config_classes.jpg (revision 7)
trunk/doc/raw_config_classes.jpg Property changes : Added: svn:mime-type ## -0,0 +1 ## +application/octet-stream \ No newline at end of property Index: trunk/doc/sd_export_variable.jpg =================================================================== Cannot display: file marked as a binary type. svn:mime-type = application/octet-stream Index: trunk/doc/sd_export_variable.jpg =================================================================== --- trunk/doc/sd_export_variable.jpg (nonexistent) +++ trunk/doc/sd_export_variable.jpg (revision 7)
trunk/doc/sd_export_variable.jpg Property changes : Added: svn:mime-type ## -0,0 +1 ## +application/octet-stream \ No newline at end of property Index: trunk/doc/wave_tb_dp_repack_data.jpg =================================================================== Cannot display: file marked as a binary type. svn:mime-type = application/octet-stream Index: trunk/doc/wave_tb_dp_repack_data.jpg =================================================================== --- trunk/doc/wave_tb_dp_repack_data.jpg (nonexistent) +++ trunk/doc/wave_tb_dp_repack_data.jpg (revision 7)
trunk/doc/wave_tb_dp_repack_data.jpg Property changes : Added: svn:mime-type ## -0,0 +1 ## +application/octet-stream \ No newline at end of property Index: trunk/CREDITS.md =================================================================== --- trunk/CREDITS.md (nonexistent) +++ trunk/CREDITS.md (revision 7) @@ -0,0 +1,41 @@ +# RadioHDL credits + +The purpose of this document is to acknowledge the persons, projects and institutes that contribute or contributed to the RadioHDL package. + + +## Contributors + +|Name |Affiliation | Part | +|---|---|---| +|E. Kooistra | [ASTRON] | RadioHDL concepts and initial scripts in Python2 | +|D. van der Schuur| [ASTRON] | Scripts for Modelsim, Quartus and UniBoard1 | +|R. Overeem | [ASTRON] | Refactoring of RadioHDL gear in Python3 and bash | +|P. Donker | [ASTRON] | Scripts maintenance | +|L. Hiemstra | [ASTRON] | Scripts for Vivado and Gemini board | +|M. Baquiran | [CSIRO] | Scripts for Vivado and Gemini board | +|W. Poiesz | [Inspiro] | Initial scripts for Modelsim | +|H. Verkouter | [JIVE] | Initial bash scripts for Quartus and UniBoard1 | + + + +## Projects + +Initial scripts for Modelsim were developed for the RSP and TBB FPGA boards in the LOFAR stations [LOFAR]. + +Initial scripts for Quartus and the RadioHDL configuration files were developed for UniBoard1 in APERTIF [1] + +Initial scripts for Vivado were developed for the Gemini board in SKA CSP.Low.CBF [2] + + +## References + +[1] "The application of UniBoard as a beam former for APERTIF”, A. Gunst, A. Szomoru, G. Schoonderbeek, E. Kooistra, D. van der Schuur, H. Pepping, Experimental Astronomy, Volume 37, Issue 1, pp 55-67, February 2014, doi:10.1007/s10686-013-9366-x. + +[2]:"Gemini FPGA Hardware Platform for the SKA Low Correlator and Beamformer", E. Kooistra, G. A. Hampson, A. W. Gunst, J. D. Bunton, G. W. Schoonderbeek, A. Brown, 32nd URSI GASS, Montreal, 19-26 August 2017 + + +[LOFAR]:http://www.lofar.org/ +[ASTRON]:https://www.astron.nl +[JIVE]:https://www.jive.nl/ +[Inspiro]:https://www.inspiro.nl +[CSIRO]:https://www.csiro.au/en/Research/Astronomy Index: trunk/LICENSE.md =================================================================== --- trunk/LICENSE.md (nonexistent) +++ trunk/LICENSE.md (revision 7) @@ -0,0 +1,32 @@ +# RadioHDL license + +The RadioHDL package is open source and available under the Apache Licence 2.0. The following text fragment shall be placed in comments at the top of each (new) source code file: + +``` + Copyright [year] [name of copyright owner] + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +``` +#### Replace `````` by the current year. + +#### For [ASTRON] replace ```Copyright [year] [name of copyright owner]``` by: +``` + Copyright Stichting Nederlandse Wetenschappelijk Onderzoek Instituten, + ASTRON Netherlands Institute for Radio Astronomy +``` + + +[ASTRON]:https://www.astron.nl + + + Index: trunk/NOTICE.md =================================================================== --- trunk/NOTICE.md (nonexistent) +++ trunk/NOTICE.md (revision 7) @@ -0,0 +1,15 @@ +Citation Notice version 1.0 + +``` +This Citation Notice is part of the RadioHDL software suite. + +Parties that use ASTRON Software resulting in papers and/or publications are requested to +refer to the DOI(s) that correspond(s) to the version(s) of the ASTRON Software used: + +10.5281/zenodo.3631361 + +Parties that use ASTRON Software for purposes that do not result in publications (e.g. +commercial parties) are asked to inform ASTRON about their use of ASTRON Software, by +sending an email to including the DOIs mentioned above in the message. +``` +
trunk/NOTICE.md Property changes : Added: svn:executable ## -0,0 +1 ## +* \ No newline at end of property Index: trunk/README.md =================================================================== --- trunk/README.md (nonexistent) +++ trunk/README.md (revision 7) @@ -0,0 +1,49 @@ +# RadioHDL + +The purpose of RadioHDL is to speed up HDL development by providing a uniform and automated way of using tools and building code for FPGAs. The RadioHDL user guide provides the introduction to RadioHDL and a quick start example: + +* [radiohdl_user_guide.md](./doc/radiohdl_user_guide.md) + +The RadioHDL package consists of a set of scripts that interpret configuration files and that setup or run tools. RadioHDL uses three kinds of configuration files to setup your source code and tools: + +- ***hdl_buildset_.cfg*** configuration file per FPGA board +- ***hdl_tool_.cfg*** configuration file per vendor tool +- ***hdllib.cfg*** configuration file per HDL library + +A RadioHDL configuration file contains a collection of key-value pairs. The configuration files are described in: + +* [radiohdl_hdl_buildset_key_descriptions.md](./doc/radiohdl_hdl_buildset_key_descriptions.md) +* [radiohdl_hdl_library_key_descriptions.md](./doc/radiohdl_hdl_library_key_descriptions.md) + +RadioHDL was first applied for an FPGA board called UniBoard1. The buildset description for the UniBoard1 provides a more advanced example, that shows how RadioHDL is used to develop HDL for an FPGA board using Mentor Modelsim for simulation and Intel/Altera Quartus for synthesis. + +Currently these vendor tools are supported: + +* [radiohdl_hdl_tool_modelsim.md](./doc/radiohdl_hdl_tool_modelsim.md) +* [radiohdl_hdl_tool_quartus.md](./doc/radiohdl_hdl_tool_quartus.md) + +Currently these FPGA boards are supported: + +* [radiohdl_hdl_buildset_uniboard1.md](./doc/doc/radiohdl_hdl_buildset_uniboard1.md) + +The RadioHDL user guide describes how support for more FPGA boards and more vendor tools can be added to RadioHDL. + +The concepts and working of the RadioHDL scripts are described in the RadioHDL programmer guide: + +* [radiohdl_programmer_guide.md](./doc/radiohdl_programmer_guide.md) + + +If you use (part of) the RadioHDL package please attribute the use as indicated this citation NOTICE: + +### [NOTICE](NOTICE.md) + +The RadioHDL package is Open Source and available under the following LICENSE: + +### [LICENSE](LICENSE.md) + +The RadioHDL package was developed at [ASTRON] and used in several projects, but others have contributed and are welcome to contribute as well. The CREDITS lists the contributers of RadioHDL: + +### [CREDITS](CREDITS.md) + + +[ASTRON]:https://www.astron.nl Index: trunk/generic.sh =================================================================== --- trunk/generic.sh (revision 6) +++ trunk/generic.sh (revision 7) @@ -1,3 +1,23 @@ +############################################################################### +# +# Copyright 2018 Stichting Nederlandse Wetenschappelijk Onderzoek Instituten +# ASTRON Netherlands Institute for Radio Astronomy +# JIVE (Joint Institute for VLBI in Europe) +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# +############################################################################### + # This file contains a collection of convenience functions and definitions. # # automatically export to subsequent commands (-a)

powered by: WebSVN 2.1.0

© copyright 1999-2024 OpenCores.org, equivalent to Oliscience, all rights reserved. OpenCores®, registered trademark.