diff --git a/tools/hdltool_readme.txt b/tools/hdltool_readme.txt index ea513840e04fbd7dec8e62007110aa5bd2b1c022..6fa6ebcc4fa16d88b251fce3ccded61b8d0c4f2e 100644 --- a/tools/hdltool_readme.txt +++ b/tools/hdltool_readme.txt @@ -17,7 +17,7 @@ Contents: 3) HDL environment configuration files a) Tools and libraries b) Target configuration scripts - c) hdltool.cfg key descriptions + c) hdltool_<toolset>.cfg key descriptions d) hdllib.cfg key descriptions 4) Porting from $UNB to $RADIOHDL @@ -271,8 +271,8 @@ a) Tools and libraries The HDL environment consists of tools and libraries. The HDL environment is defined in configuration files. -- hdltool.cfg : HDL tool configuration dictionary file. One central file. -- hdllib.cfg : HDL library configuration dictionary file. One file for each HDL library. +- hdltool<toolset>.cfg : HDL tool configuration dictionary file. One central file per toolset. +- hdllib.cfg : HDL library configuration dictionary file. One file for each HDL library. The HDL libraries can define a module library with VHDL that is reused in other libraries or a design library with a top level entity that maps on the IO of the FPGA. For the hdllib.cfg there is no difference between @@ -297,6 +297,8 @@ The configuration files are interpreted by Python scripts in $RADIOHDL/tools/one - common_dict_file.py - read and modify a dictionary file - hdl_config.py - get tool dictionary info, all HDL library dictionary infos and the target technology name +The hdllib_config.py can also run standalone to manipulate cfg files, eg. to insert, remove or rename keys. + These general dictionary file and HDL configuration file handling scripts are used by the HDL library target scripts: - modelsim_config.py - for target t1) @@ -317,18 +319,14 @@ See also the docstring help text in the Python code: >> help(quartus_config.py) -c) hdltool.cfg key descriptions +c) hdltool_<toolset>.cfg key descriptions - lib_root_dir = Root directory from where all HDL library configuration files (hdllib.cfg) are searched -- build_dir_sim = - Global root path (e.g. $HDL_BUILD_DIR) to the build directory for simulation. The path gets extended with the - tool_name_sim from hdltool.cfg. - -- build_dir_synth = +- build_dir = Global root path (e.g. $HDL_BUILD_DIR) to the build directory for simulation. The path gets extended with the - tool_name_synth from hdltool.cfg. + tool_name_<build_type> from hdltool_<toolset>.cfg. - tool_name_sim = Used as directory name in the build directory, e.g. modelsim. @@ -337,8 +335,24 @@ c) hdltool.cfg key descriptions Used as directory name in the build directory, e.g. quartus. - model_tech_dir = - Used to get the location of the modelsim.ini file, e.g. /home/software/Mentor/modeltech. + Used to get the location of the modelsim.ini file, e.g. /home/software/Mentor/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_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. + +- technology_names = + The technology_names key lists the IP technologies that are supported within this toolset, eg. ip_stratixiv, ip_arria10. + It is possible to define multiple technologies. As long as Modelsim supports these technolgies (ie 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. 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. + + d) hdllib.cfg key descriptions @@ -356,9 +370,12 @@ d) hdllib.cfg key 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 key 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. This seperation avoids that libraries that are only needed for the - test bench simulations also get included in the list of libraries for synthesis. Often the 'test_bench_files' do not - depend on other libraries, so then the 'hdl_lib_uses_sim' remains empty. + dependencies that come from the test bench files. Quartus can exit with error if IP is included in the hdl_lib_uses_synth + list of libraries but not actually used in the design, eg due to a sdc file that is then sourced but that cannot find + some IP signals. Having a seperate hdl_lib_uses_synth 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. This seperation avoids + that libraries that are only needed for the test bench simulations also get included in the list of libraries for + synthesis. Often the 'test_bench_files' do not depend on other libraries, so then the 'hdl_lib_uses_sim' remains empty. - hdl_lib_excludes = Defines the libraries that must be excluded from the list of library dependencies that are derived from hdl_lib_uses_synth @@ -366,11 +383,16 @@ d) hdllib.cfg key descriptions of the IP but not actually used in the design. Typically present but unused IP is no problem, but for synthesis the constraint files for unused IP can cause problems. Therefore then use hdl_lib_excludes to exclude this IP library. An example is to exclude ip_stratixiv_ddr3_uphy_4g_800_slave if via io_ddr / tech_ddr only the - ip_stratixiv_ddr3_uphy_4g_800_master is used because only one DDR memory is used. + ip_stratixiv_ddr3_uphy_4g_800_master is used because only one DDR memory is used. The exclusion cannot be done at the io_ddr + or tech_ddr level, because these are instantiated as entities. 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 difference between this 'hdl_lib_excludes' 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 with 'hdl_lib_excludes' are still created in the buid directory, but they are not used for that HDL library. - + are excluded with 'hdl_lib_excludes' are still created in the build directory, but they are not used for that HDL library + so they are excluded dynamically. + - 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 ''. For simulating systems with multiple FPGA technologies it is also possible to list multiple IP technology names. @@ -381,18 +403,24 @@ d) hdllib.cfg key descriptions the Altera IP the compile_ip.tcl is derived from the msim_setup.tcl that is generated by the MegaWizard or Qsys. - map_ip.tcl : a TCL script that maps a VHDL library name to another location. -- 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. +- <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 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 in SVN or from the build dir location. Whether the source + directory is the hdllib.cfg location in SVN or the build_dir location depends on the <tool_name>. For modelsim_copy_files and + quartus_copy_files the relative source directory is the hdllib.cfg location in SVN and the relative destination directory is the + build_dir location. The direction can be from build dir to dir in SVN 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_dir. + If the destination directory is not in the build_dir then it first needs to be removed manually to avoid accidentally removing a + directory tree that should remain (eg. ~). - modelsim_copy_files = - Copy listed all directories and files for simulation with Modelsim, used when tool_name_sim = modelsim in hdltool.cfg. + 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 SVN directory to the build directory where the Modelsim project file is. For data files that are read in VHDL the path then becomes data/<file_name>. - quartus_copy_files = - Copy listed all directories and files for synthesis with Quartus, used when tool_name_synth = quartus in hdltool.cfg. + Copy listed all directories and files for synthesis with Quartus, used when tool_name_synth = quartus in hdltool_<toolset>.cfg. Can be used to eg. copy sopc or qsys file from SVN directory to the build directory where the Quartus project file is and that is where the run_* bash commands expect them to be. @@ -466,10 +494,13 @@ find the new avs2_eth_coe in $RADIOHDL. The Modelsim and Quartus build location central outside the $RADIOHDL sources directory tree: - $HDL_BUILD_DIR/quartus/<hdl_lib_name> - /modelsim/<hdl_lib_name> + <build_dir>/<toolset>/<tool_name>/<hdl_lib_name> + +eg. + + $HDL_BUILD_DIR/unb1/modelsim/common -The location is made via the build_dir_sim and build_dir_synth keys that specify the root path to the central directory e.g. +The location is made via the 'build_dir' key that specify the root path to the central directory e.g. via $HDL_BUILD_DIR. 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. @@ -480,7 +511,7 @@ time though. a) Creating the Modelsim project files -The binaries for Modelsim get build in a separate directory tree with absolute path set by the build_dir_sim key in the hdltool.cfg. +The binaries for Modelsim get build in a separate directory tree with absolute path set by the build_dir key in the hdltool_<toolset>.cfg. Currently the path is set to $HDL_BUILD_DIR = $RADIOHDL/build. Using a completely separate absolute build tree is more clear than building the library in a local build directory. To create the Modelsim project files for all HDL libraries in the $RADIOHDL tree do: @@ -600,8 +631,6 @@ e) tools/ a) modelsim_config.py command line arguments: --lib : default create all mpf, when specified only create project files for listed libraries - --technology : default create mpf for all libraries, when specified only keep the libraries that are needed for - the listed technologies --compile : default do not build the libraries, when specified also run 'mk clean all' and then 'mk all' etc. @@ -616,30 +645,19 @@ b) quartus_config.py command line arguments: c) quartus_* keys and synth_top_level_entity . The quartus_* keys are now source oriented. Instead it may be better to redefine thme as target oriented. Eg. a - quartus_create_qsf key that defines to create a qsf file using the intormation listed in the values. - . 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. - -d) *_copy_files keys - . The copy_files() method in hdl_config.py currently uses shutil.rmtree(buildPath), this is probably too risky and - needs to be made more save to avoid that accidentally some wrong dir tree is removed. Eg. by only accepting - shutil.rmtree(buildPath) for local subdirectories or subdirectories within the $HDL_BUILD_DIR directory and - otherwise exit or ask the user to confirm. - . The source and destination directory definition needs to be made somewhat more clear. The path can be absolute or - relative. The relative path can be from hdllib.cfg location in SVN or from the build dir. The direction van be - from build dir to dir in SVN or vice versa, or to any directory location. - -e) modelsim_search_libraries - Do not explicitely list all -L libraries at this modelsim_search_libraries key, but instead only the technology - name(s). The modelsim_config.py can then itself add the required -L string to the simulation configurations. In - theory all simulation configurations could get the -L libraries even if they do not need them. This would make - the modelsim_search_libraries key obsolete and avoid bothering hdllib.cfg with it. + 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 use for one or more targets. + In general if a file is used for more targets then source oriented is prefered to avoid having to list the file + name twice. If a file is used only for one target then target oriented is prefered to be more clear about the + purpose of the key. + . The synth_top_level_entity enfoitrces 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. f) 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 seems an unnecessary intermediate step if the IP is + 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. The advantage of a generate_ip.sh script is that it can hide whether the + 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: quartus_copy_files = @@ -654,43 +672,46 @@ f) Generate Quartus IP key 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: - $HDL_BUILD_DIR/quartus/<hdl_lib_name>/generated + $HDL_BUILD_DIR/<toolset>/quartus/<hdl_lib_name>/generated For generated IP that is kept in SVN that IP could still remain there. - The hdllib.cfg should then also define a build dir, eg.: + The hdllib.cfg should then also define a IP toolname subdirectory in build dir, eg.: - build_dir_ip = $HDL_BUILD_DIR + <build_dir>/<toolset>/<tool_name> = $HDL_BUILD_DIR/qsys or + $HDL_BUILD_DIR/megawizard - or build_dir_megawizard and build_dir_qsys? But then perhaps build_dir_synth should become build_dir_quartus? + or more general $HDL_BUILD_DIR/ip? The $HDL_BUILD_DIR now has a modelsim and quartus subdir: - $HDL_BUILD_DIR/modelsim -- made by modelsim_config.py using tool_name_sim from hdltool.cfg - $HDL_BUILD_DIR/quartus -- made by quartus_config.py using tool_name_synth from hdltool.cfg + $HDL_BUILD_DIR/<toolset>/modelsim -- made by modelsim_config.py using tool_name_sim from hdltool_<toolset>.cfg + $HDL_BUILD_DIR/<toolset>/quartus -- made by quartus_config.py using tool_name_synth from hdltool_<toolset>.cfg - The IP can be put in a subdir + The IP can be put in a subdir using eg 'tool_name_ip' = quartus_ip: - $HDL_BUILD_DIR/quartus_ip -- made by quartus_config.py using a new tool_name_ip from hdltool.cfg + $HDL_BUILD_DIR/<toolset>/quartus_ip -- made by quartus_config.py using a new tool_name_ip from hdltool_<toolset>.cfg or can it be put in the tool_name_synth directory: - $HDL_BUILD_DIR/quartus + $HDL_BUILD_DIR/<toolset>/quartus - or do we need tool_name_megawizard and tool_name_qsys to beable to create: - - $HDL_BUILD_DIR/megawizard -- Altera MegaWizard - $HDL_BUILD_DIR/qsys -- Altera QSYS - $HDL_BUILD_DIR/coregen -- Xilinx + or do we need tool_name_megawizard and tool_name_qsys to be able to create: + + <build_dir>/<toolset>/<tool_name> + $HDL_BUILD_DIR/unb1/megawizard -- Altera MegaWizard + $HDL_BUILD_DIR/unb1/qsys -- Altera QSYS + $HDL_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 hdltool.cfg both MegaWizard and Qsys can be regarded as + already covered by the generate_ip.sh scripts. In the hdltool_<toolset>.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. Conclusion: - - Using build_dir_synth is also sufficient/suitable to define the build subdirectory for IP generation. + - Using tool_name_synth = quartus is also sufficient/suitable to define the build subdirectory for IP generation. + Having a dedicate tool_name_ip could be nice, to more clearly see in the build tree which libraries have IP. g) regression test script - To simulate all self-checking VHDL test benches and report the result. @@ -701,35 +722,8 @@ g) regression test script 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. -h) hdltool.cfg per toolset (see also i, j, k) - . The model_tech_dir key in hdltool.cfg depends on the modelsim version that is defined in the toolset. The - model_tech_dir gives the path to the modelsim.ini that needs to be included in the mpf, because without the - IEEE and STD libraries are not known anymore after the mpf is loaded. - . Should we define a dedicated hdltool.cfg for each toolset similar as with the unb1 and unb2 toolsets that are - specified with the run_modelsim and run_quartus startup scripts. The hdltool_<toolset>.cfg then needs to be - specified via a --toolset command line option. For --toolset unb1 the hdltool_unb1.cfg then becomes eg.: - - tool_name_sim = modelsim_6_6c - tool_name_synth = quartus_11_1 - model_tech_dir = /home/software/Mentor/6.6c/modeltech - - and for unb2 the hdltool_unb2.cfg then becomes eg: - - tool_name_sim = modelsim_10.4 - tool_name_synth = quartus_14_1 - model_tech_dir = /home/software/Mentor/10.4/modeltech - - Currently the 6.6c modelsim.ini is used even if Modelsim 10.4 is ran. - . (FIXED erko) The build_dir_sim and build_dir_synth are now defined in the hdltool.cfg instead of in each - hdllib.cfg. It seems better to define these keys in the hdltool.cfg, because currently all they are the same - in all hdllib.cfg and with the possibility to define different hdltool.cfg there is already enough freedom. - - Conclusion: - - Is the hdltool.cfg necessary/useful at all? Yes. Keep hdltool.cfg, but define dedicated hdltool_<toolset>.cfg - and add --toolset command line option. - i) multiple libRootDirs for finding hdllib.cfg files - The libRootDir is now defined via a the 'lib_root_dir' key in the hdltool.cfg. + The libRootDir is now defined via a the 'lib_root_dir' key in the hdltool_<toolset>.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 @@ -737,52 +731,6 @@ i) multiple libRootDirs for finding hdllib.cfg files 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. -j) (FIXED - erko) Central build tree or local build directory - The get_lib_build_dirs() in hdl_config.cfg provides the option to build the sources locally in the library - directory or in a central build tree. The central build tree is preferred, because the local build in the library - is scattered and fills the SVN tree with build files. The local build option is not used. Therefore it may be - better and more clear to completely remove the support to do a local build from get_lib_build_dirs(). - --> fixed: the build_dir key now must specify a build directory. - -k) Support multiple --technology - It should be possible to define multiple technologies at the --technology option. As long as Modelsim supports - these technolgies (ie the technology libraries are available) then unused technologies are not disturbing and - then they also do not cause simulation load errors with the 'modelsim_search_libraries' key. - Probably a better scheme is to add a technology key to the hdltool.cfg and consider the hdltool.cfg as belonging - to a toolset. Each toolset then has a hdltool.cfg that defines which version of Modelsim and Quartus to use, - where to build and which technologies are supported. The toolset name (eg. 'unb1', 'unb2', ...) then is used - as command line option. This scheme also allows having mutliple build trees. - -l) (FIXED - erko) Location of modelsim_project_files.txt - Default the modelsim_project_files.txt used to be created in the SVN directory set by 'toolRootDir'/modelsim. Instead - the modelsim_project_files.txt should better be created in the build directory 'build_dir_sim'/modelsim/. - -m) (FIXED - erko) Issue exit error when a library name occurs double - When a HDL library directory is copied and the hdllib.cfg is not updated then the library name will be double - and cause misalignenment errors in the libraries lists which are difficult for a user to diagnose. The - __init__ in hdl_config.py could check this. - -n) Rename keys: - This is easily done using hdllib_config with mode 4. - * Rename modelsim_compile_ip_files into more precise name eg. modelsim_execute or modelsim_pre_execute. - * Rename key test_bench_files into sim_files, but does the hdllib.cfg become more clear to do this rename? - -o) (FIXED - erko) How to avoid Quartus exit due to IP that is included at configuration, but not used at synthesis - * (FIXED - erko) due to test_bench_files --> 'hdl_lib_uses_sim' key - Quartus can exit with error if IP is included in the hdl_lib_uses list of libraries but not actually used in - the design, eg due to a sdc file that is then sourced but that cannot find some IP signals. Having a seperate - hdl_lib_uses_synth 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. - * (FIXED - erko) due to not-generate a certain IO component at compile time --> 'hld_lib_excludes' key - In some designs we want to be able to temporarily disable the synthesis of an IO component (eg. io_ddr) to reduce - synthesis time. In that case the Quartus should not need to source the qip and sdc settings for that IP. The - IP can be excluded for a design by using the 'hld_lib_excludes' key to exclude the DDR IP library in the hdllib.cfg - of the design revision that has the io_ddr but does not generate it. The exclusion cannot be done at the io_ddr - or tech_ddr level, because these are instantiated as entities. Therefore the eclusiong 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. - p) 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. An @@ -831,12 +779,9 @@ a) ** Fatal: Error occurred in protected context. when loading a simulation in M # ** Fatal: Error occurred in protected context. # Time: 0 fs Iteration: 0 Instance: /tb_<...>/<hierarchy path to ip>/ip_stratixiv_phy_xaui_0_inst/<protected>/<protected>/<protected>/<protected>/<protected>/<protected> File: nofile # FATAL ERROR while loading design - - - Fix: - The fix is to add to the StratixIV IP search libraries to the hdllib.cfg: - - modelsim_search_libraries = - 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 + + Make sure that the StratixIV IP search libraries are defined by modelsim_search_libraries in the hdltool_<toolset>.cfg. - - Remarks: This error relates to items 100 e) and 100 k) \ No newline at end of file +b) vsim load warnings on missing IP + The c_tech_select_default must match the toolset, so need to manually edit c_tech_select_default = c_tech_stratixiv + or c_tech_arria10 in technology_select_pkg.vhd \ No newline at end of file