GitLab and Riviera-PRO Integration

This app note provides the information required to connect a GitLab project with Continuous Integration (CI) to Riviera-PRO to simulate the RTL project. To make the process clear, we'll go over the important steps. Let's start with GitLab structure.

What is GitLab:

GitLab is a web-based DevOps tool which provides Continuous Integration (CI), Continuous Delivery and Continuous Deployment (CD). GitLab enables users to host their repository either on GitLab or on any other hosts and still harness its CI/CD features. You don't even have to change your Git provider in order to use get GitLab CI/CD. The only requirement to run CI/CD is the presence of a special GitLab CI YAML configuration file. The "gitlab-ci.yml" file is a YAML file where you configure specific instructions for GitLab CI/CD.

In the "gitlab-ci.yml" file, you can define:

The scripts you want to run.
Other configuration files and templates you want to include.
Dependencies and caches.
The commands you want to run in sequence and those you want to run in parallel.
The location to deploy your application to.
Whether you want to run the scripts automatically or trigger any of them manually.

Pipeline:

The scripts are grouped into jobs and jobs run as part of a larger pipeline. You can group multiple independent jobs into stages that run in a defined order. The CI/CD configuration needs at least one job that is not hidden. Pipelines are the top-level component of continuous integration, delivery, and deployment.

Jobs, which define what to do. For example, jobs that compile or test code.
Stages, which define when to run the jobs. For example, stages that run tests after stages that compile the code.

Runner:

GitLab Runner is an application that works with GitLab CI/CD to run jobs in a pipeline. You can choose to install the GitLab Runner application on an infrastructure that you own or manage. Alternatively, you can use the runners on the cloud which is part of the GitLab infrastructure. When you use separate machines, you can have different operating systems and tools, like Kubernetes or Docker, on each. GitLab Runner is open-source and is written in Go. It can run as a single binary; no language-specific requirements are needed. For the purposes of this Application Note, we will be using a local runner installed on a local machine.

Creating a GitLab project:

Visit the GitLab website and register.
Create a blank project
Name the project and either make it public or private depending on your preference.
Add the project files to the GitLab project. For this app note, we will be using one of the code coverage prebuilt examples designs which can be found under "<Riviera-PRO-Installation-Folder> \examples\coverage\coverage_database\testplan_rank". There are two ways to add the files to the GitLab project:
- Using the Upload File button.
- Pushing an existing folder using git.
Then create a new file and call it "gitlab-ci.yml".
Make sure all the project files are added to GitLab properly.
Add the stages, jobs and builds into the gitlab-ci.yml file based on your project. To run Riviera-PRO in batch mode, "vsimsa -do <Run-File-Path>" is used. This command needs to be added under the script in build-job section.
To run the pipeline on our system, we need to install the GitLab runner on our local machine. Here is a complete runner installation documentation provided by GitLab.
- Linux system:
  - Download the installation file here.
  - Install the runner:
    1. Debian or Ubuntu: dpkg -i gitlab-runner_ <arch>.deb
    2. CentOS or Red Hat Enterprise Linux: rpm -i gitlab-runner_arch.rpm
  - Register the runner:
    - sudo gitlab-runner register
    - Enter your GitLab instance URL (ex. https://gitlab.com/).
    - Enter the token you obtained to register the runner.
    - Enter a description for the runner.
    - Enter associated tags: ci, ssh.
    - Provide a runner executer, for example shell.
  - Set the environment variable for Riviera-PRO.
- Windows machine:
  - Download the installation file here.
  - Install the runner:
    1. Create a folder somewhere in your system, ex.: C:\GitLab-Runner and transfer the installation file into it.
    2. Make sure to restrict the Write permissions on the GitLab Runner directory and executable. If you do not set these permissions, regular users can replace the executable with their own and run arbitrary code with elevated privileges.
    3. Run an elevated command prompt.
  - Register a runner:
    1. Run ./gitlab-runner.exe register.
    2. Enter your GitLab instance URL (ex. https://gitlab.com/).
    3. Enter the token you obtained to register the runner.
    4. Enter a description for the runner.
    5. Enter associated tags: ci, ssh
    6. Provide a runner executer, for example shell.
  - Install GitLab Runner as a service and start it.
    1. cd C:\GitLab-Runner
    2. .\gitlab-runner.exe install
    3. .\gitlab-runner.exe start
  - Set the environment variable for Riviera-PRO
    1. Make sure the path for Riviera-PRO is correct by going to Control Panel > System > Advanced System Settings > Environment Variables.
    2. If the path is not correct, select the Riviera-PRO variable and click Edit.
    3. If the path for Riviera-PRO is not listed as a System Variable or User Variable, then create the path by selecting New.
To make sure that the runner is working fine, check /settings/CICD/ and expand runner. If there is a green sign next to your runner's name at the bottom of the page, it's working.
- If there is a black triangle next to your runner’s name, run an elevated command prompt and type: .\gitlab-runner.exe verify and then check your runner again.
Next step is to run the pipeline. To do that, select CI/CD tab from the left side bar and click on Pipelines. Then, click "Run pipelines" on the top right.
Once the run is done, by clicking on pipeline ID and then on the build-job, we can see the console logs. Here is a part of the log for my project.
- If you get an error message saying "Job failed…exec: "pwsh"…" then edit your config.toml file by replacing "pwsh" with "powershell".
- Then restart the gitlab-runner: gitlab-runner.exe restart.
  - If your config.toml does not have any content and/or doesn't include the line: shell = "pwsh" then delete your config.toml file, open an elevated command prompt and type: .\gitlab-runner.exe stop, and then create a new runner following step 8.

The design example chosen for this app note provides code coverage and test ranking features which are covered briefly in the following sections. The runme.do file consists of multiple commands to compile, initialize, and simulate the tests, generate report, and generate the test ranking. This file is shown in the image below.

If you'd like to visualize the code coverage results in GitLab, refer to this app note: Cobertura.

Test Ranking

The coverage results in Riviera-PRO is saved into an ACDB database. These results can be ranked by using the acdb rank command that classifies the results basing on contribution of tests to total coverage score. The command allows comparing a single coverage result against all others to determine its usability. The test ranking feature enables us to realize if we are doing excessive testing which results in longer simulation time and increase in project costs. Let's look at the test ranking results of the example design that we used in this app note.

The result shows that only 3 tests are required to achieve 100% code coverage and the rest of the 3 cases are extra. This feature can expedite the simulation process and save time and cost for big projects.