AN 1008: Using the FPGA AI Suite Docker* Image

Download PDF
ID 820119
Date 4/25/2025
Public
Document Table of Contents x
1. Using the FPGA AI Suite Docker Image Overview 2. FPGA AI Suite Docker Image Requirements 3. Setting Up the FPGA AI Suite Docker Image 4. Running the FPGA AI Suite Docker* Container 5. Containerized FPGA AI Suite SoC Design Example Quick-Start Tutorial 6. AN 1008: Using the FPGA AI Suite Docker* Image Document Revision History
1. Using the FPGA AI Suite Docker Image Overview
2. FPGA AI Suite Docker Image Requirements
3. Setting Up the FPGA AI Suite Docker Image
4. Running the FPGA AI Suite Docker* Container
5. Containerized FPGA AI Suite SoC Design Example Quick-Start Tutorial
6. AN 1008: Using the FPGA AI Suite Docker* Image Document Revision History

3. Setting Up the FPGA AI Suite Docker Image

To set up the FPGA AI Suite Docker image:

  1. Install the WSL 2 environment on your Microsoft* Windows* system.
  2. Install a Docker* client. During the client setup, use WSL 2 as the virtualization option.
  3. (Optional) To speed up the container, create or update the .wslconfig file to adjust the host hardware resources (such as CPU and RAM) in the container environment. The .wslconfig file is typically found in C:\Users\<username>\.wslconfig.
    You can use the following example file to create or update your file. Update the lines highlighted in bold text to customize your WSL container environment. 
    # Settings apply across all Linux distros running on WSL 2
[wsl2]
# Limits VM memory to use no more than <memory_allocated> GB, this can be set as whole numbers using GB or MB
memory=<memory_allocated>GB 
# Sets the VM to use <number of virtual_processors_assigned to VM> virtual processors
processors=<number of virtual_processors_assigned to VM>
# Sets amount of swap storage space to <swap_file_size> GB, default is 25% of available RAM
swap=<swap_file_size>GB
# Sets swapfile path location, default is %USERPROFILE%\AppData\Local\Temp\swap.vhdx
swapfile=C:\\temp\\wsl-swap.vhdx
# Turn off default connection to bind WSL 2 localhost to Windows localhost
localhostforwarding=false
#true
# Disables nested virtualization
nestedVirtualization=false
# Turns on output console showing contents of dmesg when opening a WSL 2 distro for debugging
debugConsole=false
    If you create or update the .wslconfig file, restart the Docker* client and the WSL 2 environment:
    1. Exit the Docker* client.
    2. Shut down the WSL 2 environment by running the following command in a Windows Terminal session:
      wsl --shutdown
    3. Start the Docker* client.

      Starting the Docker* client restarts the WSL 2 environment.

  4. [FPGA] Install the SoC EDS software.

    For installation instructions, refer to the Intel® SoC FPGA Embedded Development Suite (SoC EDS) User Guide

  5. [FPGA] Install the USB/IP open-source project (usbipd-win).

    For installation instructions, refer to the "Install the USBIPD-WIN project" section of Connect USB devices at Microsoft* Learn.

  6. [FPGA] Attach your FPGA development kit to the host machine using the development kit UART and JTAG connections.
  7. Pull the latest FPGA AI Suite Docker* image from the Docker* Hub Container Image Library with the following command:
    docker pull alterafpga/fpgaaisuite-v2025.1:latest
  8. [FPGA] Set up serial port access to the FPGA board as follows:
    1. Start a Windows command prompt session with Administrator privileges and run the following command:
      usbipd list
      The command output should be like the following example output: 
      BUSID VID:PID   DEVICE                                    STATE
1-7   067b:23a3 Prolific PL2303GC                   Not shared
                USB Serial COM Port (COM3) 
1-8   0bda:4c60 Realtek USB Audio, USB Input Device Not shared
1-9   0403:6001 USB Serial Converter                Not shared
1-14  8087:0033 Intel(R) Wireless Bluetooth(R)      Not shared
6-5   0bda:1100 USB Input Device                    Not shared
7-4   06c4:c413 USB Input Device                    Not shared
8-1   046d:c33f USB Input Device                    Not shared
8-3   046d:c08b USB Input Device                    Not shared
9-2   0bda:8153 Realtek(R)                          Not shared
                USB GbE Family Controller

      Find you FPGA development kit. The kit is listed as USB Serial Converter. In the example output, the kit has Bus ID 1-9.

    2. Run the following command to give the WSL 2 environment access to the FPGA development kit:
      usbipd bind --busid 1-9
      After running this command, the usbipd list command should show the device in the Shared state: 
      BUSID VID:PID   DEVICE                       STATE
...
1-9    0403:6001 USB Serial Converter      Shared
...
      Tip: If you need to remove the FPGA development kit, you can use the unbind command to unbind the device from the WSL 2 environment: usbipd unbind --busid 1-9.
    3. Attach the FPGA development kit to the WSL 2 environment:
      usbipd attach --wsl --busid 1-9
      Tip: If you do not need to access the FPGA development kit, detach the FPGA development kit device to avoid possible errors: 
      usbipd detach --wsl --busid 1-9
Level Two Title