Artifacts

Artifacts are an essential part of any pipeline. This document describes the artifact store's features and how to upload and download your own artifacts.

Overview

The artifact store provides long-term storage for artifacts. Artifacts are files or folders that have been produced by jobs or uploaded by users. The artifact store means users can:

• Have a single source of truth for a FPGA design's files and folders.
• Download files once a workflow has finished
• Upload files for use in jobs and workflows.

Uploading artifacts

To upload a file as an artifact to the store, click the 'upload file' button. You will then be able to upload a file as well as declare an Artifact type. Types determine the usage of the artifact and are used to determine if a specific file location must be used. The artifact types available are:

• Platform: Used for uploading hardware platforms to be used in software-defined environments.
  • When used in a runner containing Vitis Unified Development Environment, platforms are be default downloaded into the /tools/Xilinx/Vitis/<Vitis version>/platforms. Platform folders must be compressed into a .zip or .tar.gz before upload.
• Firmware: Used for uploading files for use in firmware, such as sysroot.
  • When used in a runner, firmware files are downloaded to the workspace folder. Firmware folders must be compressed into a .zip or .tar.gz before upload.
• Library: Used for uploading library files, such as the Vitis library.
  • When used in a runner, library files are downloaded to the workspace folder. Library folders must be compressed into a .zip or .tar.gz before upload.
• Build: Used for distinguishing files that have been created by a build job.
  • When used in a runner, build files are downloaded to the workspace folder. Build folders must be compressed into a .zip or .tar.gz before upload.
• Board: Used for uploading board files for use in hardware. Vivado that have been created by a build job.
  • When used in a runner containing Vivado, platforms are be default downloaded into the /tools/Xilinx/Vivado/<Vivado version>/data/boards/board_files. Board folders must be compressed into a .zip or .tar.gz before upload.
• Miscellaneous: Used for other files that do not fit into any of the above categories.
  • When used in a runner, build files are downloaded to the workspace folder.

Uploading platform artifact

To upload a platform artifact, you must first either create your own platform or download a pre-made platform from Xilinx . This folder must be compressed to .zip or .tar.gz.

In the File Upload page, choose the file you wish to download and ensure the artifact type is Platform. Click submit to begin uploading. Since platform files are large, this process may take a few minutes.

Once finished you will be redirected to the artifact store and able to see the file you uploaded in the list of artifacts.

Using artifacts as input in a job

Artifacts within may be used as inputs to jobs. Within the job the key input: followed by the artifact: and a list of the artifacts is used to indicate the artifacts that are to be placed on the runner. The location of where the artifact is placed on the runner is dependent upon the artifact type. If the artifact is type miscellaneous, it will be placed in the current working directory in the container where the job is running, which by default is ~/.

In the following example, the artifact example-1.txt is used in the job job-1.

jobs:   
 job-1:
  runner: example-runner
  input: 
   artifact: 
    - example-1.txt
  steps:
   ...

Outputting artifacts from a job

Files that are generated by a job can be stored as an artifact. The artifact is located relative to the current working directory, which by default ~/. Absolute directories may also be used.

jobs:   
 build-SW-emu:
  runner: example-runner
  output: 
   artifact: 
    - example-1.txt
  steps:
   ...

Complete example

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 first example.

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; 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