Home

Altera SDK for OpenCL Custom Platform Toolkit User Guide

Contents

1. For Windows systems you may invoke the make command or use Microsoft Visual Studio If you invoke the make command the Makefile is located in the ALTERAOCLSDKROOT board custom_ platform_toolkit tests boardtest directory If you build your host application in Microsoft Visual Studio the boardtest sIn and main cpp files are located in the ALTERAOCLSDKROOT board custom_platform_toolkit tests boardtest host directory e For Linux systems invoke the make f Makefile linux command The Makefile linux file is located in the ALTERAOCLSDKROOT board custom_platform_toolkit tests boardtest directory 6 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 Altera preferred board rigorous testing across multiple boards is necessary Specifically you should perform overnight testing of all Custom Platform tests and executes the AOCL example designs on multiple boards All board variants within a Custom Platform must go through the testing process Applying for the Altera Preferred Board Status Registering your Custom Platform and the supported FPGA boards in the Altera Preferred Board Partner Program allows them to benefit from ongoing internal testing across versions of the Altera Complete Design Suite ACDS Altera tested Custom Platforms and boards are more likely to be forward co
2. aocl mmd shared mem free The aoci mmd shared mem free function frees allocated shared memory This function does nothing if shared memory is not available Altera Corporation AOCL Custom Platform Toolkit Reference Material C Send Feedback OCL007 15 0 0 2015 05 04 aocl_mmd_reprogram 2 25 Syntax void aocl_mmd_shared_mem_free int handle void host_ptr size t size Function Arguments 1 handle A positive int value representing the handle to the board obtained from the aocl mmd open call 2 host ptr The host pointer that points to the shared memory as returned by the aocl mmd shared mem alloc function 3 size The size of the allocated shared memory that the function frees Declare size with the type size t Return Value The aoci mmd shared mem free function has no return value aocl mmd reprogram The aoci 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 aoc1 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 oc1 mmd set status handler and aocl mmd set interrupt handler again which enable the interrupts If events such as interrupts occur during aocl_
3. global mem 2 9 width 64 maxburst 1 Size 0x1000000 latency 150 addpipe 1 gt name kernel qdrl r direction r gt name kernel qdrl w direction w gt width 64 maxburst 1 size 0x1000000 latency 150 addpipe 1 gt name kernel qdr2 r direction r gt name kernel qdr2 w direction w gt width 64 maxburst 1 Size 0x1000000 latency 150 addpipe 1 gt name kernel qdr3 r direction r gt name kernel qdr3 w direction w Note For each global memory that the kernel accesses you must include one interface element that describes its characteristics Table 2 9 Attributes for the global mem Element EE RENE NE 7 CON name The name the Altera SDK for OpenCL AOCL 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 of all global memory interfaces combined in their current configuration The Altera Offline Compiler AOC uses max bandwidth to choose an architecture suitable for the application and the board Compute this bandwidth value from datasheets of your memories interleaved bytes The AOC 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 Ther
4. ct ios A 2 19 sre mind T dd yuciiniy in n 2 20 aoc mind ur 2 20 adc tmd cote rrr E 2 21 ac l mmd set interrupt handler ccccscsesissesscessesevssesssescevevsseecnencavanvoeactencenenvoensbicatnonsberssseadae 2 22 aocl snmma set stat s handler awe db D Lnd t RO rel REA Kona tn 2 23 creo mmd yield E 2 23 acl md shared meia DOG 4 0H 54 4440 00 2 n n ris ish tepida in ins 2 24 Altera Corporation aocl mmd shared mem fIee u ereke reee ere erek eke rexek keke KEKE KK KH HAH AH AH HHHH KH KK nn 2 24 aocl mind Tepio AI he ecb elec bic ee M ta lec ced Ne a op cR RD ER 2 25 Document Revision History ettet net tie rese Po E UR I der din 2 26 Altera Corporation Altera SDK for OpenCL Custom Platform Toolkit User Guide 2015 05 04 OCL007 15 0 0 X subscribe C_ Send Feedback 1 The Altera SDK for OpenCL Custom Platform Toolkit User Guide outlines the procedure for creating an TM Altera Software Development Kit SDK for OpenCL AOCL Custom Platform The Altera SDK for OpenCL Custom Platform Toolkit provides the necessary tools for implementing a fully functional Custom Platform The Custom Platform Toolkit is available in the ALTERAOCLSDKROOT board directory where the environment variable ALTERAOCLSDKROOT points to the location of the A
5. A memory mapped device MMD software library that implements basic I O between the host and the board Board utilities An implementation of AOCL utilities for managing the accelerator board including tasks such as installing and testing the board Directories and Files in an AOCL Custom Platform Populate your Altera SDK for OpenCL AOCL Custom Platform with files libraries and drivers that allow an OpenCL kernel to run on the target FPGA board Table 1 1 Contents within the Top Level Custom Platform Directory board env xml The eXtensible Markup Language XML file that describes the board installation to the AOCL hardware Directory containing the Quartus II 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 AOCL 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 Altera recommended directory structure and naming convention when you create an Altera SDK for OpenCL AOCL Custom Platform Make the ALTERAOCLSDKROOT board directory the location of the bo
6. The board version must match the AOCL 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 3 For the device element perform the following steps to specify the name of the device model file a Navigate to the ALTERAOCLSDKROOT share models dm directory where ALTERAOCLSDKROOT points to the path to the AOCL installation The directory contains a list of device models files that describe available FPGA resources on accelerator boards If your device is listed in the dm directory specify the device_mode1 attribute with the name of the device model file Proceed to Step 4 For example device model 2 5sgsed8k2f40c2 dm xml If your device is not listed in the dm directory or if your board uses an FPGA that does not have a device model create a new device model by performing the tasks described in Steps d to g Copy a device model from the ALTERAOCLSDKROOT share models dm directory for example 5sgxma7h2fe35c2 dm xml Place your copy of the device model in the Custom Platform subdirectory in which your board spec xml file resides Rename the file and modify the values to describe the part your board uses g In the board spec xml file update the device model attribute of the device element with the name of your file 4 For the device element specify the parameters in the used reso
7. bean eies y diny 1 18 Testing the Hardware DSlBB iecit asa berto der RE HEV R H r ctt a 1 20 Applying for the Altera Preferred Board SCAPUS uas epe bot tnde dun dab pend pac 1 20 Shipping Recom nen da ti0 MN 1 22 Document Revision Historty tte tet te REI HER EUR EIE E eta teta edet o HE eee e ku 1 22 AOCL Custom Platform Toolkit Reference Material 2 1 The Board QSyS SUDSy S TI 4454514 2 1 AOCL Specific Qsys System Gomponentsacciuiccaucusiaicainisindasantodaquiiniaaaueoaneds 2 2 XML Elements Attributes and Parameters in the board_spec xml File sss 2 6 Der MT 2 7 SU n 2 7 global il e Ker N N 2 8 rr N 2 10 Contessa 20112240 44355545 qu MEME Mp ans 2 10 Inutile PR CETT E EEA EEE 2 11 interface TP H T 2 12 COMPLE ee S 2 13 MMD API Descriptions eerte eter bc e beber bee roe eene bee eset et HET EE ae RU ee ree EAEE esos 2 14 aoc mmd get offline Ibo ooo eap tied bove k l d atte dap end pu a e 2 15 ao cl ui din T a 2 18 aoc mmd Open E b n 2 19
8. device The device element of the board_spec xml file provides the device model and the resources that the board design uses AOCL Custom Platform Toolkit Reference Material Altera Corporation send Feedback OCL007 15 0 0 2 8 global_mem 2015 05 04 Example eXtensible Markup Language XML code device device model 2 5sgsed8k2f40c2 dm xml used resources alms num 45000 lt ALMs used in final placement ALMs used for registers gt ffs num 117500 gt dsps num 0 gt rams num 511 used resources device Table 2 8 Attributes for the device Element EE REN NN EE CON 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 AOCL 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 e ffs num The number of flip flops dsps num The number of DSP blo
9. AOCL utilities These utilities enable users to manage the accelerator board through the AOCL 6 Testing the Hardware Design on page 1 20 After you create the software utilities and the memory mapped device MMD layer and your hardware design achieves timing closure test the design Designing the Board Hardware Altera SDK for OpenCL Custom Platform Toolkit User Guide To design an accelerator board for use with the Altera SDK for OpenCL AOCL you must create all the board and system components and the files that describe your hardware design to the Altera Offline Compiler AOC Each board variant in the Custom Platform consists of a Quartus II project and a board_spec xml eXtensible Markup Language XML file that describes the system to the AOC The board_spec xml file describes the interfaces necessary to connect to the kernel The AOC generates a custom circuit based on the data from the board spec xml file Then it incorporates the OpenCL kernel into the Qsys system you create for all nonkernel logic Altera Corporation CJ Send Feedback OCL007 15 0 0 1 6 Creating the Board Qsys System 2015 05 04 You must preserve the design of all nonkernel logic You can preserve your design in the Quartus II software via one of the following methods e 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 Qsys subsystem se
10. Guide e Cyclone V SoC Development Board Reference Manual e OpenCL Platforms page on the Altera website Overview of the AOCL Custom Platform An Altera SDK for OpenCL AOCL Custom Platform is a collection of tools and libraries necessary for the communication between the Altera Offline Compiler AOC and the FPGA boards Currently the AOC targets a single Custom Platform at a time The environment variable AOCL_BOARD_PACKAGE_ROOT points to the path of the board_env xml board environment eXtensible Markup Language XML file within a Custom Platform 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 Altera Corporation Altera SDK for OpenCL Custom Platform Toolkit User Guide C Send Feedback OCL007 15 0 0 2015 05 04 Directories and Files in an AOCL Custom Platform 1 3 board variants allows simultaneous communication with different boards in a multiple device environ ment An AOCL Custom Platform contains the following components Quartus II skeleton project A Quartus II project for your board which the AOC 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
11. Linux Creating the board env xml File on page 1 10 The board env xml file describes your Custom Platform to the AOCL Creating the board spec xml File on page 1 12 The board spec xml eXtensible Markup Language XML file contains metadata necessary to describe your hardware system to the Altera SDK for OpenCL AOCL Creating the board env xml File For the Altera Offline Compiler AOC to target a Custom Platform the Altera SDK for OpenCL AOCL user has to set the environment variable AOCL BOARD PACKAGE ROOT to point to the Custom Platform directory in which the board env xml file resides The board env xml file describes your Custom Platform to the AOCL Together with the other contents of the Custom Platform the board env xml file sets up the board installation that enables the AOC to target a specific accelerator board A board env xml template is available in the board package directory of the Custom Platform Toolkit 1 Create a board env top level eXtensible Markup Language XML element Within board env include the following XML elements a hardware b platform Include a plat form element for each operating system platform that your Custom Platform supports 2 Within each plat form element include the following XML elements a linkflags b linklibs utilbindir 3 Parameterize each element and corresponding attribute s with information specific to your Custom Platform as outline in the table below Altera Corpo
12. Offline Compiler Executable file aocx during compilation The contents of the fpga bin is irrelevant to the AOC 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 Altera SDK for OpenCL Program ming Guide Related Information e OpenCL Specification version 1 0 e Programming an FPGA via the Host Document Revision History Table 2 15 Document Revision History of the AOCL Custom Platform Toolkit Reference Material Chapter of the Altera SDK for OpenCL Custom Platform Toolkit User Guide a KM May 2015 15 0 0 Maintenance release December 14 1 0 e Under XML Elements Attributes and Parameters in the board _ 2014 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 aocl1 mmd get offline info function October 2014 14 0 1 Reorganized existing document into two chapters June 2014 14 0 0 e Initial release Altera Corporation AOCL Custom Platform Toolkit Reference Material C Send Feedback
13. Table 2 11 Parameters for the kernel clk reset Attribute Important Name the kernel clock and reset interfaces in the Qsys connection format that is instance name interface name For example board kernel clk SSS eae emma clk The Qsys name for the kernel clock interface The kerne1_c1k output from the OpenCL Kernel Clock Generator component drives this interface clk2x The Qsys name for the kernel clock interface The kernel_clk2x output from the OpenCL Kernel Clock Generator component drives this interface reset The Qsys connection for the kernel reset The kernel_reset output from the OpenCL Kernel Interface component drives this interface Related Information interface on page 2 12 AOCL Custom Platform Toolkit Reference Material send Feedback Altera Corporation OCL007 15 0 0 2 12 interface 2015 05 04 interface In the board spec xml file each global memory channel or kernel interface is comprised of individual interfaces For the g10ba1 mem channels and interfaces eXtensible Markup Language XML elements include an interface attribute for each interface and specify the corresponding parameters Table 2 12 Parameters for the interface XML Attribute name For g1obal mem name of the Qsys component for the slave interface of the memory For channels instance name of the Qsys component that has the channel interface For interfaces name of the entity in which the kernel int
14. a Qsys component that takes an incoming request from the host interface on the Avalon Memory Mapped Avalon MM slave port and routes it to the appropriate bank master port OpenCL Kernel Clock Generator The OpenCL Kernel Clock Generator is a Qsys component that generates a clock output and a clock 2x output for use by the OpenCL kernels An Avalon Memory Mapped Avalon MM slave interface allows reprogramming of the phase locked loops PLLs and kernel clock status information Table 2 1 Parameter Settings for the OpenCL Kernel Clock Generator Component REF CLK RATE Frequency of the reference clock that drives the kernel PLL that is pll refclk KERNEL TARGET CLOCK Frequency that the Quartus II software attempts to achieve during RATE compilation Keep this parameter at its default setting Altera Corporation AOCL Custom Platform Toolkit Reference Material C Send Feedback OCL007 15 0 0 2015 05 04 OpenCL Kernel Interface 2 3 Table 2 2 Signals and Ports for the OpenCL Kernel Clock Generator Component 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 cix 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 sig
15. 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 Stratix V Network Reference Platform s5 net In particular the acl pcie cpp file implements the API functions defined in the aocl mmd h file If the AOCL users need to load a particular library at runtime deliver the library in a directory that the operating system can locate Instruct the AOCL users to add the library path to the LD LIBRARY PATH for Linux or PATH for Windows environment variable at runtime Modify the 1inkflags element in the board env xml file by specifying the library flags necessary for linking with the MMD layer Related Information MMD API Descriptions on page 2 14 Kernel Power up State The OpenCL kernel is an unknown state after you power up your system or reprogram your FPGA Asa result the memory mapped device 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 aoc1 mmd set interrupt handler is called Therefore enable interrupts
16. as part of your Custom Platform 1 Create a placed and routed design partition using the incremental compilation feature of the Quartus II software This is the design partition for nonkernel logic Altera SDK for OpenCL Custom Platform Toolkit User Guide Altera Corporation GC Send Feedback OCLO007 15 0 0 1 10 Creating the Board XML Files 2015 05 04 For more information on how to use the incremental compilation feature to generate a timing closed design partition refer to the Quartus II Incremental Compilation for Hierarchical and Team Based Design chapter in Volume 1 of the Quartus II Handbook 2 Import the post fit partition from Step 1 into the top level design as part of the compilation flow 3 Run the ALTERAOCLSDKROOT ip board bsp adjust plls tcl script as a post flow process where ALTERAOCLSDKROOT points to the path of the Altera SDK for OpenCL AOCL installation The adjust plls tcl script determines the maximum kernel clock frequency and stores it in the p11 rom on chip memory of the OpenCL Kernel Clock Generator component Related Information Quartus II Incremental Compilation for Hierarchical and Team Based Design Creating the Board XML Files Your Custom Platform must include the eXtensible Markup Language XML files that describe your Custom Platform and each of your hardware system to the Altera SDK for OpenCL AOCL You may create these XML files in simple text editors for example WordPad for Windows and vi for
17. 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 1 handle A positive int value representing the handle to the board obtained from the aocl mmd open call Altera Corporation AOCL Custom Platform Toolkit Reference Material C Send Feedback OCL007 15 0 0 2015 05 04 aocl_mmd_set_status_handler 2 23 2 n The callback function to invoke when a kernel interrupt occurs The n 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 3 user data The void type user provided data that passes to n 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 e When the operation completes with errors and status is a negative value Syntax int aocl mm
18. 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 DIG Oe W bu dem get offline info open get info set status handler set interrupt handler get info read write copy yield close Setting Up the Altera Client Driver The AOCL supports the Altera Client Driver ACD custom extension The ACD allows the AOCL to automatically find and load the Custom Platform libraries at host runtime Attention To allow AOCL users to use the ACD you must remove the memory mapped device MMD library from the 1inkl1ibs element in the board env xml file Enumerating the Custom Platform ACD on Windows Specify the Custom Platform libraries in the registry key HKEY_LOCAL_MACHINE SOFTWARE Altera OpenCL Boards Enter one value for each library Each value must include the path to the library as the string value and a dword setting of 0 Altera SDK for OpenCL Custom Platform Toolkit User Guide Altera Corporation GC Send Feedback zdis ub OCL007 15 0 0 1 18 Providing AOCL Utilities Support 2015 05 04 For example HKEY_LOCAL_MACHINE SOFTWARE Altera OpenCL Boards c Wboard vendor aV Wuny board mmd dll dword 00000000 To enumerate Custom Platform ACDs on Windows the ACD Loader scans the value in the registry key HKEY_LOCAL_MACHINE SOFTWARE Altera OpenCL Boards For each value in this key the dword parameter specifies the path to a dyna
19. interface from the host to the kernel channels on page 2 10 Include the channe1s element in the board spec xml file if your accelerator board provides channels for direct kernel to I O accesses interfaces on page 2 11 The interfaces element of the board spec xml file describes the kernel interfaces which will connect to OpenCL kernels and control their behaviors interface on page 2 12 For the g1obal mem channels and interfaces eXtensible Markup Language XML elements include an interface attribute for each interface and specify the corresponding parameters compile on page 2 13 The compile element of the board spec xml file and its associated attributes and parameters describe the general control of Quartus II compilation registration and automigration 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 15 0 name s5_net gt lt boze Table 2 7 Attributes for the board Element NENNEN REBERE EEE version The version of the board The board version must match the version of the Quartus II 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 s5_net
20. 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 AOCL Custom Platform Toolkit Reference Material LJ Send Feedback Altera Corporation OCL007 15 0 0 2 6 XML Elements Attributes and Parameters in the board spec xml File 2015 05 04 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 aci 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 Qsys alters the width of aci bsp snoop You must update the width of the st reamsource interface within the channels element in the board spec xml file to match the width of aci bsp snoop Important In the board spec xml file update the width of the snoop interface acl internal snoop specified with the st reamsource 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 aci bsp memorg host interface of the OpenCL Ke
21. port udpO0 in type streamsink width 256 chan id eth0 out interface name udp 0 port udpl out type streamsource width 256 chan id ethl in interface name udp 0 port udpl in type streamsink width 256 chan id eth1 out lt channels gt Related Information interface on page 2 12 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 irgand streamsource Refer to the interface section for the parameters you must specify for each interface Example eXtensible Markup Language XML code lt interfaces gt interface name board port kernel_cra type master width 64 misc 0 gt interface name board port kernel_irq type irq width 1 gt lt interface name board port acl_internal_snoop type streamsource enable SNOOPENABLE width 33 clock board kernel_clk gt Xkernel clk reset clk board kernel_clk clk2x board kernel_clk2x reset board kernel reset interfaces In addition to the master irg and streamsource interfaces if your design includes a separate Qsys 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 kexne1 clk reset attribute and its corresponding parameters
22. to control the Quartus II compilation registra tion and automigration Below is the XML code of an example board spec xml file lt xml version 1 0 gt lt board version 15 0 name s5_net gt device device model 2 5sgsed8k2f40c2 dm xml used resources lt alms num 45000 gt lt ALMs used in final placement ALMs used for registers gt lt ffs num 117500 gt dsps num 0 gt lt rams num 511 gt lt used_resources gt Altera Corporation Altera SDK for OpenCL Custom Platform Toolkit User Guide C Send Feedback OCL007 15 0 0 2015 05 04 device 1 DDR3 1600 gt lt global_mem name DDR max_bandwidth 25600 config_addr 0x018 gt interface name board port kernel mem0 type slave width 512 maxburst 16 address 0x00000000 size 0x100000000 latency 240 gt interface name board port kernel meml type slave width 512 interleaved_bytes 1024 Creating the board_spec xml File maxburst 16 address 0x100000000 size 0x100000000 latency 240 gt global mem l ODRII 5 global mem name QDR max bandwidth 17600 config addr 0x100 interface name board type slave width 64 maxburst 1 address 0x200000000 size 0x1000000 latency 150 addpipe 1 gt interleaved_bytes 8 port name kernel qdr0 r direction r gt port name kernel qdr0 w direction w gt interface interface name board type s
23. use these signals Based on the number of global memory systems you specify in the OpenCL Kernel Interface component parameter editor the Quartus II 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 Qsys component that takes an incoming request from the host interface on the Avalon Memory Mapped 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 2 5 Parameter Settings for the OpenCL Memory Bank Divider Component Number of banks Number of memory banks for each of the global memory types included in your board system Altera Corporation AOCL Custom Platform Toolkit Reference Material Send Feedback O
24. 1 2 AOCL Software Architecture This figure depicts the four layers of the Altera SDK for OpenCL AOCL software architecture runtime hardware abstraction layer HAL MMD layer and kernel mode driver Runtime OpenCL API HAL for memory transfers and kernel launches MMD layer for raw read and write operations Kernel mode driver for accessing communication medium Board Hardware The following tasks outline the procedure for creating an MMD library for use with PCI Express PCIe 1 2 Name a new library file that implements the MMD layer in the following manner lt board_vendor_name gt _ lt board_family_name gt _ lt unique_string gt _mmd lt a so lib dll gt Where lt board_vendor_name gt is the entity responsible for the accelerator board lt board_family_name gt is the board family name that the library supports lt unique_string gt is a designation that you create Altera recommends that you include information such as revision and interface type lt a so lib dll gt 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 Altera Corporation Altera SDK for OpenCL Custom Platform Toolkit User Guide C Send Feedback OCL007 15 0 0 2015 05 04 Kernel Power up State 1 17 Example library file name altera svdevkit pcierevi mmd so Include the ALTERAOCLSDKROOT board custom platform toolkit mmd
25. A device Store the executables in the utilbindir directory of your Custom Platform 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 Altera SDK for OpenCL Custom Platform Toolkit User Guide Altera Corporation GC Send Feedback OCLO007 15 0 0 1 20 Testing the Hardware Design 2015 05 04 Related Information Creating the board env xml File on page 1 10 e Reprogram Support on page 2 26 aoc mmd reprogram on page 2 25 Testing the Hardware Design After you create the software utilities and the memory mapped device MMD layer and your hardware design achieves timing closure test the design To test the hardware design perform the following tasks 1 Navigate to the boardtest cl OpenCL kernel within the ALTERAOCLSDKROOT board custom platform toolkit tests boardtest directory ALTERAOCLSDKROOT points to the location of the Altera SDK for OpenCL AOCL installation 2 Compile your kernel to generate an Altera Offline Compiler Executable file aocx by invoking the aoc no interleaving default boardtest cl command 3 Program the accelerator board by invoking the aocl program acl0 boardtest aocx command 4 Invoke the commands aocl compile configand aocl link config Confirm they include flags necessary for your MMD layer to compile and link successfully 5 Build the boardtest host application
26. Altera SDK for OpenCL Custom Platform Toolkit User Guide X subscribe OCL007 15 0 0 2015 05 04 LJ Send Feedback 101 Innovation Drive am San Jose CA 95134 AHNERA www altera com TOC 2 Contents Altera SDK for OpenCL Custom Platform Toolkit User Guide 1 1 PHOTOG UL Sib Si cura Gulan N SEN HEYE R YE EY SE MON SEK KANE HEE covevenss 1 1 Overview of the AOCL Custom Platform eee eee eee eyer ee xereke dn eee etd rod HHHH HAH AKAR 1 2 Directories and Files in an AOCL Custom Plathotiit ivinseccoucesssasnsriaseseaviassennsiusosssanecsuavacnantesbes 1 3 Recommendations for Structuring the Custom Platform Directory 1 3 Custom Platform Automigration for Forward Compatibility eene 1 4 Customizing AutomigratiOn e cerebri tt en EORR svcd y a R Hee H r WEN ios vaga 1 4 Cre ating n AOCL Custom Platformen a 1 5 Designing the Board Hatd ware scsicsiisccsssasicssacscssnasssasssescecaosssvsseancsncotiashatbesaaptavenetaarsaseaesscusanasenaae 1 5 Creating the Board XML Piles cisccicnniaciinaqinntanconieanaannanaseaamaitemecniin 1 10 Creating the MIM IL iDI dya Ai dn cossndnsuencesn day k de d He c n ke Nauck dy K 1 16 Setting Up the Altera Client DEIVeLtuseseeocetiserent iare esiti re o rod MR a 1 17 Providing AOCL Utilities SHDDOEL aperiri an 1 458 0
27. CL007 15 0 0 2015 05 04 OpenCL Memory Bank Divider 2 5 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 Burst size maximum Total number of address bits necessary to address all global memory 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 Qsys 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 Table 2 6 Signals and Ports for the OpenCL Memory Bank Divider Component clk The bank divider logic uses this clock input If the intellectual property IP of your host and memory interfaces have different clocks ensure that c1k 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
28. E 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 Altera s support for this level of SVM is preliminary Some features might not be fully supported int bit field AOCL Custom Platform Toolkit Reference Material send Feedback Altera Corporation OCL007 15 0 0 2 18 aocl mmd get info 2015 05 04 2 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 AoCt 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 3 param value A void pointer to the variable that receives the returned information 4 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 aoci1 mmd get info function obtains information about the board specified in the requested info id argument Syntax int aocl mmd get i
29. Feedback 1 22 Shipping Recommendations OCL007 15 0 0 2015 05 04 Shipping Recommendations Before shipping your Altera verified board to Altera SDK for OpenCL AOCL 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 AOCL user to power on the board and observe a working kernel Download the hello_world OpenCL design example from the OpenCL Design Examples page of the Altera 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 Altera SDK for OpenCL Getting Started Guide Related Information e OpenCL Design Examples on the Altera website Programming the Flash Memory of an FPGA on Windows Programming the Flash Memory of an FPGA on Linux Document Revision History Table 1 4 Document Revision History of the AOCL Custom Platform Design Chapter of the Altera SDK for OpenCL Custom Platform Toolkit User Guide HEKE veson T Senas May 2015 15 0 0 Added the Setting Up the Altera Client Driver section December 14 1 0 2014 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 boa
30. OCL installation The goal is to enable an AOCL 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 AOCL BOARD PACKAGE ROOT to this local directory Invoke the aocl install utility command Compile the OpenCL kernel and build the host application AYP YN For Windows systems set the PATH environment variable For Linux systems set the LD_LIBRARY_PATH environment variable 7 Run the host application Prerequisites Set environment variables to point to the location of the memory mapped device MMD library The Altera SDK for OpenCL Custom Platform Toolkit User Guide assumes that you have prior hardware design knowledge necessary for using the Custom Platform Toolkit to create an Altera SDK for OpenCL AOCL Custom Platform OpenCL and the OpenCL logo are trademarks of Apple Inc used by permission of the Khronos Group The Altera 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 2015 Altera Corporation All rights reserved ALTERA ARRIA CYCLONE ENPIRION MAX MEGACORE NIOS QUARTUS and STRATIX words and logos are trademarks of Altera Corporation and registered in the U S Patent a
31. OCL007 15 0 0 2015 05 04 Providing AOCL Utilities Support 1 19 Create an install utility executable that sets up the current host computer with the necessary drivers to communicate with the board via the memory mapped device MMD layer The install utility takes no argument For example the PCI Express PCIe based MMD might need to install PCIe drivers into the host operating system Executable call aocl install 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 Create a dual purpose diagnose utility executable that confirms the board s integrity and the functionality of the MMD layer When users invoke the diagnose utility command without an argument it queries the devices in the Custom Platform and supplies a list of valid lt device_name gt strings assigned to the list of devices Executable call without argument aocl diagnose When users invoke the diagnose utility command with a lt device_name gt argument the utility runs your diagnostic test for the board 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 lt device_name gt where lt devi
32. addition to organizing your design code having this subsystem allows you to create a Quartus II partition that you can preserve To create your board system in a Qsys subsystem you may modify the board qsys template in the Custom Platform Toolkit Altera Corporation Altera SDK for OpenCL Custom Platform Toolkit User Guide C Send Feedback OCL007 15 0 0 2015 05 04 Creating the Board Qsys System 1 7 An implementation of a board Qsys subsystem might include the following components Proper reset sequencing Altera SDK for OpenCL AOCL specific components Host to FPGA communication intellectual property IP Memory IP used for AOCL global memory Streaming channels to board specific interfaces Refer to The Board Qsys System section for more information Templates of the following hardware design files are available in the ALTERAOCLSDKROOT 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 ALTERAOCLSDKROOT 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 Qsys system or in a board Qsys subsystem 1 In Qsys add your host and memory IPs to the Qsys system and establish all necessary connections and exports Attention You might need to acquire separ
33. all 2 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 3 1en The size of the data in bytes that the function transfers Declare 1en with type size_t 4 intf The handle to the interface that aoc1 mma read is accessing For example to access global memory this handle is the enum value aoc1 mmd get info returns when its xequested info id argument is AOCL MMD MEMORY INTERFACE The interface argument is of type aocl mmd interface t andcan take one of the following values NENNEN INMEMENNEMNMMENEM EMEN AOCL MMD KERNEL Control interface into the kernel interface AOCL MMD MEMORY Data interface to device memory AOCL MMD PLL Interface for reconfigurable phase locked loop PLL 5 src offset The size t byte offset within the source interface at which the data transfer begins 6 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
34. and the Altera SDK for OpenCL AOCL Important Automigration is more likely to complete successfully if your Custom Platform resembles an Altera Reference Platform as closely as possible The following information applies to a Custom Platform that is version 14 0 and beyond 1 To update a Custom Platform for use with the current version of the ACDS which includes the AOCL do not modify your Custom Platform The automigration capability detects the version of your Custom Platform based on certain characteristics and updates it automatically 2 If you have modified a Custom Platform and you want to update it for use with the current version of the ACDS which includes the AOCL 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 ACDS or AOCL version will not interfere with Custom Platform functionality When the Altera Offline Compiler AOC compiles a kernel it probes the board spec xml file for the following information 1 The version of the Custom Platform as specified by the version attribute of the board eXtensible Markup Language XML element 2 The platform type as specified by the plat orm type parameter of the auto migr
35. ard installation where ALTERAOCLSDKROOT points to the location of the AOCL installation Attention Do not remove any existing subdirectories from the ALTERAOCLSDKROOT board directory Create a board vendor name subdirectory within the ALTERAOCLSDKROOT board directory to store the Custom Platform Store the contents of a given Custom Platform in a ALTERAOCLSDKROOT 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 Altera SDK for OpenCL Custom Platform Toolkit User Guide Altera Corporation GC Send Feedback e M OCL007 15 0 0 1 4 Custom Platform Automigration for Forward Compatibility 2015 05 04 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 AOCL user can access XYZ by performing the following tasks 1 Install the XYZ Custom Platform in ALTERAOCLSDKROOT board ABC XYZ where ALTERAOCLSDK ROOT is the environment variable that points to the absolute path to the AOCL installation package 2 Set the AOCL_BOARD_PACKAGE_ROOT environment variable to point to ALTERAOCLSDKROOT board ABC XYZ Custom Platform Automigration for Forward Compatibility The automigration feature updates an existing Altera registered Custom Platform for use with the current version of the Altera Complete Design Suite ACDS
36. ate IP licenses For a list of available licensed and unlicensed IP solutions visit the All Intellectual Property page of the Altera website For more information about each IP click the link in the Product Name column to navigate to the product page a 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 configu ration b Modify the parameters ofthe 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 so port of pipe stage host ctrl Connect the m0 port Ofpipe 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 c Adjust the number of clock cross kernel mem Nw 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 ea
37. ate attribute within the compile XML element Based on the information the AOCL names a set of fixes it must apply during Custom Platform migration It applies the fixes to the Quartus II project that the AOC uses to compile the OpenCL kernel It also generates an automigration rpt report file in the AOCL 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 Altera field applications engineer for assistance Customizing Automigration You and the Altera SDK for OpenCL AOCL 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 AOCL you want to apply to your Custom Platform Altera Corporation Altera SDK for OpenCL Custom Platform Toolkit User Guide C Send Feedback OCL007 15 0 0 2015 05 04 Creating an AOCL Custom Platform 1 5 1 Disable automigration in one of the following manners e Ifyou area board developer within the compile eXtensible Markup Language XML element in the board spec xml file set the platform type parameter of the auto migrate attribute to none e Ifyou are an AOCL user invoke the aoc no auto migrate command 2 To explicitly include or exclude fixes that the AOCL identifies in the board spec xml file subscribe or unsubscribe to each fix by listing it in the include fixes or ex
38. ator 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 Config Clock Global Reset Interface Kernel CRA Interface Kernel Memory Org Interface Lat N Kernel CIk CIK2x Kernel Clock Generator Kernel Reset Host Host Controller Memory nternal Snoop Interface Interface Pipeline Bridge Bank Divider Kernel Memory Kernel Memory Memory Interface Clock Crossing Bridge Interface Memory Interface Kernel Memory Interface Kernel Memory Clock Crossing Bridge Note Blocks denoted with an asterisk are blocks that you have to add to the board Osys 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 Qsys system O 2015 Altera Corporation All rights reserved ALTERA ARRIA CYCLONE ENPIRION MAX MEGACORE NIOS QUARTUS and STRATIX words and logos are trademarks of Altera Corporation and registered in the U S Patent and Trade
39. 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 Qsys component 7 If your board provides channels for direct OpenCL kernel to I O accesses include the channels element for all channel interfaces Specify the parameters in the interface attribute to describe the characteristics of each channel interface 8 Include the interfaces element to describe the kernel interfaces connecting to and controlling OpenCL kernels Include one of each interface types that is master irq and st reamsource a Specify the parameters in the interface attribute to describe the characteristics of each kernel interface For the st reamsource 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 ac1 internal snoop specified with the streamsource kernel interface Updating the width ensures that the g105a1 mem interface entries in board spec xml match the characteristics of the bank lt n gt Avalon Memory Mapped Avalon MM masters from corresponding OpenCL Memory Bank Divider component for the default memory b Specify the parameters in the kernel clk reset attribute to include the exported kernel clock and reset interfaces as kernel interfaces 9 Include the compile element and specify its attributes
40. bsystem on page 2 1 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 Altera SDK for OpenCL AOCL compilation results The best approach to optimizing the board partition is to experiment with a range of different OpenCL kernels Altera Corporation Altera SDK for OpenCL Custom Platform Toolkit User Guide C Send Feedback OCL007 15 0 0 2015 05 04 Establishing Guaranteed Timing Flow 1 9 The list below captures some of the parameters that might impact the quality of AOCL compilation results Resources Used Minimize the number of resources the partition uses to maximize the resources available for the OpenCL kernels Kernel Clock Frequency Altera 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
41. ce name gt is the acl number that corresponds to the FPGA device Create a program utility executable that receives the fpga bin file 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 and an Altera Offline Compiler Executable file name lt kernel_filename gt aocx as arguments When users invoke the command the AOCL extracts the fpga bin file and passes it to the program utility Important Altera 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 informa tion Executable call aocl program lt device_name gt lt kernel_filename gt aocx where lt device name gt 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 AOCL 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 FPG
42. ch 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 mo master clock and reset ports of clock cross kernel mem Nw that is m0 m0 c1k and m0 reset respectively to your memory IP Altera SDK for OpenCL Custom Platform Toolkit User Guide Altera Corporation GC Send Feedback OCL007 15 0 0 1 8 General Quality of Results Considerations for the Exported Board Partition 2015 05 04 Important Connect m0 reset in such a way that assertion of kernel reset from the OpenCL Memory Bank Divider component triggers this reset 2 Customize the AOCL specific Qsys system components Attention If you use the board qsys system template to create a Qsys subsystem note that it is preconfigured with the necessary connections between the AOCL specific system components and the appropriate interfaces exported to match the board_spec xml file Altera recommends that you preserve the preconfigured connections as much as possible a In Qsys click Tools gt Options In the Options dialog box add ALTERAOCLSDKROOT ip board to the Qsys IP Search Path and then click Finish b 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 c Instantiate the OpenCL Kernel Interface component Specify the c
43. ck OCL007 15 0 0 M 2015 05 04 aocl mmd get offline info 2 15 aocl mmd read on page 2 20 The aoci nnd read function is the read operation on a single interface aocl mmd write on page 2 20 The aoci mmd write function is the write operation on a single interface aocl mmd copy on page 2 21 The aoci mmd copy function is the copy operation on a single interface aocl mmd set interrupt handler on page 2 22 The aocl mmd set interrupt handler function sets the interrupt handler for the opened device aocl mmd set status handler on page 2 23 The aocl mmd set status handler function sets the operation status handler for the opened device aoc mmd yield on page 2 23 The aocl_mmd_yield function is called when the host interface is idle aocl_mmd_shared_mem_alloc on page 2 24 The aocl_mmd_shared_mem_alloc function allocates shared memory between the host and the FPGA aocl_mmd_shared_mem_free on page 2 24 The aoci mmd shared mem free function frees allocated shared memory aocl mmd reprogram on page 2 25 The aoci mmd reprogram function is the reprogram operation for the specified device aocl mmd get offline info The aocl1 mmd get offline info function obtains offline information about the board specified in the requested info idargument This function is offline because it is device independent and does not require a handle from the aoc1 mma open call Syntax int aocl mmd get offline info aocl mmd offline info
44. cks e 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 eXtensible Markup Language XML code lt DDR3 1600 gt lt global_mem name DDR max_bandwidth 25600 interleaved_bytes 1024 config_addr 0x018 gt interface name board port kernel_mem0 type slave width 512 maxburst 16 address 0x00000000 size 0x100000000 latency 240 gt interface name board port kernel_mem1l type slave width 512 maxburst 16 address 0x100000000 size 0x100000000 latency 240 gt lt global_mem gt lt l ODRII gt global mem name QDR max bandwidth 2 17600 interleaved bytes 8 config addr 0x100 interface name board type slave width 64 maxburst 1 address 0x200000000 size 0x1000000 latency 150 addpipe 1 gt port name kernel qdr0 r direction r gt port name kernel qdr0 w direction w gt interface Altera Corporation AOCL Custom Platform Toolkit Reference Material Send Feedback OCL007 15 0 0 2015 05 04 interface name board type slave address 0x201000000 port port interface interface name board type slave address 0x202000000 lt port lt port lt interface gt interface name board type slave address 0x203000000 port port interface global mem
45. clude 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 AOCL Custom Platform The following topics outline the tasks you must perform to create a Custom Platform for use with the Altera SDK for OpenCL AOCL 1 Designing the Board Hardware on page 1 5 To design an accelerator board for use with the Altera SDK for OpenCL AOCL you must create all the board and system components and the files that describe your hardware design to the Altera Offline Compiler AOC 2 Creating the Board XML Files on page 1 10 Your Custom Platform must include the eXtensible Markup Language XML files that describe your Custom Platform and each of your hardware system to the Altera SDK for OpenCL AOCL 3 Creating the MMD Library on page 1 16 Your Custom Platform requires a memory mapped device MMD layer necessary for communication with the accelerator board 4 Setting Up the Altera Client Driver on page 1 17 The ACD allows the AOCL to automatically find and load the Custom Platform libraries at host runtime 5 Providing AOCL Utilities Support on page 1 18 Each Custom Platform you develop for use with the Altera SDK for OpenCL AOCL must support a set of
46. d set status handler int handle aocl mmd status handler fn fn void user data Function Arguments 1 handle A positive int value representing the handle to the board obtained from the aocl mmd open call 2 n The callback function to invoke when a status update occurs The n 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 3 user data The void type user provided data that passes to n 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 AOCL Custom Platform Toolkit Reference Material LJ Send Feedback Altera Corporation OCL007 15 0 0 2 24 aocl mmd shared mem alloc 2015 05 04 Function Arguments 1 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
47. e Hardware Design on page 1 20 Creating the board spec xml File The board spec xml eXtensible Markup Language XML file contains metadata necessary to describe your hardware system to the Altera SDK for OpenCL AOCL 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 Altera Corporation Altera SDK for OpenCL Custom Platform Toolkit User Guide C Send Feedback OCL007 15 0 0 2015 05 04 Creating the board_spec xml File 1 13 template is available in the ALTERAOCLSDKROOT board custom_platform_toolkit board_package hardware template directory of the Custom Platform Toolkit 1 Structure the board_spec xml file to include the following XML elements and attributes Table 1 3 XML Elements and Attributes Specified in the board_spec xml File board version name device device_model used_resources global_mem name max_bandwidth interleaved_bytes config_addr default interface host kernel_config channels interface interfaces interface kernel_clk_reset compile project revision qsys_file generic_kernel generate_cmd synthesize_cmd auto_migrate 2 For the board element specify the board version and the name of the accelerator board The name of the board must match the name of the directory in which the board_spec xml file resides Important
48. e figure below The top level system qsys Osys system can then instantiate this exported board Qsys 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 Osys system file for example system qsys You must design all the components and the board spec xml file that describe the system to the AOCL Figure 1 1 Example System Hierarchy with a Board Qsys Subsystem system qsys board qsys optional Avalon ST Source U Streaming Source Avalon MM Master gt Avalon MM Slave gt Avalon ST Sink Avalon ST Sink po Avalon ST S eine aod Avalon MM Slave Memory i Interface Avalon MM Master 4 nd Avalon MM Slave Memory Interface Avalon MM Master l 0 1 Creating the Board Qsys System on page 1 6 To create your board system in a Qsys subsystem you may modify the board qsys template in the Custom Platform Toolkit 2 Establishing Guaranteed Timing Flow on page 1 9 Deliver a design partition for nonkernel logic that has a clean timing closure flow as part of your Custom Platform Creating the Board Qsys System When designing your board hardware you have the option to create a Qsys subsystem within system qsys that contains all the board logic In
49. efore the configuration of the AOCL Memory Bank Divider must match the exported kernel slave interfaces in this respect config addr The address of the ACL Mem Organization Control Qsys 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 AOCL Custom Platform Toolkit Reference Material send Feedback Altera Corporation OCL007 15 0 0 ZR host 2015 05 04 EE CR scion 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 Related Information interface on page 2 12 host The nost element of the board spec xml file provides information on the interface from the host to the kernel Example eXtensible Markup Language XML code host Xkernel config start 0x00000000 size 0x0100000 gt host Table 2 10 Attributes for the host Elem
50. ent SE NN kernel config This attribute informs the Altera Offline Compiler AOC at what offset the kernel resides from the perspective ofthe 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 kerne1_cra master should not master anything except kernels size keep this parameter at the default value of 0x0100000 channels The Altera SDK for OpenCL AOCL supports data streaming directly between kernels and I O via explicitly named channels Include the cnanne1s element in the board spec xml file if your accelerator board provides channels for direct kernel to I O accesses For the channe1s element you must identify all the channel interfaces which are implemented using the Avalon Streaming 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 eXtensible Markup Language XML code channels interface name udp 0 port udp0 out type streamsource width 256 chan id ethO0 in Altera Corporation AOCL Custom Platform Toolkit Reference Material C Send Feedback OCL007 15 0 0 2015 05 04 interfaces 2 11 interface name udp 0
51. equivalent interfaces If you have streaming I O you must also include the corresponding IPs in the board Qsys system In addition you must update the board_spec xml file to describe the channel interfaces AOCL Specific Qsys System Components The Qsys system for your board logic includes components specific to the Altera SDK for OpenCL AOCL that are necessary for implementing features that instantiate host communication and global memory interfaces The board Qsys system must export an Avalon Memory Mapped 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 ALTERAOCLSDKROOT ip board directory of the AOCL includes a library that contains AOCL specific Qsys system components where ALTERAOCLSDKROOT points to the location of the AOCL 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 1 OpenCL Kernel Clock Generator on page 2 2 The OpenCL Kernel Clock Generator is a Qsys component that generates a clock output and a clock 2x output for use by the OpenCL kernels 2 OpenCL Kernel Interface on page 2 3 The OpenCL Kernel Interface is a Qsys component that allows the host interface to access and control the OpenCL kernel 3 OpenCL Memory Bank Divider on page 2 4 The OpenCL Memory Bank Divider is
52. erface resides for example board port For g1obal mem name of the Qsys component for the slave interface of the memory For channels name of the streaming interface in the Qsys component For interfaces name of the interface to the OpenCL Kernel Interface Qsys component For example kernel crais the Avalon Memory Mapped Avalon MM interface and All kernel_ irq is an interrupt type For global_mem set to slave For channels e Set to streamsource for a stream source that provides data to the kernel e Set to streamsink for a stream sink interface that consumes data from the kernel For interfaces set to either master irg Or streamsource width For global_mem width of the memory interface in bits For channels number of bits in the channel interface Valid data widths are 8 16 32 64 128 256 and 512 bits For interfaces width of the kernel interface in bits Altera Corporation AOCL Custom Platform Toolkit Reference Material C Send Feedback OCL007 15 0 0 2015 05 04 compile 2 13 maxburst Maximum burst size for the slave interface Attention The value of width 8xmaxburst 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 addres
53. es that the function transfers Declare 1en with type size t 4 src The host buffer of type const void from which data is read 5 interface The handle to the interface that aoc1 mmd write is accessing For example to access global memory this handle is the enum value aoci mma get info returns when its requested info id argument is AOCL MMD MEMORY INTERFACE The interface argument is of type aocl mmd interface t andcan take one of the following values EE STEN DEDEN ON AOCL MMD KERNEL Control interface into the kernel interface AOCL MMD MEMORY Data interface to device memory AOCL MMD PLL Interface for reconfigurable phase locked loop PLL 6 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 aoci mmd copy function is the copy operation on a single interface Syntax int aocl mmd read int handle aocl mmd op t op size t len aocl mmd interface t intf size t src offset size t dst offset AOCL Custom Platform Toolkit Reference Material Altera Corporation LJ Send Feedback OCL007 15 0 0 2 22 aocl_mmd_set_interrupt_handler 2015 05 04 Function Arguments 1 handle A positive int value representing the handle to the board obtained from the aocl_mmd_open c
54. gt lt generate_cmd qsys generat synthesis VERILOG system qsys gt lt synthesize_cmd quartus_sh flow compile top c top gt lt auto_migrate platform_type s5_net gt lt include fixes gt lt exclude fixes gt lt auto_migrate gt lt compile gt AOCL Custom Platform Toolkit Reference Material Altera Corporation send Feedback 2 14 MMD API Descriptions OCL007 15 0 0 2015 05 04 NEM C INN ee ee project Name of the Quartus II project file qpf that the Quartus II software intends to compile revision Name of the revision within the Quartus II project that the Quartus II software compiles to generate the Altera Offline Executable file aocx qsys file Name of the Osys file into which the OpenCL kernel is embedded generic kernel generate cmd Set this value to 1 if you want the Altera Offline Compiler AOC to generate a common Verilog interface for all OpenCL compilations This setting is necessary in situations where you must set up Quartus II design partitions around the kernel such as in the Configuration via Protocol CvP flow Command required to prepare for full compilation such as to generate the Verilog files for the Qsys 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 Quartus II software to perform a full compilation auto migra
55. he library is necessary for all devices with an MMD layer utilbindir Directory in which the AOCL expects to locate the AOCL utility executables that is install uninstall program diagnose and flash Tip You can use a to reference the AOCL installation directory and b to reference your board installation directory Your board_env xml file should resemble the following example lt xml version 1 0 gt lt board_env version 15 0 name s5_net gt lt hardware dir hardware default s5_net gt lt hardware gt lt platform name linux64 gt lt compileflags gt I b include lt compileflags gt linkflags L b linux64 lib linkflags lt linklibs gt lalterahalmmd laltera s5 net mmd linklibs lt utilbindir gt b linux64 libexec lt utilbindir gt lt platform gt Altera SDK for OpenCL Custom Platform Toolkit User Guide Altera Corporation Send Feedback OCL007 15 0 0 1 12 Testing the board_env xml File 2015 05 04 lt platform name windows64 gt lt compileflags gt I b include lt compileflags gt lt linkflags gt libpath b windows64 lib lt linkflags gt lt linklibs gt alterahalmmd lib altera s5 net mmd lib linklibs lt utilbindir gt b windows64 libexec lt utilbindir gt lt platform gt lt board_env gt Related Information Prerequisites for the Altera SDK for OpenCL Prerequisites for the Altera RTE for OpenCL Testing the board_env xml File After you generate
56. ion 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 AOCL Custom Platform Toolkit Reference Material Altera Corporation LJ Send Feedback OCL007 15 0 0 2 20 aocl_mmd_read 2015 05 04 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 1 handle A positive int value representing the handle to the board obtained from the aocl mmd open call 2 op The operation object of type aoc1 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 3 1en The size of the data in bytes that the function transfers Declare 1en with type size t 4 dst The host buffer of type void to which data is written 5 interface The handle to the interface that aoci mma read is accessing For example to access global memory this handle is the enum value aoci mma ge
57. l_snoop type streamsource enable SNOOPENABLE reset board lt interfaces gt lt compile project top width 33 Xkernel clk reset clk board kernel_clk kernel reset Xgenerate cmd 2 qsys generat synthesis V clock board kernel clk clk2x board kernel_clk2x revision top qsys_file system qsys generic_kernel 1 gt ERILOG system qsys gt lt synthesize_cmd quartus_sh flow compile top c top gt lt auto_migrate platform_type s5_net gt lt include fixes gt lt exclude fixes gt lt auto_migrate gt Altera SDK for OpenCL Custom Platform Toolkit User Guide C Send Feedback Altera Corporation OCL007 15 0 0 1 16 Creating the MMD Library 2015 05 04 lt compile gt lt board gt Related Information XML Elements Attributes and Parameters in the board_spec xml File on page 2 6 Creating the MMD Library Your Custom Platform requires a memory mapped device 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 communica tion Figure
58. lave width 64 maxburst 1 address 0x201000000 size 0x1000000 latency 150 addpipe 1 gt port name kernel qdrl r direction r gt port name kernel qdrl w direction w gt interface interface name board type slave width 64 maxburst 1 address 0x202000000 size 0x1000000 latency 150 addpipe 1 gt port name kernel qdr2 r direction r gt port name kernel qdr2 w direction w gt interface interface name board type slave width 64 maxburst 1 address 0x203000000 size 0x1000000 latency 150 addpipe 1 gt port name kernel qdr3 r direction r gt port name kernel qdr3 w direction w gt interface global mem channels interface name udp 0 chan id eth0 in interface name udp 0 chan id ethO0 out interface name udp 0 chan id ethl in interface name udp 0 chan id eth1l out port udpO0 out port2 udpO0 in type streamsink width 256 port udpl out port udpl in type streamsink width 256 type 2 streamsource width 256 type streamsource width 256 lt channels gt lt host gt lt kernel_config start 0x00000000 size 0x0100000 gt lt host gt lt interfaces gt interface name board port kernel_cra type master width 64 misc 0 gt lt interface name board port kernel_irg type irg width 1 gt lt interface name board port acl_interna
59. le s and the AOCL on your machine Refer to the Altera SDK for OpenCL Getting Started Guide for installation instructions Before designing your Custom Platform download the Stratix V Network Reference Platform s5 net from the OpenCL Reference Platforms page of the Altera website The Altera SDK for OpenCL Custom Platform Toolkit User Guide refers to example files and code snippets from s5 net You have the following Custom Platform design options e Refer to the information in the Altera SDK for OpenCL Custom Platform Toolkit User Guide to create a Custom Platform from the templates available in the Custom Platform Toolkit e Refer to the information in the following documents to create a Custom Platform by modifying relevant files in s5 net 1 Altera SDK for OpenCL Custom Platform Toolkit User Guide 2 Altera Stratix V Network Reference Platform Porting Guide e Refer to the information in the following documents to create a Custom Platform by modifying relevant files in the Cyclone V SoC Development Kit Reference Platform c5soc available with the AOCL 1 Altera SDK for OpenCL Custom Platform Toolkit User Guide 2 Altera Cyclone V SoC Development Kit Reference Platform Porting Guide 3 Cyclone V SoC Development Board Reference Manual Related Information Altera SDK for OpenCL Getting Started Guide Altera Stratix V Network Reference Platform Porting Guide e Altera Cyclone V SoC Development Kit Reference Platform Porting
60. m Platform Toolkit tests swapper Actual clock freq as reported in the acl quartus report txt file from the blank test in the Custom Platform Toolkit ALTERAOCLSDKROOT 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 5 Submit the necessary number of boards to Altera 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 a b E d Install the board into the physical machine Boot the machine and invoke the aocl install utility command Invoke the aocl diagnose command Run the AOCL test programs The tester can also invoke the aocl program device name lt kernel_filename gt cl command to verify the functionality of the program utility Related Information OpenCL Design Examples page on the Altera website Altera SDK for OpenCL Custom Platform Toolkit User Guide Altera Corporation GC Send
61. mark Office and in other countries All other words and logos identified as trademarks or service marks are the property of their respective holders as described at www altera com common legal html Altera warrants performance ISO of its semiconductor products to current specifications in accordance with Altera s standard warranty but reserves the right to make changes to any ial egistere products and services at any time without notice Altera assumes no responsibility or liability arising out of the application or use of any information product or service described herein except as expressly agreed to in writing by Altera Altera customers are advised to obtain the latest version of device specifications before relying on any published information and before placing orders for products or services JANOS RYA 101 Innovation Drive San Jose CA 95134 OCL007 15 0 0 2 2 AOCL Specific Qsys System Components 2015 05 04 For example an MMD layer executes on a PCI Express PCIe based host interface and the host interface generates Avalon interface requests from an Altera PCIe endpoint on the FPGA Within the board Qsys 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
62. mic link library DLL and a numerical data value 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 AOCL attempts to open any board that is associated with that library In this case the ACD opens the library cWboard vendor amy 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 ACD on Linux Enter the absolute paths of Custom Platform libraries in an acd file Store the acd file in the opt Altera OpenCL boards directory To enumerate Custom Platform ACDs on Linux the ACD Loader scans the files with the extension acd in the path opt Altera OpenCL boards The ACD Loader opens each acd file in this path as a text file Each acd 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 AOCL attempts to open any board that is associated with that library For example consider the file opt Altera OpenCL boards PlatformA acd If it contains the line opt PlatformA libPlattormA mmd so the ACD Loader loads the library opt PlatformA libPlatfo
63. 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 1 handle A positive int value representing the handle to the board obtained from the aocl_mmd_open call 2 user data The void type binary contents of the fpga bin file that are created during compilation 3 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 AOCL Custom Platform Toolkit Reference Material Altera Corporation LJ Send Feedback 2 26 Reprogram Support Reprogram Support OCL007 15 0 0 2015 05 04 For Altera SDK for OpenCL AOCL 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 memory mapped device 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 Quartus II compilation The Altera Offline Compiler AOC packages the exact contents of fpga bin into the Altera
64. mpatible with future ACDS versions Altera Corporation Altera SDK for OpenCL Custom Platform Toolkit User Guide C Send Feedback OCL007 15 0 0 2015 05 04 Applying for the Altera Preferred Board Status 1 21 For your Custom Platform and the supported FPGA boards to achieve the Altera Preferred Board status you must generate the following data and submit it to Altera 1 The output from invoking the aocl board xml test command 2 The output from invoking the aoc list boards command 3 The outputs from the host compilation host execution and all Quartus II report files rpt Also for each board in your Custom Platform the acl quartus report txt file from the following tests a b All tests included in the ALTERAOCLSDKROOT board custom platform toolkit tests directory where ALTERAOCLSDKROOT points to location of the Altera SDK for OpenCL AOCL installation Compilations of the following examples on the OpenCL Design Examples page of the Altera website Vector Addition Matrix Multiplication FFT 1D FFT 2D Sobel Filter Finite Difference Computation 3D 4 For each board in the Custom Platform a summary of the following a b HOST TO MEMORY BANDWIDTH as reported by the boardtest test in the Custom Platform Toolkit tests boardtest KERNEL TO MEMORY BANDWIDTH as reported by the boardtest test Throughput in swap and execute s reported by the swapper test in the Custo
65. nal 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 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 Qsys 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 Qsys system interface with kernel clk except for any I O that you add kernel clk2x 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 Qsys system OpenCL Kernel Interface The OpenCL Kernel Interface is a Qsys component that allows the host interface to access and control the OpenCL kernel Table 2 3 Parameter Settings for the OpenCL Kernel Interface Component Number of global memory Number of global memory types in your board design systems Table 2 4 Signals and Ports for the OpenCL Kernel Interface Component 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 h
66. nd Trademark Office and in other countries All other words and logos identified as trademarks or service marks are the property of their respective holders as described at www altera com common legal html Altera warrants performance of its semiconductor products to current specifications in accordance with Altera s standard warranty but reserves the right to make changes to any products and services at any time without notice Altera assumes no responsibility or liability arising out of the application or use of any information product or service described herein except as expressly agreed to in writing by Altera Altera customers are advised to obtain the latest version of device specifications before relying on any published information and before placing orders for products or services Iso 9001 2008 Registered ANU amp RYA 101 Innovation Drive San Jose CA 95134 OCL007 15 0 0 1 2 Overview of the AOCL Custom Platform 2015 05 04 You must have experiences in the following hardware design areas e Quartus II design with Qsys HDL and Tcl e Altera intellectual property IP necessary to communicate with the physical interfaces of the board e High speed design timing analysis and Synopsys Design Constraints SDC constraints FPGA architecture including clock and global routing floorplanning and I O e Team based design that is incremental compilation You must install the Quartus II software the relevant device support fi
67. nfo int handle aocl mmd info t requested info id size t param value size void param value size t param size ret Function Arguments 1 handle A positive int value representing the handle to the board obtained from the aocl mmd open call 2 requested info id An enum value of type aocl mmd offline info t that indicates the device information returning to the caller Table 2 14 Possible Enum Values for the requested info id Argument EE KNEE CNN RN 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 PCI Express PCIe informa char tion AOCL MMD BOARD NAME Board name char AOCL MMD BOARD UNIQUE ID Unique board ID char 3 param value size Size ofthe param value field in bytes This size t value should match the size of the expected return type that the enum definition indicates Altera Corporation AOCL Custom Platform Toolkit Reference Material C Send Feedback OCL007 15 0 0 2015 05 04 aocl_mmd_open 2 19 For example if AocL_MMD_TEMPERATURE returns a value of type float set the param_value_size to sizeof float Yo
68. omponent parameters and connect the signals and ports as outlined in the OpenCL Kernel Interface section d 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 Qsys generates a master that inherits the same characteristics as your specifications 3 If you choose to create a Qsys subsystem for the nonkernel logic export any necessary I Os to the top level system qsys Osys system 4 Edit the top level top v file to instantiate system qsys and connect any board specific I Os Set up the top qpf Quartus II project with all the necessary settings for your board design 6 Modify the post flow tcl file to include the Tcl code that generates the fpga bin file during Quartus II compilation The fpga bin file is necessary for programming the board 7 Edit the board spec xml file to include board specific descriptions Related Information All Intellectual Property page on the Altera website e OpenCL Kernel Clock Generator on page 2 2 e OpenCL Kernel Interface on page 2 3 e OpenCL Memory Bank Divider on page 2 4 e The Board Qsys Su
69. ost 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 AOCL Custom Platform Toolkit Reference Material Altera Corporation CJ Send Feedback 2 4 OpenCL Memory Bank Divider OCL007 15 0 0 2015 05 04 kernel cra This Avalon Memory Mapped Avalon MM master interface communicates directly with the kernels generated by the Altera Offline Compiler AOC 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 memory mapped device 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 synchron ized to the c1x 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
70. ration Altera SDK for OpenCL Custom Platform Toolkit User Guide C Send Feedback OCL007 15 0 0 2015 05 04 Creating the board env xml File 1 11 Table 1 2 Specifications of XML Elements and Attributes in the board_env xml File board_env version The AOCL Custom Platform Toolkit release you use to create your Custom Platform Attention The Custom Platform version must match the AOCL 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 AOC targets when the AOCL user does not specify an explicit argument for the board lt board_name gt AOC option platform name Name of the operating system Refer to the Altera SDK for OpenCL Getting Started Guide and the Altera RTE for OpenCL Getting Started Guide for more information linkflags A string that specifies the linker flags necessary for linking with the memory mapped device MMD layer available with the board Tip You can use a to reference the AOCL installation directory and b to reference your board installation directory linklibs A string that specifies the libraries the AOCL must link against to use the MMD layer available with the board Note Include the alterahalmmd library available with the AOCL in this field because t
71. rd_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 Altera Corporation Altera SDK for OpenCL Custom Platform Toolkit User Guide C Send Feedback OCL007 15 0 0 2015 05 04 Document Revision History 1 23 a c ON June 2014 14 0 0 e Initial release Altera SDK for OpenCL Custom Platform Toolkit User Guide Altera Corporation C Send Feedback AOCL Custom Platform Toolkit Reference Material 2015 05 04 OCL007 15 0 0 X subscribe C_ Send Feedback The AOCL Custom Platform Toolkit Reference Material chapter provides supplementary information that can assist you in the implementation of your Custom Platform The Board Qsys Subsystem When designing your board hardware you have the option to create a Qsys subsystem within the top level Qsys system system qsys that contains all nonkernel logic The board Qsys subsystem is the main design entry point for a new acceler
72. rmA mmd so If the acd 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 acd file For more information on how AOCL users link their host applications to the Installable Client Driver ICD and the ACD refer to the Linking Your Host Application to the Khronos ICD Loader Library section in the Altera SDK for OpenCL Programming Guide Related Information Linking Your Host Application to the Khronos ICD Loader Library Providing AOCL Utilities Support Each Custom Platform you develop for use with the Altera SDK for OpenCL AOCL must support a set of AOCL utilities These utilities enable users to manage the accelerator board through the AOCL 1 If you create a new Custom Platform perform the following tasks to create executables of the AOCL utilities for your Custom Platform Tip Within the path to s5 net source util directory of the Stratix V Network Reference Platform s5 net you can find source code for the diagnose program and flash utilities in the diagnostic reprogram and flash subdirectories respectively Scripts for the install and uninstall utilities are available in the path to s5 net OS platform libexec directory Altera Corporation Altera SDK for OpenCL Custom Platform Toolkit User Guide C Send Feedback
73. rnel 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 g1obal menm interface that begins at address 0 must correspond to the memory master in bank1 from the OpenCL Memory Bank Divider Related Information e channels on page 2 10 e interfaces on page 2 11 e global mem on page 2 8 e OpenCL Kernel Interface on page 2 3 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 on page 2 7 The board element of the board spec xml file provides the version and the name of the accelerator board Altera Corporation AOCL Custom Platform Toolkit Reference Material C Send Feedback OCL007 15 0 0 2015 05 04 board 2 7 device on page 2 7 The device element of the board spec xml file provides the device model and the resources that the board design uses global mem on page 2 8 The g1obal mem and interface elements of the board spec xml file provides information on the memory interfaces that connect to the kernel host on page 2 10 The host element of the board spec xml file provides information on the
74. rporation AOCL Custom Platform Toolkit Reference Material C Send Feedback OCL007 15 0 0 2015 05 04 aocl_mmd_get_offline_info 2 17 HE HEME Deci Te 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 intellectual properties IPs 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 c1 menm objects and the requirement of explicit user function calls to synchronize the cache between the host processor and the FPGA Note Currently Altera 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 synchro nizes the cache between the host processor and the FPGA automatically Note Currently Altera does not support this level of SVM except for a subset of AOCL MMD SVM FIN
75. 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 Quartus II 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
76. s 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 lobal E latency omens An integer specifying the time in nanoseconds ns for the memory interface to respond to a request The latency is the round trip time from the kernel issuing the board system a memory read request to the memory data returning to the kernel For example the Altera DDR3 memory controller running at 200 MHz with clock crossing bridges has a latency of approxi mately 240 ns 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 Quartus II compilation registration and automigration Example eXtensible Markup Language XML code compile project top revision top qsys_file system qsys generic_kernel 1
77. t info returns when its requested info id argument is AOCL MMD MEMORY INTERFACE The interface argument is of type aocl mmd interface t andcan take one of the following values SS eS ERE ZEWE AOCL MMD KERNEL Control interface into the kernel interface AOCL MMD MEMORY Data interface to device memory AOCL MMD PLL Interface for reconfigurable phase locked loop PLL 6 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 aoci mmd write function is the write operation on a single interface Altera Corporation AOCL Custom Platform Toolkit Reference Material send Feedback OCL007 15 0 0 2015 05 04 aocl mmd copy 2 21 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 1 handle A positive int value representing the handle to the board obtained from the aocl mmd open call 2 op The operation object of type aoc1 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 3 1en The size of the data in byt
78. t requested info id size t param value size void param value size t param size ret Function Arguments l requested info i An enum value of type aocl mmd offline info t that indicates the offline device information returning to the caller Table 2 13 Possible Enum Values for the requested info id Argument EE CREE CON ERN AOCL MMD VERSION Version of memory mapped device MMD char layer AOCL_MMD_NUM_BOARDS Number of candidate boards int AOCL Custom Platform Toolkit Reference Material Altera Corporation send Feedback 2 16 aocl_mmd_get_offline_info OCL007 15 0 0 2015 05 04 ime ei a AOCL MMD BOARD NAMES Names of available boards char Attention Separate each board name by a semicolon delimiter 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 Altera SDK for int OpenCL AOCL 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 AOCL 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 utiliza tion if the aocl_mmd_yield function does not suspend the current thread Altera Co
79. te platform type Choose this value based on the value referenced in the Altera Reference Platform from which you derive your Custom Platform Valid values are none 55 net c5soc and a10 ref e include fixes Comma separated list of named fixes that you want to apply to the Custom Platform e exclude fixes Comma separated list of named fixes that you do not want to apply to the Custom Platform MMD API Descriptions The memory mapped device 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 Altera SDK for OpenCL AOCL Custom Platform Toolkit Include the file in the operating system specific implementations of the MMD layer aocdl mmd get offline info on page 2 15 The aoc1_ mmd get offline info function obtains offline information about the board specified in the requested info id argument aocl mmd get info on page 2 18 The aoci mmd get info function obtains information about the board specified in the requested info id argument aocl mmd open on page 2 19 The aoc1 mmd open function opens and initializes the specified device aocdl mmd close on page 2 19 The aoc1 mmd close function closes an opened device via its handle Altera Corporation AOCL Custom Platform Toolkit Reference Material C Send Feedba
80. 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 aoci mmd shared mem al11oc function allocates shared memory between the host and the FPGA The host accesses the shared memory via the pointer returned by aoc1 mmd shared mem alloc The FPGA accesses the shared memory via device ptr out Ifshared 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 1 handle A positive int value representing the handle to the board obtained from the aocl mmd open call 2 size The size of the shared memory that the function allocates Declare size with the type size t 3 device ptr out The argument that receives the pointer value the device uses to access shared memory The device ptr outisoftype 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
81. the board_env xml file test the file within your board installation directory to ensure that the Altera Offline Compiler AOC recognizes the board installation 1 Set the environment variable AOCL_BOARD_TOOLKIT_ROOT to point to the Custom Platform subdirectory in which your board_env xml file resides 2 At the command prompt invoke the aocl board xml test command to verify that the Altera SDK for OpenCL AOCL can locate the correct field values Using the board env xml file from the Stratix V Network Reference Platform s5 net as an example refer to the Creating the board env xml File section for Linux systems the AOCL generates an output similar to the one below board path board default board hw path board link flags board libs board util bin path to Custom Platform s5 net path to Custom Platform hardware s5 net L path to Custom Platform linux64 1lib lalterahalmmd laltera s5 net mmd path to Custom Platform linux64 libexec 3 Invoke the aoc list boards command to verify that the AOC can identify and report the board variants in the Custom Platform For example if your Custom Platform includes two FPGA boards the AOCL 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 AOC to generate a design for your board Related Information Creating the board env xml File on page 1 10 e Testing th
82. u should see the same number of bytes returned in the param_size_ret argument 4 param_value A void pointer to the variable that receives the returned information 5 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 aoc1 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_mmp_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 aoc1_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 memory mapped device MMD layer does not exit the application if an open call fails aocl mmd close The aoc1 mmd close funct
83. urces 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 Altera SDK for OpenCL Custom Platform Toolkit User Guide Altera Corporation GC Send Feedback OCL007 15 0 0 1 14 Creating the board_spec xml File 2015 05 04 5 For each global memory type specify the following information a Name of the memory type b The combined maximum global memory bandwidth You can calculate this bandwidth value from datasheets of your memories c The size of the data that the Altera Offline Compiler AOC interleaves across memory banks Note interleaved_bytes burst_size X width_bytes d 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_adar attribute with the base address of the ACL Mem Organization Control Qsys component mem_org_mode e 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 f Specify the parameters in the interface attribute to describe the characteristics of each memory interface 6 For the host element specify the parameters in the kernel config

Download Pdf Manuals

Related Search

Related Contents

Chillers Aermec ANK Technical Installation Manual  IPA Help Desk  Samsung MM-X8 Manual de Usuario  BEDIENUNGSANLEITUNG  Section No. Content/Service Operation  M100 M100 M100  Operation and Service Manual  1. Refer to User Manual for “Safety and Maintenance Notes”. 2  

Copyright © All rights reserved. Failed to retrieve file