Intel FPGA SDK for OpenCL Standard Edition: Custom Platform Toolkit User Guide
Intel FPGA SDK for OpenCL Standard Edition Custom Platform Toolkit User Guide
The Intel® FPGA SDK for OpenCL™ 1 2 Standard Edition Custom Platform Toolkit provides the necessary tools for implementing a fully functional Custom Platform. The Custom Platform Toolkit is available in the INTELFPGAOCLSDKROOT/board directory, where the environment variable INTELFPGAOCLSDKROOT points to the location of the SDK installation.
The goal is to enable an SDK user to target any given Custom Platform seamlessly by performing the following tasks:
- Acquire an accelerator board and plug it into their system.
- Acquire the Custom Platform and unpack it to a local directory.
- Set the environment variable QUARTUS_ROOTDIR_OVERRIDE to point to installation directory of the Intel® Quartus® Prime Standard Edition software .
- Invoke the aocl install <path_to_customplatform> utility command.
- Compile the OpenCL kernel and build the host application.
- Set environment variables to point to the location of the
memory-mapped device (MMD) library.
- For Windows* systems, set the PATH environment variable.
- For Linux* systems, set the LD_LIBRARY_PATH environment variable.
- Run the host application.
Prerequisites for the Intel FPGA SDK for OpenCL Standard Edition Custom Platform Toolkit
You must have experiences in the following hardware design areas:
- Intel® Quartus® Prime Standard Edition software design with Platform Designer (Standard), HDL and Tcl
- Intel® FPGA intellectual property (IP) necessary to communicate with the physical interfaces of the board
- High speed design, timing analysis and Synopsys Design Constraints (SDC) constraints
- FPGA architecture, including clock and global routing, floorplanning, and I/O
- Team-based design (that is, incremental compilation)
You must install the Intel® Quartus® Prime Standard Edition software, the relevant device support file(s), and the SDK on your machine. Refer to the Intel® FPGA SDK for OpenCL™ Standard Edition Getting Started Guide for installation instructions.
You have the following Custom Platform design options:
- Refer to the information in this document to create a Custom Platform from the templates available in the Custom Platform Toolkit.
- Refer to the information in this document and the
Intel® FPGA SDK for OpenCL™
Intel
Stratix V Network Reference Platform Porting Guide to create a Custom
Platform by modifying relevant files in the
Intel®
Stratix® V Network Reference Platform (s5_net).
Download s5_net from the Intel® FPGA SDK for OpenCL™ FPGA Platforms page on the Intel® FPGA website. The link for the download is under Custom.
- Refer to the information
in this
document and
the
following documents to create a Custom Platform by modifying relevant files in the
Intel®
Cyclone® V
SoC Development Kit Reference Platform (c5soc), available with the SDK:
- Intel® FPGA SDK for OpenCL™ Intel® Cyclone® V SoC Development Kit Reference Platform Porting Guide
- Intel® Cyclone® V SoC Development Board Reference Manual
Overview of the Intel FPGA SDK for OpenCL Standard Edition Custom Platform
Currently, the offline compiler targets a single Custom Platform at a time.
A given Custom Platform installation can include several board variants of the same board interface. You might have different FPGA parts, or you might want to support different subsets of board interfaces. Colocating the board variants allows simultaneous communication with different boards in a multiple-device environment.
An Intel® FPGA SDK for OpenCL™ Standard Edition Custom Platform contains the following components:
- Intel® Quartus® Prime skeleton project—A Intel® Quartus® Prime project for your board, which the SDK's offline compiler modifies to include the compiled kernel. This project must include a post-place-and-route partition for all logic not controlled by the kernel clock.
- Board installation setup—A description of your board and its various components.
- Generic I/O interface—An MMD software library that implements basic I/O between the host and the board.
- Board utilities—An implementation of the SDK's utilities for managing the accelerator board, including tasks such as installing and testing the board.
Directories and Files in an Intel FPGA SDK for OpenCL Standard Edition Custom Platform
Content | Description |
---|---|
board_env.xml | The XML file that describes the board installation to the SDK. |
<hardware> | Directory containing the Intel® Quartus® Prime projects for the supported boards within a given Custom Platform. Specify the name of this directory in the board_env.xml file. Within this directory, the SDK assumes that any subdirectory containing a board_spec.xml file is a board. |
include | Directory containing board-specific header files. |
source | Directory containing board-specific files, libraries and drivers. |
platform | Directory containing platform-specific (for example, x86_64 Linux) drivers and utilities. |
Recommendations for Structuring the Custom Platform Directory
For ease of use, consider adopting the Intel® -recommended directory structure and naming convention when you create an Intel® FPGA SDK for OpenCL™ Standard Edition Custom Platform.
- Make the
INTELFPGAOCLSDKROOT/board directory the location of the board
installation, where INTELFPGAOCLSDKROOT points to the
location of the SDK installation.Attention: Do not remove any existing subdirectories from the INTELFPGAOCLSDKROOT/board directory.
- Create a <board_vendor_name> subdirectory within the INTELFPGAOCLSDKROOT/board directory to store the Custom Platform.
- Store the contents of a given Custom Platform in a INTELFPGAOCLSDKROOT/board/<board_vendor_name>/<board_family_name> subdirectory.
- Assign unique names to software libraries (for example, lib<board_vendor_name>_<board_family_name>.so) to avoid name collisions.
For example, if you (ABC Incorporated) create a Custom Platform for a family of boards named XYZ, set up your Custom Platform such that the SDK user can access XYZ by installing the XYZ Custom Platform in INTELFPGAOCLSDKROOT/board/ABC/XYZ, where INTELFPGAOCLSDKROOT is the environment variable that points to the absolute path to the SDK installation package.
Custom Platform Automigration for Forward Compatibility
Automigration is more likely to complete successfully if your Custom Platform resembles an Intel® FPGA Reference Platform as closely as possible.
The following information applies to a Custom Platform that is version 14.0 and beyond:
- To update a Custom Platform for use with the current version of the Intel® Quartus® Prime Design Suite, which includes the SDK, do not modify your Custom Platform. The automigration capability detects the version of your Custom Platform based on certain characteristics and updates it automatically.
- If you have modified a Custom Platform and you want to update it for use with the current version of the Intel® Quartus® Prime Design Suite, which includes the SDK, implement all features mandatory for the current version of the Custom Platform. After you modify a Custom Platform, automigration can no longer correctly detect its characteristics. Therefore, you must upgrade your Custom Platform manually.
A successfully-migrated Custom Platform will preserve its original functionality. In most cases, new features in a new Intel® Quartus® Prime Design Suite or SDK version will not interfere with Custom Platform functionality.
- The version of the Custom Platform, as specified by the version attribute of the board XML element.
- The platform type, as specified by the platform_type parameter of the auto_migrate attribute within the compile XML element.
Based on the information, the SDK names a set of fixes it must apply during Custom Platform migration. It applies the fixes to the Intel® Quartus® Prime project that the offline compiler uses to compile the OpenCL kernel. It also generates an automigration.rpt report file in the SDK user's current working directory describing the applied fixes.
The automigration process does not modify the installed Custom Platform.
Customizing Automigration
-
Disable automigration in one of the following manners:
- If you are a board developer, within the compile XML element in the board_spec.xml file, set the platform_type parameter of the auto_migrate attribute to none.
- If you are an SDK user, invoke the aoc -no-auto-migrate command.
-
To explicitly include or exclude fixes that the
SDK identifies, in the
board_spec.xml file, subscribe or
unsubscribe to each fix by listing it in the include
fixes or exclude fixes parameter,
respectively. The include fixes and exclude fixes parameters are part of the auto_migrate attribute within the compile element. When listing multiple fixes,
separate each fix by a comma.
Refer to the automigration.rpt file for the names of the fixes that you specify in the include fixes and exclude fixes parameters.
Creating an Intel FPGA SDK for OpenCL Standard Edition Custom Platform
- Designing the Board Hardware
To design an accelerator board for use with the Intel® FPGA SDK for OpenCL™ Standard Edition, you must create all the board and system components, and the files that describe your hardware design to the Intel® FPGA SDK for OpenCL™ Offline Compiler. - Creating the Board XML Files
Your Custom Platform must include the XML files that describe your Custom Platform and each of your hardware system to the Intel® FPGA SDK for OpenCL™ Standard Edition. - Creating the MMD Library
Your Custom Platform requires an MMD layer necessary for communication with the accelerator board. - Setting Up the FPGA Client Driver
The FPGA Client Driver (FCD) allows the SDK to automatically find and load the Custom Platform libraries at host run time. - Providing Intel FPGA SDK for OpenCL Standard Edition Utilities Support
Each Custom Platform you develop for use with the Intel® FPGA SDK for OpenCL™ Standard Edition must support a set of SDK utilities. These utilities enable users to manage the accelerator board through the SDK. - Testing the Hardware Design
After you create the software utilities and the MMD layer, and your hardware design achieves timing closure, test the design.
Designing the Board Hardware
Each board variant in the Custom Platform consists of an Intel® Quartus® Prime project, and a board_spec.xml XML file that describes the system to the offline compiler. The board_spec.xml file describes the interfaces necessary to connect to the kernel. The offline compiler generates a custom circuit based on the data from the board_spec.xml file. Then it incorporates the OpenCL kernel into the Platform Designer (Standard) system you create for all nonkernel logic.
You must preserve the design of all nonkernel logic. You can preserve your design in the Intel® Quartus® Prime software via one of the following methods:
- Create a design partition containing all nonkernel logic under a single HDL hierarchy and then export the partition. For example, you may create and export a board.qsys Platform Designer (Standard) subsystem (see figure below). The top-level system.qsys Platform Designer (Standard) system can then instantiate this exported board Platform Designer (Standard) subsystem.
- Implement the Configuration via Protocol (CvP) configuration scheme, which preserves all logic outside a design partition. In this case, you only need to create a partition around the kernel logic. You may place all nonkernel logic into a single top-level Platform Designer (Standard) system file (for example, system.qsys).
You must design all the components and the board_spec.xml file that describe the system to the SDK.
Creating the Board Platform Designer (Standard) System
An implementation of a board Platform Designer (Standard) subsystem might include the following components:
- Proper reset sequencing
- Intel® FPGA SDK for OpenCL™ Standard Edition-specific components
- Host-to-FPGA communication IP
- Memory IP used for SDK's global memory
- Streaming channels to board-specific interfaces
Refer to The Board Platform Designer (Standard) System section for more information.
Templates of the following hardware design files are available in the INTELFPGAOCLSDKROOT/board/custom_platform_toolkit/board_package/hardware/template directory:
- board.qsys
- system.qsys
- top.v
- top.qpf
- board_spec.xml
Template of the post_flow.tcl file is available in the INTELFPGAOCLSDKROOT/board/custom_platform_toolkit/board_package/hardware/template/scripts directory of the Custom Platform Toolkit.
To create nonkernel logic, perform the following tasks in the system.qsys top-level Platform Designer (Standard) system or in a board Platform Designer (Standard) subsystem:
-
In Platform Designer (Standard), add your host and memory IPs to the
Platform Designer (Standard) system, and establish all necessary connections and
exports.
Attention: You might need to acquire separate IP licenses. For a list of available licensed and unlicensed IP solutions, visit the All Intellectual Property page of the Intel® FPGA website. For more information about each IP, click the link in the Product Name column to navigate to the product page.
-
Connect your host interface clock such that it drives
por_reset_controller/clk. Your design's global reset and clock
inputs are fed to a reset counter (por_reset_counter). This reset counter then synchronizes
to the host interface clock in the Merlin Reset Controller (por_reset_controller).
The por_reset_counter ACL SW Reset component implements the power-on reset. It resets all the device hardware by issuing a reset for a number of cycles after the FPGA completes its configuration.
- Modify the parameters of the pipe_stage_host_ctrl Avalon® Memory-Mapped (Avalon-MM) Pipeline Bridge component such that it can receive requests from your host IP. Connect your host interface's Avalon-MM master port to the s0 port of pipe_stage_host_ctrl. Connect the m0 port of pipe_stage_host_ctrl to all the peripherals that must communicate with your host interface, including the OpenCL Kernel Clock Generator and the OpenCL Kernel Interface components.
-
Adjust the number of clock_cross_kernel_mem_<N>
Avalon-MM Clock Crossing Bridge
components to match the number of memory interfaces on your board. This
component performs clock crossing between the kernel and memory
interfaces. Modify the parameters of each component so that they are
consistent with the parameters of the OpenCL Memory Bank Divider
component and the interface attribute
described in board_spec.xml.
Connect the m0 master, clock, and reset
ports of clock_cross_kernel_mem_<N>
(that is, m0, m0_clk, and m0_reset,
respectively) to your memory IP.
Important: Connect m0_reset in such a way that assertion of kernel_reset from the OpenCL Memory Bank Divider component triggers this reset.
-
Connect your host interface clock such that it drives
por_reset_controller/clk. Your design's global reset and clock
inputs are fed to a reset counter (por_reset_counter). This reset counter then synchronizes
to the host interface clock in the Merlin Reset Controller (por_reset_controller).
-
Customize the SDK-specific Platform Designer (Standard) system
components..
Attention: If you use the board.qsys system template to create a Platform Designer (Standard) subsystem, note that it is preconfigured with the necessary connections between the SDK-specific system components and the appropriate interfaces exported to match the board_spec.xml file. Intel® recommends that you preserve the preconfigured connections as much as possible.
- In Platform Designer (Standard), click Tools > Options. In the Options dialog box, add INTELFPGAOCLSDKROOT/ip/board to the Qsys IP Search Path and then click Finish.
- Instantiate the OpenCL Kernel Clock Generator component. Specify the component parameters, and connect the signals and ports as outlined in the OpenCL Kernel Clock Generator section.
- Instantiate the OpenCL Kernel Interface component. Specify the component parameters, and connect the signals and ports as outlined in the OpenCL Kernel Interface section.
-
For each global memory type, instantiate the OpenCL
Memory Bank Divider component. Specify the component parameters, and
connect the signals and ports as outlined in the OpenCL Memory Bank Divider section.
Attention: Set the parameters such that the resulting bank masters have the equivalent address bits and burst widths as those from the kernel, as defined in the interface attribute of the global_mem element in the board_spec.xml file. For each memory bank, Platform Designer (Standard) generates a master that inherits the same characteristics as your specifications.
- If you choose to create a Platform Designer (Standard) subsystem for the nonkernel logic, export any necessary I/Os to the top-level system.qsys Platform Designer (Standard) system.
- Edit the top-level top.v file to instantiate system.qsys and connect any board-specific I/Os.
- Set up the top.qpf Intel® Quartus® Prime project with all the necessary settings for your board design.
-
Modify the post_flow.tcl
file to include the Tcl code that generates the fpga.bin file during
Intel®
Quartus® Prime compilation.
The fpga.bin file is necessary for programming the board.
- Edit the board_spec.xml file to include board-specific descriptions.
General Quality of Results Considerations for the Exported Board Partition
The list below captures some of the parameters that might impact the quality of SDK compilation results:
- Resources
Used
Minimize the number of resources the partition uses to maximize the resources available for the OpenCL kernels.
- Kernel Clock Frequency
Intel® recommends that the kernel clock has a high clock constraint (for example, greater than 350 MHz for a Stratix® V device). The amount of logic in the partition clocked by the kernel clock should be relatively small. This logic should not limit the kernel clock speed for even the simplest OpenCL kernels. Therefore, at least within the partition, the kernel clock should have a high clock constraint.
- Host-to-Memory Bandwidth
The host-to-memory bandwidth is the transfer speed between the host processor to the physical memories on the accelerator card. To measure this memory bandwidth, compile and run the host application included with the Custom Platform Toolkit.
- Kernel-to-Memory
Bandwidth
The kernel-to-memory bandwidth is the maximum transfer speed possible between the OpenCL kernels and global memory.
To measure this memory bandwidth, compile and run the host program included in the /tests/boardtest/host directory of the Custom Platform Toolkit.
- Fitter Quality of
Results (QoR)
To ensure that OpenCL designs consuming much of the device's resources can still achieve high clock frequencies, region-constrain the partition to the edges of the FPGA. The constraint allows OpenCL kernel logic to occupy the center of the device, which has the most connectivity with all other nodes.
Test compile large designs to ensure that other Fitter-induced artifacts in the partition do not interfere with the QoR of the kernel compilations.
- Routability
The routing resources that the partition consumes can affect the routability of a compiled OpenCL design. A kernel might use every digital signal processing (DSP) block or memory block on the FPGA; however, routing resources that the partition uses might render one of these blocks unroutable. This routing issue causes compilation of the Intel® Quartus® Prime project to fail at the fitting step. Therefore, it is imperative that you test a partition with designs that use all DSP and memory blocks.
Establishing Guaranteed Timing Flow
-
Create a placed and routed design partition using the
incremental compilation feature of the
Intel®
Quartus® Prime software. This is the design partition
for nonkernel logic.
For more information on how to use the incremental compilation feature to generate a timing-closed design partition, refer to the Intel® Quartus® Prime Incremental Compilation for Hierarchical and Team-Based Design chapter in Volume 1 of the Intel® Quartus® Prime Standard Edition Handbook.
- Import the post-fit partition from 1 into the top-level design as part of the compilation flow.
-
Run the
INTELFPGAOCLSDKROOT/ip/board/bsp/adjust_plls.tcl
script as a post-flow process, where INTELFPGAOCLSDKROOT points to the path of the
Intel® FPGA SDK for OpenCL™
Standard
Edition installation.
The adjust_plls.tcl script determines the maximum kernel clock frequency and stores it in the pll_rom on-chip memory of the OpenCL Kernel Clock Generator component.
Creating the Board XML Files
Creating the board_env.xml File
A board_env.xml template is available in the /board_package directory of the Custom Platform Toolkit.
-
Create a board_env top-level
XML element. Within board_env, include the
following XML elements:
- hardware
-
platform
Include a platform element for each operating system that your Custom Platform supports.
-
Within each platform element,
include the following XML elements:
- mmdlib
- linkflags
- linklibs
- utilbindir
-
Parameterize each element and corresponding attribute(s) with information specific to your Custom Platform, as outline in the table below:
Table 2. Specifications of XML Elements and Attributes in the board_env.xml File Element Attribute Description board_env version: The SDK's Custom Platform Toolkit release you use to create your Custom Platform. Attention: The Custom Platform version must match the SDK version you use to develop the Custom Platform.name: Name of the board installation directory containing your Custom Platform.
hardware dir: Name of the subdirectory, within the board installation directory, that contains the board variants. default: The default board variant that the offline compiler targets when the SDK user does not specify an explicit argument for the --board <board_name> offline compiler option.
platform name: Name of the operating system. Refer to the Intel® FPGA SDK for OpenCL™ Standard Edition Getting Started Guide and the Intel® FPGA RTE for OpenCL Standard Edition Getting Started Guide for more information.
mmdlib A string that specifies the path to the MMD library of your Custom Platform. To load multiple libraries, specify them in an ordered, comma-separated list. The host application will load the libraries in the order that they appear in the list.
Tip: You can use %b to reference your board installation directory.linkflags A string that specifies the linker flags necessary for linking with the MMD layer available with the board. Tip: You can use %a to reference the SDK installation directory and %b to reference your board installation directory.linklibs A string that specifies the libraries the SDK must link against to use the MMD layer available with the board. Note: Include the alterahalmmd library, available with the SDK, in this field because the library is necessary for all devices with an MMD layer.utilbindir Directory in which the SDK expects to locate the its utility executables (that is, install, uninstall, program, diagnose and flash). Tip: You can use %a to reference the SDK installation directory and %b to reference your board installation directory.
<?xml version="1.0"?> <board_env version="<SDK_version>" name="<Custom_Platform_name>"> <hardware dir="hardware" default="<board_name>"></hardware> <platform name="linux64"> <mmdlib>%b/linux64/lib/libaltera_<Custom_Platform_name>_mmd.so</mmdlib> <linkflags>-L%b/linux64/lib</linkflags> <linklibs>-laltera_<Custom_Platform_name>_mmd</linklibs> <utilbindir>%b/linux64/libexec</utilbindir> </platform> <platform name="windows64"> <mmdlib>%b/windows64/bin/altera_<Custom_Platform_name>_mmd.dll</mmdlib> <linkflags>/libpath:%b/windows64/lib</linkflags> <linklibs>altera_<Custom_Platform_name>_mmd.lib</linklibs> <utilbindir>%b/windows64/libexec</utilbindir> </platform> </board_env>
Where:
- <SDK_version> is the Intel® FPGA SDK for OpenCL™ Standard Edition version.
- <customplatform_name> is the name of your Custom Platform (for example, s5_net).
- <board_name> is the name of the FPGA board.
Testing the board_env.xml File
After you generate the board_env.xml file, test the file within your board installation directory to ensure that the Intel® FPGA SDK for OpenCL™ Offline Compiler recognizes the board installation.
- Set the environment variable AOCL_BOARD_TOOLKIT_ROOT to point to the Custom Platform subdirectory in which your board_env.xml file resides.
-
At the command prompt, invoke the
aocl
board-xml-test
command to
verify that the
Intel® FPGA SDK for OpenCL™
Standard
Edition can locate the correct field values.
The SDK generates an output similar to the one below:
board-path = <path_to_customplatform> board-version = <SDK_version> board-name = <customplatform_name> board-default = <board_name> board-hw-path = <path_to_customplatform>/hardware/<customplatform_name> board-link-flags = /libpath:<path_to_customplatform/windows64/lib board-libs = alterahalmmd.lib altera_<customplatform_name>_mmd.lib board-util-bin = <path_to_customplatform>/windows64/libexec board-mmdlib = <path_to_customplatform>/windows64/bin/altera_<customplatform_name>_mmd.dll
-
Invoke the
aoc
-list-boards
command to verify
that the offline compiler can identify and report the board variants in the
Custom Platform.
For example, if your Custom Platform includes two FPGA boards, the SDK generates an output similar to the one below:
Board list: <board_name_1> <board_name_2>
The last board installation test takes place when you use the offline compiler to generate a design for your board.
Creating the board_spec.xml File
-
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 -
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: s5_net).
-
For the device element, perform the following steps to specify the name of the device model file.
- 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.
-
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="5sgsed8k2f40c2_dm.xml"
- 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:
- Copy a device model from the INTELFPGAOCLSDKROOT/share/models/dm directory (for example, 5sgxma7h2fe35c2_dm.xml).
- Place your copy of the device model in the Custom Platform subdirectory in which your board_spec.xml file resides.
-
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, 5sgxma7h2fe35c2).
You can search for the Intel® FPGA device part number on the Buy page of the Intel® FPGA website.
- In the board_spec.xml file, update the device_model attribute of the device element with the name of your file.
-
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.
-
For each global memory type, specify the following information:
- Name of the memory type.
-
The combined maximum global memory bandwidth.
You can calculate this bandwidth value from datasheets of your memories.
-
The size of the data that the
Intel® FPGA SDK for OpenCL™ Offline Compiler interleaves across
memory banks.
Note: interleaved_bytes = burst_size x width_bytes
- 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 (Standard) component (mem_org_mode).
-
If you choose to set a global memory type as default, assign a value of 1 to the optional default attribute.
If you do not include this attribute, the first memory defined in the board_spec.xml file becomes the default memory.
- Specify the parameters in the interface attribute to describe the characteristics of each memory interface.
- 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 master in the OpenCL Kernel Interface Platform Designer (Standard) component.
- 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.
-
Include the interfaces element to describe the kernel interfaces connecting to and controlling OpenCL kernels. Include one of each interface types (that is master, irq, and streamsource).
-
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) masters from corresponding OpenCL Memory Bank Divider component for the default memory.
- Specify the parameters in the kernel_clk_reset attribute to include the exported kernel clock and reset interfaces as kernel interfaces.
-
Specify the parameters in the interface attribute to describe the characteristics of each kernel interface.
- Include the compile element and specify its attributes to control the Intel® Quartus® Prime compilation, registration, and automigration.
<?xml version="1.0"?> <board version="<SDK_version>" name="<board_name>"> <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="<customplatform_name>" > <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="<customplatform_name>" > <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="<customplatform_name>" > <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 <customplatform_name> <board_name>"/> <auto_migrate platform_type="<customplatform_name>" > <include fixes=""/> <exclude fixes="pre_skipbak"/> </auto_migrate> </compile> <device device_model="<devicemodel_filename>"> <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="slave" 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="master" 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>
Creating the MMD Library
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.
The following tasks outline the procedure for creating an MMD library for use with PCI Express® (PCIe®).
-
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
-
Include the
INTELFPGAOCLSDKROOT/board/custom_platform_toolkit/mmd/aocl_mmd.h
header file 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.
-
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_s5_net>/source/host/mmd directory of the Intel® Stratix® V 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.
- Modify the mmdlib and linkflags elements in the board_env.xml file by specifying the library flags necessary for linking with the MMD layer.
Kernel Power-up State
The general sequence of calls for a single host application is as follows:
- get_offline_info
- open
- get_info
- set_status_handler
- set_interrupt_handler
- get_info /read/write/copy/yield
- close
Setting Up the FPGA Client Driver
Enumerating the Custom Platform FCD on Windows
Specify the Custom Platform libraries in the registry key HKEY_LOCAL_MACHINE\SOFTWARE\Altera\OpenCL\Boards. Specify the value name to be the path to the library, and specify the data to be a DWORD that is set to 0.
For example:
[HKEY_LOCAL_MACHINE\SOFTWARE\Altera\OpenCL\Boards] "c:\board_vendor a\my_board_mmd.dll"=dword:00000000
To enumerate Custom Platform FCDs on Windows, the FCD Loader scans the value in the registry key HKEY_LOCAL_MACHINE\SOFTWARE\Altera\OpenCL\Boards. For each value in this key, the name specifies the path to a DLL and the data is a dword. If the dword data is 0, the Installable Client Driver (ICD) Loader attempts to open the corresponding DLL. If the DLL is an MMD library, then the SDK attempts to open any board that is associated with that library.
In this case, the FCD opens the library c:\board_vendor a\my_board_mmd.dll.
If the registry key specifies multiple libraries, the Loader loads the libraries in the order that they appear in the key. If there is an order dependency between the libraries available with your Custom Platform, ensure that you list the libraries accordingly in the registry key.
Enumerating the Custom Platform FCD on Linux
Enter the absolute paths of Custom Platform libraries in a .fcd file (formerly, a .acd file). Store the .fcd file in the /opt/Intel/OpenCL/Boards/ directory.
To enumerate Custom Platform FCDs on Linux, the FCD Loader scans the files with the extension .fcd in the path /opt/Intel/OpenCL/Boards/. The FCD Loader opens each .fcd file in this path as a text file. Each .fcd file should contain the absolute path to every library in the Custom Platform, one library per line. The ICD Loader attempts to open each library. If the library is an MMD library, then the SDK attempts to open any board that is associated with that library.
For example, consider the file /opt/Intel/OpenCL/Boards/PlatformA.fcd. If it contains the line /opt/PlatformA/libPlatformA_mmd.so, the FCD Loader loads the library /opt/PlatformA/libPlatformA_mmd.so.
If the .fcd file specifies multiple libraries, the Loader loads the libraries in the order that they appear in the file. If there is an order dependency between the libraries available with your Custom Platform, ensure that you list the libraries accordingly in the .fcd file.
Starting in the Intel® FPGA SDK for OpenCL™ version 16.1, FCD allows the SDK users to load multiple heterogeneous boards from different Custom Platforms and use them together in a single host application. However, this feature has limited support for legacy Custom Platforms that are released prior to 16.1.
For more information on how SDK users link their host applications to the ICD and FCD, refer to the Linking Your Host Application to the Khronos ICD Loader Library section in the Intel® FPGA SDK for OpenCL™ Standard Edition Programming Guide.
Providing Intel FPGA SDK for OpenCL Standard Edition Utilities Support
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:
Within the <path_to_s5_net>/source/util directory of the Intel® Stratix® V Network 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_s5_net>/<OS_platform>/libexec directory.
You can find the source code for the diagnose utility in the <path_to_s5_net>/source/util/diagnostic directory within the Intel® Stratix® V Network Reference Platform.
-
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>
-
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>
-
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> .
-
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_reprogram function implemented in the MMD layer. Refer to the aocl_mmd_reprogram and Reprogram 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.
-
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.
Testing the Hardware Design
To test the hardware design, perform the following tasks:
-
Navigate to the boardtest.cl
OpenCL™ kernel within the
INTELFPGAOCLSDKROOT/board/custom_platform_toolkit/tests/boardtest
directory.
INTELFPGAOCLSDKROOT points to the location of the Intel® FPGA SDK for OpenCL™ Standard Edition installation.
- Compile your kernel to generate an Intel® FPGA SDK for OpenCL™ Offline Compiler executable file (.aocx) by invoking the aoc -no-interleaving=default boardtest.cl command.
- Program the accelerator board by invoking the aocl program acl0 boardtest.aocx command.
- Invoke the commands aocl compile-config and aocl link-config . Confirm they include flags necessary for your MMD layer to compile and link successfully.
-
Build the boardtest
host application.
- For Windows systems, you
may invoke the
make -f Makefile.windows command or use
Microsoft Visual Studio.
If you invoke the make command, use the Makefile.windows file located in the INTELFPGAOCLSDKROOT/board/custom_platform_toolkit/tests/boardtest directory.
If you build your host application in Microsoft Visual Studio, the boardtest.sln and main.cpp files are located in the INTELFPGAOCLSDKROOT/board/custom_platform_toolkit/tests/boardtest/host directory.
- For Linux systems, invoke
the
make
-f Makefile.linux command.
The Makefile.linux file is located in the INTELFPGAOCLSDKROOT/board/custom_platform_toolkit/tests/boardtest directory.
- For Windows systems, you
may invoke the
make -f Makefile.windows command or use
Microsoft Visual Studio.
- Run the boardtest executable.
To qualify as an Intel® FPGA preferred board, rigorous testing across multiple boards is necessary. Specifically, you should perform overnight testing of all Custom Platform tests and executes the SDK example designs on multiple boards . All board variants within a Custom Platform must go through the testing process.
Applying for the Intel FPGA SDK for OpenCL Standard Edition Preferred Board Status
For your Custom Platform and the supported FPGA boards to achieve the Intel® FPGA SDK for OpenCL™ Preferred Board status, you must generate the following data and submit it to Intel® :
- The output from invoking the aocl board-xml-test command.
- The output from invoking the aoc -list-boards command.
-
The outputs from the host compilation, host execution, and all
Intel®
Quartus® Prime report files (.rpt). Also, for each board in your Custom Platform, the
acl_quartus_report.txt file from the
following tests:
- All tests included in the INTELFPGAOCLSDKROOT/board/custom_platform_toolkit/tests directory, where INTELFPGAOCLSDKROOT points to location of the Intel® FPGA SDK for OpenCL™ Standard Edition installation.
-
Compilations of the following examples on the OpenCL
Design Examples page of the
Intel
FPGA website:
- Vector Addition
- Matrix Multiplication
- FFT (1D)
- FFT (2D)
- Sobel Filter
- Finite Difference Computation (3D)
-
For each board in
the Custom Platform, a summary of the following:
- HOST-TO-MEMORY BANDWIDTH as reported by the boardtest test in the Custom Platform Toolkit (/tests/boardtest).
- KERNEL-TO-MEMORY BANDWIDTH as reported by the boardtest test.
- Throughput in swap-and-execute(s) reported by the swapper test in the Custom Platform Toolkit (/tests/swapper).
- Actual clock freq as reported in the acl_quartus_report.txt file from the blank test in the Custom Platform Toolkit ( INTELFPGAOCLSDKROOT/board/custom_platform_toolkit/tests/blank).
Important: Use global routing to reduce consumption of local routing resources. Using global routing is necessary because it helps meet timing and improve kernel performance (Fmax). Use global or regional routing for any net with fan-out greater than 5000, and for kernel clock, 2x clock and reset. Check the Non-Global High Fan-Out Signals report in the Resource subsection, which is under the Fitter section of the Compilation Report. -
Submit the necessary number of boards to
Intel®
for in-house regression
testing. Regression testing tests the out-of-the-box experience for each board
variant on each operating system that your Custom Platform supports. Ensure that
you test the procedure outlined below before you submit your boards:
- Install the board into the physical machine.
- Boot the machine and invoke the aocl install <path_to_customplatform> utility command.
- Invoke the aocl diagnose command.
- Run the SDK's test programs. The tester can also invoke the aocl program <device_name> <kernel_filename>.cl command to verify the functionality of the program utility.
Shipping Recommendations
Before shipping your Intel® -verified board to Intel® FPGA SDK for OpenCL™ users, program the flash memory of the board with the hello_world OpenCL design example. Programming the flash memory of the board with the hello_world.aocx hardware configuration file allows the SDK user to power on the board and observe a working kernel.
Download the hello_world OpenCL design example from the OpenCL Design Examples page on the Intel FPGA website.
For more information, refer to the README.txt file available with the hello_world OpenCL design example and the Programming the Flash Memory of an FPGA sections in the Intel® FPGA SDK for OpenCL™ Standard Edition Getting Started Guide.
Intel FPGA SDK for OpenCL Standard Edition Custom Platform Design Revision History
Document Version | Intel® Quartus® Prime Version | Changes |
---|---|---|
2018.09.24 | 18.1 |
|
2018.05.04 | 18.0 |
|
Date | Version | Changes |
---|---|---|
November 2017 | 2017.11.03 |
|
May 2017 | 2017.05.08 |
|
October 2016 | 2016.10.31 |
|
May 2016 | 2016.05.02 |
|
November 2015 | 2015.11.02 |
|
May 2015 | 15.0.0 |
|
December 2014 | 14.1.0 |
|
October 2014 | 14.0.1 |
|
June 2014 | 14.0.0 |
|
Intel FPGA SDK for OpenCL Standard Edition Custom Platform Toolkit Reference Material
The Board Platform Designer (Standard) Subsystem
The diagram below represents a board system implementation in more details:
The OpenCL host communication interface and global memory interface are the main components of the board system. The memory-mapped device (MMD) layer communicates, over some medium, with the intellectual property (IP) core instantiated in this Platform Designer (Standard) system.
For example, an MMD layer executes on a PCI Express® (PCIe®)-based host interface, and the host interface generates Avalon interface requests from an Intel® PCIe endpoint on the FPGA.
Within the board Platform Designer (Standard) subsystem, you can also define the global memory system available to the OpenCL kernel. The global memory system may consist of different types of memory interfaces. Each memory type may consist of one, two, four, or eight banks of physical memory. All the banks of a given memory type must be the same size in bytes and have equivalent interfaces. If you have streaming I/O, you must also include the corresponding IP in the board Platform Designer (Standard) system. In addition, you must update the board_spec.xml file to describe the channel interfaces.
Intel FPGA SDK for OpenCL Standard Edition-Specific Platform Designer (Standard) System Components
The board Platform Designer (Standard) system must export an Avalon®-MM master for controlling OpenCL kernels. It must also export one or more Avalon-MM slave ports that the kernels use as global memory interfaces. The INTELFPGAOCLSDKROOT/ip/board directory of the SDK includes a library that contains SDK-specific Platform Designer (Standard) system components, where INTELFPGAOCLSDKROOT points to the location of the SDK installation. These components are necessary for implementing features such as Avalon-MM interfaces, organizing programmable banks, cache snooping, and supporting Altera's guaranteed timing closures.
- OpenCL Kernel Clock Generator
The OpenCL™ Kernel Clock Generator is a Platform Designer (Standard) component that generates a clock output and a clock 2x output for use by the OpenCL kernels. - OpenCL Kernel Interface
The OpenCL™ Kernel Interface is a Platform Designer (Standard) component that allows the host interface to access and control the OpenCL kernel. - OpenCL Memory Bank Divider
The OpenCL™ Memory Bank Divider is a Platform Designer (Standard) component that takes an incoming request from the host interface on the Avalon®-MM slave port and routes it to the appropriate bank master port.
OpenCL Kernel Clock Generator
Parameter | Description |
---|---|
REF_CLK_RATE | Frequency of the reference clock that drives the kernel PLL (that is, pll_refclk). |
KERNEL_TARGET_CLOCK_RATE | Frequency that the
Intel®
Quartus® Prime Standard Edition software attempts to achieve
during compilation. Keep this parameter at its default setting. |
Signal or Port | Description |
---|---|
pll_refclk | The reference clock for the kernel PLL. The frequency of this clock must match the frequency you specify for the REF_CLK_RATE component parameter. |
clk | The clock used for the host control interface. The clock rate of clk can be slow. |
reset | The reset signal that resets the PLL and the control logic. Resetting the PLL disables the kernel clocks temporarily. Connect this reset signal to the power-on reset signal in your system. |
ctrl | The slave port used to connect to the OpenCL host interface and to adjust the frequency based on the OpenCL kernel. |
kernel_clk
kernel_clk2x |
The kernel clock and its 2x variant that runs on twice the speed. The kernel_clk2x signal is directly exported from this interface. Because kernel_clk has internal Platform Designer (Standard) connections, export it using a clock source component. You can also use the clock source to export the kernel reset. In addition, clock all logic at the board Platform Designer (Standard) system interface with kernel_clk, except for any I/O that you add. |
kernel_pll_locked | (Optional) If the PLL is locked onto the reference clock, the value of this signal is 1. The host interface manages this signal normally; however, this signal is made available in the board Platform Designer (Standard) system. |
OpenCL Kernel Interface
Parameter | Description |
---|---|
Number of global memory systems | Number of global memory types in your board design. |
Signal or Port | Description |
---|---|
clk | The clock input used for the host control interface. The clock rate of clk can be slow. |
reset | This reset input resets the control interface. It also triggers the kernel_reset signal, which resets all kernel logic. |
kernel_ctrl | Use this slave port to connect to the OpenCL host interface. This interface is a low-speed interface with which you set kernel arguments and start the kernel's execution. |
kernel_clk | The kernel_clk output from the OpenCL Kernel Clock Generator drives this clock input. |
kernel_cra | This Avalon®-MM master interface communicates directly with the kernels generated by the Intel® FPGA SDK for OpenCL™ Offline Compiler. Export the Avalon-MM interface to the OpenCL Kernel Interface and name it in the board_spec.xml file. |
sw_reset_in | When necessary, the OpenCL host interface resets the kernel via the kernel_ctrl interface. If the board design requires a kernel reset, it can do so via this reset input. Otherwise, connect the interface to a global power-on reset. |
kernel_reset | Use this reset output to reset the kernel and any other
hardware that communicates with the kernel. Warning: This reset occurs between the MMD
open and close calls. Therefore, it must not reset anything
necessary for the operation of your MMD.
|
sw_reset_export | This reset output is the same as kernel_reset, but it is synchronized to the clk interface. Use this output to reset logic that is not in the kernel_clk clock domain but should be reset whenever the kernel resets. |
acl_bsp_memorg_host | The memory interfaces use these signals. Based on the number of global memory systems you specify in the OpenCL Kernel Interface component parameter editor, the Intel® Quartus® Prime Standard Edition software creates the corresponding number of copies of this signal, each with a different hexadecimal suffix. Connect each signal to the OpenCL Memory Bank Divider component associated with each global memory system (for example, DDR). Then, list the hexadecimal suffix in the config_addr attribute of the global_mem element in the board_spec.xml file. |
kernel_irq_from_kernel | An interrupt input from the kernel. This signal will be exported and named in the board_spec.xml file. |
kernel_irq_to_host | An interrupt output from the kernel. This signal will connect to the host interface. |
OpenCL Memory Bank Divider
Parameter | Description |
---|---|
Number of banks | Number of memory banks for each of the global memory types included in your board system. |
Separate read/write ports | Enable this parameter so that each bank has one port for read operation and one for write operation. |
Add pipeline stage to output | Enable this parameter to allow for potential timing improvements. |
Data Width | Width of the data bus to the memory in bits. |
Address Width (total addressable) | Total number of address bits necessary to address all global memory. |
Burst size (maximum) | The maxburst value defined in the interface attribute of the global_mem element in the board_spec.xml file. |
Maximum Pending Reads | Maximum number of pending read transfers the component
can process without asserting a waitrequest signal. CAUTION: A high Maximum Pending Reads value
causes Platform Designer (Standard) to insert a deep response FIFO
buffer, between the component's master and slave, that consumes
a lot of device resources. It also increases the achievable
bandwidth between host and memory interfaces.
|
Split read/write bursts on burst word boundary | Enable splitting of read and write bursts on burst
word boundary. Enable this parameter if the Number of banks parameter value is greater than 1, and the burst reads and writes that the host controller sends to the slave port crosses burst word boundary. |
Signal or Port | Description |
---|---|
clk | The bank divider logic uses this clock input. If the IP of your host and memory interfaces have different clocks, ensure that clk clock rate is not slower than the slowest of the two IP clocks. |
reset | The reset input that connects to the board power-on reset. |
s | The slave port that connects to the host interface controller. |
kernel_clk | The kernel_clk output from the OpenCL Kernel Clock Generator drives this clock input. |
kernel_reset | The kernel_reset output from the OpenCL Kernel Interface drives this reset input. |
acl_bsp_snoop | Export this Avalon®
Streaming (Avalon-ST) source. In the board_spec.xml file, under interfaces, describe only the snoop interface for the
default memory (acl_internal_snoop). If you have a heterogeneous memory
design, perform these tasks only for the OpenCL Memory Bank Divider
component associated with the default memory. Important: The memory system you build in
Platform Designer (Standard) alters the width of acl_bsp_snoop. You must update the
width of the streamsource
interface within the channels
element in the board_spec.xml file to match the width of
acl_bsp_snoop.
Important: In the board_spec.xml file, update the
width of the snoop interface (acl_internal_snoop) specified with the streamsource kernel interface
within the interfaces element.
Updating the width ensures that the global_mem interface entries in board_spec.xml match the
characteristics of the bank<N>
Avalon-MM
masters from corresponding OpenCL Memory Bank Divider component
for the default memory.
|
acl_bsp_memorg_host | This conduit connects to the acl_bsp_memorg_host interface of the OpenCL Kernel Interface. |
bank1, bank2, ..., bank8 | The number of memory masters available
in the OpenCL Memory Bank Divider depends on the number of memory banks that were included when the unit was instantiated. Connect each bank with each memory interface in the same order as the
starting address for the corresponding kernel memory interface specified in the
board_spec.xml file. For example, global_mem interface that begins at address 0 must correspond to the memory master in bank1 from the OpenCL Memory Bank Divider. |
XML Elements, Attributes, and Parameters in the board_spec.xml File
- board
The board element of the board_spec.xml file provides the version and the name of the accelerator board. - device
The device element of the board_spec.xml file provides the device model and the resources that the board design uses. - 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. - host
The host element of the board_spec.xml file provides information on the interface from the host to the kernel. - channels
Include the channels element in the board_spec.xml file if your accelerator board provides channels for direct kernel-to-I/O accesses. - interfaces
The interfaces element of the board_spec.xml file describes the kernel interfaces which will connect to OpenCL™ kernels and control their behaviors. - interface
For the global_mem, channels, and interfaces XML elements, include an interface attribute for each interface and specify the corresponding parameters. - compile
The compile element of the board_spec.xml file and its associated attributes and parameters describe the general control of Intel® Quartus® Prime compilation, registration, and automigration.
board
<board version="<version>" name="<Custom_Platform_name>"> ... </board>
Attribute | Description |
---|---|
version | The version of the board. The board version must match the version of the Intel® Quartus® Prime Standard Edition software you use to develop the Custom Platform. |
name | The name of the accelerator board, which must match the name of the directory in which the board_spec.xml file resides. The name must contain a combination of only letters, numbers, underscores (_), hyphens (-), or periods (.) (for example, a10_ref). |
device
<device device_model="5sgsed8k2f40c2_dm.xml"> <used_resources> <alms num="45000"/> <!-- ALMs used in final placement - ALMs used for registers --> <ffs num="117500"/> <dsps num="0"/> <rams num="511"/> </used_resources> </device>
Attribute | Description |
---|---|
device_model | The file name of the device model file that describes the available FPGA resources on the accelerator board. |
used_resources | Reports the number of adaptive logic modules (ALMs),
flip-flops, digital signal processor (DSP) blocks and RAM blocks
that the board design consumes, in the absence of any kernel, to the
Intel® FPGA SDK for OpenCL™
Standard Edition. If you create a defined
partition around all the board logic, you can obtain the used
resources data from the Partition Statistics section of the Fitter
report. Extract the information from the following parameters:
|
global_mem
<!-- DDR3-1600 --> <global_mem name="DDR" max_bandwidth="25600" interleaved_bytes="1024" config_addr="0x018"> <interface name="board" port="kernel_mem0" type="slave" width="512" maxburst="16" address="0x00000000" size="0x100000000" latency="240"/> <interface name="board" port="kernel_mem1" type="slave" 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="slave" 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="slave" 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="slave" 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="slave" 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>
Attribute | Description |
---|---|
name | The name the Intel® FPGA SDK for OpenCL™ Standard 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, which is generally computed by burst_size x width_bytes. 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 slave 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 (Standard) 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 will use 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. 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. |
host
<host> <kernel_config start="0x00000000" size="0x0100000"/> </host>
Attribute | Description |
---|---|
kernel_config | This attribute informs the
Intel® FPGA SDK for OpenCL™ Offline Compiler
at what offset the kernel resides, from the perspective of the
kernel_cra master on the
kernel_interface module. start: the starting address of the kernel. Normally, this attribute has a value of 0 because the kernel_cra master should not master anything except kernels. size: keep this parameter at the default value of 0x0100000. |
channels
<channels> <interface name="udp_0" port="udp0_out" type="streamsource" width="256" chan_id="eth0_in"/> <interface name="udp_0" port="udp0_in" type="streamsink" width="256" chan_id="eth0_out"/> <interface name="udp_0" port="udp1_out" type="streamsource" width="256" chan_id="eth1_in"/> <interface name="udp_0" port="udp1_in" type="streamsink" width="256" chan_id="eth1_out"/> </channels>
interfaces
<interfaces> <interface name="board" port="kernel_cra" type="master" 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>
In addition to the master, irq, and streamsource interfaces, if your design includes a separate Platform Designer (Standard) subsystem containing the board logic, the kernel clock and reset interfaces exported from it are also part of the interfaces element. Specify these interfaces with the kernel_clk_reset attribute and its corresponding parameters.
Attribute | Description |
---|---|
clk | The Platform Designer (Standard) name for the kernel clock interface. The kernel_clk output from the OpenCL Kernel Clock Generator component drives this interface. |
clk2x | The Platform Designer (Standard) name for the kernel clock interface. The kernel_clk2x output from the OpenCL Kernel Clock Generator component drives this interface. |
reset | The Platform Designer (Standard) connection for the kernel reset. The kernel_reset output from the OpenCL Kernel Interface component drives this interface. |
interface
Parameter | Applicable Interface | Description |
---|---|---|
name | All | For global_mem: instance name
of the Platform Designer (Standard) component. For channels: instance name of the Platform Designer (Standard) component that has the channel interface. For interfaces: name of the entity in which the kernel interface resides (for example, board). |
port | For global_mem: name of the
Avalon®-MM interface in
the Platform Designer (Standard) component that corresponds to the
interface attribute. For channels: name of the streaming interface in the Platform Designer (Standard) component. For interfaces: name of the interface to the OpenCL™ Kernel Interface Platform Designer (Standard) component. For example, kernel_cra is the Avalon®-MM interface, and kernel_irq is an interrupt. |
|
type | For global_mem: set to
slave. For channels:
For interfaces: set to either master, irq, or streamsource. |
|
width | For global_mem: width of the
memory interface in bits. For channels: number of bits in the channel interface. For interfaces: width of the kernel interface in bits. |
|
waitrequest_allowance |
For global_mem: [Optional] Amount of Avalon-MM waitrequest allowance supported on the slave interface (that is, kernel-facing interface) of the clock-crossing bridge that spans between the memory and the kernel clock domains. For kernel_cra: [Optional] Amount of Avalon-MM waitrequest allowance that the kernel_cra slave interface must support. This parameter defaults to 0 if you do not specify it in the board_spec.xml file. A value of 0 indicates that this waitrequest allowance feature is disabled. |
|
maxburst | global_mem | Maximum burst size for the slave interface. Attention: The value of width ÷ 8 x maxburst must equal to the value of interleaved_bytes.
|
address | Starting
address of the memory interface that corresponds to the host interface-side address. For example, address 0 should correspond to the bank1 memory master from the OpenCL Memory Bank Divider. In addition, any non-zero starting address must abut the end address of the previous memory. |
|
size | Size of the memory interface in bytes. The sizes of all memory interfaces should be equal. | |
latency_type | If the memory interface has variable latency, set this parameter to average to signify that the specified latency is considered the average case. If the complete kernel-to-memory path has a guaranteed fixed latency, set this parameter to fixed. | |
chan_id | channels | A string used to identify the channel interface. The string may have up to 128 characters. |
clock | interfaces | For the streamsource kernel interface type, the parameter specifies the name of the clock that the snoop stream uses. Usually, this clock is the kernel clock. |
compile
Example XML code:
<compile project="top" revision="top" qsys_file="none" generic_kernel="1"> <generate cmd="echo"/> <synthesize cmd="quartus_sh -t import_compile.tcl"/> <auto_migrate platform_type="s5_net" > <include fixes=""/> <exclude fixes=""/> </auto_migrate> </compile>
Attribute | Description |
---|---|
project | Name of the Intel® Quartus® Prime project file (.qpf) that the Intel® Quartus® Prime Standard Edition software intends to compile. |
revision | Name of the revision within the Intel® Quartus® Prime project that the Intel® Quartus® Prime Standard Edition software compiles to generate the Intel® FPGA SDK for OpenCL™ Offline Compiler executable file (.aocx). |
qsys_file | Name of the Platform Designer (Standard) file into which the OpenCL™
kernel is embedded. You have the option to assign a value of "none" to qsys_file if you do not require the Intel® Quartus® Prime Standard Edition software to create a top-level .qsys file for your design. |
generic_kernel | Set this value to 1 if you want the offline compiler to generate a common Verilog interface for all OpenCL compilations. This setting is necessary in situations where you must set up Intel® Quartus® Prime design partitions around the kernel, such as in the Configuration via Protocol (CvP) flow. |
generate_cmd | Command required to prepare for full compilation, such as to generate the Verilog files for the Platform Designer (Standard) system into which the OpenCL kernel is embedded. |
synthesize_cmd | Command required to generate the fpga.bin file from the Custom Platform. Usually, this command instructs the Intel® Quartus® Prime Standard Edition software to perform a full compilation. |
auto_migrate |
|
MMD API Descriptions
The MMD interface is a cumulation of all the MMD application programming interface (API) functions.
- 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. - aocl_mmd_get_info
The aocl_mmd_get_info function obtains information about the board specified in the requested_info_id argument. - aocl_mmd_open
The aocl_mmd_open function opens and initializes the specified device. - aocl_mmd_close
The aocl_mmd_close function closes an opened device via its handle. - aocl_mmd_read
The aocl_mmd_read function is the read operation on a single interface. - aocl_mmd_write
The aocl_mmd_write function is the write operation on a single interface. - aocl_mmd_copy
The aocl_mmd_copy function is the copy operation on a single interface. - aocl_mmd_set_interrupt_handler
The aocl_mmd_set_interrupt_handler function sets the interrupt handler for the opened device. - aocl_mmd_set_status_handler
The aocl_mmd_set_status_handler function sets the operation status handler for the opened device. - aocl_mmd_yield
The aocl_mmd_yield function is called when the host interface is idle. - aocl_mmd_shared_mem_alloc
The aocl_mmd_shared_mem_alloc function allocates shared memory between the host and the FPGA. - aocl_mmd_shared_mem_free
The aocl_mmd_shared_mem_free function frees allocated shared memory. - aocl_mmd_reprogram
The aocl_mmd_reprogram function is the reprogram operation for the specified device. - aocl_mmd_hostchannel_create
The aocl_mmd_hostchannel_create function creates a channel interface. - aocl_mmd_hostchannel_destroy
The aocl_mmd_hostchannel_destroy function destroys the channel interface. - aocl_mmd_hostchannel_get_buffer
The aocl_mmd_hostchannel_get_buffer function provides a host with a pointer to the buffer they can access to write or read from the channel interface, along with the space or data available in the buffer, in bytes. - aocl_mmd_hostchannel_ack_buffer
You can acknowledge write or read from the channel by calling aocl_mmd_hostchannel_ack_buffer.
aocl_mmd_get_offline_info
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 17. 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™ Standard 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.
aocl_mmd_get_info
Syntax
int aocl_mmd_get_info( int handle, aocl_mmd_info_t requested_info_id, size_t param_value_size, void* param_value, size_t* param_size_ret );
Function Arguments
- handle—A positive int value representing the handle to the board obtained from the aocl_mmd_open() call.
-
requested_info_id—An enum value of type aocl_mmd_offline_info_t that indicates the device information returning to the caller.
Table 18. Possible Enum Values for the requested_info_id Argument Name Description Type AOCL_MMD_NUM_KERNEL_INTERFACES Number of kernel interfaces int AOCL_MMD_KERNEL_INTERFACES Kernel interfaces int* AOCL_MMD_PLL_INTERFACES Kernel clock handles int* AOCL_MMD_MEMORY_INTERFACE Global memory handle int AOCL_MMD_TERMPERATURE Temperature measurement float AOCL_MMD_PCIE_INFO PCIe® information char* AOCL_MMD_BOARD_NAME Board name char* AOCL_MMD_BOARD_UNIQUE_ID Unique board ID char* -
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_TEMPERATURE returns a value of type float, set the param_value_size to sizeof (float). 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.
aocl_mmd_open
Syntax
int aocl_mmd_open( const char* name );
Function Arguments
name—The function opens the board with a name that matches this const char* string. The name typically matches the one specified by the AOCL_MMD_BOARD_NAMES offline information.
The OpenCL™ runtime first queries the AOCL_MMD_BOARD_NAMES offline information to identify the boards that it might be able to open. Then it attempts to open all possible devices by calling aocl_mmd_open and using each of the board names as argument.
Return Value
If aocl_mmd_open() executes successfully, the return value is a positive integer that acts as a handle to the board.
If aocl_mmd_open() fails to execute, a negative return value indicates an error. In the event of an error, the OpenCL runtime proceeds to open other known devices. Therefore, it is imperative that the MMD layer does not exit the application if an open call fails.
aocl_mmd_close
Syntax
int aocl_mmd_close( int handle );
Function Arguments
handle—A positive int value representing the handle to the board obtained from the aocl_mmd_open() call.
Return Value
If the aocl_mmd_close() executes successfully, the return value is 0.
If aocl_mmd_close() fails to execute, a negative return value indicates an error.
aocl_mmd_read
Syntax
int aocl_mmd_read( int handle, aocl_mmd_op_t op, size_t len, void* dst, aocl_mmd_interface_t interface, size_t offset );
Function Arguments
- handle—A positive int value representing the handle to the board obtained from the aocl_mmd_open() call.
-
op—The operation object of type aocl_mmd_op_t used to track the progress of the
operation. If op is NULL, the call must block,
and return only after the operation completes.Note:
aocl_mmd_op_t is defined as follows:
typedef void* aocl_mmd_op_t;
- len—The size of the data, in bytes, that the function transfers. Declare len with type size_t.
- dst—The host buffer, of type void*, to which data is written.
-
interface—The handle to the interface that aocl_mmd_read is accessing. For example, to access global memory, this handle is the enum value aocl_mmd_get_info() returns when its requested_info_id argument is AOCL_MMD_MEMORY_INTERFACE. The interface argument is of type aocl_mmd_interface_t, and can take one of the following values:
Name Description AOCL_MMD_KERNEL Control interface into the kernel interface AOCL_MMD_MEMORY Data interface to device memory AOCL_MMD_PLL Interface for reconfigurable PLL - offset—The size_t byte offset within the interface at which the data transfer begins.
Return Value
If the read operation is successful, the return value is 0.
If the read operation fails, a negative return value indicates an error.
aocl_mmd_write
Syntax
int aocl_mmd_write( int handle, aocl_mmd_op_t op, size_t len, const void* src, aocl_mmd_interface_t interface, size_t offset );
Function Arguments
- handle—A positive int value representing the handle to the board obtained from the aocl_mmd_open() call.
-
op—The operation object of type aocl_mmd_op_t used to track the progress of the
operation. If op is NULL, the call must block,
and return only after the operation completes.Note:
aocl_mmd_op_t is defined as follows:
typedef void* aocl_mmd_op_t;
- len—The size of the data, in bytes, that the function transfers. Declare len with type size_t.
- src—The host buffer, of type const void*, from which data is read.
-
interface—The handle to the interface that aocl_mmd_write is accessing. For example, to access global memory, this handle is the enum value aocl_mmd_get_info() returns when its requested_info_id argument is AOCL_MMD_MEMORY_INTERFACE. The interface argument is of type aocl_mmd_interface_t, and can take one of the following values:
Name Description AOCL_MMD_KERNEL Control interface into the kernel interface AOCL_MMD_MEMORY Data interface to device memory AOCL_MMD_PLL Interface for reconfigurable PLL - offset—The size_t byte offset within the interface at which the data transfer begins.
Return Value
If the read operation is successful, the return value is 0.
If the read operation fails, a negative return value indicates an error.
aocl_mmd_copy
Syntax
int aocl_mmd_copy( int handle, aocl_mmd_op_t op, size_t len, aocl_mmd_interface_t intf, size_t src_offset, size_t dst_offset );
Function Arguments
- handle—A positive int value representing the handle to the board obtained from the aocl_mmd_open() call.
-
op—The operation object of type aocl_mmd_op_t used to track the progress of the
operation. If op is NULL, the call must block,
and return only after the operation completes.Note:
aocl_mmd_op_t is defined as follows:
typedef void* aocl_mmd_op_t;
- len—The size of the data, in bytes, that the function transfers. Declare len with type size_t.
-
intf—The handle to the interface that aocl_mmd_read is accessing. For example, to access global memory, this handle is the enum value aocl_mmd_get_info() returns when its requested_info_id argument is AOCL_MMD_MEMORY_INTERFACE. The interface argument is of type aocl_mmd_interface_t, and can take one of the following values:
Name Description AOCL_MMD_KERNEL Control interface into the kernel interface AOCL_MMD_MEMORY Data interface to device memory AOCL_MMD_PLL Interface for reconfigurable PLL - src_offset—The size_t byte offset within the source interface at which the data transfer begins.
- dst_offset—The size_t byte offset within the destination interface at which the data transfer begins.
Return Value
If the copy operation is successful, the return value is 0.
If the copy operation fails, a negative return value indicates an error.
aocl_mmd_set_interrupt_handler
Syntax
int aocl_mmd_set_interrupt_handler( int handle, aocl_mmd_interrupt_handler_fn fn, void* user_data );
Function Arguments
- handle—A positive int value representing the handle to the board obtained from the aocl_mmd_open() call.
-
fn—The callback function to invoke when a kernel interrupt occurs. The fn argument is of type aocl_mmd_interrupt_handler_fn, which is defined as follows:
typedef void (*aocl_mmd_interrupt_handler_fn)( int handle, void* user_data );
- user_data—The void* type user-provided data that passes to fn when it is called.
Return Value
If the function executes successfully, the return value is 0.
If the function fails to execute, a negative return value indicates an error.
aocl_mmd_set_status_handler
- When the operation completes successfully and status is 0.
- When the operation completes with errors and status is a negative value.
Syntax
int aocl_mmd_set_status_handler( int handle, aocl_mmd_status_handler_fn fn, void* user_data );
Function Arguments
- handle—A positive int value representing the handle to the board obtained from the aocl_mmd_open() call.
-
fn—The callback function to invoke when a status update occurs. The fn argument is of type aocl_mmd_status_handler_fn, which is defined as follows:
type void (*aocl_mmd_status_handler_fn)( int handle, void* user_data, aocl_mmd_op_t op, int status );
- user_data—The void* type user-provided data that passes to fn when it is called.
Return Value
If the function executes successfully, the return value is 0.
If the function fails to execute, a negative return value indicates an error.
aocl_mmd_yield
Syntax
int aocl_mmd_yield( int handle );Function Arguments
- handle—A positive int value representing the handle to the board obtained from the aocl_mmd_open() call.
Return Value
A nonzero return value indicates that the yield function performed work necessary for proper device functioning such as processing direct memory access (DMA) transactions.
A return value of 0 indicates that the yield function did not perform work necessary for proper device functioning.
aocl_mmd_shared_mem_alloc
Syntax
void * aocl_mmd_shared_mem_alloc( int handle, size_t size, unsigned long long *device_ptr_out );
Function Arguments
- handle—A positive int value representing the handle to the board obtained from the aocl_mmd_open() call.
- size—The size of the shared memory that the function allocates. Declare size with the type size_t.
- device_ptr_out—The argument that receives the pointer value the device uses to access shared memory. The device_ptr_out is of type unsigned long long to handle cases where the host has a smaller pointer size than the device. The device_ptr_out argument cannot have a NULL value.
Return Value
If aocl_mmd_shared_mem_alloc executes successfully, the return value is the pointer value that the host uses to access the shared memory. Otherwise, the return value is NULL.
aocl_mmd_shared_mem_free
Syntax
void aocl_mmd_shared_mem_free( int handle, void* host_ptr, size_t size );
Function Arguments
- handle—A positive int value representing the handle to the board obtained from the aocl_mmd_open() call.
- host_ptr—The host pointer that points to the shared memory, as returned by the aocl_mmd_shared_mem_alloc() function.
- size—The size of the allocated shared memory that the function frees. Declare size with the type size_t.
Return Value
The aocl_mmd_shared_mem_free function has no return value.
aocl_mmd_reprogram
Disable interrupts and reprogram the FPGA with the data from user_data, which has a size specified by the size argument. The host then calls aocl_mmd_set_status_handler and aocl_mmd_set_interrupt_handler again, which enable the interrupts. If events such as interrupts occur during aocl_mmd_reprogram execution, race conditions or data corruption might occur.
Syntax
int aocl_mmd_reprogram( int handle, void* user_data, size_t size );
Function Arguments
- handle—A positive int value representing the handle to the board obtained from the aocl_mmd_open() call.
- user_data—The void* type binary contents of the fpga.bin file that are created during compilation.
- size—The size of user_data in bytes. The size argument is of size_t.
Return Value
If aocl_mmd_reprogram executes successfully, the return value is the pointer value that the host uses to access shared memory.
Reprogram Support
The data in the user_data argument is the same fpga.bin data created during Intel® Quartus® Prime compilation. The Intel® FPGA SDK for OpenCL™ Offline Compiler packages the exact contents of fpga.bin into the .aocx file during compilation. The contents of the fpga.bin is irrelevant to the offline compiler. It simply passes the file contents through the host and to the aocl_mmd_reprogram call via the user_data argument.
For more information on the clCreateProgramWithBinary function, refer to the OpenCL Specification version 1.0 and the Programming an FPGA via the Host section of the Intel® FPGA SDK for OpenCL™ Standard Edition Programming Guide.
aocl_mmd_hostchannel_create
Syntax
int aocl_mmd_hostchannel_create( int handle, char *channel_name, size_t queue_depth, int direction );
Function Arguments
- handle—A positive int value representing the handle to the board obtained from the aocl_mmd_open() call.
- channel_name—Name of the channel to be initialized. The channel name is same as that used in the board_spec.xml file.
- queue_depth—The size of pinned internal buffer in bytes. Pointer to the internal buffer is provided when the user calls the aocl_mmd_hostchannel_get_buffer() function.
- direction—The direction of the channel.
Return Value
If the function executes successfully, the return value is positive and is handle to the channel.
If the function fails to execute, a negative return value indicates an error.
aocl_mmd_hostchannel_destroy
Syntax
int aocl_mmd_hostchannel_destroy( int handle, int channel );
Function Arguments
- handle—A positive int value representing the handle to the board obtained from the aocl_mmd_open() call.
- channel—A positive int value representing handle to the channel to close obtained from the aocl_mmd_hostchannel_create() call.
Return Value
If the function executes successfully, the return value is 0.
If the function fails to execute, a negative return value indicates an error.
aocl_mmd_hostchannel_get_buffer
Syntax
void *aocl_mmd_hostchannel_get_buffer( int handle, int channel, size_t *buffer_size, int *status );
Function Arguments
- handle—A positive int value representing the handle to the board obtained from the aocl_mmd_open() call.
- channel—A positive int value representing handle to the channel to close obtained from the aocl_mmd_hostchannel_create() call.
- buffer_size—A pointer to size_t that the function will write available buffer space or size to.
- status—A pointer to int that the function will write result of the call to.
Return Value
If the function executes successfully, int pointed to by the status pointer will be 0. Returned void* may still be NULL, in which case size_t pointed by the buffer_size will be 0.
If the function fails to execute, int pointed by the status pointer will be a negative value.
aocl_mmd_hostchannel_ack_buffer
Syntax
size_t aocl_mmd_hostchannel_ack_buffer( int handle, int channel, size_t send_size, int *status );
Function Arguments
- handle—A positive int value representing the handle to the board obtained from the aocl_mmd_open() call.
- channel—A positive int value representing handle to the channel to close obtained from the aocl_mmd_hostchannel_create() call.
- send_size—The size in bytes that the user is acknowledging.
- status—A pointer to int that the function will write result of the call to.
Return Value
If the function executes successfully, int pointed to by status pointer will be 0. Also, there is no guarantee that the user's send_size will be the actual size that gets acknowledged. The returned size_t will be the amount of bytes that was actually acknowledged.
If the function fails to execute, int pointed by status pointer will be a negative value.
Intel FPGA SDK for OpenCL Standard Edition Custom Platform Toolkit Reference Manual Revision History
Document Version | Intel® Quartus® Prime Version | Changes |
---|---|---|
2018.09.24 | 18.1 |
|
2018.05.04 | 18.0 |
|
Date | Version | Changes |
---|---|---|
November 2017 | 2017.11.03 |
|
May 2017 | 2017.05.08 |
|
October 2016 | 2016.10.31 |
|
May 2016 | 2016.05.02 |
|
November 2015 | 2015.11.02 |
|
May 2015 | 15.0.0 |
|
December 2014 | 14.1.0 |
|
October 2014 | 14.0.1 |
|
June 2014 | 14.0.0 |
|