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. Current conformance status can be found at www.khronos.org/conformance. 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
101 Innovation Drive
San Jose, CA 95134
www.altera.com
Feedback Subscribe
ISO
9001:2008
Registered
Altera SDK for OpenCL
Getting Started
The 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.
Prerequisites
To 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.
Page 2 Installing an FPGA Board
Altera SDK for OpenCL
Getting Started
June 2013 Altera Corporation
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 Board
To 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 Software
You 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.
Licensing Page 3
Altera SDK for OpenCL
Getting Started
June 2013 Altera Corporation
Licensing
When 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 Subscriptions
Altera 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?
Page 4 Licensing
Altera SDK for OpenCL
Getting Started
June 2013 Altera Corporation
Obtaining a License File
You 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 <hostname>, <port number> and <path to daemon
executable>.
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.
Licensing Page 5
Altera SDK for OpenCL
Getting Started
June 2013 Altera Corporation
Rehosting a License
You can rehost or transfer a license from one computer to another. You can rehost each
license up to three times within your maintenance period.
1. Log on to your myAltera account from the Altera website.
2. Access the Self-Service Licensing Center.
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.
Page 6 Licensing
Altera SDK for OpenCL
Getting Started
June 2013 Altera Corporation
Adding Floating Seats
You 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.
1. Log on to your myAltera account from the Altera website.
2. Access the Self-Service Licensing Center.
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 License
You 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.
1. Log on to your myAltera account from the Altera website.
2. Access the Self-Service Licensing Center.
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.
Licensing Page 7
Altera SDK for OpenCL
Getting Started
June 2013 Altera Corporation
Activating a License
You 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.
1. Log on to your myAltera account from the Altera website.
2. Access the Self-Service Licensing Center.
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 File
There 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.
Page 8 Licensing
Altera SDK for OpenCL
Getting Started
June 2013 Altera Corporation
License File Conditions
If you modify the <license>.dat file, where <license> 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 <license>.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 License
To set up a fixed license file, perform the following steps:
1. Make a backup copy of any existing <license>.dat file for reference.
2. Save the new <license>.dat file on your local hard drive. You should save and use
the <license>.dat file attached to the licensing email you received from Altera.
3. After you save the <license>.dat file on your local hard drive, proceed to
Specifying the License File with the LM_LICENSE_FILE Environment
Variableto specify your license.
Licensing Page 9
Altera SDK for OpenCL
Getting Started
June 2013 Altera Corporation
Setting Up a Floating Network License
The 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 <hostname> <8 or 12 character host or NIC ID> <port>
The license location for the user is <port>@<hostname>. If a port is not listed in the
<license>.dat file, specify @<hostname>.
2. After you save the <license>.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
Panel
You 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
Variable
Specify 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 on
Page 10 Installing the Altera SDK for OpenCL
Altera SDK for OpenCL
Getting Started
June 2013 Altera Corporation
Setting Up Floating Network Licenses on the License Server
Setting 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 File
If 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 OpenCL
This 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 Windows
To 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\<version>\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
<path_to_SDK>
where <path_to_SDK> is the path to the folder containing the extracted
installation package
PATH %QUARTUS_ROOTDIR%\bin64
PATH %ALTERAOCLSDKROOT%\windows64\bin
LM_LICENSE_FILE all the necessary <license>.dat files
Installing the Altera SDK for OpenCL Page 11
Altera SDK for OpenCL
Getting Started
June 2013 Altera Corporation
Verifying SDK Installation on Windows
To 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 Windows
The 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 support
team 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\driver
Page 12 Installing the Altera SDK for OpenCL
Altera SDK for OpenCL
Getting Started
June 2013 Altera Corporation
Verifying the Board Driver Installation on Windows
Before 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 Board
Installing the Altera SDK for OpenCL Page 13
Altera SDK for OpenCL
Getting Started
June 2013 Altera Corporation
Uninstalling the SDK on Windows
To 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 Linux
To 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/<version>/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%\bin64
PATH %ALTERAOCLSDKROOT%\windows64\bin
ALTERAOCLSDKROOT Remove the ALTERAOCLSDKROOT variable
Table 3. Environment Variables Set during SDK Installation on Linux
Environment Variable Path Added
ALTERAOCLSDKROOT
<path_to_SDK>
where <path_to_SDK> is the path to the directory containing the
extracted installation package
PATH $QUARTUS_ROOTDIR/bin
PATH $ALTERAOCLSDKROOT/linux64/bin
LD_LIBRARY_PATH $ALTERAOCLSDKROOT/linux64/lib
LM_LICENSE_FILE all the necessary <license>.dat files
Page 14 Installing the Altera SDK for OpenCL
Altera SDK for OpenCL
Getting Started
June 2013 Altera Corporation
Installing the Board Driver on Linux
The 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 support
team 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_64
make: 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.
Configuring and Running the Moving Average Example Page 15
Altera SDK for OpenCL
Getting Started
June 2013 Altera Corporation
f 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 Linux
You 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 Linux
To 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 Example
The 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/bin
PATH $ALTERAOCLSDKROOT/linux64/bin
ALTERAOCLSDKROOT Remove the ALTERAOCLSDKROOT variable
LD_LIBRARY_PATH $ALTERAOCLSDKROOT/linux64/lib
Page 16 Configuring and Running the Moving Average Example
Altera SDK for OpenCL
Getting Started
June 2013 Altera Corporation
Configuring and Running the Moving Average Example on Windows
Prerequisites
Before 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 Windows
Contents of the moving_average example are located in the
%ALTERAOCLSDKROOT%\designs\ moving_average\
moving_average_<board_name> 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 Example
Configuring and Running the Moving Average Example Page 17
Altera SDK for OpenCL
Getting Started
June 2013 Altera Corporation
Compiling the OpenCL Kernel and Generating the Hardware Program on
Windows
The moving_average.cl file within the moving_average_<board_name> 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\<board_name>.
2. At a command prompt, navigate to your target boards subfolder of the
moving_average design (that is, %ALTERAOCLSDKROOT%\designs\
moving_average\moving_average_<board_name>).
3. To compile the kernel for your target FPGA board, type
aoc --board <board_name> 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.
Page 18 Configuring and Running the Moving Average Example
Altera SDK for OpenCL
Getting Started
June 2013 Altera Corporation
Building the Host Application on Windows
The host.sln file within the moving_average_<board_name> 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 Studio
Configuring and Running the Moving Average Example Page 19
Altera SDK for OpenCL
Getting Started
June 2013 Altera Corporation
Programming FPGA Hardware on Windows
The 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 support
team for information on how to debug board installation problems.
--------------------------------------------------------------------
Page 20 Configuring and Running the Moving Average Example
Altera SDK for OpenCL
Getting Started
June 2013 Altera Corporation
To 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 Windows
Once 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.
Configuring and Running the Moving Average Example Page 21
Altera SDK for OpenCL
Getting Started
June 2013 Altera Corporation
Example 1 shows the output of the host application.
Configuring and Running the Moving Average Example on Linux
Prerequisites
Before 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 Linux
Contents of the moving_average example are located in the
$ALTERAOCLSDKROOT/designs/moving_average/
moving_average_<board_name> directory. Extract the moving_average example to a
location to which you have write access. The moving_average_<board_name>
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 CPU
The results from the FPGA and host CPU match
Freeing resources and exiting...
Page 22 Configuring and Running the Moving Average Example
Altera SDK for OpenCL
Getting Started
June 2013 Altera Corporation
Compiling the OpenCL Kernel and Generating the Hardware Program on Linux
The moving_average.cl file within the moving_average_<board_name> 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/<board_name>.
2. At a command prompt, navigate to your target boards subdirectory of the
moving_average design (that is, $ALTERAOCLSDKROOT/designs/
moving_average/moving_average_<board_name>).
3. To compile the kernel for your target FPGA board, type
aoc --board <board_name> 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 Linux
To build the host executable in Linux, navigate to the
moving_average_<board_name> directory and then type $ make -f Makefile.linux.
Configuring and Running the Moving Average Example Page 23
Altera SDK for OpenCL
Getting Started
June 2013 Altera Corporation
Programming FPGA Hardware on Linux
The 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 support
team for information on how to debug board installation problems.
--------------------------------------------------------------------
Page 24 Configuring and Running the Moving Average Example
Altera SDK for OpenCL
Getting Started
June 2013 Altera Corporation
To 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 Linux
After 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 CPU
The results from the FPGA and host CPU match
Freeing resources and exiting...
Conclusion Page 25
Altera SDK for OpenCL
Getting Started
June 2013 Altera Corporation
Conclusion
You 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 Programming
If 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.
Page 26 Appendix A
Altera SDK for OpenCL
Getting Started
June 2013 Altera Corporation
Programming the Flash Memory of an FPGA
By 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 Board
To 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.
Appendix A Page 27
Altera SDK for OpenCL
Getting Started
June 2013 Altera Corporation
Programming the Flash Memory of a BittWare Board
If 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 support
team 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.
Page 28 Document Revision History
Altera SDK for OpenCL
Getting Started
June 2013 Altera Corporation
Document Revision History
Table 5 lists the revision history for this document.
Table 5. Document Revision History
Date Version Changes
June 2013
13.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.