Syncleus · freemo · Mar 1, 2015 · Mar 1, 2015 · Mar 1, 2015 · Mar 2, 2015
diff --git a/.gitignore b/.gitignore
@@ -31,3 +31,7 @@ hs_err_pid*
 /.libs/
 /findbugs/
 /target/
+
+# java files
+*.class
+*~
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,21 @@
 # Aparapi Changelog
 
+## 2.0.0
+
+* Fixed OpenCL compilation which would throw null kernel or JNI linking exceptions.
+* work on config, mem override, mem align, sync with java-ucores
+* Java for UCores is meant to be an accelerator 'friendly' Java version based on OpenJDK and obuildfactory. Accelerator users should consider using Java for UCores in conjunction with Aparapi UCores as it will automatically allocate memory on boundaries that can enhance PCIE transfer speeds.
+* Added a a more flexible way of per-platform config through ConfigSettings.cpp
+* Support for Altera OpenCL V15
+* Support for platform select using Altera OpenCL V15 ICD
+* Support for selection of binary/source flow for non-Altera platforms (usage examples below)
+* Control dynamic binary/source/default flow through kernel (usage examples below)
+* Device select for systems with multiple devices of the same type (usage examples below)
+* New Configuration Settings file for better per platform settings control (ConfigSettings.h)
+* Improved build system for Altera JNI
+* Aparapi Range.getFactors bug fix – fixed a bug in the original Aparapi distribution.
+* Altera ICD bug fix – only other accelerators were discovered
+
 ## 1.3.3
 
 * Fixed a bug where calling createProgram resulted in an exception.
@@ -37,4 +53,4 @@
 
 ## 1.1.0
 
-* Changed group id and package to com.aparapi
+* Changed group id and package to com.aparapi
diff --git a/LICENSE b/LICENSE
@@ -198,5 +198,4 @@ Apache License
    distributed under the License is distributed on an "AS IS" BASIS,
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    See the License for the specific language governing permissions and
-   limitations under the License.
-
+   limitations under the License.
diff --git a/README.md b/README.md
@@ -20,6 +20,24 @@ Aparapi was originally a project conceived and developed by AMD corporation. It
 
 Aparapi Javadocs: [latest](http://www.javadoc.io/doc/com.aparapi/aparapi) - [1.3.2](http://www.javadoc.io/doc/com.aparapi/aparapi/1.3.2) - [1.3.1](http://www.javadoc.io/doc/com.aparapi/aparapi/1.3.1) - [1.3.0](http://www.javadoc.io/doc/com.aparapi/aparapi/1.3.0) - [1.2.0](http://www.javadoc.io/doc/com.aparapi/aparapi/1.2.0) - [1.1.2](http://www.javadoc.io/doc/com.aparapi/aparapi/1.1.2) - [1.1.1](http://www.javadoc.io/doc/com.aparapi/aparapi/1.1.1) - [1.1.0](http://www.javadoc.io/doc/com.aparapi/aparapi/1.1.0) - [1.0.0](http://www.javadoc.io/doc/com.syncleus.aparapi/aparapi/1.0.0)
 
+The original Aparapi framework was built with GPUs/APUs in mind. We believe that heterogeneous computing has a lot more to offer than just combining CPUs and GPUs together. In the past few years we have started to see OpenCL support for FPGAs (Altera/Xilinx) and DSPs(TI) and more types computing devices will soon follow suite.
+
+Combining several types of devices and architectures is at the heart of heterogeneous computing's power efficiency advantage. We believe that in order to optimize performance per watt and accommodate the needs of today's high level programming requirements we need to be able to work with all these types of devices using a single high level code base.
+
+The framework has been tested and known to work on the following device types/OpenCL SDKs*:
+1. CPUs (AMD/Intel)
+2. GPUs (AMD/NVidia)
+2. APUs (AMD)
+3. FPGAs(Altera - Nallatech/Terasic boards)
+
+Changes from original work
+-----------------------------------
+1. Support for FPGA devices (right now Altera OpenCL is supported)
+2. Support for multiple platforms (platform selection)
+3. Support for accelerators and OpenCL binary file format and flow
+3. Built against OpenJDK (to allow more control/flexibility in future Java/OpenCL integration)
+4. Misc small changes - Improve profiling usability etc.
+
 For detailed documentation see [Aparapi.com](http://Aparapi.com) or check out the [latest Javadocs](http://www.javadoc.io/doc/com.aparapi/aparapi).
 
 For support please use [Gitter](https://gitter.im/Syncleus/aparapi) or the [official Aparapi mailing list](https://groups.google.com/d/forum/aparapi).
@@ -100,3 +118,63 @@ Kernel kernel = new Kernel() {
 Range range = Range.create(result.length);
 kernel.execute(range);
 ```
+
+Project History 
+---------------
+To the best of my knowledge the original idea of trying to target FPGAs from Java using Aparapi was the brain child of Sai Rahul Chalamalasetti and Mitch Wright from HP Servers. 
+
+I started writing the first implementation of the project (called APARAPI-FPGA's) while working as an intern at HP Servers in 2013.  It started as a proof of concept but showed great promise.
+
+During that work I started envisioning a more general solution using Aparapi that will allow us to target any OpenCL device. i.e. not only GPUs or FPGAs.
+
+The project culminated with two publications in Sept 2014 (FPL 2014 and FSP 2014) in which we described our findings and promised to release our initial work back to the open source community.
+
+Since then we received a lot of interest and requests to release the source and we have been planning to release our implementation for some time now.
+
+This project was left on the back burner for a long time, but a couple of months back I started to dedicate some time to rewrite the framework to what I originally envisioned it to be i.e. a general, programmer friendly, high level framework for heterogeneous devices. 
+
+Two things were important to me working towards this public release:
+1. I wanted to make sure it will be something that can be usable by regular Java programmers and not just release another difficult to understand research project that would require significant effort to make it work. 
+2. I wanted to implement the more general idea (not just an FPGA frame work or GPU framework)
+
+The initial release is still far from being programmer "Friendly", but it is a step forward and I hope it will encourage high level programmers to experiment with "exotic" heterogeneous architectures.
+
+I welcome any one that wants to be involved in improving this framework.
+
+If you use this work for academic purposes please reference the original FPL/FSP papers describing our initial Aprapi work(see below).
+
+References
+-----------------------------
+
+The modified Aparapi framework that supports FPGAs was first introduced in the following papers:
+
+Oren Segal, Sai Rahul Chalamalasetti, Mitch Wright and Martin Margala. “High Level Programming Framework for FPGAs in the Data Center”, Field Programmable Logic and Applications (FPL), 2014 24th International Conference on. IEEE, 2014.
+http://ieeexplore.ieee.org/xpls/abs_all.jsp?arnumber=6927442
+
+Segal, Oren, Martin Margala, Sai Rahul Chalamalasetti, and Mitch Wright. “High Level Programming for Heterogeneous Architectures.” arXiv preprint arXiv:1408.4964 (2014).
+http://arxiv.org/abs/1408.4964
+
+The original Aparapi project can be found at:
+https://code.google.com/p/aparapi/
+
+This work is part of the Heterogeneous computing research that is conducted by the Mora research group at UML:
+http://mora.uml.edu/
+
+Documentation
+---------------
+For information on how to setup the environment and run some tests please check the [project root]/docs folder:
+https://gitlab.com/mora/aparapi-ucores/tree/master/docs
+
+Wiki:
+https://gitlab.com/mora/aparapi-ucores/wikis/home
+
+Screenshots:
+https://gitlab.com/mora/aparapi-ucores/wikis/Screenshots
+
+Acknowledgments
+---------------
+1. AMD for doing such a great job with Aparapi without which this project would be an order of magnitude more complex.
+
+2. HP Servers which believed back in 2012 that Java-OpenCL on FPGAs is something worth looking at.
+
+3. Altera, Nallatech and Terassic for contributing FPGA hardware for us to develop and test on.
diff --git a/docs/APARAPIInstallationNotes.txt b/docs/APARAPIInstallationNotes.txt
@@ -0,0 +1,41 @@
+---------------------------------------------------------
+APARAPI Installation Notes for CentOS release 6.x (Tested on 6.3/4/5/6)
+---------------------------------------------------------
+
+* Note default CentOs repository versions of Java(1.6) and Ant(1.7) are not compatible with latest APARAPI svn src
+  need to download newr versions (see below)
+
+- install Java JDK
+  sudo yum install java-1.7.0-openjdk-devel
+
+- install ANT
+  Download latest ANT -> currently apache-ant-1.9.1-bin.tar.gz
+  sudo tar xvzf apache-ant-1.9.1-bin.tar.gz -C /opt
+  sudo ln -s /opt/apache-ant-1.9.1 /opt/ant
+
+- install AMD APP SDK
+
+  - needed for build even if hardware not available
+
+- install git
+
+- install g++
+
+  sudo yum install gcc-c++
+
+- get src from git repository
+
+  git clone ... [project folder]
+
+- set environment vars
+
+  source [project folder]/env/aparapiBuildEnv
+
+- build
+
+  cd [project folder]/src/aparapi
+
+  ant clean build dist
+
+
+
diff --git a/docs/AparapiUcoresBinaryFlow.txt b/docs/AparapiUcoresBinaryFlow.txt
@@ -0,0 +1,34 @@
+Aparapi Ucores Binary Flow
+--------------------------
+
+This is currently used only for FPGAs but we plan to expand it for general manual optimization/compilation of OpenCL source code.
+
+A Binary flow is one where the Aparapi framework generates an OpenCL file while running and then tries to read and execute the binary compilation of that source file.
+
+Sequence of events
+------------------
+
+1. Aparapi Application is executed. Aparapi automatically generates an OpencL source file describing the kernel(file name is the full java kernel class name.cl)
+
+2. Aparapi Application automatically tries to load the binary compiled file (full java kernel class name.aocx)
+
+3. If Aparapi Application finds the compiled file it executes the compiled kernel (runs the kernel on the accelerator) else it will revert to JTP mode in which case the application runs as specified without acceleration (JTP mode). A simulation mode if you will.
+
+How this works for FPGAs
+------------------------
+
+1. We first run the Application CPU/GPU/ACC mode. Aparapi-Ucores will generate an OpenCL file (ClassXXXName.cl), but will not find the equivalent binary file (ClassXXXName.aocx). It will revert to another execution mode such as JTP. We can simulate if the kernel works logically correct using JTP.
+
+2. We feed the OpenCL file (ClassXXXName.cl) to an FPGA OpenCL compiler.
+
+Example:
+
+	a. aoc ClassXXXName.cl -O3 --board pcie385n_a7 -v --report
+
+	b. Wait until an optimized FPGA design is created...currently takes several hours
+
+	c. Output of the compiler will be: ClassXXXName.aocx
+
+	3. Copy the binary output file (ClassXXXName.aocx) to folder where the .cl file resides.
+
+4. Run application again in ACC/GPU mode. This time Aparapi will detect the ClassXXXName.aocx and use the FPGA as the acclerator.
diff --git a/docs/HowToBuildAPARAPI.txt b/docs/HowToBuildAPARAPI.txt
@@ -0,0 +1,63 @@
+
+---------------------------------------------------------
+How to build APARAPI from the cmd line after modifications to code 
+---------------------------------------------------------
+* first read APARAPI Installation Notes (APARAPIInstallationNotes.txt) for general instructions on getting the project setup and initial build steps
+
+- open new terminal window 
+
+- set environment variables
+
+  source [project folder]/env/AlteraV14Env 
+
+- to build the APARAPI src tree
+
+  cd [project folder]/src/aparapi
+
+  ant clean build dist
+
+  * this does not build the jni proxy with FPGA support automatically (see below for jni FPGA build)
+
+- to build the APARAPI jni proxy library (should run after initial build and after any changes to CPP source files)
+
+  - goto jni dir  
+
+   cd [project folder]/src/aparapi/com.amd.aparapi.jni/
+
+  - to use ant to build standard jni version *
+
+   ant 
+
+  - to use ant to build FPGA jni version *
+
+   ant -f build_altera_ocl.xml 
+
+* The output of the com.amd.aparapi.jni build is a dll stored in dist folder:
+
+  [project folder]/src/aparapi/com.amd.aparapi.jni/dist/libaparapi_x86_64.so
+
+If you have a system where you want to have both FPGA and standard versions available (i.e. with multi OpenCL hardware platforms)you can simply copy the dll's to diffrent locations after the build and link to them through the java vm command line parameters:
+
+Example:
+
+Copy the fpga and standard dll's to the following locations respectively:
+/src/aparapi/com.amd.aparapi.jni/dist.fpga/libaparapi_x86_64.so
+/src/aparapi/com.amd.aparapi.jni/dist.std/libaparapi_x86_64.so
+
+To select one JNI version or the other at execution time run use the following paramaters to the java command:
+java -Djava.library.path=../../com.amd.aparapi.jni/dist.std  [rest of cmd line]
+java -Djava.library.path=../../com.amd.aparapi.jni/dist.fpga [rest of cmd line]
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/docs/HowToRunAPARAPI.txt b/docs/HowToRunAPARAPI.txt
@@ -0,0 +1,62 @@
+
+---------------------------------------------------------
+How to run APARAPI tests from the cmd line
+---------------------------------------------------------
+
+- open new terminal window 
+
+- set environment variables
+
+  source [project folder]/env/AlteraV14Env 
+
+- got to either samples/examples
+
+  - samples dir -> 
+
+    cd [project folder]/src/aparapi/samples
+
+  - examples dir-> 
+
+    cd [project folder]/src/aparapi/examples/
+
+- to run any sample or example: 
+
+  - run the shell script file named after the sample/example name and specify type of run
+
+  Format is*:
+
+  sh [name].sh [ACC|CPU|JTP|GPU|SEQ]
+
+  Examples:
+
+  - run nbody simulation
+    cd [project folder]/src/aparapi/examples/nbody
+    sh nbody.sh JTP
+    sh nbody.sh CPU
+    sh nbody.sh GPU
+    sh nbody.sh ACC
+
+  - run mandel
+    cd [project folder]/src/aparapi/samples/mandel/
+    sh mandel.sh JTP
+    sh mandel.sh CPU
+    sh mandel.sh GPU
+    sh mandel.sh ACC
+
+
+* For more sophisticated use cases with dual configs(fpga/std) you can use the following format:
+
+  sh [name].std.sh [ACC|CPU|JTP|GPU|SEQ]
+
+  sh [name].fpga.sh [ACC|CPU|JTP|GPU|SEQ]
+
+You can read more about dual config in how to build aparapi.
+
+
+
+
+
+
+
+
+
diff --git a/docs/WorkingWithMultiplePlatforms.txt b/docs/WorkingWithMultiplePlatforms.txt
@@ -0,0 +1,46 @@
+Working with multiple platforms
+-------------------------------
+
+The original version of Aparapi does not support platform selection (it just chooses the first available one).
+
+This means that in scenarios where you have multiple OpenCL platforms such as AMD, NVidia, Intel, Altera etc. you do not have control over what accelerator device will be used.
+
+One of the changes we made is to allow selection for platforms that support the OpenCL ICD model.
+(https://www.khronos.org/news/permalink/opencl-installable-client-driver-icd-loader)
+
+In the spirit of other Aparapi configuration options for device selection this can be set using a configuration option.
+
+The platform configuration option is called: com.amd.aparapi.platformHint
+
+When this option is set it causes Aparapi to search for the string platformHint inside the available platform names and if it found it will select that platform over other available ones.
+
+You can use it on the command line in the following way:
+
+java -Dcom.amd.aparapi.platformHint=AMD .... 
+
+or
+
+java -Dcom.amd.aparapi.platformHint=NVIDIA .... 
+
+
+Nbody simulation example with platform selection
+---------------------------------------------------------------------
+
+The script nbody.std.no-opengles-platform-select.sh contains the following java command line:
+
+java \
+  -Djava.library.path=../../com.amd.aparapi.jni/dist.std:../third-party/jogamp \
+  -Dcom.amd.aparapi.executionMode=$1 \
+  -Dbodies=$2 \
+  -Dcom.amd.aparapi.platformHint=$3 \
+  -Dheight=600 \
+  -Dwidth=600 \
+  -Djogl.disable.opengles \
+  -classpath ../third-party/jogamp/jogl-all.jar:../third-party/jogamp/gluegen-rt.jar:../../com.amd.aparapi/dist/aparapi.jar:nbody.jar \
+  com.amd.aparapi.examples.nbody.Main 
+
+To choose an AMD GPU for example we would invoke the script in the following way(the third parameter):
+
+nbody.std.no-opengles-platform-select.sh GPU 1024 AMD
+
+
diff --git a/env/AlteraV14Env b/env/AlteraV14Env
@@ -0,0 +1,8 @@
+export QUARTUS_ROOTDIR=/home/sdev/altera/14.0/quartus
+export PATH=$PATH:$QUARTUS_ROOTDIR/bin
+export ALTERAOCLSDKROOT=/home/sdev/altera/14.0/hld
+export LD_LIBRARY_PATH=$ALTERAOCLSDKROOT/host/linux64/lib:$ALTERAOCLSDKROOT/board/nalla_pcie/linux64/lib
+export PATH=$PATH:$ALTERAOCLSDKROOT/bin
+export AOCL_BOARD_PACKAGE_ROOT=/home/sdev/altera/14.0/hld/board/nalla_pcie
+export LM_LICENSE_FILE=[your license file here]
+