Altera Opencl Getting Started

June 2013 Altera Corporation

OCL001-13.0 SP1.0

2013 Altera Corporation. All rights reserved. ALTERA, ARRIA, CYCLONE, ENPIRION, HARDCOPY, MAX, MEGACORE, NIOS, QUARTUS and STRATIX words and logos are trademarks of Altera Corporation and registered in the U.S. Patent and Trademark Office and in other countries. OpenCL and the OpenCL logo are trademarks of Apple Inc. used by permission of Khronos. * The Altera SDK for OpenCL is based on a published Khronos Specification, and is expected to pass the Khronos Conformance Testing Process.logos identified as trademarkswww.altera.com/common/legaccordance with Altera's standwithout notice. Altera assumesservice described herein except

101 Innovation DriveSan Jose, CA 95134www.altera.com

Altera SDK for OpenCLGetting Started Current conformance status can be found at www.khronos.org/conformance. All other words and or service marks are the property of their respective holders as described at al.html. Altera warrants performance of its semiconductor products to current specifications in ard warranty, but reserves the right to make changes to any products and services at any time no responsibility or liability arising out of the application or use of any information, product, or as expressly agreed to in writing by Altera. Altera customers are advised to obtain the latest version

Feedback Subscribe

ISO 9001:2008 RegisteredThe Altera SDK for OpenCL Getting Started Guide describes the procedures you use to install the Altera SDK for OpenCL version 13.0 SP1 and to compile an example OpenCL application with it.

OpenCL is an open standard for the programming of heterogeneous parallel devices. The Altera SDK for OpenCL allows you to build and run OpenCL code on supported boards with Altera field programmable gate arrays (FPGAs).

f For more information about the OpenCL Specification version 1.0, refer to OpenCL Reference Pages on the Khronos Group website. The SDK supports the Embedded Profile of the OpenCL Specification version 1.0.

PrerequisitesTo install a supported FPGA board, the host system must meet the following minimum requirements:

Operating SystemThe host system must be running a 64-bit operating system. Any binaries built must be 64-bit executables. The Altera SDK for OpenCL supports the following operating systems:

Microsoft 64-bit Windows 7

Red Hat Enterprise 64-bit Linux (RHEL) 5.6

c You must have administrator privileges on the host system to install the necessary packages and drivers.

The host machine motherboard must have at least one eight-lane PCI Express port (PCIe x8). If an eight-lane port is not available, you can use a sixteen-lane (PCIe x16) port.

Only one FPGA accelerator board may be installed in the host machine.

Software prerequisites for the installation of the SDK include the Quartus II software version 13.0 SP1, and a compiler infrastructure or development environment. The following are the version requirements of these prerequisites:

FPGA Design SoftwareThe Quartus II software version 13.0 SP1 must be installed in order to build an OpenCL kernel and program the FPGA with the Altera Offline Compiler Executable file (.aocx). Your Quartus II software subscription or license must include Quartus II Compilation and Programming support.

Device SupportYou must install the support software for Stratix V devices.

Installing an FPGA Board Board DriverYou must install a board driver to allow communication between host programs and hardware kernel programs.

C Compiler or Development EnvironmentTo build host executable code, Altera recommends the following compatible C compiler or software development environment:

For Windows systems, use Microsoft Visual Studio version 2010 Professional.

For Linux systems, use the C compiler included with GCC, the GNU Compiler Collection.

Installing an FPGA BoardTo install an FPGA board, follow the board manufacturers instructions.

1 If you have a BittWare S5-PCIe-HQ Altera Stratix V GSMD5 half-length PCIe board, you must also install the BittWare board development software, which you can download from the BittWare Developer Site of the BittWare website.

Downloading the SoftwareYou can download the following software from the Altera SDK for OpenCL Download Center of the Altera website:

Quartus II software version 13.0 SP1

Stratix V device support

Altera SDK for OpenCL version 13.0 SP1

c You must install the Quartus II software and the Stratix V device support before you install the Altera SDK for OpenCL.

f Refer to the Altera Software Installation and Licensing Manual for installation and licensing instructions for the Quartus II software.

c Installation of the Quartus II software sets the system-wide environment variable QUARTUS_ROOTDIR. It is very important that QUARTUS_ROOTDIR points to the 13.0 SP1 version of the software because the SDK depends on this environment variable to compile OpenCL kernels.

c You must add the following path to your PATH environment variable:

For Windows systems, the path is %QUARTUS_ROOTDIR%\bin64.

For Linux systems, the path is $QUARTUS_ROOTDIR/bin.Altera SDK for OpenCLGetting Started


Licensing Page 3LicensingWhen you purchase the Altera SDK for OpenCL software license, the license file supports the version of the SDK software you purchase, all previous versions, and all versions released within a year of the purchase date. You can use the version of the Altera SDK for OpenCL software you purchase indefinitely.

Supported Software SubscriptionsAltera offers the following types of software subscriptions for the Altera SDK for OpenCL software:

Fixed licensea stand-alone (node-locked, single-user) license tied to the network interface card (NIC) ID.

Floating licensea floating network (multiuser) license for users running the Altera SDK for OpenCL software on Windows PCs or Linux workstations. Floating licenses are not operating system-specific. You can purchase additional seats to add to your floating license after its original purchase.

1 Altera recommends that you run the Altera SDK for OpenCL software on a stand-alone machine.

If you use a fixed license, you can perform an automatic web license retrieval to allow the SDK software to retrieve the license file from the Altera website. See Obtaining a License File for more information.

If you have a valid license file, you can specify the location of your license file. See Setting Up the License File on page 7 for more information.

w If the software cannot detect a valid license file, you will receive a message similar to the one shown below when you run the Altera Offline Compiler (AOC):

Could not acquire OpenCL SDK license

aoc: The Altera SDK for OpenCL compiler front end (aocl-clang) is not available.

aoc: 1. Did you set ALTERAOCLSDKROOT environment variable to the absolute path of the directory where the Altera SDK for OpenCL is installed AND updated your path to include $ALTERAOCLSDKROOT/linux64/bin ?aoc: 2. Do you have a valid license for the Altera SDK for OpenCL?Altera SDK for OpenCLGetting Started


LicensingObtaining a License FileYou can obtain a license file (.dat), from the Self-Service Licensing Center of the Altera website with the information described in this section.

f For more information on the tasks you can perform with the Self-Service Licensing Center, refer to the Altera Software Installation and Licensing Manual.

You can obtain a license file for an existing, new, or renewed license. If you want to obtain a license file for a new or renewed license, you must first activate or renew the license using the procedure in Activating a License on page 7 or Renewing a License on page 6 respectively.

1. Log on to your myAltera account from the Altera website.

2. Access the Self-Service Licensing Center.

3. Click Create New License.

4. Expand a list of products, double-click to select one or more products from the Unlicensed Products table, and then click Next.

5. Select a computer to which you want to assign your license from the Available Computers table, and then click Next.

6. Click Confirm Selection to generate the license file.

Your license file is sent to the email address specified for your licensed user. If you have not specified an email address, your license file is sent to the email address in your myAltera account profile. Your software license type must match the license type of any license you want to assign your computer. Use the attached license file if you have a fixed license. If you have a floating license, you must edit the attached license file to update the , and .

1 If you do not receive an email from Altera within 12 hours of requesting a license, or if you do not know all the required information to complete the process, file a service request at the mySupport section of the Altera website.

To add computers to your myAltera account profile, refer to the Creating a Computer Profile section of the Altera Software Installation and Licensing Manual.Altera SDK for OpenCLGetting Started


Licensing Page 5Rehosting a LicenseYou can rehost or transfer a license from one computer to another. You can rehost each license up to three times within your maintenance period.



3. To rehost a license to an existing computer profile, perform the following steps:

a. In the Products and Users tab, locate the product you want to rehost.

b. In the Primary Computer Name column, click the Assign Computer icon.

c. In the Change Primary Computer page, select an existing computer, and click Change Computer.

4. To rehost a license to a new computer, perform the following steps:

a. In the Products and Users tab, locate the product you want to rehost.

b. In the Primary Computer Name column, click the Assign Computer icon.

c. In the Change Primary Computer page, click Add New Computer to select a computer to which you want to rehost your license, and then click Change Computer.

5. Click Get License.

Your license file is sent to the email address specified for your myAltera account profile. Your software license type must match the license type of any license you want to assign your computer.

If you do not have any computers listed in the My Computers table, you can add computers. Refer to the Creating a Computer Profile section of the Altera Software Installation and Licensing Manual for instructions.Altera SDK for OpenCLGetting Started


LicensingAdding Floating SeatsYou can add floating seats to an existing floating license to increase the number of users available. Adding more seats to an existing floating license might affect its maintenance expiration date.



3. In the Add Seat Products tab, click Add Seats to access the Add Seats page.

4. On the Add Seats page, select a product to which you want to add additional seats, and click Next.

5. Select the product with the seats you want to apply and click Next.

6. Type the number of additional seats you want to add to your floating license in the Number of Seats to Add box.

When you add additional seats to an existing floating license, the new maintenance subscription term of the floating license is calculated by adding the total number of maintenance months for the existing and new seats, and then dividing by the total number of seats. Any partial number is rounded up to the nearest whole number.

For example, if you have an existing floating license with ten seats that expires in five months and you purchase two additional seats, your updated floating license maintenance subscription will expire in seven months for all twelve seats.

Renewing a LicenseYou can renew an existing license with the Self-Service Licensing Center. You must first purchase your license renewal, for example, from the Buy Design Software page of the Altera website, before applying a renewal.



3. In the Renewal Products tab, click Apply Renewals to access the Apply Renewals page.

4. Select the product you want to renew, and click Next.

5. Select the renewal product you want to apply, and click Next.Altera SDK for OpenCLGetting Started


Licensing Page 7Activating a LicenseYou can activate a new license with the Self-Service Licensing Center. You must first purchase your new license, for example, from the Buy Design Software page of the Altera website, before activating the new license.



3. If the product you want to license is not listed, click Find it with Your License Activation Code.

4. Type your license activation code or Altera SDK for OpenCL software serial number in the Find/Activate Products page, and click Search.

5. Select the products that you want to activate in the Activate Products table. Click Activate Selected Products.

Setting Up the License FileThere are two ways to set up your license files for the Altera SDK for OpenCL software:

To append your license files to existing license files, perform the following the steps:

1. Refer to Setting Up a Fixed Licenseor Setting Up a Floating Network Licensefor set up instructions.

2. Refer to Specifying Multiple License Files with the LM_LICENSE_FILE Environment Variable for instructions on how to concatenate your license files.

To set up your license files by modifying the .dat file for your specific licensing options, perform the following steps:

1. Refer to License File Conditionsfor guidelines on how to modify your .dat file.

2. Refer to Setting Up a Fixed Licenseor Setting Up a Floating Network Licensefor set up instructions.Altera SDK for OpenCLGetting Started


LicensingLicense File ConditionsIf you modify the .dat file, where is the name of your license file, ensure that the following conditions are met:

The text editor does not append .txt or any other file extension to the file name, for example .dat.txt.

A carriage return (new line) is present at the end of the last FEATURE line.

Any FEATURE line that wraps to a second or third line contains a backslash (\) at the end of each line to indicate that it continues. However; there is no backslash (\) at the end of the lines if the VENDOR_STRING line wraps to multiple lines. The backslash should only be added outside the line with double quotation marks (").

Ensure a space exists between the closing double quotation mark(") and backslash (\) at the end of the VENDOR_STRING line.

No hidden control characters exist in the license file.

If you open the license file with any software other than a plain text editor, the software might add hidden characters. For example, WYSIWYG editors such as Microsoft Excel, Word, or WordPad, might insert special control characters such as a tab or carriage return. If special control characters are pasted into another plain text document, the license file can be corrupted by characters that might not be visible in a plain text editor.

If you edit the license file in one operating system, copy the license file in another operating system, and then copy the license file to the Windows operating system, the second operating system might insert unwanted control characters into the license file if you do not convert the file correctly.

Setting Up a Fixed LicenseTo set up a fixed license file, perform the following steps:

1. Make a backup copy of any existing .dat file for reference.

2. Save the new .dat file on your local hard drive. You should save and use the .dat file attached to the licensing email you received from Altera.

3. After you save the .dat file on your local hard drive, proceed to Specifying the License File with the LM_LICENSE_FILE Environment Variableto specify your license. Altera SDK for OpenCLGetting Started


Licensing Page 9Setting Up a Floating Network LicenseThe procedure below describes how to set up a floating license. For instructions on how to set up a floating license server (typically performed by a system administrator), refer to Setting Up Floating Network Licenses on the License Server on page 10.

To set up a floating license, perform the following steps:

1. Obtain the port number and host name from the network or system administrator. This information can also be found in the license file line beginning with SERVER.

SERVER

The license location for the user is @. If a port is not listed in the .dat file, specify @.

2. After you save the .dat file on your local hard drive, proceed to Specifying the License File with the LM_LICENSE_FILE Environment Variableto specify your license.

Specifying the License File with the LM_LICENSE_FILE Environment Variable

Altera recommends specifying the Altera SDK for OpenCL software license location with the LM_LICENSE_FILE environment variable.

Setting the LM_LICENSE_FILE Environment Variable in the Windows Control PanelYou can specify the location of your license file outside the Altera SDK for OpenCL software for Windows by setting system variables in the Windows System Control Panel.

Setting the LM_LICENSE_FILE Environment Variable in the Linux Workstation C Shell Resource File (.cshrc)To specify the license file on each client (user) workstation, make sure that you update the LM_LICENSE_FILE environment variable that is specified in the .cshrc file located in each users home directory.

Specifying Multiple License Files with the LM_LICENSE_FILE Environment VariableSpecify multiple license files with the LM_LICENSE_FILE environment variable by separating the license files in the following manner:

For Windows systems, append multiple license files by separating them using semicolons. For example:

LM_LICENSE_FILE=license_A.dat;license_B.dat; ... and so on

For Linux systems, append multiple license files by separating them using colons. For example:

LM_LICENSE_FILE=license_A.dat:license_B.dat: ... and so onAltera SDK for OpenCLGetting Started


Installing the Altera SDK for OpenCLSetting Up Floating Network Licenses on the License ServerSetting up a floating network license server is typically performed by a system administrator. You can set up a floating network license on a Windows or Linux license server using the FLEXlm license manager software provided by Altera. Refer to the Setting Up Floating Network Licenses on the License Server and Modifying the Network License File sections of the Altera Software Installation and Licensing Manual for more information. To upgrade or set up a license manager server, refer to Upgrading or Setting Up a License Manager Server section of the Altera Software Installation and Licensing Manual.

Transferring a License FileIf you want to transfer your license file to another computer, you can rehost your license. Refer to the procedure inRehosting a License on page 5.

Installing the Altera SDK for OpenCLThis section describes the installation of the Altera SDK for OpenCL on your host system. The SDK currently supports the Windows and Linux operating systems, with a separate installation package for each.

To install the Altera SDK for OpenCL on Windows systems, refer to Installing the SDK on Windows for installation instructions.

To install the Altera SDK for OpenCL on Linux systems, refer to Installing the SDK on Linux on page 13 for installation instructions.

Installing the SDK on WindowsTo install the SDK on Windows, you must install it in a folder that you own (that is, a folder that is not a system folder). You must also have administrator privileges.

The SDK installation package should be extracted to an empty folder, and the path must not contain any spaces. The installer extracts the SDK to a location of your choice. The default location is C:\ALTERA\\AOCL.

After you extract the SDK to the target location, you must verify that the environment variables listed in Table 1 are set.

Table 1. Environment Variables Set during SDK Installation on Windows

Environment Variable Path Added

ALTERAOCLSDKROOT

where is the path to the folder containing the extracted installation package

PATH %QUARTUS_ROOTDIR%\bin64PATH %ALTERAOCLSDKROOT%\windows64\binLM_LICENSE_FILE all the necessary .dat filesAltera SDK for OpenCLGetting Started


Installing the Altera SDK for OpenCL Page 11Verifying SDK Installation on WindowsTo verify that the SDK installation was successful, perform the following steps:

1. Open a command prompt (cmd.exe).

2. Type where aoc. If the path to the aoc.bat file is not returned, installation was not successful.

If installation was not successful, reinstall the SDK.

Installing the Board Driver on WindowsThe board driver implements the interface between the host program and the FPGA accelerator board. On Windows systems, the Altera SDK for OpenCL uses the Jungo WinDriver board driver software. You need administrative privileges to install the board driver.

Installing the Board Driver for the Nallatech PCIe-385N FPGA Computing Card

For a Nallatech PCIe-385N FPGA computing card, install the board driver by invoking the aocl install command.

w If you have a BittWare board and you invoke the aocl install command to install the board driver, you might receive the following message:

aocl install--------------------------------------------------------------------

No board installation routine supplied.Please consult your board manufacturer's documentation or supportteam for information on how to properly install your board.--------------------------------------------------------------------

Installing the Board Driver for the BittWare S5-PCIe-HQ Altera Stratix V GSMD5 Half-Length PCIe Board

For a BittWare board, install the board driver by performing the following steps:

1. Set the AOCL_BOARD_PACKAGE_ROOT environment variable to %ALTERAOCLSDKROOT%\board\s5pciehq

2. Run install.bat, located at %ALTERAOCLSDKROOT%\windows64\driverAltera SDK for OpenCLGetting Started


Installing the Altera SDK for OpenCLVerifying the Board Driver Installation on WindowsBefore you program your FPGA via the PCIe bus, you can verify the successful installation of the board driver in the Windows Device Manager. A successfully installed Jungo WinDriver for a Nallatech board appears in the Windows Device Manager as shown in Figure 1. Ensure that the name of the FPGA board also appears in the Windows Device Manager under Accelerators.

A successfully installed Jungo WinDriver for a BittWare board appears in the Windows Device Manager as shown in Figure 2.

w If your system runs on Windows 7, you might receive the following message during board driver installation:

difx_install_preinstall_inf: err a, last event 0, last error 0. ERROR_BAD_ENVIRONMENT

If you receive the above message and the Jungo WinDriver does not appear in the Windows Device Manager, you must reinstall the board driver by inserting the -compat option to the wdreg commands in install.bat, as shown below:

wdreg -compat -inf windrvr6.inf install

wdreg -compat -inf acl_boards.inf install

If you have a Nallatech board, the install.bat script is located in the %ALTERAOCLSDKROOT%\board\pcie385n\windows64\driver folder.

If you have a BittWare board, the install.bat script is located in the %ALTERAOCLSDKROOT%\windows64\driver folder.

Figure 1. A Correct Windows Device Manager after Complete Board Driver Installation for a Nallatech Board

Figure 2. A Correct Windows Device Manager after Complete Board Driver Installation for a BittWare BoardAltera SDK for OpenCLGetting Started


Installing the Altera SDK for OpenCL Page 13Uninstalling the SDK on WindowsTo uninstall the SDK, run the Uninstall Altera SDK for OpenCL executable located in the Altera SDK for OpenCL folder. Additionally, to complete the uninstallation, ensure that the environment variables or paths listed in Table 2 are removed.

Installing the SDK on LinuxTo install the SDK on Linux, you must install it in a directory that you own (that is, a directory that is not a system directory). You must also have sudo or root privileges.

Extract the installation package to an empty directory. The path must not contain any spaces. For example, /usr/altera//AOCL/.

After you extract the SDK to the target location, you must verify that the environment variables listed in Table 3 are set.

w If you install the SDK on a system that does not contain any .cshrc or Bash Resource file (.bashrc) in your directory, you must set the ALTERAOCLSDKROOT and PATH environment variables manually. Alternatively, you may create the .cshrc and .bashrc files, and then append the environment variables to them. To ensure that the updates take effect, restart your terminal after you set the environment variables.

Table 2. Environment Variables or Paths to be Removed upon SDK Uninstallation on Windows

Environment Variable Item to Remove

PATH %QUARTUS_ROOTDIR%\bin64PATH %ALTERAOCLSDKROOT%\windows64\binALTERAOCLSDKROOT Remove the ALTERAOCLSDKROOT variable

Table 3. Environment Variables Set during SDK Installation on Linux

Environment Variable Path Added

ALTERAOCLSDKROOT

where is the path to the directory containing the extracted installation package

PATH $QUARTUS_ROOTDIR/binPATH $ALTERAOCLSDKROOT/linux64/binLD_LIBRARY_PATH $ALTERAOCLSDKROOT/linux64/libLM_LICENSE_FILE all the necessary .dat filesAltera SDK for OpenCLGetting Started


Installing the Altera SDK for OpenCLInstalling the Board Driver on LinuxThe board driver for a Linux operating system interfaces between the board and the operating system.

Installing the Board Driver for the Nallatech PCIe-385N FPGA Computing Card

For a Nallatech PCIe-385N FPGA computing card, install the board driver by invoking the aocl install command.

w If you have a BittWare board and you invoke the aocl install command to install the board driver, you might receive the following message:

aocl install--------------------------------------------------------------------

No board installation routine supplied.Please consult your board manufacturer's documentation or supportteam for information on how to properly install your board.--------------------------------------------------------------------

Installing the Board Driver for the BittWare S5-PCIe-HQ Altera Stratix V GSMD5 Half-Length PCIe Board

As is common with Linux software development, you must build and install the board driver for a BittWare board with the GNU Build Environment commands. To build and install the board driver, you must first set the environment variable AOCL_BOARD_PACKAGE_ROOT to $ALTERAOCLSDKROOT/board/s5pciehq.

1 You must use the same version of gcc to build the Linux kernel and the board driver. You must install the kernel source code for the specific kernel running on your machine.

1 Altera strongly recommends that you build and install the driver in systems that operate on RHEL 5.6.

To build the driver, compile the driver as a normal user by typing sh make_all.sh. You can access the driver source at $ALTERAOCLSDKROOT/linux64/driver/. The following output appears after a successful compilation:

Using kernel source files from /usr/src/kernels/2.6.18-238.el5-x86_64make: Entering directory `/usr/src/kernels/2.6.18-238.el5-x86_64'

Building modules, stage 2.Modpost

make: Leaving directory `/usr/src/kernels/2.6.18-238.el5-x86_64'

Load the compiled driver by typing sudo sh ./aclpci_load.

1 You must reload the driver after you reboot your system.

Test the driver by typing ./user. If the driver and board work correctly, the system responds with several lines of output that end with Done testing!.

To unload the compiled driver, type sudo sh ./aclpci_unload.

1 You can load and unload the driver as necessary. You must have sudo or superuser privileges to load and unload the driver on the host system.Altera SDK for OpenCLGetting Started


Configuring and Running the Moving Average Example Page 15f For more information on the board driver installation process, refer to the README.txt file located at $ALTERAOCLSDKROOT/linux64/driver.

Verifying the Board Driver Installation on LinuxYou can verify that the board driver is loaded by typing at the command prompt:

lspci | grep Altera Upon successful installation of the driver, you should see an output similar to the ones below:

For Nallatech board, the output is

04:00.0 Unassigned class [ff00]: Altera Corporation Device ab00 (rev 01)

For BittWare board, the output is

04:00.0 Unassigned class [ff00]: Altera Corporation Device e385 (rev 01)

If you do not see this output, there might be a problem with the board driver installation, and you might need to reinstall the driver.

Uninstalling the SDK on LinuxTo uninstall the SDK, run the ./uninstall program located in the INSTALL_DIRECTORY/AOCL directory. Additionally, to complete the uninstallation, you should remove the environment variables or paths listed in Table 4.

Configuring and Running the Moving Average ExampleThe following sections describe the set up procedure, the steps to building both the host-side code and the board-side code, and finally program execution of an example OpenCL application called moving_average on a host system with an attached FPGA.

To configure and run the moving_average example on Windows, refer to Configuring and Running the Moving Average Example on Windows for details.

To configure and run the moving_average example on Linux, refer to Configuring and Running the Moving Average Example on Linux on page 21 for details.

Table 4. Environment Variables or Paths to be Removed upon SDK Uninstallation on Linux

Environment Variable Item to Remove

PATH $QUARTUS_ROOTDIR/binPATH $ALTERAOCLSDKROOT/linux64/binALTERAOCLSDKROOT Remove the ALTERAOCLSDKROOT variable

LD_LIBRARY_PATH $ALTERAOCLSDKROOT/linux64/libAltera SDK for OpenCLGetting Started


Configuring and Running the Moving Average ExampleConfiguring and Running the Moving Average Example on Windows

PrerequisitesBefore you configure and run the moving_average example, you must complete the following hardware and software setup:

Install the Quartus II software and the Stratix V device support. You can download these software from the Altera SDK for OpenCL Download Center.

Install the FPGA board. Refer to Installing an FPGA Board on page 2 for installation instructions.

Install the SDK. Refer to Installing the SDK on Windows on page 10 for instructions.

Install the board driver. Refer to Installing the Board Driver on Windows on page 11 and Verifying the Board Driver Installation on Windows on page 12 for more information.

1 You must develop your code in Microsoft Visual Studio 2010 Professional because the SDK is compatible with 64-bit host binaries only.

Setting Up the Moving Average Example on WindowsContents of the moving_average example are located in the %ALTERAOCLSDKROOT%\designs\ moving_average\ moving_average_ folder. Extract the moving_average example to a location to which you have write access. The extracted files are shown in Figure 3.

Figure 3. Contents of the Moving Average ExampleAltera SDK for OpenCLGetting Started


Configuring and Running the Moving Average Example Page 17Compiling the OpenCL Kernel and Generating the Hardware Program on WindowsThe moving_average.cl file within the moving_average_ folder contains the OpenCL kernel source code. Perform the following steps to invoke the AOC on the kernel using the aoc command:

1. Select your target FPGA board. To list all FPGA boards available with the SDK, type aoc --list-boards.

c Ensure that you set the environment variable AOCL_BOARD_PACKAGE_ROOT to %ALTERAOCLSDKROOT%\board\.

2. At a command prompt, navigate to your target boards subfolder of the moving_average design (that is, %ALTERAOCLSDKROOT%\designs\moving_average\moving_average_).

3. To compile the kernel for your target FPGA board, typeaoc --board moving_average.cl. This command performs the following tasks:

Generates the Quartus II design project files from the OpenCL source code

Checks for initial syntax errors

Performs basic optimizations

Creates the Altera Offline Compiler Object file (.aoco)

Creates the .aocx hardware configuration file

1 The .aocx file might take hours to build, depending on the complexity of the kernel. The command prompt will appear after the hardware configuration file is created.

c Altera recommends that you perform this hardware configuration step on a computer that is equipped with at least 24 gigabytes (GB) of RAM.

At this point, you have built the hardware image that can be loaded onto the FPGA. The section Programming FPGA Hardware on Windows on page 19 describes the procedure for loading the hardware image. But first you can build your OpenCL host application.Altera SDK for OpenCLGetting Started


Configuring and Running the Moving Average ExampleBuilding the Host Application on WindowsThe host.sln file within the moving_average_ folder contains the host solution. Open this file in Visual Studio. After you open the host.sln file, you can build the host side code in main.cpp. Perform the following steps to build the host application:

1. Open the solution in Visual Studio, as shown in Figure 4.

2. Verify that the build configuration is correct. The default build configuration is Debug, but you can use Release. You must select the x64 option as the solution platform.

3. Build the solution with the Build->Build Solution menu option or by pressing F7.

4. Verify that the solution built correctly. An output ending with a message similar to the one shown below notifies you of a successful build:

1> Build succeeded.1>1> Time Elapsed 00:00:03:29========== Build: 1 succeeded, 0 failed, 0 up-to-date, 0 skipped ==========

1 You can safely ignore the LNK4009: PDB 'vc90.pdb' was not found with warnings because they have no affect on the build. The compiler might issue this type of warning messages if you built your Windows libraries using a previous version of Microsoft Visual Studio.

Figure 4. Opening host.sln in Visual StudioAltera SDK for OpenCLGetting Started


Configuring and Running the Moving Average Example Page 19Programming FPGA Hardware on WindowsThe FPGA boards supported by the Altera SDK for OpenCL version 13.0 SP1 are preprogrammed with a default hardware configuration file that includes PCIe interface. You can run aocl diagnostic to verify the functionality of your FPGA board.

c Prior to invoking the aocl diagnostic command, ensure that you have set the AOCL_BOARD_PACKAGE_ROOT environment variable to the board package that corresponds to your FPGA board.

Verifying the Functionality of the Nallatech Board

When you run aocl diagnostic, the AOC generates one of the following outputs:

If the output of the diagnostic test is DIAGNOSTIC_PASSED, proceed to Running the Host Application on Windows.

If the output of the diagnostic test is DIAGNOSTIC_FAILED, perform the tasks, listed below, that correspond to the cause of the failure:

If your FPGA board is not installed properly, refer to Installing an FPGA Board on page 2 for more information.

If the board driver is not installed properly, refer to Installing the Board Driver for the Nallatech PCIe-385N FPGA Computing Card on page 11 for installation instructions.

If your FPGA board is not preprogrammed to configure the PCIe device, or if you have an incompatible image stored in the flash memory, refer to Programming the Flash Memory of a Nallatech Board on page 26 for more information.

Verifying the Functionality of the BittWare Board

If you have a BittWare board, you might receive the following message when you invoke the aocl diagnostic command:

aocl diagnostic--------------------------------------------------------------------

No board diagnostic routine supplied.Please consult your board manufacturer's documentation or supportteam for information on how to debug board installation problems.--------------------------------------------------------------------Altera SDK for OpenCLGetting Started


Configuring and Running the Moving Average ExampleTo verify the functionality of your BittWare board, perform the following tasks:

To verify the successful installation of the board driver, refer to Verifying the Board Driver Installation on Windows on page 12 for more information. To reinstall the board driver, refer to Installing the Board Driver for the BittWare S5-PCIe-HQ Altera Stratix V GSMD5 Half-Length PCIe Board on page 11 for instructions.

To determine if your BittWare board is installed properly, verify that the board is registered by your host machine by performing the following tasks:

1. Open the Windows Device Manager.

2. Verify that your FPGA board is listed under Accelerators or Unknown PCIe Device.

3. Hover your mouse over the device name and then select Properties from the right-click menu to open the Properties dialog box.

4. In the Details tab, click Hardware Ids from the Property pull-down menu. The hardware ID is displayed in the Value pane.

To identify the device and vendor IDs, consider the following example hardware ID:

PCI\VEN_1172&DEV_AB00&SUBSYS_00041172&REV_01

This hardware ID indicates that the vendor ID is VEN_1172 and the device ID is DEV_AB00,

where:

DEV_AB00 is the device ID for the Nallatech board

DEV_E385 is the device ID for the BittWare board

To reinstall the FPGA board, refer to Installing an FPGA Board on page 2 for instructions.

If your FPGA board is not preprogrammed to configure the PCIe device, or if you have an incompatible image stored in the flash memory, refer to Programming the Flash Memory of a BittWare Board on page 27 for more information.

Running the Host Application on WindowsOnce you have loaded the hardware program onto the FPGA and built the host application, you can run the application. To run the host application, perform the following steps:

1. At a command prompt, navigate to the folder that contains the host executable. If you built a debug version of the solution, this folder is moving_average\host\x64\Debug. If you built a release version of the solution, this folder is moving_average\host\x64\Release.

2. Type host.exe. This command runs the host executable, which in turn executes the kernel code on the FPGA.Altera SDK for OpenCLGetting Started


Configuring and Running the Moving Average Example Page 21Example 1 shows the output of the host application.

Configuring and Running the Moving Average Example on Linux

PrerequisitesBefore you configure and run the moving_average example, you must complete the following hardware and software setup:

Install the Quartus II software and the Stratix V device support. You can download these software from the Altera SDK for OpenCL Download Center.

Install the FPGA board. Refer to Installing an FPGA Board on page 2 for installation instructions.

Install the SDK. Refer to Installing the SDK on Linux on page 13 for instructions.

Install the board driver. Refer to Installing the Board Driver on Linux and Verifying the Board Driver Installation on Linux on page 15 for more information.

1 GNU development tools such as gcc and make are required to build the application under Linux.

Setting Up the Moving Average Example on LinuxContents of the moving_average example are located in the $ALTERAOCLSDKROOT/designs/moving_average/ moving_average_ directory. Extract the moving_average example to a location to which you have write access. The moving_average_ directory contains files for building the host application, a moving_average.cl file and a moving_average.h file.

Example 1. Successful Execution of the Host Application

Moving average filter example-----------------------------

Populating input data and clearing output data

Running moving average filter across data using the FPGA

Running moving average filter across data using the host CPU

Validating the results from the FPGA and host CPUThe results from the FPGA and host CPU match

Freeing resources and exiting...Altera SDK for OpenCLGetting Started


Configuring and Running the Moving Average ExampleCompiling the OpenCL Kernel and Generating the Hardware Program on LinuxThe moving_average.cl file within the moving_average_ directory contains the OpenCL kernel source code. Perform the following steps to invoke the AOC on the kernel using the aoc command:

1. Select your target FPGA board. To list all FPGA boards available with the SDK, type aoc --list-boards.

c Ensure that you set the environment variable AOCL_BOARD_PACKAGE_ROOT to $ALTERAOCLSDKROOT/board/.

2. At a command prompt, navigate to your target boards subdirectory of the moving_average design (that is, $ALTERAOCLSDKROOT/designs/moving_average/moving_average_).

3. To compile the kernel for your target FPGA board, typeaoc --board moving_average.cl. This command performs the following tasks:

Generates the Quartus II design project files from the OpenCL source code

Checks for initial syntax errors

Performs basic optimizations

Creates the Altera Offline Compiler Object file (.aoco)

Creates the .aocx hardware configuration file

1 The .aocx file might take hours to build, depending on the complexity of the kernel. The command prompt will appear after the hardware configuration file is created.

c Altera recommends that you perform this hardware configuration step on a computer that is equipped with at least 24 gigabytes (GB) of RAM.

At this point, you have built the hardware image that can be loaded onto the FPGA. The section Programming FPGA Hardware on Linux on page 23 describes the procedure for loading the hardware image. But first you can build your OpenCL host application.

Building the Host Application on LinuxTo build the host executable in Linux, navigate to the moving_average_ directory and then type $ make -f Makefile.linux. Altera SDK for OpenCLGetting Started


Configuring and Running the Moving Average Example Page 23Programming FPGA Hardware on LinuxThe FPGA boards supported by the Altera SDK for OpenCL version 13.0 SP1 are preprogrammed with a default hardware configuration file that includes PCIe interface. You can run aocl diagnostic to verify the functionality of your FPGA board.

c Prior to invoking the aocl diagnostic command, ensure that you have set the AOCL_BOARD_PACKAGE_ROOT environment variable to the board package that corresponds to your FPGA board.

Verifying the Functionality of the Nallatech Board

When you run aocl diagnostic, the AOC generates one of the following outputs:

If the output of the diagnostic test is DIAGNOSTIC_PASSED, proceed to Running the Host Application on Linux.

If the output of the diagnostic test is DIAGNOSTIC_FAILED, perform the tasks, listed below, that correspond to the cause of the failure:

If your FPGA board is not installed properly, refer to Installing an FPGA Board on page 2 for more information.

If the board driver is not installed properly, refer to Installing the Board Driver for the Nallatech PCIe-385N FPGA Computing Card on page 14 for installation instructions.

If your FPGA board is not preprogrammed to configure the PCIe device, or if you have an incompatible image stored in the flash memory, refer to Programming the Flash Memory of a Nallatech Board on page 26 for more information.

Verifying the Functionality of the BittWare Board

If you have a BittWare board, you might receive the following message when you invoke the aocl diagnostic command:

aocl diagnostic--------------------------------------------------------------------

No board diagnostic routine supplied.Please consult your board manufacturer's documentation or supportteam for information on how to debug board installation problems.--------------------------------------------------------------------Altera SDK for OpenCLGetting Started


Configuring and Running the Moving Average ExampleTo verify the functionality of your BittWare board, perform the following tasks:

To verify the successful installation of the board driver, refer to Verifying the Board Driver Installation on Linux on page 15 for more information. To reinstall the driver, refer to Installing the Board Driver for the BittWare S5-PCIe-HQ Altera Stratix V GSMD5 Half-Length PCIe Board on page 14 for instructions.

To determine if your BittWare board is installed properly, verify that the board is registered by your host machine by invoking the lspci command. The output provides information on the device and vendor IDs:

The device ID for the Nallatech board is 0xab00.

The device ID for the BittWare board is 0xe385.

The vendor ID is 0x1172.

To reinstall the FPGA board, refer to Installing an FPGA Board on page 2 for instructions.

If your FPGA board is not preprogrammed to configure the PCIe device, or if you have an incompatible image stored in the flash memory, refer to Programming the Flash Memory of a BittWare Board on page 27 for more information.

Running the Host Application on LinuxAfter you have loaded the hardware program onto the FPGA and built the host application, you can run the application. To run the host application, perform the following steps:

1. At a command prompt, navigate to the directory that contains the host executable. If you built a debug version of the solution, this directory is moving_average/host/.

2. Type host.exe. This command runs the host executable, which in turn executes the kernel code on the FPGA.

The host application generates an output similar to the one shown in Example 2.

Example 2. Successful Execution of the Host Application

Moving average filter example-----------------------------

Populating input data and clearing output data

Running moving average filter across data using the FPGA

Running moving average filter across data using the host CPU

Validating the results from the FPGA and host CPUThe results from the FPGA and host CPU match

Freeing resources and exiting...Altera SDK for OpenCLGetting Started


Conclusion Page 25ConclusionYou have successfully performed all of the steps necessary to execute an OpenCL application on a supported FPGA-based accelerator board. You can follow these same steps to execute a different OpenCL code example or application. For a more in-depth explanation of how to perform these steps for a generic program, refer to the Altera SDK for OpenCL Programming Guide. The programming guide also serves as a general guide to writing OpenCL applications with the SDK. The Altera SDK for OpenCL Optimization Guide helps you master optimization techniques for SDK applications. Both guides are available on the Altera SDK for OpenCL documentation page of the Altera website.

Appendix A

Installing the USB-Blaster Driver on Windows for Flash ProgrammingIf your FPGA board is not preprogrammed to configure the PCIe device inside the FPGA, you must install a USB-Blaster driver to load a hardware configuration file into the flash memory of the FPGA. This hardware configuration file programs the FPGA when you power up your system, and it configures the PCIe device in the process.

f For more information on flash programming, refer to Programming the Flash Memory of an FPGA.

1 You need administrative privileges to install the USB driver.

To install the USB driver, perform the following steps:

1. Ensure that the board has been physically installed, as described Installing an FPGA Board on page 2, and the power adaptor to the board is plugged in.

2. Connect the USB cable from the FPGA board to the USB port on the host computer, or to the computer running the Quartus II software.

On your host computer, the Windows Found New Hardware Wizard appears, prompting you to install the USB driver. To continue the driver installation process, perform the following steps:

3. Select Install from a list or specific location (Advanced), and then click Next.

4. Under Search for the best driver in these locations, select Include this location in the search, and then click Next.

5. Browse to %QUARTUS_ROOTDIR%\drivers\, and then click OK.

6. In the Hardware Installation dialog box, click Continue Anyway.

7. Click Finish.

You have completed the installation of the Altera USB-Blaster driver, enabling the FPGA to be programmed via the USB interface.Altera SDK for OpenCLGetting Started


Appendix AProgramming the Flash Memory of an FPGABy default, you configure an FPGA using the image (that is, the hardware configuration file) stored in the flash memory of the device. When there is no power, the FPGA retains the hardware configuration file stored in the flash memory. When you power up the system, the FPGA circuitry is configured based on the hardware configuration file stored in flash memory. Therefore, it is imperative that an OpenCL-compatible default image is loaded into the flash memory to ensure proper configuration of the FPGA.

The reason for programming the flash memory of your FPGA is that FPGA OpenCL kernels communicate with the host program via a PCIe device in the FPGA. The FPGA boards supported by the Altera SDK for OpenCL version 13.0 SP1 are preprogrammed with a default hardware configuration file that configures the PCIe device inside the FPGA. If the PCIe device in your FPGA board is not configured properly, you must program the flash memory of the FPGA with a OpenCL-compatible image. After you power down and then power up your system, this default image will configure the FPGA and instantiate the PCIe device.

c When you load the hardware configuration file into the flash memory of the FPGA, it is imperative to not prematurely power down the system or attempt to launch any host code that calls OpenCL kernels or might otherwise communicate with the FPGA board.

Programming the Flash Memory of a Nallatech BoardTo load your hardware configuration file into the flash memory of the Nallatech board, perform the following steps:

1. Ensure that the USB-Blaster driver is installed successfully so that you can load your hardware configuration file into the flash memory.

For Windows systems, if your USB-Blaster driver is not installed properly, refer to Installing the USB-Blaster Driver on Windows for Flash Programming on page 25 for installation instructions.

For Linux systems, it is unnecessary to install the USB-Blaster driver because RHEL 5.6 host systems natively include the USB driver.

2. Ensure that you have set the AOCL_BOARD_PACKAGE_ROOT environment variable to the board package that corresponds to your FPGA board.

3. Type aocl flash moving_average.aocx to load the hardware configuration file into the flash memory.

4. Power down your host machine and then power it up again.

w If you do not power down your host machine after you program the flash memory, you might not have a valid image loaded onto your FPGA.Altera SDK for OpenCLGetting Started


Appendix A Page 27Programming the Flash Memory of a BittWare BoardIf you have a BittWare board, you might receive the following message when you invoke the aocl flash command:

aocl flash--------------------------------------------------------------------

No board flash routine supplied.Please consult your board manufacturer's documentation or supportteam for information on how to modify the default FPGA image.--------------------------------------------------------------------

If you receive this message, verify that you have installed your FPGA board and the board driver properly.

For Windows systems, refer to Verifying the Functionality of the BittWare Board on page 19 for more information.

For Linux systems, refer to Verifying the Functionality of the BittWare Board on page 23 for more information.

If you continue to receive this warning message after your have reinstalled your board and board driver, contact your board vendor for support to program the flash memory and instantiate the PCIe device in your BittWare board. Refer to the BittWare Developer Site of the BittWare website for more information.Altera SDK for OpenCLGetting Started


Document Revision HistoryDocument Revision HistoryTable 5 lists the revision history for this document.

Table 5. Document Revision History

Date Version Changes

June 201313.0

SP1.0

Updated requisite Quartus II and Altera SDK for OpenCL software versions from 13.0 to 13.0 SP1.

Inserted the figure A Correct Windows Device Manager After Complete Board Driver Installation for a BittWare Board.

Updated the vendor and device IDs in the Verifying the Functionality of the BittWare Board section for Windows.

Updated the SDK installation instructions for Linux systems that do not contain a .cshrc or a .bashrc file in the directory.

Updated path to the Altera SDK for OpenCL design examples.

Updated the figure Contents of the Moving Average Example.

Updated flash programming instructions.

May 2013 13.0.1

Renamed the OpenCL_SDK folder or directory to AOCL.

Inserted warning about the SDK installation dependency on .cshrc and .bashrc files for Linux systems.

Included reminder to BittWare board users about installing the BittWare development software.

Inserted warning about potential Jungo WinDriver installation failure for systems running on Windows 7. Included reinstallation instructions.

Inserted warnings about error messages displayed for aocl commands that have not been implemented for the BittWare FPGA board.

Inserted caution message about setting the AOCL_BOARD_PACKAGE_ROOT environment variable.

Updated board driver installation procedures for Windows and Linux systems.

Modified the path to the default location of the Altera SDK for OpenCL for Windows and Linux systems.

Modified the path name added to the PATH environment variable when installing the SDK on Linux systems. The path name should be $QUARTUS_ROOTDIR/bin instead of $QUARTUS_ROOTDIR/bin64.

May 2013 13.0.0

Updated installation and compilation procedures.

Incorporated licensing procedure.

Updated flash programming procedure and moved it to Appendix A.

Updated links to software and documentation download pages.

November 2012 12.1.0 Initial release.Altera SDK for OpenCLGetting Started


Altera SDK for OpenCL Getting StartedPrerequisitesInstalling an FPGA BoardDownloading the SoftwareLicensingSupported Software SubscriptionsObtaining a License FileRehosting a LicenseAdding Floating SeatsRenewing a LicenseActivating a License

Setting Up the License FileLicense File ConditionsSetting Up a Fixed LicenseSetting Up a Floating Network License

Specifying the License File with the LM_LICENSE_FILE Environment VariableSetting the LM_LICENSE_FILE Environment Variable in the Windows Control PanelSetting the LM_LICENSE_FILE Environment Variable in the Linux Workstation C Shell Resource File (.cshrc)Specifying Multiple License Files with the LM_LICENSE_FILE Environment Variable

Setting Up Floating Network Licenses on the License ServerTransferring a License File

Installing the Altera SDK for OpenCLInstalling the SDK on WindowsVerifying SDK Installation on WindowsInstalling the Board Driver on WindowsVerifying the Board Driver Installation on WindowsUninstalling the SDK on Windows

Installing the SDK on LinuxInstalling the Board Driver on LinuxVerifying the Board Driver Installation on LinuxUninstalling the SDK on Linux

Configuring and Running the Moving Average ExampleConfiguring and Running the Moving Average Example on WindowsPrerequisitesSetting Up the Moving Average Example on WindowsCompiling the OpenCL Kernel and Generating the Hardware Program on WindowsBuilding the Host Application on WindowsProgramming FPGA Hardware on WindowsRunning the Host Application on Windows

Configuring and Running the Moving Average Example on LinuxPrerequisitesSetting Up the Moving Average Example on LinuxCompiling the OpenCL Kernel and Generating the Hardware Program on LinuxBuilding the Host Application on LinuxProgramming FPGA Hardware on LinuxRunning the Host Application on Linux

ConclusionAppendix AInstalling the USB-Blaster Driver on Windows for Flash ProgrammingProgramming the Flash Memory of an FPGAProgramming the Flash Memory of a Nallatech BoardProgramming the Flash Memory of a BittWare Board

Document Revision History

Altera Opencl Getting Started

Documents

Transcript of Altera Opencl Getting Started