Intel® FPGA SDK for OpenCL™ Pro Edition: Custom Platform Toolkit User Guide

Download PDF
ID 683085
Date 3/28/2022
Public
Document Table of Contents
Document Table of Contents x
1. Intel® FPGA SDK for OpenCL™ Pro Edition Custom Platform Toolkit User Guide 2. Intel® FPGA SDK for OpenCL™ Pro Edition Custom Platform Toolkit Reference Material 3. Intel FPGA SDK for OpenCL Pro Edition Custom Platform Toolkit Archives 4. Document Revision History for Intel® FPGA SDK for OpenCL™ Pro Edition Custom Platform Toolkit User Guide
1. Intel® FPGA SDK for OpenCL™ Pro Edition Custom Platform Toolkit User Guide x
1.1. Prerequisites for the Intel® FPGA SDK for OpenCL™ Pro Edition Custom Platform Toolkit 1.2. Overview of the Intel® FPGA SDK for OpenCL™ Pro Edition Custom Platform 1.3. Custom Platform Automigration for Forward Compatibility 1.4. Creating an Intel® FPGA SDK for OpenCL™ Custom Platform 1.5. Applying for the Intel® FPGA SDK for OpenCL™ Pro Edition Preferred Board Status 1.6. Shipping Recommendations
1.2. Overview of the Intel® FPGA SDK for OpenCL™ Pro Edition Custom Platform x
1.2.1. Directories and Files in an Intel® FPGA SDK for OpenCL™ Pro Edition Custom Platform 1.2.2. Recommendations for Structuring the Custom Platform Directory
1.3. Custom Platform Automigration for Forward Compatibility x
1.3.1. Customizing Automigration
1.4. Creating an Intel® FPGA SDK for OpenCL™ Custom Platform x
1.4.1. Designing the Board Hardware 1.4.2. Creating the Board XML Files 1.4.3. Creating the MMD Library 1.4.4. Setting Up the FPGA Client Driver 1.4.5. Providing Intel® FPGA SDK for OpenCL™ Utilities Support 1.4.6. Testing the Hardware Design
1.4.1. Designing the Board Hardware x
1.4.1.1. Creating the Board Platform Designer System 1.4.1.2. Establishing Guaranteed Timing Flow
1.4.1.1. Creating the Board Platform Designer System x
1.4.1.1.1. General Quality of Results Considerations for the Exported Board Partition
1.4.2. Creating the Board XML Files x
1.4.2.1. Creating the board_env.xml File 1.4.2.2. Creating the board_spec.xml File
1.4.2.1. Creating the board_env.xml File x
1.4.2.1.1. Testing the board_env.xml File
1.4.3. Creating the MMD Library x
1.4.3.1. Kernel Power-up State
2. Intel® FPGA SDK for OpenCL™ Pro Edition Custom Platform Toolkit Reference Material x
2.1. The Board Platform Designer Subsystem 2.2. XML Elements, Attributes, and Parameters in the board_spec.xml File 2.3. MMD API Descriptions
2.1. The Board Platform Designer Subsystem x
2.1.1. Intel® FPGA SDK for OpenCL™ Pro Edition-Specific Platform Designer System Components
2.1.1. Intel® FPGA SDK for OpenCL™ Pro Edition-Specific Platform Designer System Components x
2.1.1.1. OpenCL Kernel Clock Generator 2.1.1.2. OpenCL Kernel Interface 2.1.1.3. OpenCL Memory Bank Divider
2.2. XML Elements, Attributes, and Parameters in the board_spec.xml File x
2.2.1. board 2.2.2. device 2.2.3. global_mem 2.2.4. host 2.2.5. channels 2.2.6. interfaces 2.2.7. interface 2.2.8. compile
2.3. MMD API Descriptions x
2.3.1. aocl_mmd_get_offline_info 2.3.2. aocl_mmd_get_info 2.3.3. aocl_mmd_open 2.3.4. aocl_mmd_close 2.3.5. aocl_mmd_read 2.3.6. aocl_mmd_write 2.3.7. aocl_mmd_copy 2.3.8. aocl_mmd_set_interrupt_handler 2.3.9. aocl_mmd_set_device_interrupt_handler 2.3.10. aocl_mmd_set_status_handler 2.3.11. aocl_mmd_yield 2.3.12. aocl_mmd_shared_mem_alloc 2.3.13. aocl_mmd_shared_mem_free 2.3.14. aocl_mmd_program 2.3.15. aocl_mmd_reprogram 2.3.16. aocl_mmd_hostchannel_create 2.3.17. aocl_mmd_hostchannel_destroy 2.3.18. aocl_mmd_hostchannel_get_buffer 2.3.19. aocl_mmd_hostchannel_ack_buffer 2.3.20. aocl_mmd_host_alloc 2.3.21. aocl_mmd_free 2.3.22. aocl_mmd_device_alloc 2.3.23. aocl_mmd_shared_alloc 2.3.24. aocl_mmd_shared_migrate
2.3.14. aocl_mmd_program x
2.3.14.1. Program Support
1. Intel® FPGA SDK for OpenCL™ Pro Edition Custom Platform Toolkit User Guide
2. Intel® FPGA SDK for OpenCL™ Pro Edition Custom Platform Toolkit Reference Material
3. Intel FPGA SDK for OpenCL Pro Edition Custom Platform Toolkit Archives
4. Document Revision History for Intel® FPGA SDK for OpenCL™ Pro Edition Custom Platform Toolkit User Guide

1.4.5. Providing Intel® FPGA SDK for OpenCL™ Utilities Support

Each Custom Platform you develop for use with the Intel® FPGA SDK for OpenCL™ Pro Edition must support a set of SDK utilities. These utilities enable users to manage the accelerator board through the SDK.

If you create a new Custom Platform, perform the following tasks to create executables of the SDK utilities and then store them in the utilbindir directory of your Custom Platform:

Tip:

Within the <path_to_a10_ref>/source/util directory of the Intel® Arria® 10 10 GX FPGA Development Kit Reference Platform, you can find source code for the program and flash utilities in the reprogram and flash subdirectories, respectively. Scripts for the install and uninstall utilities are available in the <path_to_a10_ref>/<OS_platform>/libexec directory.

You can find the source code for the diagnose utility in the <path_to_a10_ref>/source/util/diagnostic directory within the Intel® Arria® 10 GX FPGA Development Kit Reference Platform.

  1. Create an install utility executable that sets up the current host computer with the necessary drivers to communicate with the board via the MMD layer. The install utility takes no argument.
    For example, the PCIe®-based MMD might need to install PCIe drivers into the host operating system.
    Executable call: aocl install <path_to_customplatform>
  2. Create an uninstall utility executable that removes the current host computer drivers (for example, PCIe drivers) used for communicating with the board. The uninstall utility takes no argument.
    Executable call: aocl uninstall <path_to_customplatform>
  3. Create a diagnose utility executable that confirms the board's integrity and the functionality of the MMD layer.

    The diagnose utility must support the following internal calling modes:

    Calling Mode Description
    -probe Prints all available devices in a Custom Platform. For a given hardware configuration, the utility lists the devices in the same order, and each device is associated with the same identification string each time.
    -probe <device_name> Queries the specified device and prints summary statistics about the device.
    <device_name>

    where <device name> is the string that corresponds to the FPGA device.

    		Performs a full diagnostic test for the specified device.

    The utility generates the message DIAGNOSTIC_PASSED as the output. Otherwise, the utility generates the message DIAGNOSTIC_FALIED.

    When users invoke the diagnose utility command without an argument, it queries the devices in the Custom Platform and supplies a list of valid <device_name> strings assigned to the list of devices.

    Executable call without argument: aocl diagnose

    When users invoke the diagnose utility command with a <device_name> argument, the utility runs your diagnostic test for the board. A user may give a board a different logical device name than the physical device name associated with the Custom Platform. The aocl utility simply converts the user-side logical device name to the Custom Platform-side physical device name. If the diagnostic test runs successfully, the utility generates the message DIAGNOSTIC_PASSED as the output. Otherwise, the utility generates the message DIAGNOSTIC_FALIED.

    Executable call with argument: aocl diagnose <device_name> .

  4. Create a program utility executable that receives the fpga.bin file and the Intel® FPGA SDK for OpenCL™ Offline Compiler executable file (.aocx) and configures that design onto the FPGA. Although the main method for FPGA programming is via the host and the MMD, make this utility available to users who do not have a host system or who perform offline reprogramming.
    The program utility command takes <device_name>, fpga.bin, and <kernel_filename>.aocx as arguments. When users invoke the command, the SDK extracts the fpga.bin file and passes it to the program utility.
    Important: Intel® highly recommends that the program utility links with and calls the aocl_mmd_program function implemented in the MMD layer. Refer to the aocl_mmd_program and Program Support reference sections for more information.

    Executable call: aocl program <device_name> <kernel_filename>.aocx, where <device name> is the acl number that corresponds to the FPGA device.

  5. Create a flash utility executable that receives the fpga.bin file and programs that design into the flash memory on the board. The flash utility command takes <device_name> and a .aocx file name as arguments. When users invoke the command, the SDK extracts the fpga.bin file and passes it to the flash utility.

    Executable call: aocl flash <device_name> <kernel_filename>.aocx, where <device name> is the acl number that corresponds to the FPGA device.

When users invoke a utility command, the utility probes the current Custom Platform's board_env.xml file and executes the <utility_executable> file within the utilbindir directory.
Related Information
Level Two Title