Altera SDK for OpenCL Cyclone V SoC User Manual

Altera SDK for OpenCL

Cyclone V SoC Getting Started Guide

Subscribe
Send Feedback

OCL006-15.0.0

2015.05.04

101 Innovation Drive
San Jose, CA 95134

www.altera.com

TOC-2

Altera SDK for OpenCL Cyclone V SoC Getting Started Guide

Contents

Altera SDK for OpenCL Cyclone V SoC Getting Started Guide........................1-1

Setting Up the Altera SDK for OpenCL, SoC EDS, and the Cyclone V SoC

Development Kit for Windows....................................................................... 2-1

Prerequisites..................................................................................................................................................1-2

Contents of the Altera SDK for OpenCL..................................................................................................1-2

Overview of the AOCL and Cyclone V SoC Development Kit Setup Processes.................................1-4

Cyclone V SoC Development Kit Reference Platform Board Variants................................................1-5

Design Considerations................................................................................................................................1-6

Upgrading to Current Version of AOCL for Cyclone V SoC................................................................2-2

Downloading the Altera SDK for OpenCL.............................................................................................. 2-2

Downloading the SoC EDS.........................................................................................................................2-3

Installing the Altera SDK for OpenCL......................................................................................................2-3

Setting the Environment Variables for Windows................................................................................... 2-4

Installing the SoC EDS ...............................................................................................................................2-5

Licensing the Software.................................................................................................................................2-5

Installing the Cyclone V SoC Development Kit...................................................................................... 2-6

Writing an SD Card Image onto the Micro SD Flash Card on Windows................................2-6

Configuring the SW3 Switches.......................................................................................................2-7

Setting Up Terminal Connection in Windows............................................................................2-8

Setting Environment Variables and Loading OpenCL Linux Kernel Driver..........................2-8

Connecting the Board to Network via Ethernet..........................................................................2-9

Creating the Hardware Configuration File of an OpenCL Kernel for SoC.......................................2-10

Executing an OpenCL Kernel on an SoC............................................................................................... 2-12

Building the Host Application..................................................................................................... 2-13

Running the Host Application.....................................................................................................2-13

Output from Successful Kernel Execution on the Cyclone V SoC Development Kit..........2-13

Uninstalling the Software......................................................................................................................... 2-14

Setting Up the Altera SDK for OpenCL, SoC EDS, and the Cyclone V SoC

Altera Corporation

Development Kit for Linux............................................................................. 3-1

Upgrading to Current Version of AOCL for Cyclone V SoC................................................................3-2

Downloading the Altera SDK for OpenCL.............................................................................................. 3-2

Downloading the SoC EDS.........................................................................................................................3-3

Installing the Altera SDK for OpenCL......................................................................................................3-3

Setting the Environment Variables for Linux..........................................................................................3-4

Installing the SoC EDS................................................................................................................................3-5

Licensing the Software.................................................................................................................................3-5

Installing the Cyclone V SoC Development Kit...................................................................................... 3-6

Writing an SD Card Image onto the Micro SD Flash Card on Linux......................................3-7

Altera SDK for OpenCL Cyclone V SoC Getting Started Guide

TOC-3

Configuring the SW3 Switches.......................................................................................................3-7

Setting Up Terminal Connection in Linux...................................................................................3-8

Setting Environment Variables and Loading OpenCL Linux Kernel Driver..........................3-9

Connecting the Board to Network via Ethernet..........................................................................3-9

Creating the Hardware Configuration File of an OpenCL Kernel for SoC.......................................3-11

Executing an OpenCL Kernel on an SoC............................................................................................... 3-13

Building the Host Application..................................................................................................... 3-14

Running the Host Application.....................................................................................................3-14

Output from Successful Kernel Execution on the Cyclone V SoC Development Kit..........3-14

Uninstalling the Software......................................................................................................................... 3-15

Document Revision History...............................................................................A-1

Altera Corporation

Altera SDK for OpenCL Cyclone V SoC Getting

www.altera.com

101 Innovation Drive, San Jose, CA 95134

Started Guide

2015.05.04

OCL006-15.0.0

Subscribe

The Altera SDK for OpenCL Cyclone V SoC Getting Started Guide describes the procedures you follow to set up and use the Altera® Software Development Kit (SDK) for OpenCL application on the Altera Cyclone® V SoC Development Kit.

OpenCL is a C-based open standard for the programming of heterogeneous parallel devices. The AOCL
provides a compiler and tools for you to build and run OpenCL applications that target Altera FPGAs.
The AOCL supports the embedded profile of the OpenCL Specification version 1.0. For more information
on the OpenCL Specification version 1.0, refer to the OpenCL Reference Pages. The OpenCL Specification
version 1.0 includes detailed information on the OpenCL application programming interface (API) and
programming language.

This document assumes the following:

1. You are knowledgeable in OpenCL concepts and application programming interfaces (APIs), as

described in the OpenCL Specification version 1.0 by the Khronos Group.

2. You have experience in creating OpenCL applications, and are familiar with the contents of the

OpenCL Specification.

3. You are familiar with the information available in the following AOCL documentation:

Send Feedback

™

(1)

(AOCL)

(2)

to run an OpenCL

1

• Altera SDK for OpenCL Getting Started Guide.

• Altera SDK for OpenCL Programming Guide.

• Altera SDK for OpenCL Best Practices Guide.

Related Information

• OpenCL Reference Pages

• OpenCL Specification version 1.0

• Altera RTE for OpenCL Getting Started Guide

• Altera SDK for OpenCL Getting Started Guide

• Altera SDK for OpenCL Programming Guide

• Altera SDK for OpenCL Best Practices Guide

(1)

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

(2)

The Altera SDK for OpenCL is based on a published Khronos Specification, and has passed the Khronos
Conformance Testing Process. Current conformance status can be found at www.khronos.org/

conformance.

©

2015 Altera Corporation. All rights reserved. ALTERA, ARRIA, CYCLONE, ENPIRION, MAX, MEGACORE, NIOS, QUARTUS and STRATIX words and logos are
trademarks of Altera Corporation and registered in the U.S. Patent and Trademark Office and in other countries. All other words and logos identified as
trademarks or service marks are the property of their respective holders as described at www.altera.com/common/legal.html. Altera warrants performance
of its semiconductor products to current specifications in accordance with Altera's standard warranty, but reserves the right to make changes to any
products and services at any time without notice. Altera assumes no responsibility or liability arising out of the application or use of any information,
product, or service described herein except as expressly agreed to in writing by Altera. Altera customers are advised to obtain the latest version of device
specifications before relying on any published information and before placing orders for products or services.

ISO
9001:2008
Registered

1-2

Prerequisites

Prerequisites

To install the Altera SDK for OpenCL (AOCL) and create an OpenCL application for the Cyclone V SoC
Development Kit, your system must meet certain hardware, target platform, and software requirements.

Hardware Requirements

Ensure that your system meets the following minimum hardware and operating system (OS) require‐
ments:

1. The accelerator board is the Altera Cyclone V SoC Development Kit.

2. Development system requirements:

• You must have administrator privileges on the development system to install the necessary
packages and drivers.

• The development system has at least 8 gigabytes (GB) of RAM.

• The development system must be running on one of the following supported target platforms:

• Microsoft 64-bit Windows 7 on the x86-64 architecture.

• Red Hat Enterprise 64-bit Linux (RHEL) versions 6 on the x86-64 architecture.
You will use the development system to perform the following tasks:

OCL006-15.0.0

2015.05.04

• Compile OpenCL kernel source files to create hardware configuration files.

• Cross-compile the host executables to the ARM® processor.

• Connect your system to the SoC board so that they can communicate with each other using

UART over USB connection.

Software Prerequisites

• Linux systems require the Perl command version 5 or later. Ensure that your PATH environment

variable setting includes the path to the Perl command.

Contents of the Altera SDK for OpenCL

The AOCL provides logic components, drivers, and AOCL-specific libraries and files.

Logic Components

• The Altera Offline Compiler (AOC) translates your OpenCL device code into a hardware configuration

file that the system loads onto an Altera FPGA.

• The AOCL utility includes a set of commands you can invoke to perform high-level tasks such as

running diagnostic tests.

• The host runtime provides the OpenCL host platform application programming interface (API) and

runtime API for your OpenCL host application.

Drivers, Libraries and Files

The software installation process installs the software into a directory that you own. The
ALTERAOCLSDKROOT environment variable references the path to the software installation directory.

Altera Corporation

The host runtime consists of libraries that provide OpenCL APIs, hardware abstractions, and helper
libraries.

Altera SDK for OpenCL Cyclone V SoC Getting Started Guide

Send Feedback

OCL006-15.0.0

2015.05.04

Table 1-1: Select Contents of the AOCL Installation Directory

Windows Folder Linux Directory Description

bin bin User commands in the AOCL. Include this directory in your PATH

environment variable setting.

board board The AOCL Custom Platform Toolkit and Reference Platforms available

with the software.

• The path to the Custom Platform Toolkit is

ALTERAOCLSDKROOT/board/custom_platform_toolkit

• The path to the Cyclone V SoC Development Kit Reference
Platform, is

ALTERAOCLSDKROOT/board/c5soc

ip ip Intellectual property (IP) cores used to compile device kernels.
host host Files necessary for compiling and running your host application.
host\include host/include OpenCL Specification version 1.0 header files and software interface

files necessary for compiling and linking your host application.
The host/include/CL subdirectory also includes the C++ header file

cl.hpp. The file contains an OpenCL version 1.1 C++ wrapper API.

These C++ bindings enable a C++ host program to access the OpenCL
runtime APIs using native C++ classes and methods.

Contents of the Altera SDK for OpenCL

1-3

Important: The OpenCL version 1.1 C++ bindings are compatible

with OpenCL Specification versions 1.0 and 1.1.

Add this path to the include file search path in your development
environment.

host\
windows64\lib

host/linux64/lib OpenCL host runtime libraries that provide the OpenCL platform and

runtime APIs. These libraries are necessary for linking your host
application.

To run an OpenCL application on Linux, include this directory in the
LD_LIBRARY_PATH environment variable setting.

host\
windows64\bin

host/linux64/bin Runtime commands and libraries necessary for running your host

application, wherever applicable. For 64-bit Windows system, include
this directory in your PATH environment variable setting.

For Windows system, this folder only contains runtime libraries.
For Linux system, this directory contains platform-specific binary for

the aocl utility command.

share share Architecture-independent support files.

Example OpenCL Applications

You can download example OpenCL applications from the OpenCL Design Examples page on the Altera
website.

Altera SDK for OpenCL Cyclone V SoC Getting Started Guide

Send Feedback

Altera Corporation

1-4

Overview of the AOCL and Cyclone V SoC Development Kit Setup Processes

Related Information

OpenCL Design Examples page on the Altera website

Overview of the AOCL and Cyclone V SoC Development Kit Setup
Processes

The Altera SDK for OpenCL Cyclone V SoCs Getting Started Guide outlines the procedures for installing
the Altera SDK for OpenCL (AOCL) and all related software. It also outlines the setup process for the
Cyclone V SoC Development Kit.

Figure 1-1: Key Components of the Cyclone V SoC Development Kit

OCL006-15.0.0

2015.05.04

The figure below summarizes the steps for setting up the necessary software and installing the Cyclone V
SoC Development Kit.

Altera Corporation

Altera SDK for OpenCL Cyclone V SoC Getting Started Guide

Send Feedback

Review prerequisites

Download installers from altera.com

(Quartus II software, Cyclone V + Stratix V

device support, AOCL, SoC EDS)

Install Quartus II software,

Cyclone V + Stratix V device support,

AOCL, SoC EDS

HW, SW,
OS prereq
satisfied?

Acquire prerequisite

HW, SW, OS

aoc executable

runs?

NO

YES

NO

YES

Legend

Action
Decision

Install Cyclone V SoC

Development Kit

Run hello_world

on FPGA

aocl

diagnose

<device_name>

= PASSED?

YES

NO

Set up Cyclone V Development Kit

1. Write SD card image onto flash card

2. Set DIP switches

3. Terminal Connection

4. Set env. variables and load Linux kernel driver

Connect board to

network

OCL006-15.0.0

2015.05.04

Cyclone V SoC Development Kit Reference Platform Board Variants

Figure 1-2: Overview of AOCL and Board Setup

1-5

Cyclone V SoC Development Kit Reference Platform Board Variants

The Cyclone V SoC Development Kit Reference Platform (c5soc) includes two board variants.

Altera SDK for OpenCL Cyclone V SoC Getting Started Guide

Send Feedback

Altera Corporation

1-6

Design Considerations

OCL006-15.0.0

• c5soc board
This default board provides access to two DDR memory banks. The hard processor system (HPS)

DDR is accessible by both the FPGA and the CPU. The FPGA DDR is only accessible by the FPGA.

• c5soc_sharedonly board
This board variant contains only HPS DDR connectivity. The FPGA DDR is not accessible. This board

variant is more area efficient because less hardware is necessary to support one DDR memory bank.
The c5soc_sharedonly board is also a good prototyping platform for a final production board with a
single DDR memory bank.

To target this board variant when compiling your OpenCL kernel, include the --board
c5soc_sharedonly option in your aoc command.

For more information on the -- board <board_name> option of the aoc command, refer to the

Compiling a Kernel for a Specific FPGA Board (--board <board_name>) section of the Altera SDK for
OpenCL Programming Guide.

Related Information

Compiling a Kernel for a Specific FPGA Board (--board <board_name>)

2015.05.04

Design Considerations

When designing your OpenCL kernel and host program for execution on the Cyclone V SoC
Development Kit, factor in design considerations such as shared memory usage and FPGA area
optimization.

Shared memory is the preferred memory for FPGA kernels. For information on how to allocate and use
shared memory, refer to the Allocating Shared Memory for OpenCL Kernels Running on SoCs section of
the Altera SDK for OpenCL Programming Guide.

The Cyclone V SoC FPGA on the Cyclone V SoC Development Kit is not considered a large FPGA.
However, if you structure your kernel code in a way that optimizes hardware usage, it can provide
sufficient hardware resources to implement complex computations. Altera recommends that you consult
the Altera SDK for OpenCL Best Practices Guide to get a good understanding of the Altera Offline
Compiler (AOC). In addition, refer to the Strategies for Optimizing FPGA Area Usage section of the Altera
SDK for OpenCL Best Practices Guide for tips on area optimization.

Related Information

• Allocating Shared Memory for OpenCL Kernels Targeting SoCs

• Strategies for Optimizing FPGA Area Usage

• Altera SDK for OpenCL Best Practices Guide

Altera Corporation

Altera SDK for OpenCL Cyclone V SoC Getting Started Guide

Send Feedback

Setting Up the Altera SDK for OpenCL, SoC EDS,

www.altera.com

101 Innovation Drive, San Jose, CA 95134

and the Cyclone V SoC Development Kit for

Windows

2015.05.04

OCL006-15.0.0

Subscribe

The Altera SDK for OpenCL (AOCL) setup process includes downloading and installing the software,
installing the Cyclone V SoC Development Kit, and then executing an OpenCL kernel on the SoC.

1. Upgrading to Current Version of AOCL for Cyclone V SoC on page 2-2
If you have been using a previous version of the Altera SDK for OpenCL (AOCL) to program your
Cyclone V SoC Development Kit, you must upgrade the software programs and files to the current
version.

2. Downloading the Altera SDK for OpenCL on page 2-2
Download the AOCL and all related software for Windows from the Download Center on the Altera
website.

3. Downloading the SoC EDS on page 2-3
Download the SoC Embedded Design Suite (EDS) for Windows from the Download Center on the
Altera website.

4. Installing the Altera SDK for OpenCL on page 2-3
Install the AOCL in a folder that you own.

5. Setting the Environment Variables for Windows on page 2-4
Set the PATH user environment variable to point to Altera SDK for OpenCL (AOCL) libraries.

6. Installing the SoC EDS on page 2-5
To use the Altera SDK for OpenCL to create OpenCL kernel programs that target a Cyclone V SoC,
install the Altera SoC Embdded Design Suite (EDS) on your host system to develop the corresponding
embedded software.

7. Licensing the Software on page 2-5
Obtain the AOCL license from the Altera Self Service Licensing Center.

8. Installing the Cyclone V SoC Development Kit on page 2-6
To execute an OpenCL kernel on a Cyclone V SoC, first install the Cyclone V SoC Development Kit
and configure it as described in the Altera SDK for OpenCL (AOCL) documentation.

9. Creating the Hardware Configuration File of an OpenCL Kernel for SoC on page 2-10
To create the .aocx file for the hello_world example OpenCL application, you must download the
example design from the OpenCL Design Examples page on the Altera website. Extract the
downloaded source files, and then compile the kernel using the Altera Offline Compiler (AOC).

10.Executing an OpenCL Kernel on an SoC on page 2-12
Build your host application using the GNU Compiler Collection (GCC) cross-compiler available with
the SoC Embedded Design Suite (EDS).

Send Feedback

2

©

2015 Altera Corporation. All rights reserved. ALTERA, ARRIA, CYCLONE, ENPIRION, MAX, MEGACORE, NIOS, QUARTUS and STRATIX words and logos are
trademarks of Altera Corporation and registered in the U.S. Patent and Trademark Office and in other countries. All other words and logos identified as
trademarks or service marks are the property of their respective holders as described at www.altera.com/common/legal.html. Altera warrants performance
of its semiconductor products to current specifications in accordance with Altera's standard warranty, but reserves the right to make changes to any
products and services at any time without notice. Altera assumes no responsibility or liability arising out of the application or use of any information,
product, or service described herein except as expressly agreed to in writing by Altera. Altera customers are advised to obtain the latest version of device
specifications before relying on any published information and before placing orders for products or services.

ISO
9001:2008
Registered

2-2

Upgrading to Current Version of AOCL for Cyclone V SoC

11.Uninstalling the Software on page 2-14

To uninstall the AOCL for Windows, run the uninstaller, and restore all modified environment
variables to their previous settings.

Upgrading to Current Version of AOCL for Cyclone V SoC

If you have been using a previous version of the Altera SDK for OpenCL (AOCL) to program your
Cyclone V SoC Development Kit, you must upgrade the software programs and files to the current
version.

The AOCL is incompatible with previous versions of the Quartus® II software.

1. Upgrade the following software to the current version:
a. Quartus II software

b. AOCL
c. SoC Embedded Design Suite (EDS)

2. Reprogram the Cyclone V SoC Development Kit micro SD flash card with an image created using the

current version of the AOCL.
For instructions on programming the micro SD flash card, refer to the Writing an SD Card Image File

onto the Micro SD Flash Card section.

3. Recompile your host application using the current version of the AOCL.

OCL006-15.0.0

2015.05.04

Related Information

Writing an SD Card Image onto the Micro SD Flash Card on Windows on page 2-6

Downloading the Altera SDK for OpenCL

Download the AOCL and all related software for Windows from the Download Center on the Altera
website. Download the AOCL and all related software into a single installation package. Alternatively, if
you already have the current version of the Quartus II software in your system, download the AOCL as a
stand-alone software.

Download the following software and files:

• Quartus II software

• Cyclone V and Stratix® V device support files

• AOCL

• Altera SoC Embedded Design Suite (EDS)

1. In the main page of the Altera website, click MYALTERA and log into your account.
If you do not have a myAltera account, register for a new account.

2. Click DOWNLOADS to enter the Download Center.

3. Click Altera SDK for OpenCL to enter the download page for the subscription edition of the AOCL.

4. Select the software version. The default selection is the current version.

5. Select the Akamai DLM3 Download Manager or Direct Download as the download method.

Altera Corporation

By default, when you select Akamai DLM3 Download Manager, all the available software and device
support will be selected for download. Choose this download method if you need to install all the files.

Setting Up the Altera SDK for OpenCL, SoC EDS, and the Cyclone V SoC Development Kit for Windows

Send Feedback

OCL006-15.0.0

2015.05.04

If you do not require all the files, select Direct Download and download only the files that you need.
Choose this download method if you already have the current version of the Quartus II software and
device support installed on your machine.

6. Click the Windows SDK tab and then click More beside Download and install instructions to view
the download and installation procedure.

7. Perform the steps outlined in the download and installation instructions on the download page.

Related Information

Altera website

Downloading the SoC EDS

Download the SoC Embedded Design Suite (EDS) for Windows from the Download Center on the Altera
website.

1. In the main page of the Altera website, click MYALTERA and log into your account.
If you do not have a myAltera account, register for a new account.

2. Click DOWNLOADS to enter the Download Center.

3. Click SoC EDS to enter the download page for the subscription edition of the SoC EDS.

4. Select the software version.

5. Select Windows as the operating system.

6. Select Akamai DLM3 Download Manager or Direct Download as the download method.

7. If you select Akamai DLM3 Download Manager as the download method, click Download.

8. If you select Direct Download as the download method, click SoC Embedded Design Suite (EDS).

9. Perform the steps outlined in the download and installation instructions on the download page.

Downloading the SoC EDS

2-3

Related Information

Altera website

Installing the Altera SDK for OpenCL

If you download the AOCL, the Quartus II software, and the device support into a single installation
package, run the Quartus II software installer for Windows to install all the software and files. If you
download the AOCL as a stand-alone software, run the AOCL installer. Install the AOCL in a folder that
you own.

Before you begin

You must have administrator privileges.

Setting Up the Altera SDK for OpenCL, SoC EDS, and the Cyclone V SoC Development Kit for Windows

Send Feedback

Altera Corporation