Updated.

applications/lofar2/doc/prestudy/desp_radiohdl_article.txt

@@ -4,6 +4,14 @@
 
 Title: RadioHDL build environment for FPGA firmware
 
+Purpose: Ease the FPGA firmware development flow
+How:
+ - Organize the /source/ code in separate /libraries/
+ - /Automate/ the flow from source code to target file in a transparent way
+ - Use /configuration/ files and /target/ specific scripts
+
+The name RadioHDL reflects that it was first used for HDL development in FPGA projects for radio
+astronomy, but it can be used for any HDL development project.
 
 
 *******************************************************************************
@@ -13,23 +21,45 @@ Title: RadioHDL build environment for FPGA firmware
 a) Introduction:
 
 RadioHDL is a highly flexible automated build environment for HDL source code. The HDL is 
-organized in HDL libraries. The HDL libraries promote code reuse. The top level component
-that can run on an FPGA is also a HDL library. The parameters for HDL libraries, the build
+organized in HDL libraries. The parameters for HDL libraries, the build
 tools and target FPGA are kept in configuration files. The configuration files and source
-code are the inputs for the RadioHDL tool. The output is a build result that depends on
-which build tool is used. The buil result can e.g. be a project file for Modelsim to 
-simulate the HDL, a project for Quartus to synthesize the HDL, a report log from a 
-regression test that simulated the HDL.
-
-Technology dependent IP for e.g. PLL, RAM, FIFO, transceivers, DDR4 is included via HDL
-libraries as well. The technology dependent IP is pregenerated and instantiated using wrapper
-HDL. The wrapper HDL around the technology dependent IP makes the IP vendor agnostic. The
-wrapper HDL can select one or more vendor IP. The wrapper IP can also select a behavioral
-simulation model of the IP, to speed up the HDL simulation or to simulate without any vendor
-dependence.
+code are the inputs for the RadioHDL tool. 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. Fig 1 shows the build flow from source to target.
+The config files and source files are kept in a directory tree under version control, while
+the target files are build in a separete build directory tree.
+
+  config files\
+               --> tool specific --> target files --> Vendor tool --> target files
+  source files/    config script
+
+Fig 1. RadioHDL flow from source to target (see 30_FWbuild_Eric, SKA Hongkong)
+
+
+The HDL libraries provide a hierarchy that promotes code reuse. The top level component that
+can run on an FPGA is also a HDL library. Technology dependent IP for e.g. PLL, RAM, FIFO,
+transceivers, DDR4 is included via HDL libraries as well. The technology dependent IP is 
+pregenerated and instantiated using wrapper HDL. The wrapper HDL around the technology
+dependent IP makes the IP vendor agnostic. The wrapper HDL can select one or more vendor IP.
+The wrapper IP can also select a behavioral simulation model of the IP, to speed up the HDL
+simulation or to simulate without any vendor dependence. Fig 2 shows a possible hierarchy 
+of HDL libraries. 
+
+   Application
+   Board
+   DSP
+   IO
+   external
+   base
+   technology
+   IP
+
+
+Fig 2. Organize firmware in libraries (see 30_FWbuild_Eric, SKA Hongkong)
 
 Features:
-- Gear scripting based on Pyhton 3.x
+- RadioHDL gear scripting based on Python 3.x
 - Configuration files to define the sources and how to build them
 - Separation of source files and build result files
 - All HDL organised in HDL libraries that
@@ -39,28 +69,68 @@ Features:
   . can be used to build different revisions of the same source code based on generics
   . can include local test benches to verify the library in a regression test
 
+Pro:
+- Uniform way of using tools and building code
+
+Con:
+- Maintain tool to keep up with changes in Vendor tool versions
+- Initial effort to support new tools or tools from different vendors
+- It can be difficult to support vendor specific features. If these features are rarely used
+  or requrie human intervention, then it may be not worth the effort or even impossible to
+  sautomate the use of these features by adding a key to the config file.
 
 b) Quick start:
+- Using sim models
+- c_technology = sim or using g_sim?
 
 
 c) Config files:
-  hdllib.cfg :
-    . Each HDL Library has a local hdllib.cfg configuration file that defines the sources and
-      supported tools
-    . many, each local per HDL library in a sub directory of $RADIOHDL_WORK
+  The configuration files define key-value pairs, like a dictionary in Python. There are three
+  different kinds of configuration files:
+  
   hdl_buildset_<buildset_name>.cfg 
     . A central hdl_buildset_<name> build configuration file defines the combination of sources,
       FPGA type and version and tool versions that are needed to build target FPGA type (board)
       and type and version of the tools for synthesis, simulation.
-    . defines a combination of board, FPGA and tool versions
-    . one central per buildset located at $RADIOHDL_CONFIG
+    . defines a combination of board, FPGA, tools (sythesis, simulation) and IP libraries
+      versions
+    . one central config file per buildset located at $RADIOHDL_CONFIG
+    . buildset name is typically an abbreviation that identifies the target board hardware and
+      a version, e.g. 'unb1' for a version 1 of a board called UniBoard. If the same board is 
+      used but with another set of tool versions, then that may be identified by e.g. 'unb1a'.
+  
   hdl_tool_<tool_name>.cfg 
     . A central hdl_tool_<name>.cfg tool configuration file that defines central setting for
       that tool. Typical tools are e.g. Modelsim for simulation and Quartus for synthesis, but
       other tool vendors can also be supported and other tools like a reggression test that
       runs a set of test benches for a set of HDL libraries.
-    . defines tool specific settings (e.g. modelsim, quartus)
+    . defines tool specific settings e.g.
+    
+        tool config file           used for tool
+        hdl_tool_modelsim.cfg      Modelsim simulator
+        hdl_tool_quartus.cfg       Quartus synthesis, SOPC, QSYS, IP generation, user settings
+        
+        
     . one central per tool located at $RADIOHDL_CONFIG
+    
+  hdllib.cfg :
+    . Each HDL Library has a local hdllib.cfg configuration file that defines the sources and
+      supported tools
+    . many, each local per HDL library in a sub directory of $RADIOHDL_WORK
+    . the HDL library cam define module library with VHDL that is reused in other lirbaries or
+      a top level library with a top level entity that maps on the IO of the FPGA.
+    . typically the HDL library points to sources that are located in the same directory or in
+      its sub directories, however absolute paths to sources are also allowed
+    . the hdllib.cfg can be divided into sections to group keys that are used for a specific
+      target. The section headers are identified between square brackets [section_name],
+      similar as in a Windows ini file. The first part of a 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. E.g:
+        
+        section name              used by tool script
+        [modelsim_project_file]   modelsim_config.py
+        [quartus_project_file]    quartus_config.py
+          
 
 d) Environment setup
 
@@ -69,7 +139,7 @@ d) Environment setup
   availabel in order to build target files (TBC):
   - Make (available in /bin for win32 platforms)
   - Python 3.x
-  - Pyhton libraries (numpy, pylatex, yaml) 
+  - Python libraries (numpy, pylatex, yaml) 
 
 * Environment variables
 
@@ -109,7 +179,7 @@ d) Environment setup
 
 
 
-f) Directory structure
+f) Source directory structure
 
 RadioHDL requires that:
 
@@ -181,24 +251,49 @@ Technology independence:
 The technology/ directory contains several technology dependent libraries of vendor IP that is 
 pre generated and then wrapped by a technology agnostic wrapper entity. These wrapper entities
 are then used by the other libraries.
+
+g) Build directory structure
+
+The build directory structure contains created files and copied files and is located at
+
+  $RADIOHDL_BUILD_DIR/<hdltool_name>/                             for hdl_tool_<name>.cfg
+  $RADIOHDL_BUILD_DIR/<buildset_name>/<tool_name>/                for hdl_tool_<name>.cfg
+  $RADIOHDL_BUILD_DIR/<buildset_name>/<tool_name>/<hdllib_name>/  for hdllib.cfg per hdl_tool_<name>.cfg
+
       
       
-g) Top level HDL library:
+h) Top level HDL library:
 
 A top level HDL library is defined as a HDL library that contains a top level entity and 
 configuration parameters to synthesize it to an FPGA image that can run on an FPGA.
 A top level HDL library should not be reused in other HDL libraries, to avoid confusion
-that can occur due to conflicting or dupplciate
+that can occur due to conflicting or duplicate source files.
 
 
 
 *******************************************************************************
 * Run RadioHDL with GIT
 
+bashrc:
+- define ALTERA_DIR
+
 > cd ~/git/hdl
 > . ./init_hdl.sh               # setup development environment for hdl/
                                 # hdl/libraries, hdl/boards and hdl/applications are developed simultaneously and therefor in one git hdl/ repository
                                 # automatically also sources ../radiohdl/init_radiohdl.sh if necessary
+
+defines:
+- RADIOHDL_WORK directory for where the source code resides
+- RADIOHDL_BUILD_DIR directory for where the targets will be build
+- HDL_IOFILE_SIM_DIR=${RADIOHDL_BUILD_DIR}/sim for simulating with Modelsim using file IO
+
+copy: git user_componets.ipx into Altera dir's
+- cp ${RADIOHDL_WORK}/hdl_user_components.ipx $altera_dir/ip/altera/user_components.ipx
+
+source also radiohdl tools
+. ../radiohdl/init_radiohdl.sh
+                                
+                                
 > compile_altera_simlibs unb1   # creates build/unb1/hdl_libraries_ip_stratixiv.txt
                                 # creates build/quartus/<tool version> simulation models that need to be moved to /home/software/modelsim_altera_libs
 > generate_ip_libs unb1         # creates build/unb1/qmegawiz/
@@ -210,6 +305,7 @@ that can occur due to conflicting or dupplciate
                                 # creates build/unb1/modelsim/technology_select_pkg.vhd
 > run_qsys unb1 unb1_minimal_qsys
 
+> run_modelsim unb1 &
 
 
 *******************************************************************************
@@ -223,6 +319,9 @@ export SVN=${HOME}/svnroot/UniBoard_FP7
 . ${SVN}/RadioHDL/trunk/tools/setup_unb.sh
 
 
+*******************************************************************************
+* 2) User guide topics
+
 
 
 *******************************************************************************

applications/lofar2/doc/prestudy/station2_sdp_firmware_planning.txt

+*******************************************************************************
+* Rules
+*******************************************************************************
+
+1) Continuously plan 4 sprint ahead
+   After initial planning for thge whole project (at PDR) it remains necessary to keep on adapting
+   / fine tuning the planning per quarter, so about 4 sprints ahead. This concerns not only time
+   but also expectations, interfaces and work
+2) Guard the architecture
+   New projects / functionality must be judges by an architect (team) to decide on how it will fir
+   in the existing architecture, or how the architecture will be adapted. This may change the
+   requirements on the new project/ function. It also means that ad hoc solutions are not allowed.
+3) Complete set of documentation of finished product
+   Important for maintenance and extensions.
+
 
 
 *******************************************************************************