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.2.2. Creating the board_spec.xml File

The board_spec.xml XML file contains metadata necessary to describe your hardware system to the Intel® FPGA SDK for OpenCL™ Pro Edition.
For detailed descriptions on the type of information you must include in the board_spec.xml file, refer to the XML Elements, Attributes, and Parameters in the board_spec.xml File section.
  1. Structure the board_spec.xml file to include the following XML elements and attributes:
    Table 3.  XML Elements and Attributes Specified in the board_spec.xml File
    Element Attribute
    board version, name
    device device_model, used_resources
    global_mem name, max_bandwidth, interleaved_bytes, config_addr, [default], interface
    host kernel_config
    [channels] interface
    interfaces interface, kernel_clk_reset
    compile project, revision, qsys_file, generic_kernel, generate_cmd, synthesize_cmd, auto_migrate

  2. For the board element, specify the board version and the name of the accelerator board. The name of the board must match the name of the directory in which the board_spec.xml file resides.
    Important: The board version must match the SDK version you use to develop the Custom Platform.
    Attention: The board name must contain a combination of only letters, numbers, underscores (_), hyphens (-), or periods (.) (for example: a10_ref).
  3. For the device element, perform the following steps to specify the name of the device model file.
    1. Navigate to the INTELFPGAOCLSDKROOT/share/models/dm directory, where INTELFPGAOCLSDKROOT points to the path to the SDK installation. The directory contains a list of device models files that describe available FPGA resources on accelerator boards.
    2. If your device is listed in the dm directory, specify the device_model attribute with the name of the device model file. Proceed to Step 4.
      For example, device_model="10ax115s2f45i2sges_dm.xml"
    3. If your device is not listed in the dm directory, or if your board uses an FPGA that does not have a device model, create a new device model by performing the tasks described in Steps d to g:
    4. Copy a device model from the INTELFPGAOCLSDKROOT/share/models/dm directory (for example, 10ax115s2f45e2lg_dm.xml).
    5. Place your copy of the device model in the Custom Platform subdirectory in which your board_spec.xml file resides.
    6. Rename the file, and modify the values to describe the part your board uses.
      Important:

      The file name must conform to the format <part_number>_dm.xml, where <part_number> is the official Intel® FPGA device part number (for example, 10ax115s2f45i1sg).

      You can search for the Intel® FPGA device part number on the Buy Intel FPGA page.

    7. In the board_spec.xml file, update the device_model attribute of the device element with the name of your file.
  4. For the device element, specify the parameters in the used_resources attribute to describe the FPGA resources that the board design consumes in the absence of any OpenCL kernel.
    If your design includes a defined partition around all the board logic, you can extract the data from the Partition Statistics section of the Fitter report.
  5. For each global memory type, specify the following information:
    1. Name of the memory type.
    2. The combined maximum global memory bandwidth.
      You can calculate this bandwidth value from datasheets of your memories.
    3. The size of the data that the Intel® FPGA SDK for OpenCL™ Offline Compiler interleaves across memory banks.
    4. If you have a homogeneous memory system, proceed to Step e. If you have a heterogeneous memory system, for each global memory type, specify the config_addr attribute with the base address of the ACL Mem Organization Control Platform Designer component (mem_org_mode).
    5. If you choose to set a global memory type as default, assign a value of 1 to the optional default attribute. The default memory must start at address 0x0
      If you do not include this attribute, the first memory defined in the board_spec.xml file becomes the default memory.
    6. Specify the parameters in the interface attribute to describe the characteristics of each memory interface.
  6. For the host element, specify the parameters in the kernel_config attribute to describe the offset at which the kernel resides. Determine the start of the offset from the perspective of the kernel_cra host in the OpenCL Kernel Interface Platform Designer component.
  7. If your board provides channels for direct OpenCL kernel-to-I/O accesses, include the channels element for all channel interfaces. Specify the parameters in the interface attribute to describe the characteristics of each channel interface.
  8. Include the interfaces element to describe the kernel interfaces connecting to and controlling OpenCL kernels. Include one of each interface types (that is host, irq, and streamsource).
    1. Specify the parameters in the interface attribute to describe the characteristics of each kernel interface.
      For the streamsource interface type, also specify the clock attribute with the name of the clock the snoop stream uses. Usually, this clock is the kernel clock.
      Important: Update the width of the snoop interface (acl_internal_snoop) specified with the streamsource kernel interface. Updating the width ensures that the global_mem interface entries in board_spec.xml match the characteristics of the bank<N> Avalon® Memory-Mapped (Avalon-MM) hosts from corresponding OpenCL Memory Bank Divider component for the default memory.
    2. Specify the parameters in the kernel_clk_reset attribute to include the exported kernel clock and reset interfaces as kernel interfaces.
  9. Include the compile element and specify its attributes to control the Intel® Quartus® Prime compilation, registration, and automigration.
Below is the XML code of an example board_spec.xml file: 
<?xml version="1.0"?>
<board version="22.1" name="a10gx">

  <compile name="top" project="top" revision="top" qsys_file="none" generic_kernel="1">
    <generate cmd="quartus_sh -t scripts/pre_flow_pr.tcl"/>
    <synthesize cmd="quartus_cdb -t import_compile.tcl"/>
    <auto_migrate platform_type="a10_ref" >
      <include fixes=""/>
      <exclude fixes=""/>
    </auto_migrate>
  </compile>

  <compile name="base" project="top" revision="base" qsys_file="none" generic_kernel="1">
    <generate cmd="quartus_sh -t scripts/pre_flow_pr.tcl base"/>
    <synthesize cmd="quartus_sh --flow compile top -c base"/>
    <auto_migrate platform_type="a10_ref" >
      <include fixes=""/>
      <exclude fixes="pre_skipbak,post_skipbak"/>
    </auto_migrate>
  </compile>

  <compile name="flat" project="top" revision="flat" qsys_file="none" generic_kernel="1">
    <generate cmd="quartus_sh -t scripts/pre_flow_pr.tcl flat"/>
    <synthesize cmd="quartus_sh --flow compile top -c flat"/>
    <auto_migrate platform_type="a10_ref" >
      <include fixes=""/>
      <exclude fixes="pre_skipbak,post_skipbak"/>
    </auto_migrate>
  </compile>

  <compile name="regenerate_cache" project="top" revision="top" qsys_file="none" generic_kernel="1">
    <generate cmd="quartus_sh -t scripts/pre_flow_pr.tcl"/>
    <synthesize cmd="quartus_sh -t scripts/regenerate_cache.tcl a10_ref a10gx"/>
    <auto_migrate platform_type="a10_ref" >
      <include fixes=""/>
      <exclude fixes="pre_skipbak"/>
    </auto_migrate>
  </compile>

  <device device_model="10ax115s2f45i2sges_dm.xml">
    <used_resources>
      <alms num="33400"/> <!-- Total ALMs - ALMs available to kernel_system_inst -->
      <ffs num="133600"/>
      <dsps num="0"/>
      <rams num="182"/>
    </used_resources>
  </device>

  <!-- DDR4-2400 -->
  <global_mem name="DDR" max_bandwidth="19200" interleaved_bytes="1024" config_addr="0x018">
    <interface name="board" port="kernel_mem0" type="agent" width="512" maxburst="16" address="0x00000000" size="0x80000000" latency="240" addpipe="1"/>
  </global_mem>

  <host>
    <kernel_config start="0x00000000" size="0x0100000"/>
  </host>

  <interfaces>
    <interface name="board" port="kernel_cra" type="host" width="64" misc="0"/>
    <interface name="board" port="kernel_irq" type="irq" width="1"/>
    <interface name="board" port="acl_internal_snoop" type="streamsource" enable="SNOOPENABLE" width="31" clock="board.kernel_clk"/>
    <kernel_clk_reset clk="board.kernel_clk" clk2x="board.kernel_clk2x" reset="board.kernel_reset"/>
  </interfaces>

</board>
Related Information
Level Two Title