Subversion Repositories radiohdl

g) Tool start scripts

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:

  ${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

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


  
i) How to start Quartus for RadioHDL

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


j) How to start Modelsim for UNB

GUI:

  > unb_msim &        # for UNB
  > aaf_msim &        # for AARTFAAC
  > paasar_msim &     # for PAASAR

See the setup_unb.sh environment script and ASTRON_RP_1354_unb_minimal.pdf for more description.


n) How to use RadioHDL for Lofar RSP

* The Lofar Station firmware is kept in a separate SVN repository at:

    https://svn.astron.nl/Station
    
  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

  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:
  
  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

  Use the library mappings in the modelsim.ini that was modified by compxlib
  to create:
  
    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.

* 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 &


3) HDL environment configuration files

d) hdl_buildset_<buildset>.cfg key descriptions

- 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_<build_type> = 0 or not in tool_dict
    . project_deeper_subdir = 'p/' when project_dir_depth_<build_type> = 1
    . project_deeper_subdir = 'p/p/' when project_dir_depth_<build_type> = 2,
    . project_deeper_subdir = 'p/p/p/' when project_dir_depth_<build_type> = 3, etc

- project_dir_depth_synth =
    Same purpose as project_dir_depth_sim, but for synthesis project file location in build tree.

 

5) Build directory location

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_<buildset>.cfg:

  ${RADIOHDL_BUILD_DIR}/<buildset_name>/<hdl_lib_name>
  
eg.

  ${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.

                

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:
   
     quartus_copy_files =
         generate_ip.sh
         <technology>_<hdl_lib_name>.qsys
     quartus_generate_ip = generate_ip.sh
   
   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:
   
      $RADIOHDL_BUILD_DIR/<buildset>/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 IP toolname subdirectory in build dir, eg.:
    
     <build_dir>/<buildset>/<tool_name> = $RADIOHDL_BUILD_DIR/qsys        or
                                         $RADIOHDL_BUILD_DIR/megawizard
    
   or more general $RADIOHDL_BUILD_DIR/ip?
   The $RADIOHDL_BUILD_DIR now has a modelsim and quartus subdir:
    
      $RADIOHDL_BUILD_DIR/<buildset>/modelsim       -- made by modelsim_config.py using sim_tool_name from hdl_buildset_<buildset>.cfg
      $RADIOHDL_BUILD_DIR/<buildset>/quartus        -- made by quartus_config.py using synth_tool_name from hdl_buildset_<buildset>.cfg
   
   The IP can be put in a subdir using eg 'ip_tool_name' = quartus_ip:
   
      $RADIOHDL_BUILD_DIR/<buildset>/quartus_ip     -- made by quartus_config.py using a new ip_tool_name from hdl_buildset_<buildset>.cfg
      
   or can it be put in the synth_tool_name directory:
   
      $RADIOHDL_BUILD_DIR/<buildset>/quartus
      
   or do we need tool_name_megawizard and tool_name_qsys to be able to create:
                                      
      <build_dir>/<buildset>/<tool_name>
      $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_<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
   generation.
   
   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.
   
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_<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
(because some parameters and even port IO may change). Currently there is only one IP directory per FPGA
technology (eg. ip_arria10) so there is no further separation into device family type and tool version. The
disadvantage of this scheme is that only one version of Quartus can be supported. For a minor version 
change it may not be necessary to upgrade, but for a major version change or for a device family type (eg. from
engineering sample to production sample) change it probably is. To preserve the old version IP it is best to
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/
  
This can be renamed in:

  ${RADIOHDL_WORK}/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:

  ip_<fpga family>_device_<fpga identifier>_quartus_<version>
  
A future version of the IP can be kept in:

  ${RADIOHDL_WORK}/libraries/technology/ip_arria10_device_10AX115U4F45I3SGES_quartus_16.0/

The technology_pkg.vhd then gets;

  c_tech_arria10_device_10AX115U4F45I3SGES_quartus_14_1 = ...;
  c_tech_arria10_device_10AX115U4F45I3SGES_quartus_15_0 = ...;
  c_tech_arria10                                        = c_tech_arria10_device_10AX115U4F45I3SGES_quartus_15_0;  -- optional default
  
The hdllib.cfg of the specific technology IP library then has key (only one value):

  hdl_lib_technology = ip_arria10_device_10AX115U4F45I3SGES_quartus_15_0
  
The hdl_buildset_<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
                     ip_arria10_device_10AX115U4F45I3SGES_quartus_15_0

All libraries that have hdl_lib_technology value that is not in the list of technology_names are removed from the dictionary list
by hdl_config.py, so these IP libraries will not be build.

The build directory currently contains:

  <build_dir>/<buildset_name>/<hdl_lib_name>

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.

  hdl_lib_name = ip_arria10_fifo
  hdl_library_clause_name = ip_arria10_fifo_lib
  
then becomes:

  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 
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.

The purpose is to be able to handle in parallel different FPGA vendors, different FPGA types and different tool version. We do not have
to support all combinations, but only the combinations that we actually use. Eg. for the FPGA type this implies that we only support the FPGA types
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

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:

- for python they are defined by the hdl_buildset_<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_<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?)


h) Declare IP libraries to ensure default binding in simulation.

Currently the IP library is declared in the technology VHDL file e.g. like 'LIBRARY ip_arria10_ddr4_4g_1600_altera_emif_150;' in tech_ddr_arria10.vhd.
This IP library clause is ignored by synthesis. The IP library must be mapped for simulation, because otherwise Modelsim gives
an error when it compiles the VHDL. Therefore the IP library can then not be excluded for simulation with 'hdl_lib_include_ip' key.
Alternatively the LIBRARY clause could be omitted if the IP library is added to the -L libraries search list of each simulation configuration the
Modelsim project file. This can be achieved adding the IP library to the modelsim_search_libraries key in the hdl_buildset_unb2.cfg. However the problem is
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
   A zip script can gather all sources that are needed for a particular RadioHDL view point, eg.
   
   - zip all required libraries for a certain level library --> useful for somebody who wants to reuse a HDL library.
   - zip all code necessary to run Python test cases on HW target --> useful for somebody who only wants to use the HW.
   - zip all tool environent code --> useful for somebody who wants to use our tool flow but not our HDL.
   
   Related to this is (how) can we more clearly divide up the RadioHDL/ directory to eg. reuse only parts of it and
   to develop these in other locations/repositories (eg. GIT). Eg. the applications/ directory may not be needed or
   even suitable in RadioHDL/ because applications could be kept elsewhere, even in another repository at another 
   institute.
   
b) support dynamic generation of IP
   Very preliminary ideas:
   Currently the MegaWizard or QSYS component description file is fixed and created manually in advance via the 
   GUI. In future the component description file could be created based on parameters that are defined in the
   hdllib.cfg or even parameters that depend on the requirements from the design. In a dynamic flow the hdllib.cfg
   for IP could even not exist as a file, but only as a dictionary in the script. 
   
c) Link RadioHDL developments with the OneClick MyHDL developments.
   The hdllib.cfg dictionary format seems useful also in the OneClick flow. For some created libraries the hdllib.cfg
   may not exist as a file and but only as the dictionary in the script. The various methods in modelsim_config.py
   and quartus_config.py can also be reused in a OneClick flow.
 
   
102) Know errors

a) ** Fatal: Error occurred in protected context. when loading a simulation in Modelsim
 - Example:
   # Loading ip_stratixiv_phy_xaui_lib.ip_stratixiv_phy_xaui_0(rtl)
   # ** 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
 
   Make sure that the StratixIV IP search libraries are defined by modelsim_search_libraries in the hdl_buildset_<buildset>.cfg.