Intel FPGA SDK for OpenCL Standard Edition: Custom Platform Toolkit User Guide

RSS

UG-20153 | 2018.09.24

Intel FPGA SDK for OpenCL Standard Edition Custom Platform Toolkit User Guide

The Intel^® FPGA SDK for OpenCL™ Standard Edition Custom Platform Toolkit User Guide outlines the procedure for creating an Intel^® FPGA Software Development Kit (SDK) for OpenCL™ Standard Edition Custom Platform.

The Intel^® FPGA SDK for OpenCL™ ¹ ² 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.

¹ OpenCL™ and the OpenCL logo are trademarks of Apple Inc. used by permission of the Khronos Group™.

² The Intel^® FPGA SDK for OpenCL™ is based on a published Khronos Specification, and has passed the Khronos Conformance Testing Process. Current conformance status is available at www.khronos.org/conformance.

Prerequisites for the Intel FPGA SDK for OpenCL Standard Edition Custom Platform Toolkit

The Intel^® FPGA SDK for OpenCL™ Standard Edition Custom Platform Toolkit User Guide assumes that you have prior hardware design knowledge necessary for using the Custom Platform Toolkit to create an Intel^® FPGA SDK for OpenCL™ Standard Edition Custom Platform.

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:
1. Intel^® FPGA SDK for OpenCL™ Intel^® Cyclone^® V SoC Development Kit Reference Platform Porting Guide
2. Intel^® Cyclone^® V SoC Development Board Reference Manual

Overview of the Intel FPGA SDK for OpenCL Standard Edition Custom Platform

An Intel^® FPGA SDK for OpenCL™ Standard Edition Custom Platform is a collection of tools and libraries necessary for the communication between the Intel^® FPGA SDK for OpenCL™ Offline Compiler and the FPGA boards.

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

Populate your Intel^® FPGA SDK for OpenCL™ Standard Edition Custom Platform with files, libraries and drivers that allow an OpenCL kernel to run on the target FPGA board.

Table 1. Contents within the Top-Level Custom Platform Directory
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

The automigration feature updates an existing Intel^® -registered Custom Platform for use with the current version of the Intel^® Quartus^® Prime Design Suite and the Intel^® FPGA SDK for OpenCL™ Standard Edition.

Important:

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.

When the Intel^® FPGA SDK for OpenCL™ Offline Compiler compiles a kernel, it probes the board_spec.xml file for the following information:

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.

Note: If automigration fails, contact your local Intel^® FPGA product's field applications engineer for assistance.

Customizing Automigration

You and the Intel^® FPGA SDK for OpenCL™ user both have the ability to disable the automigration of an installed Custom Platform. In addition, you may choose which named fixes, identified by the SDK, you want to apply to your Custom Platform.

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

The following topics outline the tasks you must perform to create a Custom Platform for use with the Intel^® FPGA SDK for OpenCL™ Standard Edition.

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.

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.

Figure 1. Example System Hierarchy with a Board Platform Designer (Standard) Subsystem

Creating the Board Platform Designer (Standard) System

When designing your board hardware, you have the option to create a Platform Designer (Standard) subsystem within system.qsys that contains all the board logic. In addition to organizing your design code, having this subsystem allows you to create an Intel^® Quartus^® Prime partition that you can preserve. To create your board system in a Platform Designer (Standard) subsystem, you may modify the board.qsys template in the Custom Platform Toolkit.

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.
1. 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.
2. 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.
3. 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.
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.
1. 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.
2. 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.
3. Instantiate the OpenCL Kernel Interface component. Specify the component parameters, and connect the signals and ports as outlined in the OpenCL Kernel Interface section.
4. 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

When generating a post-place-and-route partition, take into account several design considerations for the exported board partition that might have unexpected consequences on the Intel^® FPGA SDK for OpenCL™ Standard Edition compilation results. The best approach to optimizing the board partition is to experiment with a range of different OpenCL kernels.

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

Deliver a design partition for nonkernel logic that has a clean timing closure flow as part of your Custom Platform.

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

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. You may create these XML files in simple text editors (for example, WordPad for Windows, and vi for Linux).

Creating the board_env.xml File

The board_env.xml file describes your Custom Platform to the SDK.

Together with the other contents of the Custom Platform, the board_env.xml file sets up the board installation that enables the offline compiler to target a specific accelerator board.

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.

Your board_env.xml file should resemble the following example:

<?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

The board_spec.xml XML file contains metadata necessary to describe your hardware system to the Intel^® FPGA SDK for OpenCL™ Standard Edition.

For detailed descriptions on the type of information you must include in the board_spec.xml file, refer to the XML Elements, Attributes, and Parameters in the board_spec.xml File section. A board_spec.xml template is available in the INTELFPGAOCLSDKROOT/board/custom_platform_toolkit/board_package/hardware/template directory of the Custom Platform Toolkit.

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.
1. Navigate to the INTELFPGAOCLSDKROOT/share/models/dm directory, where INTELFPGAOCLSDKROOT points to the path to the SDK installation. The directory contains a list of device models files that describe available FPGA resources on accelerator boards.
2. If your device is listed in the dm directory, specify the device_model attribute with the name of the device model file. Proceed to Step 4.
  For example, device_model="5sgsed8k2f40c2_dm.xml"
3. If your device is not listed in the dm directory, or if your board uses an FPGA that does not have a device model, create a new device model by performing the tasks described in Steps d to g:
4. Copy a device model from the INTELFPGAOCLSDKROOT/share/models/dm directory (for example, 5sgxma7h2fe35c2_dm.xml).
5. Place your copy of the device model in the Custom Platform subdirectory in which your board_spec.xml file resides.
6. Rename the file, and modify the values to describe the part your board uses.
  
  Important:
  The file name must conform to the format <part_number>_dm.xml, where <part_number> is the official Intel^® FPGA device part number (for example, 5sgxma7h2fe35c2).
  
  You can search for the Intel^® FPGA device part number on the Buy page of the Intel^® FPGA website.
7. 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:
1. Name of the memory type.
2. The combined maximum global memory bandwidth.
  You can calculate this bandwidth value from datasheets of your memories.
3. The size of the data that the Intel^® FPGA SDK for OpenCL™ Offline Compiler interleaves across memory banks.
  
  Note: interleaved_bytes = burst_size x width_bytes
4. If you have a homogeneous memory system, proceed to Step e. If you have a heterogeneous memory system, for each global memory type, specify the config_addr attribute with the base address of the ACL Mem Organization Control Platform Designer (Standard) component (mem_org_mode).
5. If you choose to set a global memory type as default, assign a value of 1 to the optional default attribute.
  If you do not include this attribute, the first memory defined in the board_spec.xml file becomes the default memory.
6. Specify the parameters in the interface attribute to describe the characteristics of each memory interface.
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).
1. Specify the parameters in the interface attribute to describe the characteristics of each kernel interface.
  For the streamsource interface type, also specify the clock attribute with the name of the clock the snoop stream uses. Usually, this clock is the kernel clock.
  Important: Update the width of the snoop interface (acl_internal_snoop) specified with the streamsource kernel interface. Updating the width ensures that the global_mem interface entries in board_spec.xml match the characteristics of the bank<N> Avalon^® Memory-Mapped (Avalon-MM) masters from corresponding OpenCL Memory Bank Divider component for the default memory.
2. Specify the parameters in the kernel_clk_reset attribute to include the exported kernel clock and reset interfaces as kernel interfaces.
Include the compile element and specify its attributes to control the Intel^® Quartus^® Prime compilation, registration, and automigration.

Below is the XML code of an example board_spec.xml file:

<?xml version="1.0"?>
<board version="<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

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

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

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

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

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 OpenCL™ kernel is an unknown state after you power-up your system or reprogram your FPGA. As a result, the MMD layer does not enable or respond to any interrupts from the kernel during these periods. The kernel is in a known state only after aocl_mmd_set_interrupt_handler is called. Therefore, enable interrupts from the kernel only after the handler becomes available to the MMD layer.

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

The Intel^® FPGA SDK for OpenCL™ Standard Edition supports the FPGA Client Driver custom extension. The FPGA Client Driver (FCD) allows the SDK to automatically find and load the Custom Platform libraries at host run time.

Attention: To allow SDK users to use FCD, you must remove the MMD library from the linklibs element in the board_env.xml file.

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

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.

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:

Tip:

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.

When users invoke a utility command, the utility probes the current Custom Platform's board_env.xml file and executes the <utility_executable> file within the utilbindir directory.

Testing the Hardware Design

After you create the software utilities and the MMD layer, and your hardware design achieves timing closure, test the 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.
Run the boardtest executable.

Attention: To ensure that your hardware design produces consistent performance, you might have to test it using multiple OpenCL kernels in addition to boardtest.cl.

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

Registering your Custom Platform and the supported FPGA boards in the Intel^® FPGA SDK for OpenCL™ Standard Edition Preferred Board Partner Program allows them to benefit from ongoing internal testing across versions of the Intel^® Quartus^® Prime Design Suite. Intel^® -tested Custom Platforms and boards are more likely to be forward compatible with future Intel^® Quartus^® Prime Design Suite versions.

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:
1. 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.
2. Compilations of the following examples on the OpenCL Design Examples page of the Intel FPGA website:
  1. Vector Addition
  2. Matrix Multiplication
  3. FFT (1D)
  4. FFT (2D)
  5. Sobel Filter
  6. Finite Difference Computation (3D)
For each board in the Custom Platform, a summary of the following:
1. HOST-TO-MEMORY BANDWIDTH as reported by the boardtest test in the Custom Platform Toolkit (/tests/boardtest).
2. KERNEL-TO-MEMORY BANDWIDTH as reported by the boardtest test.
3. Throughput in swap-and-execute(s) reported by the swapper test in the Custom Platform Toolkit (/tests/swapper).
4. 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:
1. Install the board into the physical machine.
2. Boot the machine and invoke the aocl install <path_to_customplatform> utility command.
3. Invoke the aocl diagnose command.
4. 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	Maintenance release
2018.05.04	18.0	Removed information pertaining to the Intel^® FPGA SDK for OpenCL™ Pro Edition and the Intel^® Quartus^® Prime Pro Edition software. In Creating the board_spec.xml File, added a note to specify that when creating a device model (i.e. `<part_number>`_dm.xml), `<part_number>` must be the official Intel^® FPGA device part number.

Table 4. Document Revision History of the Intel^® FPGA SDK for OpenCL™ Custom Platform Design Chapter of the Intel^® FPGA SDK for OpenCL™ Custom Platform Toolkit User Guide
Date	Version	Changes
November 2017	2017.11.03	Rebranded the references to the following: `ALTERAOCLSDKROOT` to `INTELFPGAOCLSDKROOT` Arria 10 to Intel^® Arria^® 10 Qsys to Platform Designer (Standard) In Setting Up the FPGA Client Driver, updated the /opt/Altera/OpenCL/Boards/ directory to /opt/Intel/OpenCL/Boards/ Updated instances of aocl install to aocl install <path_to_customplatform>. Updated instances of aocl uninstall to aocl uninstall <path_to_customplatform>. Removed references to `AOCL_BOARD_PACKAGE_ROOT` throughout the guide since it is deprecated. In Creating the board_env.xml File, updated the board_env version to 17.1 in the board_env.xml file. In Testing the board_env.xml File, updated board_default and board-version values. In Creating the board_spec.xml File, updated the board_spec.xml file code example. Implemented the conventions single dash and `-option=<value>` in the following topics: Customizing Automigration Testing the board_env.xml File Testing the Hardware Design Applying for the Intel^® FPGA SDK for OpenCL™ Preferred Board Status
May 2017	2017.05.08	Rebranded Altera Client Driver (ACD) to FPGA Client Driver (FCD). Updated example code of the board_env.xml and board_spec.xml files to the 17.0 version of corresponding files in the Arria^® 10 GX FPGA Development Kit Reference Platform.
October 2016	2016.10.31	Rebranded Altera SDK for OpenCL to Intel^® FPGA SDK for OpenCL™ . Rebranded Altera Offline Compiler to Intel^® FPGA SDK for OpenCL™ Offline Compiler. Updated example code of the board_env.xml and board_spec.xml files to the 16.1 version of corresponding files in the Arria^® 10 GX FPGA Development Kit Reference Platform. In Setting Up the Altera Client Driver, updated the text for clarity. In Testing the Hardware Design, modified the Windows make command in Step 5 to `make -f Makefile.windows`.
May 2016	2016.05.02	In Creating the board_spec.xml File, updated the example XML code for board_spec.xml to the current version, and updated the examples embedded in the procedure to match the example .xml file. Updated implementation requirement for the program utility in the Providing AOCL Utilities Support section. In Setting Up the Altera Client Driver, modified the Linux directory for the .acd file from /opt/Altera/OpenCL_boards/ to /opt/Altera/OpenCL/Boards/.
November 2015	2015.11.02	Changed instances of Quartus^® II to Quartus Prime. Changed instances of Altera^® Complete Design Suite to Intel^® Quartus^® Prime Design Suite . Updated the support requirement for the diagnose utility in the Providing AOCL Utilities Support section. In the Creating the board_env.xml File section, added the `mmdlib` XML element to the list of elements included in the board_env.xml file.
May 2015	15.0.0	Added the Setting Up the Altera Client Driver section.
December 2014	14.1.0	Specified that the Custom Platform Toolkit is available in the `ALTERAOCLSDKROOT`/board directory. Added the uninstall utility executable in the Providing AOCL Utilities Support section. Indicated that the version attributes in the board_env.xml and board_spec.xml files have to match the Altera^® Complete Design Suite and Altera SDK for OpenCL™ version you use to develop the Custom Platform. Added instruction for including the `compile` eXtensible Markup Language element and its associated attributes in the board_spec.xml file in the section Creating the board_spec.xml File. Added information on the automigration of Custom Platform in sections Custom Platform Automigration and Customizing Automigration. Removed the Generating the Rapid Prototyping Library section.
October 2014	14.0.1	Reorganized existing document into two chapters.
June 2014	14.0.0	Initial release.

Intel FPGA SDK for OpenCL Standard Edition Custom Platform Toolkit Reference Material

The Intel^® FPGA SDK for OpenCL™ Standard Edition Custom Platform Toolkit Reference Material chapter provides supplementary information that can assist you in the implementation of your Custom Platform.

The Board Platform Designer (Standard) Subsystem

When designing your board hardware, you have the option to create a Platform Designer (Standard) subsystem within the top-level Platform Designer (Standard) system (system.qsys) that contains all nonkernel logic.

The board Platform Designer (Standard) subsystem is the main design entry point for a new accelerator board. It is the location where the instantiations of the OpenCL™ host and global memory interfaces occur. Your board design must have a minimum of 128 kilobytes (KB) of external memory. Any Avalon^® Memory-Mapped (Avalon-MM) slave interface (for example, a block RAM) can potentially be a memory interface.

The diagram below represents a board system implementation in more details:

Note: Blocks denoted with an asterisk (*) are blocks that you have to add to the board Platform Designer (Standard) subsystem.

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 Platform Designer (Standard) system for your board logic includes components specific to the Intel^® FPGA SDK for OpenCL™ Standard Edition that are necessary for implementing features that instantiate host communication and global memory interfaces.

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. An Avalon^®-MM slave interface allows reprogramming of the phase-locked loops (PLLs) and kernel clock status information.

Table 5. Parameter Settings for the OpenCL Kernel Clock Generator Component
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.

Table 6. Signals and Ports for the OpenCL Kernel Clock Generator Component
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

The OpenCL™ Kernel Interface is a Platform Designer (Standard) component that allows the host interface to access and control the OpenCL kernel.

Table 7. Parameter Settings for the OpenCL Kernel Interface Component
Parameter	Description
Number of global memory systems	Number of global memory types in your board design.

Table 8. Signals and Ports for the OpenCL Kernel Interface Component
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

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. This component must reside on the path between the host and the global memory interfaces. In addition, it must reside outside of the path between the kernel and the global memory interfaces.

Table 9. Parameter Settings for the OpenCL Memory Bank Divider Component
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.

Table 10. Signals and Ports for the OpenCL Memory Bank Divider Component
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

This section describes the metadata you must include 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.

Example eXtensible Markup Language (XML) code:

<board version="<version>" name="<Custom_Platform_name>">
...
</board>

Table 11. Attributes for the board Element
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

The device element of the board_spec.xml file provides the device model and the resources that the board design uses.

Example XML code:

<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>

Table 12. Attributes for the device Element
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: `alms num`—The number of logic ALMs used, excluding the number of ALMs with only their registers used. The value should correspond to [a]+[b]+[d] from part [A] of the Fitter Partition Statistics. `ffs num`—The number of flip flops. `dsps num`—The number of DSP blocks. `rams num`—The number of RAM blocks.

global_mem

The global_mem and interface elements of the board_spec.xml file provides information on the memory interfaces that connect to the kernel.

Example XML code:

<!-- DDR3-1600 -->
<global_mem name="DDR" max_bandwidth="25600" interleaved_bytes="1024"
 config_addr="0x018">
  <interface name="board" port="kernel_mem0" type="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>

Note: For each global memory that the kernel accesses, you must include one interface element that describes its characteristics.

Table 13. Attributes for the global_mem Element
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

The host element of the board_spec.xml file provides information on the interface from the host to the kernel.

Example XML code:

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

Table 14. Attributes for the host Element
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

The Intel^® FPGA SDK for OpenCL™ Standard Edition supports data streaming directly between kernels and I/O via explicitly named channels. Include the channels element in the board_spec.xml file if your accelerator board provides channels for direct kernel-to-I/O accesses. For the channels element, you must identify all the channel interfaces, which are implemented using the Avalon^®-ST specification. Specify each channel interface via the interface attribute. Refer to the interface section for the parameters you must specify for each interface. The channel interface only supports data, and valid and ready Avalon-ST signals. The I/O channel defaults to 8-bit symbols and big-endian ordering at the interface level.

Example XML code:

<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

The interfaces element of the board_spec.xml file describes the kernel interfaces which will connect to OpenCL™ kernels and control their behaviors. For this element, include one of each interface of types master, irq and streamsource. Refer to the interface section for the parameters you must specify for each interface.

Example XML code:

<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.

Table 15. Parameters for the kernel_clk_reset Attribute
Important:
Name the kernel clock and reset interfaces in the Platform Designer (Standard) connection format (that is, `<instance_name>`.`<interface_name>`).

For example: `board.kernel_clk`
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

In the board_spec.xml file, each global memory, channel or kernel interface is comprised of individual interfaces. For the global_mem, channels, and interfaces XML elements, include an interface attribute for each interface and specify the corresponding parameters.

Table 16. Parameters for the interface XML Attribute
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`: Set to `streamsource` for a stream source that provides data to the kernel. Set to `streamsink` for a stream sink interface that consumes data from the kernel. 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

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.

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`	`platform_type`—Choose this value based on the value referenced in the Intel^® FPGA Reference Platform from which you derive your Custom Platform. Valid values are `none`, `s5_net`, `c5soc`. `include fixes`—Comma-separated list of named fixes that you want to apply to the Custom Platform. `exclude fixes`—Comma-separated list of named fixes that you do not want to apply to the Custom Platform.

MMD API Descriptions

The MMD interface is a cumulation of all the MMD application programming interface (API) functions.

Important: Full details about these functions, their arguments, and their return values are available in the aocl_mmd.h file. The aocl_mmd.h file is part of the Intel^® FPGA SDK for OpenCL™ Standard Edition Custom Platform Toolkit. Include the file in the operating system-specific implementations of the MMD layer.

aocl_mmd_get_offline_info

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

Syntax

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

Function Arguments

requested_info_id—An enum value of type aocl_mmd_offline_info_t that indicates the offline device information returning to the caller.

Table 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

The aocl_mmd_get_info function obtains information about the board specified in the requested_info_id argument.

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

The aocl_mmd_open function opens and initializes the specified device.

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.

Important: The name must be a C-style NULL-terminated ASCII string.

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

The aocl_mmd_close function closes an opened device via its handle.

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

The aocl_mmd_read function is the read operation on a single interface.

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

The aocl_mmd_write function is the write operation on a single interface.

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

The aocl_mmd_copy function is the copy operation on a single interface.

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

The aocl_mmd_set_interrupt_handler function sets the interrupt handler for the opened device.

When the device internals identify an asynchronous kernel event (for example, a kernel completion), the interrupt handler is called to notify the OpenCL™ runtime of the event.

Attention: Ignore the interrupts from the kernel until this handler is set.

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

The aocl_mmd_set_status_handler function sets the operation status handler for the opened device.

The operation status handler is called under the following circumstances:

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

The aocl_mmd_yield function is called when the host interface is idle. The host interface might be idle because it is waiting for the device to process certain events.

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.

Note: The yield function might be called continuously as long as it reports that it has necessary work to perform.

aocl_mmd_shared_mem_alloc

The aocl_mmd_shared_mem_alloc function allocates shared memory between the host and the FPGA. The host accesses the shared memory via the pointer returned by aocl_mmd_shared_mem_alloc. The FPGA accesses the shared memory via device_ptr_out. If shared memory is not available, aocl_mmd_shared_mem_alloc returns NULL. If you do not reboot the CPU after you reprogram the FPGA, the shared memory will persist.

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

The aocl_mmd_shared_mem_free function frees allocated shared memory. This function does nothing if shared memory is not available.

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

The aocl_mmd_reprogram function is the reprogram operation for the specified device.

The host must guarantee that no other OpenCL™ operations are executing on the device during the reprogram operation. During aocl_mmd_reprogram execution, the kernels are idle and no read, write, or copy operation can occur.

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

For Intel^® FPGA SDK for OpenCL™ Standard Edition users who program their FPGAs with the clCreateProgramWithBinary flow (that is, reprogram-on-the-fly), the aocl_mmd_reprogram subroutine is used to configure the FPGA from within the host applications. The host ensures that this call executes only when the FPGA is idle, meaning that no kernels are running and no transfers are outstanding. The MMD layer must then reconfigure the device with the data in the user_data argument of aocl_mmd_reprogram.

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

The aocl_mmd_hostchannel_create function creates a channel interface.

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

The aocl_mmd_hostchannel_destroy function destroys the channel interface.

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

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.

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

You can acknowledge write or read from the channel by calling 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	Maintenance release
2018.05.04	18.0	Removed information pertaining to the Intel^® FPGA SDK for OpenCL™ Pro Edition and the Intel^® Quartus^® Prime Pro Edition software. In interface, added information on the `waitrequest_allowance` parameter.

Date	Version	Changes
November 2017	2017.11.03	Added the following new pages: aocl_mmd_hostchannel_create aocl_mmd_hostchannel_destroy aocl_mmd_hostchannel_get_buffer aocl_mmd_hostchannel_ack_buffer
May 2017	2017.05.08	Maintenance release.
October 2016	2016.10.31	Rebranded Altera SDK for OpenCL to Intel^® FPGA SDK for OpenCL™ . Rebranded Altera Offline Compiler to Intel^® FPGA SDK for OpenCL™ Offline Compiler In OpenCL Memory Bank Divider, added information about the Split read/write bursts on burst word boundary parameter..
May 2016	2016.05.02	In the global_mem section under XML Elements, Attributes, and Parameters in the board_spec.xml File, added example calculations for determining the `max_bandwidth` value. In the interface section under XML Elements, Attributes, and Parameters in the board_spec.xml File, modified the `global_mem`-specific definitions for the `name` and `port` attributes. Added the option to assign a value of `none` to the `qsys_file` attribute within the `compile` element. Fixed a documentation error in the `aocl_mmd_copy` section.
November 2015	2015.11.02	Maintenance release, and changed instances of Quartus^® II to Quartus Prime.
May 2015	15.0.0	Maintenance release.
December 2014	14.1.0	Under XML Elements, Attributes, and Parameters in the board_spec.xml File, added information on the `compile` eXtensible Markup Language element and its associated attributes and parameters. Under MMD API Descriptions, added information on the `AOCL_MMD_USES_YIELD` and the `AOCL_MMD_MEM_TYPES_SUPPORTED` enum values for the `requested_info_id` variable in the `aocl_mmd_get_offline_info` function.
October 2014	14.0.1	Reorganized existing document into two chapters.
June 2014	14.0.0	Initial release.