Developer Guide

Intel® oneAPI DPC++/C++ Compiler Handbook for FPGAs

ID 785441
Date 10/24/2024
Public
Document Table of Contents

Managing an FPGA Board

Managing an FPGA board typically involves the following tasks:

Installing a BSP (aocl install Command)

Installing a BSP with the aocl install command installs the device drivers that make the FPGA board accessible to the host operating system, and it installs the FPGA client driver (FCD) for your board to make the board accessible to the oneAPI runtime.

Before you install a BSP, you must have the FPGA board connected to your host system.

To run the aocl install command, you must know the directory that contains the BSP files for your board. Optionally, you can set the AOCL_BOARD_PACKAGE_ROOT environment variable to point this directory. If you have the AOCL_BOARD_PACKAGE_ROOT environment variable, you can omit the path to the BSP from any FPGA utility commands that require that path.

aocl install Command Use Cases
Use Case Command
Install a BSP aocl install <BSP_root_folder>

where <BSP_root_folder> is the full path of the directory that contains the BSP.

Install the FCD for the board only

For this use case, the FPGA board device drivers must be already be installed.

This use case typically occurs if you have previous run the aocl uninstall -fcd-only command.

aocl install <BSP_root_folder> -fcd-only

where <BSP_root_folder> is the full path of the directory that contains the BSP.

After you have run the aocl install command, you can use the aocl list-devices and aocl diagnose commands to confirm that the BSP installation was successful.

Listing Detected FPGA Boards (aocl list-devices Command)

Use the aocl list-devices command to show a list of FPGA boards that are detected on your system. The board device name shown under the Device Name section in the output of this command is needed for board-specific FPGA utility commands such as aocl initialize.

The command generates output similar to the following:

--------------------------------------------------------------------
Device Name:
acl0
 
BSP Install Location:
<board_package_path>
 
Vendor: Intel(R) Corporation
 
Phys Dev Name   Status   Information
 
<phys_dev_name> Passed   <descriptive_board_name>
                         PCIe dev_id = <dev_id>, bus:slot.func = 01:00.00, Gen3 x8
                         FPGA temperature = 32.6016 degrees C.
 
DIAGNOSTIC_PASSED
--------------------------------------------------------------------

Initializing an FPGA Board (aocl initialize Command)

Initializing an FPGA board with the aocl initialize command lets the oneAPI SYCL* runtime know that the FPGA board (and board variant) is available. Your multiarchtechture binary will fail to run it if the target board is not initialized.

You must initialize an FPGA board after any of the following events:

  • The FPGA board host system was power cycled.
  • A non-SYCL* workload was run on the FPGA device.
  • The multiarchitecture binary was recompiled to a different board variant (as specified by the -Xstarget compiler command option)

To initialize a board, you must know the FPGA board device name (from the aocl list-devices command), and the name of the board variant as specified by the -Xstarget compiler command option when the multiarchitecture binary was compiled. Whoever compiled the multiarchitecture binary can provide you with the board variant to specify.

Initialize a board with the following command:

aocl intialize <board_device_name> <board_variant>

Running the Board-Related Diagnostic Utility (aocl diagnose Command)

Running the board-related diagnostic utilities checks and reports your OpenCL* installable client driver (ICD) and your FPGA client driver (FCD) configuration. For more information about the OpenCL* installable client driver (ICD) and its role in developing your multiarchitecture binary, refer to The OpenCL™ Installable Client Driver (ICD).

The utility can report information about the FPGA boards that are discoverable by the host operating system.

The diagnostic utility has the following use modes:

Default mode
In default mode, the utility runs ICD and FCD diagnostics and lists the FPGA boards that are discoverable by the host operating system. Run the utility in default mode with the following command:
aocl diagnose

If your system is configured correctly, the command output includes the following messages:

  • ICD diagnostics passed
  • DIAGNOSTIC_PASSED

Client driver–only mode
In client driver–only mode, the utility runs only the ICD and FCD diagnostics. Run the utility in client driver–only mode with the following command:
aocl diagnose -icd-only
If your system is configured correctly, the command output includes the following messages:
  • ICD diagnostics passed

You can successfully run the utility in client driver–only mode without any FPGA boards present on the host system.

Board diagnostic mode
In board diagnostic mode, the utility runs a diagnostic routine provided by your FPGA acceleration board vendor. To run the diagnostic routine, the FPGA board must be discoverable by the host operating system. Run the utility in board diagnostic mode with the following command:
aocl diagnose <board_device_name>
where <board_device_name> is the board device name as reported under the Device Name section of either the aocl list-devices command output or the default mode aocl diagnose command output.

Uninstalling a BSP (aocl uninstall Command)

Uninstalling a BSP removes the FCD for the board and uninstalls the device drivers for the board. You can also choose to uninstall only the FCD.

aocl uninstall Command Use Cases
Use Case Command
Uninstall a BSP aocl uninstall <BSP_root_folder>

where <BSP_root_folder> is the full directory path of the BSP that you are uninstalling.

Uninstall the FCD for the board only

For this use case, the FPGA board device drivers remain installed.

Use the aocl install -fcd-install command to reinstall the FCD.

aocl uninstall <BSP_root_folder> -fcd-only

where <BSP_root_folder> is the full directory path of the BSP that you are uninstalling.