ci.csn.khai.edu

CI-infrastructure of Computer Systems and Networks Department

How to perform VHDL projects with CI support in ci.csn.khai.edu

Note: In order to be able to contribute to any projects in Gerrit Code Review of ci.csn.khai.edu you must have an account in the domain @csn.khai.edu (@student.csn.khai.edu). Also make sure that your Gerrit Code Review account is configured and all necessary software (git, git-review) is installed.

Design tools for VHDL projects

Note: There are no any specific requirements for FPGA CAD tools in order to perform VHDL projects with CI support. The choice is mainly based on personal preferences. The minimum required set of software assumes some VHDL project entry tool, simulation tool (it’s better to choose those that are supported by vunit framework, which is used for testing in Jenkins (vunit-hdl-code-check).

In our case Sigasi Studio Creator is used as VHDL project entry tool, ModelSim-Altera Edition (includes Starter Edition) as a simulation tool and Quartus II Web Edition (13.0sp1) as a synthesis tool.

Source code structure for VHDL projects

In general, there no any special requirements for source code organization of VHDL projects, but it is recommended to adhere the following structure (especially in cases when project contains testbench-modules in vunit-like format):

  1. For simple projects

     project_name/
 ├── file_1.vhd
 ├── tb_file_1.vhd
 ├── file_2.vhd
 ├── tb_file_2.vhd

  2. For complex (hierarchical) projects

     project_name/
 ├── module1
 │     ├── file_1.vhd
 │     └── tb_file_1.vhd
 ├── module2
 │     ├── file_2.vhd
 │     └── tb_file_2.vhd

Note: Please note naming conventions for testbench-modules - use tb_ or _tb prefix in file name.

In this post, as for the labworks on “Development Technologies of Computer Systems” course we will use hierarchical approach of VHDL source code organization:

dtcs/
├── lab1
│     ├── file_1.vhd
│     └── tb_file_1.vhd
├── lab2
│     ├── file_2.vhd
│     └── tb_file_2.vhd

Note: It is strongly recommended to use .gitignore file when creating a project. Don’t forget to exclude “junk” files or folders, which are most often created during synthesis/compilation/verification stages or belong to specific CAD tools. More details on how to use .gitignore.

Cloning a VHDL project from the ci.csn.khai.edu repository

In order to clone any project from ci.csn.khai.edu to your local computer, you have to:

  1. Log in under your account in the Gerrit Code Review system.
  2. Open the List of projects in the Gerrit Code Review (Projects → List).

  3. Find the required project (field Filter):

    Dtcs vhdl gerrit project

    Note: Each student has a personal repository (repositories) which name (path) corresponds to surname (second name) and each of the disciplines is defined through so-called “tag”. For example: ivanov/dtcs, popov/dtcs. For discipline “Development Technologies of Computer Systems” tag dtcs is used.

  4. Open project and clone it to the local computer with git clone command (executed in the terminal window):

    Git clone dtcs vhdl

    $ git clone ssh://[email protected]:29418/kulanov/dtcs
Cloning into 'dtcs'...
remote: Counting objects: 3, done
remote: Finding sources: 100% (3/3)
remote: Total 3 (delta 0), reused 3 (delta 0)
Receiving objects: 100% (3/3), done.
Checking connectivity... done.

    Note: You can check that cloned kulanov/dtcs repository is empty (not taking into account some hidden files and directories). But till the end of the term it should contain all necessary labworks in respective lab directories.

Creating a VHDL project and configuring .gitignore file

Hereinafter in the post let’s consider an example on how to perform labworks in “Development Technologies of Computer Systems” course with corresponding hierarchical organization of VHDL source code files.

  1. Create a new VHDL project in Sigasi Studio Creator. As a project working directory specify path to the newly cloned project.
  2. Create a directory with the appropriate name, for example lab1.
  3. Create/Add source project files (*.vhd) in the lab1 directory (for example d_ff.vhd, tb_d_ff.vhd).

  4. Check the current status of the local repository with git status command:

    $ git status
On branch master
Your branch is up-to-date with 'origin/master'.
Untracked files:
  (use "git add <file>..." to include in what will be committed)
      .library_mapping.xml
      .project
      .settings/
      lab1/
nothing added to commit but untracked files present (use "git add" to track)

  5. Create .gitignore file and add there files/directories created by (related to) Sigasi Studio Creator (.project, .library_mapping.xml, .settings). Now all changes in these files/directories will not be tracked by git (check this with git status command):

    $ git status
On branch master
Your branch is up-to-date with 'origin/master'.
Untracked files:
   (use "git add <file>..." to include in what will be committed)
       .gitignore
       lab1/
nothing added to commit but untracked files present (use "git add" to track)

    Note: If the project is created in other CAD tools (Quartus II, ModelSim etc.) do not forget to add non-related to project files/directories in .gitignore.

Sending a VHDL project on review

Before sending VHDL project (or project changes) on review it is necessary to track changes that took places. Use git add command to add the contents of the working directory to the index:

$ git add. # '.' means all changes in the current directory tree

Let’s check current status of the repository:

$ git status
On branch master
Your branch is up-to-date with 'origin/master'.
Changes to be committed:
  (use "git reset HEAD <file>..." to unstage)
	new file:   .gitignore
	new file:   lab1/d_ff.vhd
	new file:   lab1/tb_d_ff.vhd

Commit changes in the local repository with git commit command:

Add lab1 project

This patch adds implementation of `dff flipflop` with respective
testbench file as a part of labwork 1 for dtcs course

# Please enter the commit message for your changes. Lines starting
# with '#' will be ignored, and an empty message aborts the commit.
# On branch master
# Your branch is up-to-date with 'origin/master'.
#
# Changes to be committed:
#       new file:   .gitignore
#       new file:   lab1/d_ff.vhd
#       new file:   lab1/tb_d_ff.vhd
#

Note: It is recommended to adhere Git Commit Good Practice.

The result of git commit command execution:

[master a04d914] Add lab1 project
 3 files changed, 107 insertions(+)
 create mode 100644 .gitignore
 create mode 100644 lab1/d_ff.vhd
 create mode 100644 lab1/tb_d_ff.vhd

… and the current state of our project repository:

$ git status
On branch master
Your branch is ahead of 'origin/master' by 1 commit.
  (use "git push" to publish your local commits)
nothing to commit, working directory clean

In order to send changes on review in Gerrit Code Review system use git review command:

$ git review
Creating a git remote called "gerrit" that maps to:
	ssh://[email protected]:29418/kulanov/dtcs.git
Your change was committed before the commit hook was installed.
Amending the commit to add a gerrit change id.
remote: Processing changes: new: 1, refs: 1, done
remote:
remote: New Changes:
remote:   https://ci.csn.khai.edu/gerrit/5 Add lab1 project
remote:
To ssh://[email protected]:29418/kulanov/dtcs.git
 * [new branch]      HEAD -> refs/publish/master

Working with VHDL project in Gerrit Code Review

The project that was sent on review in the Gerrit Code Review will appear in your personal menu (My→Changes, section Outgoing reviews):

Outgoing review dtcs vhdl projects

… click on ‘Add lab1 project’ project changes (the picture below is clickable):

Image

Section 1. Commit message. Change-Id is generated and added to your commit message automatically. Never delete or change Change-Id value when modifying commit message. More information about what is Change-Id and how it is used in Gerrit Code Review.

Section 2. Contains an information about the patch (changes) that is on review (Owner, Reviewers, Project, Branch, etc.) and control buttons (Cherry Pick, Rebase, Abandon and Follow-Up). For the first time, you will need the Reply button…(adding comments, voting +1 / -1).

Note: When adding new patch sets of VHDL projects on review, the user jenkins is automatically added as a “reviewer”. His task is to check the source code for syntax errors and perform corresponding unit tests (if any exist) described in the testbench modules (files). If no “problems” are found, then jenkins user votes +1 (see Verified label), otherwise -1. In Section 5 (History) you can see Jenkins Job execution results (SUCCESS).

Section 3. Includes different commit information, e.g.: Author of the commit, real Committer of the patch set (sometimes it can be different people), etc.

Section 4. The project files (repository) that were created or modified in the current patch set are displayed here. You can select the appropriate file to view the entire history of its changes, including differences between patch sets.

Section 5. Contains information about any activity of proposed changes either the author of the patch as all users who participate in the review of the source code, including the jenkins user. Here you can also get an information about status of jobs performed in Jenkins.

Gerrit review history view

Viewing statuses of Jenkins Jobs

To get status of the Jobs in Jenkins, click on the appropriate link url. In our case the link to the Job looks like as follows (see the figure above): https://ci.csn.khai.edu/jenkins/job/vunit-hdl-code-check/1/

One of the “useful” tabs is the Console Output tab, which allows you to get all information about the Jobs performed by jenkins.

Jenkins vunit ghdl job build demo

Some part of the output results (Console Output) of our Job in Jenkins (for the given project) looks like as follows:

Compiling lab1/tb_d_ff.vhd into lab1_lib ...
Compiling lab1/d_ff.vhd into lab1_lib ...
Running test: lab1_lib.tb_d_ff.test_write_data
Running test: lab1_lib.tb_d_ff.test_synchrounous_reset
Running 2 tests

Starting lab1_lib.tb_d_ff.test_write_data
simulation stopped @4ns with status 0
pass (P=1 S=0 F=0 T=2) lab1_lib.tb_d_ff.test_write_data (1.5 seconds)

Starting lab1_lib.tb_d_ff.test_synchrounous_reset
simulation stopped @2ns with status 0
pass (P=2 S=0 F=0 T=2) lab1_lib.tb_d_ff.test_synchrounous_reset (0.7 seconds)

==== Summary ====================================================
pass lab1_lib.tb_d_ff.test_write_data         (1.5 seconds)
pass lab1_lib.tb_d_ff.test_synchrounous_reset (0.7 seconds)
=================================================================
pass 2 of 2
=================================================================
Total time was 2.2 seconds
Elapsed time was 2.2 seconds
=================================================================
All passed!
Finished: SUCCESS

The results show that the source code of the project does not contain syntax errors and all tests were successful passed.