Container Setup


The Github repository for the Xilinx Video SDK includes predefined dockerfiles which can be used to easily create Docker images with the Xilinx Video SDK for different OS configurations. There are different Dockerfiles for on-prem and Amazon EC2 VT1 usage. The Dockerfiles included in the repository can be used as-is or customized based on end-user needs.

The instructions below explain how to create and then launch a Docker image from one of the Dockerfiles included in the Xilinx Video SDK repository. A working installation of Docker is required.

IMPORTANT: Whether working on premises or on Amazon EC2 VT1 instances, each Xilinx device can have a single point of access (whether host or container). Having multiple container instances access the same device is not currently supported and can lead to unpredictable errors.


Working with Docker Amazon EC2 VT1

Creating a Docker Image for Amazon EC2 VT1 Usage

  1. If not already available, clone the video-sdk repository on your machine:

    git clone https://github.com/Xilinx/video-sdk -b v2.0 --depth 1
    
  2. Navigate to the root of the video-sdk repository:

    cd path/to/video-sdk
    
  3. Build the docker image using the supplied Dockerfile corresponding to the desired OS:

    docker build -t video_sdk_image:v2 -f dockerfiles/vt1/Dockerfile.<Desired OS> .
    

Launching a Docker Container on Amazon EC2 VT1

  1. Gather the User BDFs and renderIDs of the Xilinx devices present in your system. For detailled information on how to do this, refer to the instructions for looking-up the User BDF and renderID.

    xbutil examine
    ...
    ls /sys/bus/pci/devices/<Domain>\:<Bus>\:<Device>.<Function>/drm
    
  2. Run the Docker container using the --device option with the renderID (user function port) of the desired devices to make them accessible by the container:

    docker run -it --device=/dev/dri/renderD<ID1>:/dev/dri/renderD<ID1>
                   --device=/dev/dri/renderD<ID2>:/dev/dri/renderD<ID2>
                   video_sdk_image:v2 /bin/bash
    
  3. Once in the container, validate that the desired devices have been successfully mapped and can properly be used:

    source /opt/xilinx/xrt/setup.sh
    xbutil examine
    

NOTES

  • The xbutil reset command should not be used from within containers running on Amazon EC2 VT1 instances. The command will kill any job running on the devices, but it will not reset the devices.

  • AWS has created a script to automatically generate the --device option with the renderID of all available devices. The script can be found here Details about how to use this script can be found on the AWS Compute Blog: https://aws.amazon.com/blogs/compute/deep-dive-on-amazon-ec2-vt1-instances/


Working with Docker On-Premises

Creating a Docker Image for On-Prem Usage

  1. If not already available, clone the video-sdk repository on your machine:

    git clone https://github.com/Xilinx/video-sdk -b v2.0 --depth 1
    
  2. Navigate to the root of the video-sdk repository:

    cd path/to/video-sdk
    
  3. Build the docker image using the supplied Dockerfile corresponding to the desired OS:

    docker build -t video_sdk_image:v2 -f dockerfiles/on_prem/Dockerfile.<Desired OS> .
    

Launching a Docker Container On-Premises

  1. Gather the User BDFs and renderIDs of the Xilinx devices present in your system. For detailled information on how to do this, refer to the instructions for looking-up the User BDF and renderID.

    xbutil examine
    ...
    ls /sys/bus/pci/devices/<Domain>\:<Bus>\:<Device>.<Function>/drm
    
  2. Gather the Management BDFs and xclmgmtID of the Xilinx devices present in your system. For detailled information on how to do this, refer to the instructions for looking-up the Management BDF and xclmgmtID.

    xbmgmt examine
    ...
    cat /sys/bus/pci/devices/<Domain>\:<Bus>\:<Device>.<Function>/instance
    
  3. Run the Docker container using the --device option with the renderID (user function port) and the xclmgmtID (management function port) of the desired devices to make them accessible by the container:

    docker run -it --device=/dev/dri/renderD<ID1>:/dev/dri/renderD<ID1> --device=/dev/xclmgmt<ID1>:/dev/xclmgmt<ID1>
                   --device=/dev/dri/renderD<ID2>:/dev/dri/renderD<ID2> --device=/dev/xclmgmt<ID2>:/dev/xclmgmt<ID2>
                   video_sdk_image:v2 /bin/bash
    
  4. Once in the container, validate that the desired devices have been successfully mapped and can properly be used:

    source /opt/xilinx/xrt/setup.sh
    xbutil examine
    

NOTES

  • The xbutil reset command will reset the specified device as well as all other devices present on the same Xilinx card, even if these other devices are not mapped to the container. In order to avoid reset conflicts, Xilinx strongly recommends mapping all the devices of a given card when running the container. For details on how to determine which devices are on the same card, consult the following instructions: Mapping Devices to Cards.

  • In the case where a single device is mapped to the container, Xilinx recommends against using the xbutil reset command.

  • Mapping the management port using the xclmgmtID allows using to the xbmgmt card management utility from within the container. Doing so is optional.