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 Syntax Function Arguments Return Value 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.3.1. aocl_mmd_get_offline_info

The aocl_mmd_get_offline_info function obtains offline information about the board specified in the requested_info_id argument. This function is offline because it is device-independent and does not require a handle from the aocl_mmd_open() call.

Syntax

int aocl_mmd_get_offline_info( aocl_mmd_offline_info_t requested_info_id,
                               size_t param_value_size,
                               void* param_value,
                               size_t* param_size_ret )

Function Arguments

  • requested_info_id—An enum value of type aocl_mmd_offline_info_t that indicates the offline device information returning to the caller.
Table 16.  Possible Enum Values for the requested_info_id Argument
Name Description Type
AOCL_MMD_VERSION Version of MMD layer char*
AOCL_MMD_NUM_BOARDS Number of candidate boards int
AOCL_MMD_BOARD_NAMES Names of available boards
Attention: Separate each board name by a semicolon (;) delimiter.
char*
AOCL_MMD_VENDOR_NAME Name of board vendor char*
AOCL_MMD_VENDOR_ID An integer board vendor ID int
AOCL_MMD_USES_YIELD A value of 0 instructs the Intel® FPGA SDK for OpenCL™ Pro Edition host runtime to suspend user's processes. The host runtime resumes these processes after it receives an event update (for example, an interrupt) from the MMD layer .

A value of 1 instructs the SDK's host runtime to continuously call the aocl_mmd_yield function while it waits for events to complete.

CAUTION:
Setting AOCL_MMD_USES_YIELD to 1 might cause high CPU utilization if the aocl_mmd_yield function does not suspend the current thread.
int
AOCL_MMD_MEM_TYPES_SUPPORTED A bit field listing all memory types that the Custom Platform supports. You may combine the following enum values in this bit field:

AOCL_MMD_PHYSICAL_MEMORY—Custom Platform includes IP to communicate directly with physical memory (for example, DDR and QDR).

AOCL_MMD_SVM_COARSE_GRAIN_BUFFER—Custom Platform supports both the caching of shared virtual memory (SVM) pointer data for OpenCL cl_mem objects and the requirement of explicit user function calls to synchronize the cache between the host processor and the FPGA.

Note: Currently, Intel® does not support this level of SVM except for a subset of AOCL_MMD_SVM_FINE_GRAIN_SYSTEM support.

AOCL_MMD_SVM_FINE_GRAIN_BUFFER—Custom Platform supports caching of SVM pointer data for individual bytes. To synchronize the cache between the host processor and the FPGA, the Custom Platform requires information from the host runtime collected during pointer allocation. After an SVM pointer receives this additional data, the board interface synchronizes the cache between the host processor and the FPGA automatically.

Note: Currently, Intel® does not support this level of SVM except for a subset of AOCL_MMD_SVM_FINE_GRAIN_SYSTEM support.

AOCL_MMD_SVM_FINE_GRAIN_SYSTEM—Custom Platform supports caching of SVM pointer data for individual bytes and it does not require additional information from the host runtime to synchronize the cache between the host processor and the FPGA. The board interface synchronizes the cache between the host processor and the FPGA automatically for all SVM pointers.

Attention: Intel® 's support for this level of SVM is preliminary. Some features might not be fully supported.
int (bit field)
  • param_value_size—Size of the param_value field in bytes. This size_t value should match the size of the expected return type that the enum definition indicates.

    For example, if AOCL_MMD_NUM_BOARDS returns a value of type int, set the param_value_size to sizeof (int). You should see the same number of bytes returned in the param_size_ret argument.

  • param_value—A void* pointer to the variable that receives the returned information.

  • param_size_ret—A pointer argument of type size_t* that receives the number of bytes of returned data.

Return Value

A negative return value indicates an error.

Level Two Title