diff --git a/applications/lofar2/doc/prestudy/desp_howtools_erko.txt b/applications/lofar2/doc/prestudy/desp_howtools_erko.txt
index 458e54aca357f71bf09309c3c58d2416fdcd3184..aa73321a0a64b83db5e414ee41c5a4f02ef5de62 100755
--- a/applications/lofar2/doc/prestudy/desp_howtools_erko.txt
+++ b/applications/lofar2/doc/prestudy/desp_howtools_erko.txt
@@ -1,7 +1,90 @@
+* RadioHDL with GIT (LOFAR2.0)
+* RadioHDL with SVN (APERTIF/ARTS)
* GIT workflow
* Confluence
* Polarion
* Latex
+* Markdown
+
+*******************************************************************************
+* RadioHDL with GIT
+*******************************************************************************
+
+# Setup vendor specific environment variables in .bashrc
+
+ * bashrc defines root directories that contain one or more versions of tool installations
+ - define MENTOR_DIR : modelsim installations
+ - define ALTERA_DIR : altera installations
+ - define MODELSIM_ALTERA_LIBS_DIR : compiled modelsim simulation libraries for altera components
+
+ - LM_LICENSE_FILE=<our_license@our_compagny>
+
+# Setup RadioHDL development environment for hdl/. The hdl/libraries, hdl/boards and hdl/applications are
+# developed simultaneously and therefor in one git hdl/ repository
+
+> cd ~/git/hdl
+
+> . ./init_hdl.sh
+
+ * init_hdl.sh 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
+
+ * init_hdl.sh copies git user_components.ipx into Altera dir's
+ - cp ${RADIOHDL_WORK}/hdl_user_components.ipx $altera_dir/ip/altera/user_components.ipx
+
+ * init_hdl.sh automatically also sources ../radiohdl/init_radiohdl.sh if necessary
+
+
+source also radiohdl tools
+. ../radiohdl/init_radiohdl.sh
+
+ * init_radiohdl.sh 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
+
+ * init_radiohdl.sh extends:
+ - PATH with ${RADIOHDL_GEAR}/core
+ ${RADIOHDL_GEAR}/quartus
+ ${RADIOHDL_GEAR}/modelsim
+ - PYTHONPATH with ${RADIOHDL_GEAR}/core
+ ${RADIOHDL_GEAR}/components
+
+
+> compile_altera_simlibs unb1 # creates build/unb1/hdl_libraries_ip_stratixiv.txt
+ # creates build/quartus/<tool version> simulation models that need to be moved
+ # manually to $MODELSIM_ALTERA_LIBS_DIR/<tool version>
+
+> generate_ip_libs unb1 # creates build/unb1/qmegawiz/
+ # creates build/unb1/quartus_sh --> empty dir, why is it there?
+
+> quartus_config unb1 # creates build/unb1/quartus/<hdllib libraries> for synthesis
+ # creates build/unb1/quartus/technology_select_pkg.vhd
+
+> modelsim_config unb1 # creates build/unb1/modelsim/<hdllib libraries> for simulation
+ # creates build/unb1/modelsim/modelsim_project_files.txt for Modelsim commands.do
+ # creates build/unb1/modelsim/technology_select_pkg.vhd
+
+> run_qsys unb1 unb1_minimal_qsys # creates QSYS block in build/unb1/quartus/unb1_minimal_qsys
+> run_qcomp unb1 unb1_minimal_qsys # creates
+
+> run_modelsim unb1 &
+
+
+*******************************************************************************
+* RadioHDL with SVN
+*******************************************************************************
+
+echo "Uniboard trunk is selected"
+export SVN=${HOME}/svnroot/UniBoard_FP7
+#Setup RadioHDL environment for UniBoard2 and and new Uniboard1 applications
+. ${SVN}/RadioHDL/trunk/tools/setup_radiohdl.sh
+# Support old UniBoard environment (including Aarfaac and Paasar)
+. ${SVN}/RadioHDL/trunk/tools/setup_unb.sh
+
+
*******************************************************************************
* GIT workflow
@@ -28,6 +111,7 @@ cd ~/git
git init # start new repo at this dir, creates .git/
git clone # get and start with existing repo
git clone git@git.astron.nl:desp/args.git
+git clone git@git.astron.nl:desp/sampy.git
git status # what is in stage area and what is modified
@@ -41,24 +125,24 @@ v git commit
* history # .git repository with entire commit graph
# To use a repo
-git add <dir>/<file> # add to stage area, set for commit. Cannot add empty dir, need empty file in it
-git add . # add all new and modified to stageing area
-git diff # diff between file in working tree and staging area
-git diff --staged # diff between file in staging area and history
-git rm <filename> # remove file from working tree and stage the delete
+git add <dir>/<file> # add to stage area, set for commit. Cannot add empty dir, need empty file in it
+git add . # add all new and modified to stageing area
+git diff # diff between file in working tree and staging area
+git diff --staged # diff between file in staging area and history
+git rm <filename> # remove file from working tree and stage the delete
git checkout -- <filename> # revert a working tree change
-git reset # clear stage area
-git reset HEAD <filename> # revert staged change
-git log -- <filename> # show history of file
+git reset # clear stage area
+git reset HEAD <filename> # revert staged change
+git log -- <filename> # show history of file
git checkout <version hash> -- s2 # retrieve file from history into staged area and working tree
Part 2:
-git commit -m "" # commit what is in stage area
-git commit -a -m "" # add to stage area and commit what is in stage area
+git commit -m "" # commit what is in stage area
+git commit -a -m "" # add to stage area and commit what is in stage area
alias graph="git log --all --decorate --oneline --graph"
-git branch <branch name> # creat branch
+git branch <branch name> # creat branch
git branch # show branches
git checkout <branch name> # change working tree and stage area to branch
git checkout master
@@ -114,12 +198,44 @@ git status
# delete branch and fetch npstream if the pull request was accepted
git remote remove <remote name> # remove a remote repo
+Review process
+
+* Jira ticket defines the work to be done
+* coder works on branch with Jira ticket number
+* manually run regression test to test the changes (for Casacore SW the merge
+ request makes github automatically issue a regression test in the cloud)
+* coder does merge request to reviewer
+* gitlab will warn if the branch will lead to a merge conflict, the coder then
+ first has to fix the merge conflict by merging the master to the branch.
+ The merge can use merging or rebasing, Ger typically uses merging.
+* reviewer reviews the code per line and in general comments in gitlab GUI,
+ so no need to pull the branch locally
+* Use 'Open in Web IDE' button to see max about 10 changes, Use 'Changes' menu
+ to see all changes. Green is new file, orange is change file, + is new lines
+ - is removed lines.
+* coder does updates on branch until both coder and reviewer are ok, they are
+ notified by gitlab
+* when review is done then the reviewer does the merge.
+* the merge automatically deletes the branch (if selected to do so in gitlab)
+ locally the coder manually needs to delete the branch
+* Use Jira tag in commit message to have link between GIT and Jira. The link
+ was made via Settings/Intergations/Jira
+
+Note:
+* In github a merge request is called a pull request
+* Default a pull pulls the master. Typically it is not necessary to pull a
+ branch because the reviewer does not need to compile and run the code and
+ because typically only one coder works on a branch.
+
+
*******************************************************************************
* Confluence:
*******************************************************************************
- space tools menu links onder om secties the ordenen.
+- space tools menu, content tools, custom export to PDF --> to export multiple
+ pages to PDF and to preserve th ASTRON logo in the export
*******************************************************************************
@@ -140,4 +256,59 @@ git remote remove <remote name> # remove a remote repo
- .
\ No newline at end of file
+*******************************************************************************
+* Markdown
+*******************************************************************************
+
+Text will wrap.
+
+Backslash is escape chararcter.
+
+# Heading 1
+## Heading 2
+### Heading 3
+#### Heading 4
+##### Heading 5
+###### Heading 6
+
+Horizontal rules three or more of ***, ___, ---
+
+*italic*
+_italic_
+**bold**
+__bold__
+**bold and _bolditalic_** combined
+`boxed`
+~~strike through~~
+
+Block quotes (alinea with an indent bar):
+> Block text will wrap
+
+Unordered list using *, -, +, indent >= 1 space
+* Main item 1
+* Main item 2
+ * sub item 2a use 2 trailing spaces for return inside paragraph
+ * sub item 2b
+
+Ordered list
+1. Main item 1
+2. Main item 2
+ 2.1 sub item 2a
+ 2.2 sub item 2b
+
+Images
+
+
+![Logo][image1]
+
+[image1]:web link to image file
+
+Links:
+[ASTRON]:https://www.astron.nl
+
+Table:
+|col1 | col2| Col3 | column titles
+|---|:---:|--:| >= 3 dashes, colon for left, center, right align
+| row text | row text | row text|
+| row text | row text | row text|
+
diff --git a/applications/lofar2/doc/prestudy/desp_radiohdl_article.txt b/applications/lofar2/doc/prestudy/desp_radiohdl_article.txt
index c1e615ead14324c22bcd41e7781a71960a1b5f44..58b182f243ea6b85dd967e1df00f1145376b0f47 100644
--- a/applications/lofar2/doc/prestudy/desp_radiohdl_article.txt
+++ b/applications/lofar2/doc/prestudy/desp_radiohdl_article.txt
@@ -14,28 +14,9 @@ The name RadioHDL reflects that it was first used for HDL development in FPGA pr
astronomy, but it can be used for any HDL development project.
-*******************************************************************************
-* 2) User guide topics
-*******************************************************************************
-
-a) Introduction:
-
-RadioHDL is a highly flexible automated build environment for HDL source code. The HDL is
-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 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)
-
+Technology independence
+- Using sim models
+- c_technology = sim or using g_sim?
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,
@@ -58,128 +39,34 @@ of HDL libraries.
Fig 2. Organize firmware in libraries (see 30_FWbuild_Eric, SKA Hongkong)
+
Features:
-- RadioHDL gear scripting based on Python 3.x
-- Configuration files to define the sources and how to build them
+- RadioHDL scripting based on Python 3.x
+- Configuration files to define the sources and how to automatically build them
- Separation of source files and build result files
- All HDL organised in HDL libraries that
. provide hierarchical structure and promote reuse
+ . can be used to build different revisions of the same source code based on generics
. allow separation of technology dependent libraries, board specific libraries, general
libraries and application specific libraries
- . 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?
+*******************************************************************************
+* Open issues:
+*******************************************************************************
+- Support more roots in RADIOHDL_WORK for searching HDL libraries
+- Central HDL_IO_FILE_SIM_DIR = build/sim --> Project local sim dir
+- avs_eth_coe.vhd per tool version? Because copying avs_eth_coe_<buildset>_hw.tcl to $HDL_BUILD_DIR
+ copies the last <buildset>, using more than one buildset at a time gices conflicts.
+- RadioHDL improvements requested by CSIRO for Vivado
-c) Config files:
- 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, 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.
-
- 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
-
-* Operating system
- RadioHDL supports both Windows and Linux operating systems. The following tools need to be
- availabel in order to build target files (TBC):
- - Make (available in /bin for win32 platforms)
- - Python 3.x
- - Python libraries (numpy, pylatex, yaml)
-
-* Environment variables
-
- .bashrc
- - ALTERA_DIR is set to where Altera tool version is installed (i.e. Quartus)
- - MENTOR_DIR is set to where Mentor tool version is installed (i.e. Modelsim)
- - MODELSIM_ALTERA_LIBS_DIR is set to where the compiled Altera tool versions HDL libraries
- for simulation with Modelsim are stored
-
- init_<my_project>.sh
- - RADIOHDL_WORK is set to location of this init_<my_project>.sh and defines the root
- directory from where all HDL libraries source files (hdllib.cfg) can be
- found
-
- - RADIOHDL_BUILD_DIR is set to ${RADIOHDL_WORK}/build and defines where all build results will
- be put
- - HDL_IOFILE_SIM_DIR is set to ${RADIOHDL_BUILD_DIR}/sim and defines where Modelsim simulation
- will keep temporary file IO files.
-
- init_radiohdl.sh
- - RADIOHDL_GEAR is set to location of this init_radiohdl.sh and defines the root directory
- of where the RadioHDL tool is installed.
- - RADIOHDL_CONFIG is set to ${RADIOHDL_GEAR}/config if not already defined by the user and
- defines where the central configuration scripts for buildsets (unb1, unb2b)
- and tools (modelsim, quartus) are kept.
-
- Environment variables for build tools (e.g. modelsim, quartus) are set automatically (TBC)
- MODEL_TECH_DIR
-
-
-* Environment files
-
- Altera hdl_user_components.ipx:
- This hdl_user_components.ipx defines where Quartus QSYS searches for user components. The
- init_<my_project>.sh copies hdl_user_components.ipx from $RADIOHDL_WORK to
- ${ALTERA_DIR}/ip/altera/user_components.ipx.
-
-
-
-f) Source directory structure
+*******************************************************************************
+* Source directory structure
+*******************************************************************************
RadioHDL requires that:
@@ -252,107 +139,15 @@ The technology/ directory contains several technology dependent libraries of ven
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
-
-
-
-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 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/
- # creates build/unb1/quartus_sh --> empty dir, why is it there?
-> quartus_config unb1 # creates build/unb1/quartus/<hdllib libraries> for synthesis
- # creates build/unb1/quartus/technology_select_pkg.vhd
-> modelsim_config unb1 # creates build/unb1/modelsim/<hdllib libraries> for simulation
- # creates build/unb1/modelsim/modelsim_project_files.txt for Modelsim commands.do
- # creates build/unb1/modelsim/technology_select_pkg.vhd
-> run_qsys unb1 unb1_minimal_qsys
-
-> run_modelsim unb1 &
-
-
-*******************************************************************************
-* Run RadioHDL with SVN
-
-echo "Uniboard trunk is selected"
-export SVN=${HOME}/svnroot/UniBoard_FP7
-#Setup RadioHDL environment for UniBoard2 and and new Uniboard1 applications
-. ${SVN}/RadioHDL/trunk/tools/setup_radiohdl.sh
-# Support old UniBoard environment (including Aarfaac and Paasar)
-. ${SVN}/RadioHDL/trunk/tools/setup_unb.sh
-
-
+* Simulation using file IO
*******************************************************************************
-* 2) User guide topics
+HDL_IOFILE_SIM_DIR is set to ${RADIOHDL_BUILD_DIR}/sim and defines where Modelsim simulation
+ will keep temporary file IO files.
-*******************************************************************************
-* 3) Programmers guide topics
-*******************************************************************************
-
-RadioHDL gear directory structure
-$RADIOHDL_GEAR/config # central config files for buildsets and tools
- /core # RadioHDL gear scripts
- /doc # manuals
- /ise # scripts for Xilinx ISE, Impact tools
- /modelsim # scripts for Mentor Modelsim tool
- /quartus # scripts for Altera Quartus, SOPC, QSYS tools
-
- init_radiohdl.sh # Initialize RadioHDL for a project at $RADIOHDL_WORK
-
- generic.sh # Collection of useful functions
-
- # Scripts to adopt RadioHDL configuration parameters as environment variables
- # or paths
- set_config_path # expand config paths
- set_config_variable # export config variables
- set_hdllib_variable # export hdllib variables
-
-*******************************************************************************
-* Open issues:
-*******************************************************************************
-- Support more roots in RADIOHDL_WORK for searching HDL libraries
-- Central HDL_IO_FILE_SIM_DIR = build/sim --> Project local sim dir
-- avs_eth_coe.vhd per tool version? Because copying avs_eth_coe_<buildset>_hw.tcl to $HDL_BUILD_DIR
- copies the last <buildset>, using more than one buildset at a time gices conflicts.
-- RadioHDL improvements requested by CSIRO for Vivado
\ No newline at end of file