aocl_programming_guide

OCL002-13.0.0 

101 Innovation Drive 

San Jose, CA 95134 

www.altera.com 

May 2013 Altera Corporation 

Altera SDK for OpenCL 

Programming Guide 

This document describes the content and functionality of the Altera ® SDK for 

OpenCL version 13.0. The Altera SDK for OpenCL is a C-based heterogeneous 

parallel programming environment for Altera field programmable gate arrays 

(FPGAs). This document assumes that you have read the Altera SDK for OpenCL 

Getting Started Guide and have performed the following tasks: 

■ Download and install the Quartus II software version 13.0. 

■ Install your Stratix V FPGA board. You must download and install all necessary 

device support software. 

■ Download the Altera SDK for OpenCL version 13.0. 

■ Install the Altera SDK for OpenCL version 13.0. 

■ Install the USB-Blaster and the PCI Express ® (PCIe ® ) drivers. 

f If you have not performed the tasks described above, refer to the Altera Software 

Installation and Licensing Manual for installation instructions on the Quartus II 

software. Refer to the Altera SDK for OpenCL Getting Started Guide for installation 

instructions on the Altera SDK for OpenCL. 

This document assumes you are knowledgeable in OpenCL concepts and application 

programming interfaces (APIs), as described in the Khronos OpenCL Specification 

version 1.0. In addition, this programming guide assumes that you are familiar with 

specific sections and clauses of the OpenCL specification. For more information about 

the OpenCL Specification version 1.0, refer to OpenCL Reference Pages on the 

Khronos Group website. 

About the Altera SDK for OpenCL 

The Altera SDK for OpenCL provides a platform that allows you to implement the 

Embedded Profile as described in Section 10 of the OpenCL Specification version 1.0, 

with key differences listed in “Appendix B”. 

Contents of the Altera SDK for OpenCL version 13.0 

The Altera SDK for OpenCL version 13.0 provides the following logical components: 

■ Compiler—The compiler translates your OpenCL C device code into a hardware 

configuration file that can be loaded onto an Altera FPGA. 

■ Altera SDK for OpenCL (AOCL) Utility —The AOCL utility includes a set of 

commands that allows you to perform high-level tasks. Refer to “Altera SDK for 

OpenCL Utility” on page 8 for more information. 

© 2013 Altera Corporation. All rights reserved. ALTERA, ARRIA, CYCLONE, 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 of device specifications before 

ISO 

9001:2008 

Registered 

Feedback Subscribe

Page 2 Example OpenCL Applications 



■ Host Runtime—The host runtime provides the OpenCL host platform API and 

runtime API for your OpenCL host application. The host runtime consists of the 

following libraries: 

■ Statically-linked libraries provide OpenCL host APIs, hardware abstractions 

and helper libraries 

■ Dynamically-linked libraries (DLLs) provide hardware abstractions and helper 

libraries 

On Windows and Linux machines, the installation process for the Altera SDK for 

OpenCL installs the SDK into a folder or directory referenced by the 

ALTERAOCLSDKROOT environment variable. The contents of the Altera SDK for OpenCL 

version 13.0 are summarized in Table 1. 

Table 1. Contents of the Altera SDK for OpenCL for Windows and Linux 

Windows 

Folder 

Example OpenCL Applications 

Linux 

Directory 

Description 

\windows64\bin /linux64/bin 

Shared libraries, executables and Windows DLLs for your development 

environment. Include this folder or directory in your PATH environment 

variable. 

The Jungo WinDriver for PCIe for Windows or the Altera OpenCL PCIe 

\windows64\driver /linux64/driver 

Driver for Linux allows your host computer to communicate with the 

FPGA board. Refer to the Altera SDK for OpenCL Getting Started Guide 

for installation instructions. 

\board /board 

The Altera Certified Board Program for OpenCL for each FPGA board 

supported by the SDK. 

\ip /ip IP cores used to compile device kernels. 

\host /host Files used to compile your program. 

OpenCL version 1.0 header files and Altera SDK for OpenCL interface files 

\host\include /host/include that are used to compile and link your host program. Add this path to the 

include file search path in your development environment. 

OpenCL host runtime libraries that comprise a generic layer and a 

\host\windows64\lib /host/linux64/lib hardware abstraction layer that interface the host CPU with the FPGA 

board via PCIe. Used to link your host program. 

— /linux64/lib 

Shared libraries for your development environment. Include this 

directory in your LD_LIBRARY_PATH environment variable. 

The Altera SDK for OpenCL includes the following example OpenCL applications. To 

access these example files, navigate to the 

ALTERAOCLSDKROOT/design/ folder or directory. 

■ fft—an OpenCL application of a fast fourier transform algorithm 

■ matrixMult—an OpenCL application of a single precision floating-point-blocked 

matrix multiplication algorithm 

■ moving_average—an OpenCL application of an averaging filter 

■ vectorAdd—an OpenCL application that adds two vectors 

May 2013 Altera Corporation

Altera SDK for OpenCL Compilation Flow Page 3 

Altera SDK for OpenCL Compilation Flow 


Compiling an OpenCL application with the SDK is a two-step process: 

1. Compile your OpenCL kernels. Refer to “Compiling the OpenCL Kernel Source 

File” on page 4. 

2. Compile and link your host program. Refer to “Compiling and Linking Your Host 

Program” on page 9. 

Figure 1 depicts the compilation flow of the Altera SDK for OpenCL. 

Figure 1. The Altera SDK for OpenCL Compilation Flow 

Kernel Code 

AOC OpenCL 

Compiler 

Kernel Binary 

Host Code 

Standard 

C Compiler 

Host Binary 

PCIe 


Programming Guide

Page 4 Using the Altera Offline Kernel Compiler 

Using the Altera Offline Kernel Compiler 



Figure 2 illustrates the compilation flow of an OpenCL application that targets an 

Altera FPGA. 

Figure 2. Compilation Flow of the Altera SDK for OpenCL Offline Kernel Compiler 

Kernel 

file 2 

Kernel 

file 1 

Kernel 

file 3 

Merged 

kernel 

source file 

You create an FPGA image of your kernel file using the Altera Offline Compiler 

(AOC). If you create multiple kernel files, you must consolidate them into a single 

kernel source file (.cl). The kernel compiler translates this kernel source file into an 

Altera Offline Compiler Object file (.aoco), which the compiler then uses to build a 

hardware configuration file, called the Altera Offline Compiler Executable file (.aocx), 

that targets the FPGA. 

Compiling the OpenCL Kernel Source File 

Altera Offline 

Kernel Compiler 

(AOC) 

FPGA 

image file 

The AOC builds your OpenCL kernels and creates your hardware configuration file. 

Table 2 lists the available aoc compilation options. By default, you type the command 

aoc .cl to compile your kernels and create your hardware 

configuration file in a single step. 

c The process of creating an FPGA hardware configuration file takes hours to complete. 

Altera recommends that you perform this hardware configuring step on a computer 

that is equipped with at least 24 gigabytes (GB) of RAM. 

Table 2. Available Compilation Options for the Altera Offline Compiler 

Command Description 

Default compilation option: 

Generates a Quartus II hardware design project and then 

creates the hardware configuration file. The raw FPGA 

aoc .cl 

programming file is the .aocx executable file in the project 

directory. 


Using the Altera Offline Kernel Compiler Page 5 


Table 2. Available Compilation Options for the Altera Offline Compiler (Continued) 

A two-step compilation option: 

Command Description 

aoc -c .cl 

aoc .aoco 

Step 1: 

Generates a Quartus II hardware design project in a 

subdirectory that has the same name as the kernel filename, 

with special characters converted to underscores.The 

subdirectory contains intermediate files that the SDK uses to 

build the bit stream used to program the FPGA. 

This command generates the .aoco object file. 

Note: 

Generating the .aoco file is a rapid process compared to 

creating the .aocx file. To increase efficiency, iterate on your 

kernel code using this compilation option before generating a 

hardware configuration. 

Step 2: 

Creates the .aocx hardware configuration file from the .aoco 

object file. 

You may also perform the compilation in stages. For example, the kernel compiler 

builds the .aoco file for a vector addition OpenCL application shown in Example 1. 

You can access the kernel source file vectorAdd.cl by navigating to the 

ALTERAOCLSDKROOT/design/vectorAdd folder or directory. 

Example 1. vectorAdd.cl Kernel Source File 

// AOCL kernel for adding two input vectors 

__kernel void vectorAdd(__global const float *x, 

__global const float *y, 

__global float *restrict z, 

int numElements) 

{ 

// get index of the work-item 

size_t index = get_global_id(0); 

if (index >= numElements) 

{ 

return; 

} 

//add the vector elements 

z[index] = x[index] + y[index]; 

} 

To create the .aoco file, type aoc -c vectorAdd.cl at the command prompt. When 

the first compilation step completes and you return to the command prompt, type 

aoc vectorAdd.aoco to create the hardware configuration file from the .aoco file. 


Programming Guide




By default, the command prompt appears to signify the completion of the 

compilation. If you want to review the kernel throughput analysis and the estimated 

resource usage summary reports for the vectorAdd kernel compilation, shown in 

Example 2, invoke the aoc -c vectorAdd.cl --report command. 

Example 2. Output of the aoc -c vectorAdd.cl --report Command 

aoc: Selected target board pcie385n_a7 

Kernel throughput analysis for : vectorAdd 

.. simd work items : 1 

.. compute units : 1 

.. throughput due to control flow analysis : 250.00 M work items/second 

.. kernel global memory bandwidth analysis : 3157.89 MB/second 

.. kernel number of local memory banks : none 

+--------------------------------------------------------------------+ 

; Estimated Resource Usage Summary ; 

+----------------------------------------+---------------------------+ 

; Resource + Usage ; 

+----------------------------------------+---------------------------+ 

; Logic utilization ; 17% ; 

; Dedicated logic registers ; 7% ; 

; Memory blocks ; 16% ; 

; DSP blocks ; 0% ; 

+----------------------------------------+---------------------------; 

aoc: First stage compile time = 10s 

1 You can also view detailed information on the compilation by accessing the log file. 

The .log file is located in the folder or 

subdirectory. 

Altera Offline Compiler Options 

You can type the command aoc --help to obtain more information about the 

command options for the kernel compiler, as summarized in Table 3. 

Table 3. AOC Command Options (Part 1 of 3) 

Option Description 

Help options: 

--help or -h Displays a list of aoc command options. 

--version Prints out version information and exits. 

-v Reports the progress of compilation. 

--report Generates reports for kernel throughput analysis and estimated resource 

usage summary. 

Overall options: 

-c Sets up a Quartus II hardware design project without performing a 

hardware build. 

-o Uses as the name for the output. 

For example: 

To specify the filename of the output .aoco file, type the command: 

aoc -c -o .aoco myKernel.cl 

To specify the filename of the output .aocx file, type the command: 

aoc -o .aocx myKernel.cl, or 

aoc -o .aocx myKernel.aoco 


Using the Altera Offline Kernel Compiler Page 7 




-I Adds to header search path. 

-D Defines a macro called , where can be a value or an actual 

name. 

For example, aoc myKernel.cl -D RADIUS = 4 is equivalent to 

adding a #define RADIUS 4 line at the top of your kernel 

source file. 

-W Suppresses warnings. 

-Werror Forces all warnings into errors. 

Modifiers: 

--board Runs compilation for the specified board. 

For example, the command 

aoc -- board pcie385n_a7 myKernel.cl compiles 

myKernel for the Nallatech PCIe-385N A7 FPGA computing card. 

--list-boards Prints a list of available boards and exits. 

Optimization controls: 

-fp-relaxed Directs the compiler to optimize floating-point operations using balanced 

trees. 

If you want to use this optimization option, your program must be able to 

tolerate small differences in floating-point results. 

Example usage: aoc -fp-relaxed=true myKernel.cl 

-fpc Directs the compiler to remove floating-point rounding operations and 

conversions when possible and to carry additional bits to maintain 

precision. 

If possible, this argument causes the compiler to round a floating-point 

operation once at the end of the balanced tree. 

Example usage: aoc -fpc=true myKernel.cl 

--sw-dimm-partition Configures the global memory as separate address spaces for each external 

memory or bank. 

After you configure the global memory, allocate each buffer in an external 

memory with the Altera specific cl_mem_flags (For example, 

CL_MEM_BANK_2_ALTERA). 

--const-cache-bytes Configures the constant cache size in bytes, rounded to the next nearest 

power of 2. 

This argument has no effect if none of the kernels uses the __constant 

address space. The default constant cache size is 16 kilobytes (kB). 

-O3 Applies resource-driven performance optimizations to improve 

performance without violations fitting requirements (estimated logic 

utilization is less than or equal to 85%). 

--util Overrides the logic utilization threshold used by the -O3 option with %. 


Programming Guide





OpenCL Build Options: 

-cl-single-precisionconstant 

-cl-denorms-are-zero 

-cl-opt-disable 

-cl-strict-aliasing 

-cl-mad-enable 

-cl-no-signed-zeros 

-cl-unsafe-mathoptimizations 

-cl-finite-math-only 

-cl-fast-relaxed-math 

Altera SDK for OpenCL Utility 


Refer to the OpenCL Specification version 1.0, section 5.4.3. 

The Altera SDK for OpenCL (AOCL) utility provides additional functionality that 

allows you to perform high-level tasks. You can obtain information on your host 

program such as flags and makefile fragments. You can invoke the aocl help 

command to obtain more information about the command options, as summarized in 

Table 4. 

Table 4. AOCL Command Options 

Option 

Subcommands for building your host program: 

Description 

aocl example-makefile Displays makefile fragments for compiling and linking a host program. 

aocl makefile Same as the example-makefile subcommand. 

aocl compile-config Displays the flags for compiling your host program. 

Shows the flags for linking your host program with the runtime libraries provided 

aocl link-config 

by the Altera SDK for OpenCL. 

This command combines the function of the ldflags and ldlibs 

subcomands. 

aocl linkflags Same as the link-config subcommand. 

Displays the linker flags used to link your host program to the host runtime 

aocl ldflags 

libraries provided by the Altera SDK for OpenCL. This command does not list the 

libraries themselves. 

aocl ldlibs Displays the list of host runtime libraries provided by the Altera SDK for OpenCL. 

aocl program 

Configures a new FPGA image onto the board. 

Usage: aocl program .aocx. 

aocl flash 

[If supported] Initializes the FPGA with a specified startup configuration. 

Usage: aocl flash .aocx. 

aocl install Installs your FPGA board into the current host system. 

aocl diagnostic Runs the board vendor’s test program for your FPGA board. 


Compiling and Linking Your Host Program Page 9 

Compiling and Linking Your Host Program 


Table 4. AOCL Command Options (Continued) 

General: 

aocl version Displays the version information. 

aocl help Displays a list of aocl options. 

aocl help Displays the help content for a particular command. 

In an OpenCL application, the host program uses standard OpenCL runtime APIs to 

manage device configuration, data buffers, kernel launches, and event 

synchronization. The host program also contains host-side functions such as file I/O 

or portions of the source code that do not run on an accelerator device. A host 

program includes C header files that describe the OpenCL APIs. These C header files 

must link against the runtime API libraries. 

Host Program Compilation Settings 

To compile your host program, type aocl compile-config at the command line to 

obtain the following path you must add to your C preprocessor to include a file search 

path: 

■ For Windows systems, add the path -I/%ALTERAOCLSDKROOT%/host/include 

■ For Linux systems, add the path -I/$ALTERAOCLSDKROOT/host/include 

The OpenCL API header files reside in this directory. You should include the OpenCL 

header file CL/opencl.h in your host source. 

1 On Windows, you must add the /MD flag to compile the Altera runtime libraries. The 

flag links the runtime libraries against the multi-threaded DLL version of the 

Microsoft C Runtime library. You must also compile your host program with the /MD 

compilation flag, or use the /NODEFAULTLIB linker option to override the selection of 

runtime library. 

Library Paths and Links 

Your host program must link against the appropriate runtime libraries provided by 

the SDK. To obtain the link options, type the command aocl link-config. 

Programming the FPGA Hardware 


By default, the AOC compiles the OpenCL kernels, and then the kernels are loaded 

onto the FPGA via PCIe CvP using clCreateProgramWithBinary, as outlined in 

“Loading Kernels onto an FPGA using clCreateProgramWithBinary” on page 13. 

c You must ensure that the PCIe device inside your FPGA board is configured properly 

prior to using clCreateProgramWithBinary to program your FPGA hardware. To 

verify the successful instantiation of the PCIe device, type the command 

aocl diagnostic. 


Programming Guide

Page 10 Running Your OpenCL Application 



1 If the PCIe device on your FPGA board is not configured properly, refer to 

“Programming the Flash Memory of an FPGA” in “Appendix A” for 

programming instructions. 

If you want to program your FPGA manually without using the host runtime API, via 

a non-standard use of clCreateProgramWithBinary, refer to “Programming the FPGA 

with the aocl program Command” in “Appendix A”. 

Running Your OpenCL Application 

After you load the FPGA hardware configuration file onto the FPGA, you can run the 

host application as outlined in the Altera SDK for OpenCL Getting Started Guide. 

OpenCL Programming Considerations 

When you create your kernel and host applications, keep in mind the following 

programming considerations: 

■ For OpenCL kernels, refer to “Kernel Programming Considerations” 

■ For host code, refer to “Host Programming Considerations” 

Kernel Programming Considerations 

Specifying a Target FPGA Board 

You can target any FPGA board that is provided in a board vendor-supplied “board 

package.” To select the board package that the compiler uses, set the 

AOCL_BOARD_PACKAGE_ROOT environment variable to the path of your board vendor's 

board package (that is, T/board/). 

For example, if you run the SDK on Linux, set the board package environment 

variable as shown below: 

■ To select the Nallatech PCIe-385N A7 FPGA computing card, set 

AOCL_BOARD_PACKAGE_ROOT to $ALTERAOCLSDKROOT/board/pcie385n 

■ To select the BittWare S5-PCIe-HQ Altera Stratix V GSMD5 half-length PCIe 

board, set AOCL_BOARD_PACKAGE_ROOT to $ALTERAOCLSDKROOT/board/s5pciehq 

Type aoc --list-boards to list the available boards within your current board 

package. You can then target any of the listed boards within that board package using 

the aoc --board command. 

File Scope __constant Address Space Qualifier 

The Altera SDK for OpenCL supports scalar file scope constant data. For example, 

you may set the __constant address space qualifier as follows: 

__constant int my_array[8] = {0x0, 0x1, 0x2, 0x3, 0x4, 0x5, 0x6, 0x7}; 

__kernel void my_kernel (__global int * my_buffer) 

{ 

size_t index = get_global_id(0); 

my_buffer[index] += my_array[index % 8]; 

} 


OpenCL Programming Considerations Page 11 


In this case, values for my_array are set in a ROM because the file scope constant data 

does not change between kernel invocations. To avoid long compilation times, file 

scope constant data should not exceed 32 kB in size. 

c Vector type file scope constant data is not supported. For example, the following line 

of code is illegal because the vector type int2 is not supported: 

__constant int2 my_array[4] = {(0x0, 0x1), (0x2, 0x3), (0x4, 0x5), (0x6, 

0x7)}; 

Modifying Your OpenCL Kernel to Target an FPGA 

To modify a kernel that was originally written to target a different architecture, 

perform the following steps: 

1. Collect the source code from all your kernels into a single file. The name of the 

single file must have a .cl extension. For example, collect all the source code from 

all your kernel source code files into a single file and name that single file 

mykernels.cl. 

2. If your kernel uses barriers and your kernel must handle work-groups larger than 

256 work-items, specify the number of work-items you require with either 

reqd_work_group_size or max_work_group_size. (The default 

max_work_group_size is 256.) 

3. Eliminate function scope __constant variables. Replace them with a pointer to a 

__constant parameter. In your host program, allocate a cl_mem object in global 

memory, copy the constant data to global memory before the kernel starts, and 

pass the cl_mem object as a parameter to the kernel. 

If a constant variable is a complex type, Altera recommends that, for simplicity, 

you use a typedef argument. For example: 

Example 3. Eliminating Function Scope __constant Variables 

If your source code includes this: Rewrite it to this: 

__kernel void original( _global int *A) 

{ 

__constant int Payoff[2][2] = 

{{ 1, 3}, {5, 3}}; 

*A = Payoff[1][2]; 

// and so on 

} 

typedef int Payoff_type[2][2]; 

__kernel void modified( _global int *A, 

__constant Payoff_type *PayoffPtr ) 

{ 

*A = (PayoffPtr)[1][2]; 

// and so on 

} 

1 Use the same type definition in both your host program and your kernel. 


Programming Guide

Page 12 OpenCL Programming Considerations 



4. Convert each structure parameter to a pointer that points to a structure. For 

example: 

Example 4. Converting Structure Parameters to Pointers that Point to Structures 

If your source code includes this: Rewrite it to this: 

struct Context 

struct Context 

{ 

{ 

float param1; 

float param1; 

float param2; 

float param2; 

int param3; 

int param3; 

uint param4; 

uint param4; 

}; 

}; 

__kernel void algorithm( 

__global float* A, 

struct Context c) 

{ 

if ( c.param3 ) 

{ 

// and so on 

} 

} 

1 The __global struct declaration creates a new buffer to store the structure. 

Use a restrict qualifier to declare the pointer to the structure to prevent 

pointer aliasing. 

f For more information about optimizing your OpenCL kernel code to target an FPGA 

refer to the Altera SDK for OpenCL Optimization Guide. 

Host Programming Considerations 

Host Binary Requirement 

You must build 64-bit host binaries from your host code. 

Host Machine Memory Requirements 

The machine that runs the host program must have enough RAM to support all of the 

following components simultaneously: 

■ The host program and operating system. 

■ The working set for the host program. 

__kernel void algorithm( 

__global float* A, 

__global struct Context* restrict c) 

{ 

if ( c->param3) 

{ // Dereference through a pointer 

// and so on 

} 

} 

■ The maximum amount of OpenCL memory buffers that can be allocated at once. 

Every device-side cl_mem buffer is associated with a corresponding storage area in 

the host process. Therefore, the amount of RAM required can be as large as the 

amount of RAM supported by the FPGA. 


OpenCL Programming Considerations Page 13 


Loading Kernels onto an FPGA using clCreateProgramWithBinary 

The Altera SDK for OpenCL provides a kernel compiler that builds the .cl file for an 

OpenCL application. Kernels are compiled separately by the workstation offline and 

then loaded onto the FPGA using clCreateProgramWithBinary, shown in Example 5. 

Example 5. Host Code Showing Usage of clCreateProgramWithBinary 

size_t lengths[1]; 

unsigned char* binaries[1] ={NULL}; 

cl_int status[1]; 

cl_int error; 

cl_program program; 

const char options[] = ""; 

FILE *fp = fopen("program.aocx","rb"); 

fseek(fp,0,SEEK_END); 

lengths[0] =ftell(fp); 

binaries[0]= (unsigned char*)malloc(sizeof(unsigned char)*lengths[0]); 

rewind(fp); 

fread(binaries[0],lengths[0],1,fp); 

fclose(fp); 

program = clCreateProgramWithBinary(context,1,device_list,lengths, 

(const unsigned char **)binaries,status,&error); 

clBuildProgram(program,1,device_list,options,NULL,NULL); 

After the .aocx file is built, you may use it to create the OpenCL program. The 

clCreateProgramWithBinary function uses the .aocx file to create a program for the 

targeted FPGA, and then host runtime programs the FPGA via clBuildProgram. You 

can load multiple FPGA programs into memory, and host runtime will reprogram the 

FPGA to match the program in memory. 

Aligned Memory Allocation 

You should use aligned memory allocations when assigning a host-side buffer to be 

written or read from the FPGA. This allows direct memory access (DMA) transfers to 

occur to and from the FPGA, which is a more efficient form of memory movement. 

Altera recommends that you use 64-byte alignment. To set up aligned memory 

allocations, add the source code in Example 6. 

Example 6. Source Code for Enabling Aligned Memory Allocations 

For Windows: 

#define AOCL_ALIGNMENT 64 

#include 

void *ptr = _aligned_malloc (size, AOCL_ALIGNMENT); 

For Linux: 

#define AOCL_ALIGNMENT 64 

#include 

void *ptr = NULL; 

posix_memalign (&ptr, AOCL_ALIGNMENT, size); 


Programming Guide

Page 14 Appendix A 

Appendix A 



Modifying Your Host Program to Target an FPGA 

To modify a host program that was originally written to target a different architecture, 

perform the following steps: 

1. To create cl_program objects, use clCreateProgramWithBinary, shown in 

Example 5, instead of clCreateProgramWithSource. You can use either 

clCreateKernelsInProgram or clCreateKernel. 

2. If you eliminated any function scope __constant variables in your kernel code (by 

replacing them with __constant pointers as described in “Modifying Your 

OpenCL Kernel to Target an FPGA” on page 11), modify your host program to 

create cl_mem objects associated with the pointers, load constant data into them 

with clEnqueueWriteBuffer, and pass the objects to the kernel as arguments with 

clSetKernelArg. 

3. If you converted any structure parameters to pointers-to-constant-structures, 

make the following changes to your host program: 

a. Allocate a cl_mem buffer to store the structure contents. (You need a separate 

cl_mem buffer for every kernel that uses a different structure value.) 

b. Set the structure kernel argument with a pointer to the structure buffer, not 

with a pointer to the structure contents. 

c. Populate the structure buffer contents before enqueuing the kernel. Ensure that 

the structure buffer is populated before the kernel launches by either 

enqueuing it on the same command queue as the kernel enqueuing, or by 

synchronizing separate kernel enqueuing and structure buffer enqueuing with 

an event. 

d. When your program no longer needs to call a kernel that uses the structure 

buffer, release the cl_mem buffer. 

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 flash memory. When you 

power up the system, the hardware configuration file stored in flash memory 

configures the FPGA circuitry. Therefore, it is imperative to load an OpenCLcompatible 

image into the flash memory to ensure the proper configuration of the 

FPGA. 

When you load the hardware configuration file into the flash memory of the FPGA, it 

is imperative to not prematurely power down the system. Also, you must not launch 

any host code that calls OpenCL kernels or might otherwise communicate with the 

FPGA board. 


Appendix B Page 15 

Appendix B 


Perform the following steps to load your hardware configuration file into the flash 

memory of the FPGA: 

1. Ensure that the USB-Blaster driver is installed successfully so that you can load 

your hardware configuration file into the Flash memory. If your USB-Blaster 

driver is not installed properly, refer to the Altera SDK for OpenCL Getting Started 

Guide for installation instructions. 

2. Generate a .aocx file. Refer to “Compiling the OpenCL Kernel Source File” on 

page 4 for more information. 

3. Type aocl flash .aocx to load the hardware configuration 

file into the flash memory of the FPGA. 

4. Reboot your host system. 

The reason for programming the flash memory of your FPGA is that OpenCL kernels 

require a PCIe device inside the FPGA so that they can communicate with the host 

program. The FPGA boards supported by the Altera SDK for OpenCL version 13.0 are 

preprogrammed with a default hardware configuration file that instantiates the PCIe 

device inside the FPGA. If the PCIe device in your FPGA board is not configured 

properly, you can configure the FPGA using the image stored in the flash memory 

such that you can have a functional PCIe device upon rebooting your system. 

Programming the FPGA with the aocl program Command 

If you want to load your hardware configuration file onto the FPGA offline without 

using the host runtime API, you may do so by implementing a non-standard use of 

clCreateProgramWithBinary in your host code, as shown below: 

cl_int status; 

cl_program program; 

const char *kernel_name = "vectorAdd"; 

size_t kernel_name_length = 9; 

cl_int kernel_status; 

program = clCreateProgramWithBinary(context, 1, &device, 

&kernel_name_length, (const unsigned char**)&kernel_name, 

&kernel_status, &status); 

To load the kernel onto the FPGA, perform the following steps: 

1. At a command prompt, navigate to the directory that contains the .aocx that 

specifies the hardware configuration for the target FPGA. 

2. Type aocl program .aocx. This command loads the 

hardware configuration onto the FPGA. 

Allocation Limits of the Altera SDK for OpenCL 

The Altera SDK for OpenCL host runtime conforms with the OpenCL platform layer 

and runtime API, with the following clarifications and exceptions: 


Programming Guide

Page 16 Appendix B 



■ Allocation limits—Table 5 lists allocation limits of the SDK. 

Table 5. Allocation Limits of the Altera SDK for OpenCL 

Item Limit 

Maximum number of contexts 4 

Maximum number of queues per context 28 

Maximum number of program objects per context 20 

Maximum number of concurrently running kernels 

The total number of 

queues 

Maximum number of enqueued kernels More than 1000 

Maximum number of kernels per FPGA device 32 

Maximum number of arguments per kernel 128 

Maximum total size of kernel arguments 256 bytes 

OpenCL Features Supported by the Altera SDK for OpenCL 

The Altera SDK for OpenCL supports the OpenCL Specification version 1.0. The SDK 

provides a platform that implements the Embedded Profile (Section 10 of the OpenCL 

Specification version 1.0 by the Khronos Group). 

Platform Layer and Runtime Implementation 

Section 4 of the OpenCL Specification version 1.0 describes the OpenCL platform layer 

that allows applications to query OpenCL devices and device configuration 

information, and to create OpenCL contexts. Section 5 of the specification describes 

the OpenCL runtime API that manages OpenCL objects such as command queues, 

memory objects, program objects, kernel objects, and calls that allow you to enqueue 

commands. 

■ Section 5.2.1: Creating Buffer Objects—Memory objects allocated in host memory 

must be aligned to 128-byte boundaries to accommodate the worst-case alignment 

of the built-in OpenCL C data types (that is, type long16 because type long16 is 

128 bytes (16 x 8 bytes)). When you provide a host memory block to 

clCreateBuffer, you must ensure that the buffer is aligned as required. 

■ Section 5.2.8: Mapping and Unmapping Memory Objects—The SDK does not present 

a coherent shared memory abstraction; host memory and device global memory 

are not shared. All memory transfers between the host and the device must be 

explicitly managed with the OpenCL host API. 

■ Section 5.4.1: Creating Program Objects—The SDK does not provide an online 

compiler. Therefore, do not use the clCreateProgramWithSource API. Instead, use 

clCreateProgramWithBinary to create a program. 

■ Section 5.8: Out-of-order Execution of Kernels and Memory Object Commands— 

Command queues do not support out-of-order execution. 



OpenCL Programming Language Implementation 


Section 6 of the OpenCL Specification version 1.0 describes the OpenCL C programming 

language. OpenCL C is based on C99 with some limitations. The Altera SDK for 

OpenCL conforms with the OpenCL C programming language with clarifications and 

exceptions summarized in Table 6. The following symbols indicate the support 

statuses of the features: 

■ “v” means that the feature is supported, and there is additional information 

available in the Notes column in Table 6. 

■ “v*” means that the feature is supported with exceptions and clarifications. 

■ “X” means that the feature is not supported. 

■ “—” means that an explanation or clarification for the feature is available in the 

Notes column Table 6. 

■ OpenCL programming language implementations that are supported with no 

additional clarifications are not shown in Table 6. 

Table 6. OpenCL Programming Language Implementation (Part 1 of 5) 

Section Feature Supported Notes 

6.1.1 Built-in Scalar Data Types 

double precision float v* 

half X 

6.1.2 Built-in Vector Data Types v* 

6.1.3 Built-in Data Types X 

6.1.4 Reserved Data Types X 

6.1.5 Alignment of Types — 

6.2.1 Implicit Conversions v 

6.2.2 Explicit Casts v 

6.5 Address Space Qualifiers v* 

6.6 Image Access Qualifiers X 

6.7 Function Qualifiers 

6.7.2 

Optional Attribute 

Qualifiers 

v 

*Preliminary support for all double precision float builtin 

scalar data types. This feature might not conform 

with the OpenCL Specification version 1.0. 

*Preliminary support for vectors with three elements. 

Three-element vectors might not conform with the 

OpenCL Specification version 1.0. 

All scalar and vector types are aligned as required 

(vectors with three elements are aligned as if they had 

four elements). 

Refer to Section 6.2.6: Usual Arithmetic Conversions in 

the OpenCL Specification version 1.2 for an important 

clarification of implicit conversions between scalar and 

vector types. 

The SDK allows scalar data casts to a vector with a 

different element type. 

*Function scope __constant variables are not 

supported. 

Refer to the Altera SDK for OpenCL Optimization Guide 

for tips on using regd_work_group_size to 

improve kernel performance. 

The SDK parses but ignores vec_type_hint and 

work_group_size_hint attribute qualifiers. 


Programming Guide






6.8 

Restrictions—The SDK implements the restrictions listed in the OpenCL Specification version 1.0 as 

follows: 

pointer assignments 

between address spaces 

— 

pointers to functions X 

structure-type kernel 

arguments 

X 

images X 

Arguments to __kernel functions declared in a 

program that are pointers must be declared with the 

__global, __constant, or __local qualifier. 

The compiler enforces the OpenCL restriction against 

point assignments between address spaces. 

The compiler does not enforce the OpenCL restriction 

against pointers to functions—you must ensure that 

your code contains no pointers to functions. 

Convert structure arguments to a pointer to a structure 

in global memory. 

bit fields X 

The compiler does not enforce this restriction—you 

must ensure that your code contains no bit fields. 

variable length arrays and 

structures 

X 

variadic macros and 

functions 

X 

C99 headers X C99 headers are not available. 

extern, static, 

auto, and register 

storage-class specifiers 

predefined identifiers v 

recursion X 

irreducible control flow X 

writes to memory of 

built-in types less than 

32 bits in size 

declaration of arguments 

to __kernel functions 

of type event_t 

elements of a struct or 

union belonging to 

different address spaces 

X 


must ensure that your code contains no extern or 

static specifiers; the auto and register 

specifiers should have no effect. 

Warning: Assigning elements of a struct or union 

to different address spaces might cause a fatal error. 

Use the -D option of the aoc command to provide 

preprocessor symbol definitions in your kernel code. 


must ensure that your code contains no recursive 

functions. 

Irreducible control flow is invalid. Code with irreducible 

control flows might result in a hardware implementation 

with unexpected behavior. Generally, irreducible control 

flow occurs in loops that have multiple entry points. 

v* *Performance of such writes is poor. 

X 

X 


must ensure that your code does not include 

__kernel function arguments of type event_t. 


must ensure that all elements of a struct or union 

belong to the same address space. 






6.9 Preprocessor Directives and Macros 

#pragma directive: 

#pragma unroll 

v 

The compiler supports only #pragma unroll. The 

unroll directive may optionally take an integer as an 

argument to control the unroll factor. 

For example, #pragma unroll 4 unrolls a loop 

with four iterations. 

By default, an unroll directive causes the compiler to 

attempt to fully unroll the loop. 

Refer to the Altera SDK for OpenCL Optimization Guide 

for tips on using #pragma unroll to improve 

kernel performance. 

__ENDIAN_LITTLE__ 

defined to be value 1 

v The target FPGA is little-endian. 

__IMAGE_SUPPORT__ X 

__IMAGE_SUPPORT__ is undefined; the SDK does 

not support images. 

6.10 Attribute Qualifiers—The compiler parses attribute qualifiers as follows: 

Specifying Attributes of 

6.10.2 Functions—Structure-type 

kernel arguments 

6.10.3 Specifying Attributes of Variables 

6.10.4 

6.10.5 

endian X 

Specifying Attributes of 

Blocks and 

Control-Flow-Statements 

Extending Attribute 

Qualifiers 

6.11.2 Math Functions 

X 

X 

— 

built-in math functions v* 

built-in half_ and 

native_ math functions 

v* 

6.11.5 Geometric Functions v 

6.11.8 

Image Read and Write 

Functions 

X 

Convert structure arguments to a pointer to a structure 

in global memory. 

The SDK for OpenCL compiler can parse attributes on 

various syntactic structures. It reserves some attribute 

names for its own internal use. Refer to the Altera SDK 

for OpenCL Optimization Guide for more information 

about these attribute names. 

*Built-in math functions for double precision float are 

supported preliminarily. These functions might not 

conform with OpenCl Specification version 1.0. 

*Built-in half_ and native_ math functions for 

double precision float are supported preliminarily. 

These functions might not conform with OpenCl 

Specification version 1.0. 

*Built-in gemometric functions for double precision 

float are supported preliminarily. These functions might 

not conform with OpenCl Specification version 1.0. 

Refer to Table 7 on page 21 for a list of built-in 

geometric functions supported by the SDK. 


Programming Guide






6.11.9 

6.11.10 

6.11.11 

Synchronization Functions— 

the barrier synchronization 

function 

Explicit Memory Fence 

Functions 

Async Copies from Global to 

Local Memory, Local to 

Global Memory, and Prefetch 

v* 

X 

v* 

*Clarifications and exceptions: 

If a kernel specifies regd_work_group_size or 

max_work_group_size attributes, barrier 

supports the corresponding number of work-items. 

If neither attribute is specified, a barrier is instantiated 

with a default limit of 256 work-items. 

The work-item limit is the maximum supported workgroup 

size for the kernel; this limit is enforced by the 

runtime. 

*The implementation is naive: 

Work-item (0,0,0) performs the copy and the 

wait_group_events is implemented as a barrier. 

If a kernel specifies the reqd_work_group_size 

or max_work_group_size attribute, 

wait_group_events supports the corresponding 

number of work-items. 

If neither attribute is specified, 

wait_group_events is instantiated with a default 

limit of 256 work-items. 

Additional built-in vector functions from the OpenCL Specification version 1.2 Section 6.12.12: Miscellaneous Vector 

Functions: 

vec_step v 

shuffle v 

shuffle2 v 






OpenCL Specification version 1.2 Section 

6.12.13: printf 

v* 

*Preliminary support. This feature might not conform 

with the OpenCL Specification version 1.0 See below for 

details. 

The printf function in OpenCL has syntax and features similar to the printf function in C99, with a few 

exceptions. For details, refer to the OpenCL Specification version 1.2. 

To use a printf function, there are no requirements for special compilation steps, buffers, or flags; you can 

compile kernels that include printf instructions with the usual aoc command. 

During kernel execution, printf data is stored in a global printf buffer that is automatically allocated by the 

compiler. The size of this buffer is 64 kB; the total size of data arguments to a printf call should not exceed this 

size. When kernel execution completes, the contents of the printf buffer are printed to standard output. 

Buffer overflows are handled seamlessly; printf instructions can be executed an unlimited number of times. 

However, if the printf buffer overflows, kernel pipeline execution stalls until the host reads the buffer and prints 

the buffer contents. 

Because printf functions store their data into a global memory buffer, the performance of your kernel will drop if it 

includes such functions. 

There are no usage limitations on printf functions. You can use printf instructions inside if-then-else 

statements, loops, etc. A kernel can contain multiple printf instructions that are executed by multiple work-items. 

Format string arguments and literal string arguments of printf calls are transferred to the host system from the 

FPGA using a special memory region. This memory region can overflow if the total size of the printf string 

arguments is large (3000 characters or less is usually safe in a typical OpenCL application). An overflow causes the 

following error message to be printed during the host program execution: 

cannot parse auto-discovery string at byte offset 4096 

Output from printf is never intermixed, even though work-items may execute printf functions 

concurrently; however, the order of concurrent printf execution is not guaranteed. In other words, printf 

outputs may not appear in program order if the printf instructions are in concurrent data paths 

Table 7. Supported Scalar and Vector Argument Built-in Geometric Functions 

Argument Type 

Function 

float double 

cross v v 

dot v v 

distance v v 

length v v 

normalize v v 

fast_distance v — 

fast_length v — 

fast_normalize v — 


Programming Guide




Numerical Compliance Implementation 

Section 7 of the OpenCL Specification version 1.0 describes features of the C99 and IEEE 

754 standards that must be supported by OpenCL compliant devices. The Altera SDK 

for OpenCL operates on 32-bit and 64-bit floating-point values in IEEE Standard 754- 

2008 format, but not all floating-point operators have been implemented, as 

summarized in Table 8. 

Table 8. Numerical Compliance Implementation 


7.1 Rounding Modes v* 

7.2 

Image Addressing and Filtering Implementation 

Image addressing and filtering are not supported. The SDK does not support images. 

Optional Extensions 

INF, NaN and Denormalized 

Numbers 

v* 

Conversions between integer and single and half 

precision floating-point types support all rounding 

modes. 

*Conversions between integer and double precision 

floating-point types support all rounding modes on a 

preliminary basis. This feature might not conform with 

the OpenCL Specification version 1.0. 

INF and NaN results for single precision operations are 

generated in a manner that conforms with the OpenCL 

Specifications version 1.0. Most operations that handle 

denormalized numbers are flushed prior to and after a 

floating-point operation. 

*Double precision floating-point operation is supported 

on a preliminary basis. This feature might not conform 

with the OpenCL Specifications version 1.0. 

7.3 Floating-Point Exceptions X The SDK discards floating-point exceptions. 

7.4 Relative Error as ULPs v* 

7.5 Edge Case Behavior v 

Single precision floating-point operations conform with 

the numerical accuracy requirements for an embedded 

profile of the OpenCL Specification version 1.0. 

*Double precision floating-point operation support is 

preliminary. This feature might not conform with the 

OpenCL Specification version 1.0. 

Section 9 of the OpenCL Specification version 1.0 describes a list of optional features that 

may be supported by some OpenCL implementations. 

■ Section 9.5: Atomic Functions for 32-bit integers—The SDK offers preliminary 

support for all 32-bit global and local memory atomic functions described in 

Section 6.12.11: Atomic Functions of the OpenCL Specification version 1.2. This feature 

might not conform with the OpenCL Specification version 1.0. 

1 The implementation of atomic functions may lower the performance of 

your design. The constraint on performance (F max) increases if more than 

one type of atomic functions are used in the kernel. 


Document Revision History Page 23 

Embedded Profile Implementation 


Section 10 of the OpenCL Specification version 1.0 describes the OpenCL embedded 

profile. The Altera SDK for OpenCL conforms with the OpenCL embedded profile 

with clarifications and exceptions summarized in Table 9. 

Multiple Host Threads 

Document Revision History 

Table 10. Document Revision History 

Table 9. Clarifications and Exceptions to OpenCL Embedded Profile 

Clause Feature Supported Notes 

1 64-bit integers v 

2 3D images X The SDK does not support images. 

3 

Create 2D and 3D images with 

image_channel_data_type 

values 

X The SDK does not support images. 

4 Samplers X 

5 Rounding modes — 

6 

Restrictions listed for single 

precision basic floating-point 

operations 

7 half type X 

8 

Error bounds listed for conversions 

from CL_UNORM_INT8, 

CL_SNORM_INT8, 

CL_UNORM_INT16 and 

CL_SNORM_INT16 to float 

Appendix A.2 Multiple Host Threads of the OpenCL Specification version 1.0—The 

Altera SDK for OpenCL host library is not thread safe. 

Table 10 lists the revision history for this document. 

X 

X 

This clause of the OpenCL Specification version 1.0 

does not apply to the SDK. 

Refer to Table 5 on page 16 for a list of allocation 

limits. 

Date Version Changes 

May 2013 13.0.0 

Updated compilation flow. 

Updated kernel compiler commands. 

Included Altera SDK for OpenCL Utility commands. 

Inserted a OpenCL Programming Considerations section. 

Updated flash programming procedure and moved it to Appendix A. 

Included a new clCreateProgramWithBinary FPGA hardware programming flow; moved the old 

clCreateProgramWithBinary hardware programming flow to Appendix A. 

Moved updated information on allocation limits and OpenCL language support to Appendix B. 

November 2012 12.1.0 Initial release. 


Programming Guide

Page 24 Document Revision History

aocl_programming_guide

You also want an ePaper? Increase the reach of your titles

Delete template?

Save as template?