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

2.2.3. global_mem

The global_mem and interface elements of the board_spec.xml file provides information on the memory interfaces that connect to the kernel.
Example XML code: 
<!-- DDR3-1600 -->
<global_mem name="DDR" max_bandwidth="25600" interleaved_bytes="1024"
 config_addr="0x018">
  <interface name="board" port="kernel_mem0" type="agent" width="512" maxburst="16"
   address="0x00000000" size="0x100000000" latency="240"/>
  <interface name="board" port="kernel_mem1" type="agent" width="512" maxburst="16"
   address="0x100000000" size="0x100000000" latency="240"/>
</global_mem>

<!-- QDRII -->
  <global_mem name="QDR" max_bandwidth="17600" interleaved_bytes="8"
   config_addr="0x100">
    <interface name="board" type="agent" width="64" maxburst="1"
     address="0x200000000" size="0x1000000" latency="150" addpipe="1">
      <port name="kernel_qdr0_r" direction="r"/>
      <port name="kernel_qdr0_w" direction="w"/>
    </interface>
    <interface name="board" type="agent" width="64" maxburst="1"
     address="0x201000000" size="0x1000000" latency="150" addpipe="1">
      <port name="kernel_qdr1_r" direction="r"/>
      <port name="kernel_qdr1_w" direction="w"/>
    </interface>
    <interface name="board" type="agent" width="64" maxburst="1"
     address="0x202000000" size="0x1000000" latency="150" addpipe="1">
      <port name="kernel_qdr2_r" direction="r"/>
      <port name="kernel_qdr2_w" direction="w"/>
    </interface>
    <interface name="board" type="agent" width="64" maxburst="1"
     address="0x203000000" size="0x1000000" latency="150" addpipe="1">
      <port name="kernel_qdr3_r" direction="r"/>
      <port name="kernel_qdr3_w" direction="w"/>
    </interface>
  </global_mem>
Note: For each global memory that the kernel accesses, you must include one interface element that describes its characteristics.
Table 12.  Attributes for the global_mem Element
Attribute Description
name The name the Intel® FPGA SDK for OpenCL™ Pro Edition user uses to identify the memory type. Each name must be unique and must comprise of less than 32 characters.
max_bandwidth The maximum bandwidth, in megabytes per second (MB/s), of all global memory interfaces combined in their current configuration. The Intel® FPGA SDK for OpenCL™ Offline Compiler uses max_bandwidth to choose an architecture suitable for the application and the board.

Compute this bandwidth value from datasheets of your memories.

Example max_bandwidth calculation for a 64-bit DDR3 interface running at 800 MHz:

max_bandwidth = 800 MHz x 2 x 64 bits ÷ 8-bits = 12800 MB/s

You have the option to use block RAM instead of or in conjunction with external memory as global memory. The formula for calculating max_bandwidth for block RAM is max_bandwidth = block RAM speed x (block RAM interface size ÷ 8 bits)

Example max_bandwidth calculation for a 512-bit block RAM running at 100 MHz:

max_bandwidth = 100 MHz x 512 bits ÷ 8 bits = 6400 MB/s

interleaved_bytes

Include the interleaved_bytes attribute in the board_spec.xml file when you instantiate multiple interfaces for a given global memory system. This attribute controls the size of data that the offline compiler distributes across the interfaces.

The offline compiler currently can interleave data across banks no finer than the size of one full burst. This attribute specifies this size in bytes and following are the recommended values:

  • For BSP with two or fewer global memory banks: maxburst x width_bytes
  • For BSP with four or more global memory banks: maxburst x width_bytes x 4

The interleaved_bytes value must be the same for the host interface and the kernels. Therefore, the configuration of the OpenCL Memory Bank Divider must match the exported kernel agent interfaces in this respect.

For block RAM, interleaved_bytes equals the width of the interface in bytes.

config_addr The address of the ACL Mem Organization Control Platform Designer component (mem_org_mode) that the host software uses to configure memory. You may omit this attribute if your board has homogeneous memory; the software uses the default address (0x18) for this component. If your board has heterogeneous memory, there is a mem_org_mode component in the board system for each memory type.

Enter the config_addr attribute and set it to the value of the base address of the mem_org_mode component(s).

default Include this optional attribute and assign a value of 1 to set the global memory as the default memory interface. The default memory must start at address 0x0.

If you do not implement this attribute, the first memory type defined in the board_spec.xml file becomes the default memory interface.

interface See the interface section for the parameters you must specify for each interface.
allocation_type A list that specifies which USM allocator is used to allocate from the global_mem element. Values allowed in this list are host, shared, and device. The following conditions apply:
  • If there are multiple global_mem elements with the same allocation_type attribute, the first allocation_type attribute in the board_spec.xml is assumed to be the one used by the specified allocator.
  • If there is a single global_mem element with multiple allocation_type attributes, this indicates that allocations of the specified types use this global_mem interface.
  • [Legacy support] If you have not specified the allocation_type attribute, it is assumed that all global memory interfaces have the device allocation_type.
Related Information
Level Two Title