Demonstration of Riviera-PRO and GitLab Integration in Docker Based Environment

This Application Note discusses the steps required to set up and run the demonstration design presenting how to put Riviera-PRO into a self-managed GitLab infrastructure using the Docker images. Riviera-PRO run within a GitLab job performs a simulation and collects the coverage statistics. The design used in this App Note is available on request. Please contact Aldec support to receive it.

Demo Prerequisites

• Linux operating system

• Installed Python >= 3.8

• Installed Docker® and permissions to use it

• Local docker image with Riviera-PRO: aldec/riviera-pro:latest

  Dockerfiles and docker images for selected Linux distributions can be requested from Aldec's support team.

• Demo design

  The design used in this presentation is available on request. Please contact Aldec support to receive it.

• Valid license server pointed by the ALDEC_LICENSE_FILE environment variable

Setup Demo Environment

Install required python packages:

python3 -m pip install -r requirements.txt

Execute the python script:

python3 gitlab_demo.py --create

The script pulls docker images for GitLab™ server instance (2.86GB) and gitlab-runner (760MB) so it may take some time. Then, it creates docker containers from images and configures them through API. Next, it will upload an open source based project containing two branches: main and coverage. The script will also create a modified docker image with Riviera-PRO (based on the original image aldec/riviera-pro:latest) and tags it as aldec/riviera-pro:demo. The modified image includes the make, python, and perl packages that are required by the example project.

Upon completion, the script displays the basic information about the access to the instance (the user is advised to write this information down):

GitLab URL: http://x.x.x.x:8880
GitLab initial root password: xxxxxxxxxxxxxxxxxxxxxxxxx
GitLab root personal API access token: xxxxxxxxxxxxxxxxxxxxxxxxx
GitLab user name: demo-user
GitLab user password: xxxxxxxxxxxxxxxxx

GitLab Overview

GitLab™ is a DevOps platform that supports every aspect of the software project management. Its main features include:

• Planning

  • Creating, tracking and assigning issues to milestones.

  • Tasks allowing splitting issues into smaller work units.

  • Checklists allow the user to manage completions of issues and merge requests or tasks using simple checkboxes.

  • Wiki based project documentation.

  • Gathering, documenting and tracking business and system requirements.

• Creating

  • Integrated Git based repository.

  • Web based branch management and commit graph.

  • Merge requests with code coverage features.

  • Supports the full workflow of code review, including quick actions.

  • Web IDE that allows you to edit and commit files from the web browser.

• Verification

  • Built-in Continuous Integration/Continuous Delivery (CI/CD)

  • GitLab runners with horizontal autoscaling.

  • Pipelines allowing orchestrating jobs and creating very complex structures from them.

  • Job artifacts that could be used to pass files between jobs or prepare deployments.

The above features are suited for software projects but can be successfully used in hardware designs. For example, artifacts can be used to send once compiled libraries to multiple simulation jobs or to collect *.acdb files from multiple jobs to merge them and generate reports. The concepts such as compilation, unit tests, code linting or code reviews are similar in both types of projects and only the applied tools are different.

GitLab Community Edition (self-hosted) is free even for commercial use and can be run as a docker container or installed from an Omnibus package. The official documentation contains the recommended architecture structure for three popular cloud services: AWS, Azure and GPC. Hosting GitLab in a cloud brings a big advantage as it allows us to use the autoscaling feature of the cloud. For example, GitLab can provision new EC2 instances or spawn jobs in AWS Fargate. Another option is using it as SaaS. In that case repository, artifacts and other data can be hosted on gitlab.com, but the user can provide gitlab-runners from his/her own infrastructure.

GitLab is not the only CI/CD platform that can be used in a workflow of a chip design project. Other worth mentioning platforms are:

• Jenkins

• TeamCity

• CircleCI

Advantages of Using Docker

There are several GitLab runner executor types. The basic one is the shell executor which spawns new jobs directly in the host shell. Various software used in CI/CD jobs may have different dependencies. Upgrading the software version requires uninstalling old version and installing a new one with possibly new dependencies on all hosts. Maintaining infrastructure in such an approach may be a challenge for the IT departments. Using the network shares to host the software may not be a solution as EDA applications take hundreds of GBs of disk space and the network bandwidth may turn out to be a bottleneck.

The solution for the above issue can be docker containers. To change the CI/CD tool from shell to the docker executor, just add a line with a valid docker image name in the .gitlab-ci.yml Gitlab configuration file, for example:

image: "registry.example.com/my/image:latest"

A docker image contains software and its all dependencies. A docker container created from an image is fully separated from the host libraries so it solves the problems with compatibility and dependency conflicts. After upgrading software to a newer version, the user needs only to push a new image to the docker private repository. The versions of the local images are checked before every job. If the docker repository contains a new version then it is pulled and cached locally. What's more, docker images are built with layers. Only the modified layer and subsequent ones are downloaded. This allows minimizing the network traffic.

The following demo shows a configuration with a single gitlab-runner which can take up to two jobs at the same time, allowing us to demonstrate CI/CD main features on a single host. In a production environment the created structure is usually much more complex, but isolating software required by CI/CD in docker images allows the user to easily manage even large infrastructure. It is worth noting that a GitLab instance and runner almost never should be hosted on the same machine and such a configuration has been presented only for demonstration purposes.

Work pools can be controlled by GitLab itself or by Kubernetes. In the first case, adding new test machine requires only installation of gitlab-runner and its registration in the GitLab instance. The second approach assumes that control of spawning job containers will be passed to a Kubernetes cluster. Adding a new machine takes place through registering it as a Kubernetes cluster node.

Docker images are also a straightforward solution in case of cloud computing. GitLab supports solutions like autoscaling AWS EC2 instances, AWS Fargate (managed container service), AWS EKS (managed Kubernetes service) and similar. Cloud services may be integrated with on-premise infrastructure creating an entity called hybrid cloud. Cloud resources can be requested dynamically on demand extending local computing power when needed. For example, additional test instances may be spawned out of work hours to utilize free software licenses. Using docker images in such cases ensures that job environment will be the same no matter where the job is executed (in a cloud or on premise).

Demo Walkthrough

When creation of the environment is completed, open a web page pointed with the GitLab URL entry in the output of the script. It should look as follows:

Log in with the user name and password shown in the output of the script. The dashboard will contain a single example project:

The project is a modified version of the open source VeeR EH1 RISC-V Core design. The only difference is that the .gitlab-ci.yml file controlling CI/CD of the project in the GitLab environment has been included in this version. The file has the YAML format and is placed in the root directory:

The CI/CD YAML syntax reference can be found in the GitLab documentation.

The .gitlab-ci.yml file has the following major sections:

• default - describes the fields with default values that can be overridden by defining them explicitly in the jobs.

  • image - defines the default docker image used by the jobs. In this case, it is a modified Riviera-PRO image including the make and perl packages.

  • retry - defines how many times a job execution will be repeated in case of failure.

• variables - defines global variables visible in the whole .gitlab-ci.yml file and pass them to all job's scripts as the shell environment variables. It can be used, for example, for pointing license servers.

• stages - defines stage count and its order in pipeline. In the default configuration, the first job of a next stage is executed only if all jobs from the previous stage finish with the success status. The jobs from the same stage can be executed in parallel.

• version_info - describes the first job in pipeline. The main item in every job is the script section defining a sequence of commands that will be executed in the runner shell. In our case, the commands just display the Riviera-PRO version on the console. The job successes only if all the commands in the sequence return 0 as the exit code. The job has also defined the image item which overrides the docker image tag from the default section with aldec/riviera-pro:latest since the command in the script section works on that image. The stage item assigns the job to the stage where it will be executed. The Bin directory is added to PATH in the Riviera-PRO image so the asim and other commands can be placed directly in the script section without sourcing the setenv.sh file.

• cmark_test - another job. The variables section sets the RV_ROOT variable required by the original project makefile so that it points to the path where the whole project will be cloned on the runner. As the project may have assigned different types of runners (docker, shell, etc.) it uses the CI_PROJECT_DIR GitLab predefined variable. The artifacts section contains settings for files and folders that should be preserved after the job is finished. These files (e.g. detailed coverage, simulation logs) can be downloaded with a web browser or used in other jobs in next stages (e.g. libraries compiled once in an early stage can be used by many simulation jobs in next stages). The script section contains the make execution and simple check of simulation results based on searching the log file for specific strings.

• hello_world_test - similar job to the previous one. The only difference is the name of the test that is passed to the make command.

The pipeline for both branches (main and coverage) were triggered during configuration of the GitLab instance in a python script. To track the progress, pick the Build | Pipelines option from the Main menu and click the pipeline of the main branch:

The page displayed below shows the structure of the pipeline created from the .gitlab-ci.yml file. There are two stages (build and test) with assigned jobs. The build stage is already successfully completed and two jobs in the test stage are running in parallel:

Clicking on the job status shows console logs:

When the job is finished the page allows the user to download artifacts (simulation log in our case):

The aldec/riviera-pro:demo docker image created by the script does not contain the RISC-V GNU Compiler Toolchain since compilation from sources may take several hours. Instead of building test programs, Makefile uses the already created .hex binary files that will be loaded into memory. The files are listed in the job logs:

Building a custom docker image is shown in the Docker Application Note. It uses RISC-V GNU Compiler Toolchain as an example of the included tool and the image built with that example is compatible with this demo. The custom image may be built before (which results in using the modified image from the start) or after executing the python script. The second approach requires to re-run the jobs manually to see the effect:

Coverage Integration

GitLab uses specific code coverage format called Cobertura which is used among other things in code review. For better integration of the Aldec products with the CI/CD workflow, the script converting Aldec's implementation of UCDB (ACDB) to the Cobertura format is provided.

The demo-design project contains the coverage branch showing how CI/CD with coverage collecting could look like. Since the source project does not support coverage, the Makefile file needs to be modified as shown below:

The .gitlab-ci.yml file also needs to be modified. The required changes are listed below:

• Added the third stage named coverage.

• Added .acdb files to artifacts in the cmark_test and hello_world_test jobs.

• A new job named merge_coverage. It contains dependencies section that specifies jobs from which artifacts are used. The section lists the jobs that produced the .acdb files. The report subsection in the artifacts section describes the format and name of the file with coverage data. The script section contains the commands that merge the .acdb files from separate jobs and export data coverage to UCDB XML format. Next, the ucdb2cobertura.py script converts the data in the UCDB XML format to the Cobertura format. Since Cobertura can only mark the covered and not covered lines directly in GitLab, the full coverage report created with Riviera-PRO (HTML) is also generated and added to the artifacts.

The coverage visualization is visible in pull requests. To present this feature, an example merge request was created during the demo project configuration. It can be accessed by selecting the Code | Merge requests option and choosing coverage feature in merge request. If pipeline status is still Running, please wait and refresh the page as the functionality requires the artifact from the last job in the stage. Exemplary changes in SystemVerilog source code can be viewed by clicking the Changes tab and selecting a SystemVerilog file:

The coverage visualization allows the user to see the lines covered and not covered by existing tests in the modified parts of code. The cover status is indicated by the vertical bars next to the line number. A green bar denotes that the line was executed at least once; a red bar in turn informs that the line was not executed. Such visualization provides information on how many changes and new code are covered by existing tests which is crucial when assigning tasks to QA teams.

The full version of the HTML coverage report can be downloaded with the Download button accessible from the artifacts of the merge_coverage job: