Workflows

Workflows form the framework for orchestrating your jobs. Effective use of workflows reduces development time and allows for efficient use of resources. This document describes workflow features and provides examples.

Overview

A workflow is a selection of jobs that are to be run autonomously. A pipeline consists of one or more workflows that define the entire build and test process. Workflows allow users to:

• Run designs in clean environments to quickly locate bugs.
• Reuse jobs in different workflows.
• Run multiple jobs in parallel.

The workflows for a particular pipeline may be found by clicking on the particular pipeline on the pipelines page.

Configuration Examples

Example 1

The following example shows a single workflow that will run two jobs in parallel. To create a workflow, you need a workflow: section in bbx./config.yaml. The workflow requires a unique name, in the provided example the workflow has been named workflow-example. Once the workflow has been declared, you need to allocate jobs to the workflow. This is performed with the jobs key followed a list of jobs to be performed by the workflow. In this example, there are two jobs example-job1 and example-job2. Once the workflow is triggered, these two jobs will run concurrently.

runners:
 example-runner:
  image: work1-virtualbox:5000/ubuntu-generic

jobs:   
 example-job1:
  runner: example-runner
  steps:
   - run:
      name: Say Hello World 1
      command: |
       echo "Hello World 1" 
   
 example-job2:
  runner: example-runner
  steps:
   - run:
      name: Say Hello World 2
      command: |
       echo "Hello World 2" 

workflows:
 workflow-example:
  jobs:
   - example-job1
   - example-job2

Example

The following example shows a two workflows that will run two separate jobs. In this example, there are two jobs example-job1 and example-job2. The first job, example-job1 belongs to workflow-example1 and the second job, example-job2 belongs to workflow-example2. The two workflows can run independently of each other. It is recommended to specify triggers for the workflows if you want them to run on separate occasions under different circumstances. More information about triggers can be found in the Triggers page.

runners:
 example-runner:
  image: work1-virtualbox:5000/ubuntu-generic

jobs:   
 example-job1:
  runner: example-runner
  steps:
   - run:
      name: Say Hello World 1
      command: |
       echo "Hello World 1" 
   
 example-job2:
  runner: example-runner
  steps:
   - run:
      name: Say Hello World 2
      command: |
       echo "Hello World 2" 

workflows:
 workflow-example1:
  jobs:
   - example-job1
 workflow-example2:
  jobs:   
   - example-job2

Example 3

The following example shows a single workflow that will run two jobs sequentially. The first job example-build, synthesises and builds a Vitis project, and the second job jobs, takes the output of the first job and performs a software emulation. As you will notice, there are a number of differences from the previous examples.

This one uses a different image for the runner — this image contains Vitis, while the previous example used a plain Ubuntu image.

The first job (build) takes in a number of input artifacts — these are necessary for Vitis to perform the build. The artifacts specified here include: a platform file xilinx_zcu104_base_202010_1.zip to represent the FPGA board for which we are compiling; a copy of the Arch Linux file system aarch64-xilinx-linux2020_1.zip for the ARM processor to use; a Linux kernel xilinx-zynqmp-common-v2020.1.tar.gz for the ARM processor on the FPGA. More information about these artifacts can be found in the artifacts page. It outputs a single artifact as a compressed file, containing all the files and folders listed under the output artifact field. There is one step which runs a shell script Emulation-SW/build.sh that contains a series of commands to build a project using Vitis.

The second job takes in two artifacts, which include: a platform file xilinx_zcu104_base_202010_1.zip to represent the FPGA board where we are running the simulation; the output of the previous build job. There is one step which runs a shell script ./sw_emu.sh containing the relevant commands to run the simulation. The depends field specifies that the first job, example-build must successfully complete before the second job, example-test can run. The second job will fail if the first job, which it depends on fails.

runners:
 example-runner:
  image: work1-virtualbox:5000/ubuntu-vitis-2020-1

jobs:   
 example-build:
  runner: example-runner
  input: 
   artifact: 
    - xilinx_zcu104_base_202010_1.zip
    - aarch64-xilinx-linux2020_1.zip
    - xilinx-zynqmp-common-v2020.1.tar.gz
  output:
   artifact:
    - Emulation-SW/build.sh
    - Emulation-SW/package    
    - sw_emu.sh
    - Emulation-SW/launch.sh
    - Emulation-SW/launch.expect  
  steps:
   - run:
      name: Run Software Emulation Build
      command: Emulation-SW/build.sh
   
 example-test:
  runner: example-runner
  depends:
   - example-build
  input: 
   artifact: 
    - example-build
    - xilinx_zcu104_base_202010_1.zip      
  steps:
   - run:
      name: Run Software Emulation
      command: ./sw_emu.sh

workflows:
 workflow-example:
  jobs:
   - example-build
   - example-test