Some Enzian infrastructure and application repos have CI configured to automatically run unit tests, build FPGA bitstreams, and publish releases so that users can download them directly.  This article describes how you can configure CI for your Enzian project.

Available runners and images

Runner selection in GitLab is achieved via defining tags: in .gitlab-ci.yml . The pool of runners for the Enzian project takes the following tag specifications:

  • enzian-docker : run the CI job using a docker container, defined by image: 
  • enzian-shell : run the CI job with the GitLab shell executor (deprecated, use the docker runner whenever possible)
  • vivado : the Xilinx Vivado suite will be made available in the environment at /opt 

The following docker images are built and published automatically by the Enzian CI images repo to the ETH GitLab registry:

  • registry.ethz.ch/project-openenzian/ci-images/ubuntu-tini:22.04 based on the upstream Ubuntu 22.04 docker image, but with the Tini init program for containers
  • registry.ethz.ch/project-openenzian/ci-images/xilinx-tools:ubuntu-22.04 based on the ubuntu-tini  image, but with necessary environment variables set for running Vivado in docker
  • registry.ethz.ch/project-openenzian/ci-images/spinal-verilator:ubuntu-22.04  based on the xilinx-tools  image, but with SpinalHDL dependencies and Verilator for simulation
  • registry.ethz.ch/project-openenzian/ci-images/publish:ubuntu-22.04 image to publish release artifacts to the ETH GitLab and link it back to the D-INFK GitLab (see below)

Example configuration

We take the Enzian Static Shell configuration as an example.  To build the bitstream, use both vivado and enzian-docker tags and the xilinx-tools  image.   Upload the built artifacts for a later job to release them on a git tag.

stages:
    - build
    - release
variables:
    GIT_SUBMODULE_STRATEGY: recursive
    GIT_SUBMODULE_FORCE_HTTPS: "true"
build:
    stage: build
    tags:
        - vivado
        - enzian-docker
    image: "registry.ethz.ch/project-openenzian/ci-images/xilinx-tools:ubuntu-22.04"
    script:
        - mkdir build
        - cd build
        - /opt/Xilinx/Vivado/2022.1/bin/vivado -mode batch -source ../build_static_shell_stub_single.tcl
    artifacts:
        paths:
            - build/shell_stub.bit
            - build/shell_stub.ltx
            - build/shell_stub_pblock_dynamic_partial.bit
            - build/static_shell_routed.dcp
            - build/shell_stub_routed.dcp

To create a release on pushing a git tag:

  • create a project on the ETH GitLab, note down the project ID; this project will host the package registry for release artifacts
  • on the ETH GitLab, go to "Settings → Repository → Deploy tokens" and create a token with write_package_registry  permissions; note down the username and token
  • on the D-INFK GitLab, go to "Settings → CI/CD → Variables" and create two variables, PACKAGE_REGISTRY_USER  and PACKAGE_REGISTRY_TOKEN , with the username and token from the previous step
  • create a release job in the .gitlab-ci.yml  and use the publish  image with the following template.  Replace PROJECT_ID  with the ETH GitLab project ID and change ARTIFACT_PATHS  accordingly
release:
    stage: release
    image: registry.ethz.ch/project-openenzian/ci-images/publish:ubuntu-22.04
    script: /publish_artifacts
    rules:
      - if: '$CI_COMMIT_TAG'
    needs:
         - job: build
           artifacts: true
    variables:
        PROJECT_ID: 48046
        PACKAGE_NAME: release
        RELEASE_NAME: 'Release $CI_COMMIT_TAG'
        RELEASE_TAG: '$CI_COMMIT_TAG'
        ARTIFACT_PATHS: |
            build/shell_stub.bit
            build/shell_stub.ltx
            build/shell_stub_pblock_dynamic_partial.bit
            build/static_shell_routed.dcp
            build/shell_stub_routed.dcp

Accessing submodules of private repos in CI

By default, the CI job can only clone public git repos as submodules.  You can either:

  • use a project access token (recommend), or
  • use a personal access token in the CI (not recommended), or
  • if the submodule project is also on the department GitLab:
    • enable CI for the submodule project: "Settings → General → Visibility, project features, permissions → CI/CD"
    • add the parent project to the list of allowed projects to access from CI: "Settings → CI/CD → Token Access → Allow CI job tokens from the following projects to access this project"
      • or maybe turn off the access restriction from CI completely (might have security concerns)

Using the released artifacts

You can configure your application project to fetch the latest release artifacts for use in CI.  An example of this can be found in the Enzian PIO NIC repo.

Adding a new docker image for your own CI pipeline

Enzian CI docker images are built and published to the docker registry on the ETH GitLab automatically.  If you need a new docker image, add the Dockerfile and CI configuration to the CI images repo.

  • No labels