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.3. Creating the MMD Library

Your Custom Platform requires an MMD layer necessary for communication with the accelerator board.

You must implement a file I/O-like software interface such as open, read, write, and close to communicate with the accelerator board over any medium. The result of your implementation is a set of linker arguments that allows an OpenCL™ host application to link against the MMD layer of the target board. A dynamic link library (DLL) that fully implements the MMD layer is also necessary for the communication.

Figure 2.  Intel® FPGA SDK for OpenCL™ Software ArchitectureThis figure depicts the four layers of the Intel® FPGA SDK for OpenCL™ Pro Edition software architecture: runtime, hardware abstraction layer (HAL), MMD layer, and kernel mode driver.

The following tasks outline the procedure for creating an MMD library for use with PCI Express® (PCIe®).

  1. Name a new library file that implements the MMD layer in the following manner:
    <board_vendor_name>_<board_family_name>[_<unique_string>]_mmd.<a|so|lib|dll>
    Where:
    • <board_vendor_name> is the entity responsible for the accelerator board.
    • <board_family_name> is the board family name that the library supports.
    • <unique_string> is a designation that you create. Intel® recommends that you include information such as revision and interface type.
    • <a|so|lib|dll> is the file extension. It can be an archive file (.a), a shared object file (.so), a library file (.lib), or a dynamic link library file (.dll).

    Example library file name: altera_svdevkit_pcierev1_mmd.so

  2. Include the aocl_mmd.h header file (refer to source/include directory in one of the reference platform BSPs available at the FPGA Software Download Center) in the operating system-specific implementation of the MMD layer.
    The aocl_mmd.h file and the MMD API Descriptions reference section contain full details on the MMD application programming interface (API) descriptions, their arguments, and their return values.
  3. Implement the MMD layer for your Custom Platform, and compile it into a C/C++ library.
    Example source codes of a functional MMD library are available in the <path_to_a10_ref>/source/host/mmd directory of the Intel® Arria® 10 GX FPGA Development Kit Reference Platform. In particular, the acl_pcie.cpp file implements the API functions defined in the aocl_mmd.h file.
    If the SDK users need to load a particular library at runtime, deliver the library in a directory that the operating system can locate. Instruct the SDK users to add the library path to the LD_LIBRARY_PATH (for Linux) or PATH (for Windows) environment variable at runtime.
  4. Modify the mmdlib and linkflags elements in the board_env.xml file by specifying the library flags necessary for linking with the MMD layer.

Section Content
Kernel Power-up State

Related Information
Level Two Title