Visible to Intel only — GUID: GUID-BD50E8CA-9886-42D1-884A-EB7CEED126F4
Visible to Intel only — GUID: GUID-BD50E8CA-9886-42D1-884A-EB7CEED126F4
Managing an FPGA Board
Managing an FPGA board typically involves the following tasks:
- Installing a board support package (BSP)
- Listing detected FPGA boards
- Initializing an FPGA board
- Getting information about an FPGA board and running diagnostic tests on the board
- Uninstalling a BSP
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.
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.
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. |