Integration with Docker

Xilinx container runtime is designed to integrate with docker easily.

Add Xilinx Container Runtime into Docker

Docker is allowed to be configured by /etc/docker/daemon.json, the following code snippet adds xilinx contianer runtime.

{
    "runtimes": {
        "xilinx": {
            "path": "/usr/bin/xilinx-container-runtime",
            "runtimeArgs": []
        }
    }
}

Optionally, you can set xilinx as the default container runtime for docker.

{
    "default-runtime": "xilinx",
    "runtimes": {
        "xilinx": {
            "path": "/usr/bin/xilinx-container-runtime",
            "runtimeArgs": []
        }
    }
}

After updating /etc/docker/daemon.json, it’s required to restart docker service for the registration of xilinx-container-runtime being effective.

sudo systemctl restart docker

Configure Xilinx Container Runtime

By defautl, xilinx container runtime will find configuration from file /etc/xilinx-container-runtime/config.toml. Here is default values in this file at installation.

[xilinx-container-runtime]
debug = "/var/log/xilinx-container-runtime.log"

[device-exclusion]
enabled = true
filepath = "/var/tmp/xilinx-device-exclusion.json"

[alias]
enabled = true

This configuration file specify the log filepath for xilinx container runtime. Also, there is flags to use Xilinx devices exclusively and enable device alias, which will be explained later.

Start a Container

Xilinx container runtime can be specified using –runtime flag. If the default runtime was set in /etc/docker/daemon.json, –runtime flag can be omitted.

For environment variables XILINX_VISIBLE_DEVICES and XILINX_VISIBLE_CARDS, the acceptable values include ‘all’ and comma separated integers of card or device index which can be got from previous command line tools.

sudo docker run -it --rm --runtime=xilinx -e XILINX_VISIBLE_DEVICES=all xilinx/xilinx_runtime_base:alveo-2021.1-ubuntu-20.04 /bin/bash
sudo docker run -it --rm --runtime=xilinx -e XILINX_VISIBLE_DEVICES=0,1 xilinx/xilinx_runtime_base:alveo-2021.1-ubuntu-20.04 /bin/bash
sudo docker run -it --rm --runtime=xilinx -e XILINX_VISIBLE_CARDS=all xilinx/xilinx_runtime_base:alveo-2021.1-ubuntu-20.04 /bin/bash
sudo docker run -it --rm --runtime=xilinx -e XILINX_VISIBLE_CARDS=0 xilinx/xilinx_runtime_base:alveo-2021.1-ubuntu-20.04 /bin/bash

For environment variables XILINX_VISIBLE_DEVICES and XILINX_ALLOCATE_CARDS, the input should be xilinx device name and the number of requested card(s) or device(s), eg. ‘xilinx_u30_gen3x4_base_2:1’. Here is few examples below.

sudo docker run -it --rm --runtime=xilinx -e XILINX_ALLOCATE_CARDS=xilinx_u30_gen3x4_base_2:1 xilinx/xilinx_runtime_base:alveo-2021.1-ubuntu-20.04 /bin/bash
sudo docker run -it --rm --runtime=xilinx -e XILINX_ALLOCATE_DEVICES=xilinx_u50_gen3x16_xdma_201920_3:1 xilinx/xilinx_runtime_base:alveo-2021.1-ubuntu-20.04 /bin/bash

Disable Device Exclusive Mode

We are using device exclusive mode by default, which assigns some device only to one container exclusively. In this mode, a device will be locked to the specific container from the time of container being created till the container is stopped. It is easy to disable the device exclusive mode by setting the environment variable ‘XILINX_DEVICE_EXCLUSIVE’ to ‘false’.

sudo docker run -it --rm --runtime=xilinx -e XILINX_VISIBLE_DEVICES=all -e XILINX_DEVICE_EXCLUSIVE=false xilinx/xilinx_runtime_base:alveo-2021.1-ubuntu-20.04 /bin/bash

Use Device Alias

Xilinx U30 device has an alias ‘ama_u30’, so we can allocate the device by its alias if the flag was set to ‘True’ in configuration.

sudo docker run -it --rm --runtime=xilinx -e XILINX_ALLOCATE_CARDS=ama_u30:1 xilinx/xilinx_runtime_base:alveo-2021.1-ubuntu-20.04 /bin/bash