diff --git a/doc/AddingLambdasToAparapi.md b/doc/AddingLambdasToAparapi.md
new file mode 100644
index 0000000000000000000000000000000000000000..4d8878eeaeb4f8781f223362265d348a43a12893
--- /dev/null
+++ b/doc/AddingLambdasToAparapi.md
@@ -0,0 +1,103 @@
+#AddingLambdasToAparapi
+*Adding Java 8 Lambda Support to Aparapi Updated Jun 24, 2013 by frost.g...@gmail.com*
+
+In the recently added ''lambda'' branch we have been experimenting with adding lambda support to Aparapi. We believe that this upcomming Java 8 feature will be a natural way to express parallel algorithms which can be executed on the GPU.
+
+A link to the branch can be found here preview.
+
+You will need to get the latest binary build of ''Project Lambda'' to experiment with these new features. The 'Project Lambda' preview can be found here.
+
+Once you have a Lambda enabled Java 8 JDK Java set JAVA_HOME to your Java8 Lambda enabled compiler and build Aparapi.
+
+So from the root of SumatraExperiments just use
+
+ $ ant
+We are slowly walking through some of the Aparapi demos and converting them. At present NBody and Mandel have been converted.
+
+With Lambda enabled Aparapi we remove the need to derive from a base Kernel class, we will allow the user to express their code as a lambda using the following basic pattern
+
+ Device.bestGPU().forEach(int range, IntConsumer lambda);
+The Java 8 stream API defines a type called java.util.function.IntConsumer. This is essentially an interface with a Single Abstract Method (these types are referred to as SAM types in the stream API code).
+
+IntConsumer looks something like....
+
+ interface IntConsumer{
+ public void accept(int Id);
+ }
+So you can run the familiar 'squares' kernel using
+
+ int in[] = ..//
+ int out[] = .../
+ Device.bestGPU().forEach(in.length, (i)->{
+ out[i] = in[i]*in[i];
+ });
+Instead of
+
+ int in[] = ..//
+ int out[] = .../
+ Device.bestGPU().forEach(in.length, new IntConsumer(){
+ public void accept(int i){
+ out[i] = in[i]*in[i];
+ }
+ });
+To accomodate lambda's we created Device.forEach(int range, IntConsumer ic) which converts the bytecode of the ic parameter to OpenCL at runtime. The captured args (in, out and i - in this case) are passed to the GPU and the kernel executed.
+
+During our early experiments we encountered an interesting issue. The new 'lambdafied' javac uses Java 7 method handles and invoke dynamic instructions to dispatch the lambda code. It does this by injecting a call to a MethodHandle factory into the call site. At runtime, this factory creates a synthetic class (to capture call-site args) and passes this to our Device.forEach().
+
+We needed to analyse this synthetically generated class in order to work out which args need to be sent to the GPU. Of course we have a bunch of tools already in Aparapi for analyzing bytecode, but this code expects to find bytecode in class files (either in a Jar or on the disk), we had to find a way to access these classfile bytes to Aparapi.
+
+We have a couple of proposed solutions for solving this. The most promising is to turn the aparapi.dll/aparapi.so native library (used by Aparapi at runtime) into a JVMTI agent (like hprof). JVMTI agents are native libraries which have access to some aspects of a running JVM (via the JVM Tool Interface). We havea prototype JVMTI agent which 'listens' for classfiles which represent these 'synthetic lambda helpers' and allows us to get hold of the bytecode for these classes.
+
+This will mean that in future we will change how Aparapi is launched.
+
+Instead of
+
+ $ java -Djava.library.path=path/to/aparapi -classpath path/to/aparapi/aparapi.jar:your.jar YourClass
+We will use
+
+ $ java -agentlib=path/to/aparapi/aparapi.dll -classpath path/to/aparapi/aparapi.jar:your.jar YourClass
+We are also looking into the possibility of having this agent provide the bytecode for all Aparapi classes. We believe that this will enable us to ultimately remove MethodModel/ClassModel and even the InstructionSet classes and handling all of this in JNI.
+
+We would welcome comments on these proposals. Either here, or in the discussion list. Let us know what you think.
+
+##Consequences of lambdification of Aparapi.
+
+* No support for local memory, group size or barriers in Lambda form
+* Calls to Kernel base class methods (such as getGlobalId()) will not be allowed. The 'global id' will be passed as an arg to the lambda.
+* We will need to add support for calling static methods (of course the bytecode for the called methods cannot violate Aparapi restrictions).
+* We might need to drop support for multi dimension dispatch. This is more a convergence story with Sumatra (which is unlikely to support this)
+* Unlikely that explicit buffer management will be simple.
+* We can use lambda's for control as well as the kernel itself. See examples below.
+
+##Alternate forms for kernel dispatch
+
+This version would allow us to carry over Aparapi's device selection
+
+ Device.bestGPU().forEach(1024, i->{lambda});
+This version would allow us to carry over Aparapi's Range selection
+
+ Device.bestGPU().range2D(width, height).forEach(1024, rid->{lambda});
+This version would allow us to mimic Kernel.execute(1024, 5)
+
+ Device.bestGPU().forEach(1024, 5, (id, passid)->{lambda});
+We could even have the range iterated over until some other lambda determines we are done
+
+ Device.bestGPU().forEachUntil(1024, id->{lambda}, ->{predicate lambda});
+Explicit buffer handling could be removed in many cases by allowing the bytecode of the 'until' predicate to be snooped for buffer references.
+
+ int lotsOfData[] = ...;
+ boolean found[false] = new boolean[1];
+ Device.bestGPU().forEachUntil(1024, 5,
+ (id, passid)->{ /* mutate lotsOfData, found[0]=true when done */ }
+ ->{found[0]]});
+In the above cases Aparapi can determine that between each pass it needs to ''ONLY'' copy found[] back from the device.
+
+There is no reason that the range itself needs to be constant, we can use a collection/iterable. This helps with some reductions.
+
+ int range[] = new int[]{1024,512,128,64,32,16,8,4,2,1,0};
+ Device.bestGPU().forEach(range,{lambda});
+or the range can be a lambda itself, here we specify a start and end value for the range itself, and a lambda to provide each step.
+
+ Device.bestGPU().forEach(1024, 1, r->{return(r/2);},(pass, r, id)->{lambda});
+ // or
+ Device.bestGPU().forEach(1, 1024, r->{return(r*2);},(pass, r, id)->{lambda});
\ No newline at end of file
diff --git a/doc/privatememoryspace.md b/doc/PrivateMemorySpace.md
similarity index 100%
rename from doc/privatememoryspace.md
rename to doc/PrivateMemorySpace.md
diff --git a/doc/README.md b/doc/README.md
index 280f18664896875ed8d55ee77783a1b09b967771..0354093d77dba7bfa35c8f2b047393fe02095f32 100644
--- a/doc/README.md
+++ b/doc/README.md
@@ -3,7 +3,7 @@ APARAPI Documentation
| | |
|----------------|------|
-| [PrivateMemorySpace](privatememoryspace.md)| Using `__private` memory space in Aparapi kernels. |
+| [PrivateMemorySpace](PrivateMemorySpace.md)| Using `__private` memory space in Aparapi kernels. |
| [SettingUpLinuxHSAMachineForAparapi](SettingUpLinuxHSAMachineForAparapi.md) | How to setup a Linux HSA machine for testing HSA enabled Aparapi |
| [PossibleAparapiLambdaSyntaxOptions](PossibleAparapiLambdaSyntaxOptions.md) | Syntax suggestions for HSA enabled Aparapi |
| [HSAEnablementOfLambdaBranchSidebar](HSAEnablementOfLambdaBranchSidebar.md)| Sidebar for HSAEnablementOfLambdaBranchAparapi|
@@ -11,7 +11,7 @@ APARAPI Documentation
| [UsingAparapiLambdaBranchWithHSASimulator](UsingAparapiLambdaBranchWithHSASimulator.md) | One-sentence summary of this page. |
| [SettingUpLinuxHSAMachineForAparapiSidebar](SettingUpLinuxHSAMachineForAparapiSidebar.md) | Sidebar for SettingUpLinuxHSAMachineForAparapi |
| HSASidebar | |
-| AddingLambdasToAparapi | Adding Java 8 Lambda Support to Aparapi |
+| [AddingLambdasToAparapi](AddingLambdasToAparapi.md) | Adding Java 8 Lambda Support to Aparapi |
| ProfilingKernelExecution | Using Aparapi's built in profiling APIs |
| HowToAddUML | How to add plantuml docs to wiki pages |
| LIbraryAgentDuality | Aparapi libraries can now be loaded as JVMTI agents. |
diff --git a/doc/SettingUpLinuxHSAMachineForAparapiSidebar.md b/doc/SettingUpLinuxHSAMachineForAparapiSidebar.md
index e69de29bb2d1d6434b8b29ae775ad8c2e48c5391..9d165df7e1fa5bd66761b5b95482d60225adb6ec 100644
--- a/doc/SettingUpLinuxHSAMachineForAparapiSidebar.md
+++ b/doc/SettingUpLinuxHSAMachineForAparapiSidebar.md
@@ -0,0 +1,10 @@
+#SettingUpLinuxHSAMachineForAparapiSidebar
+*Sidebar for SettingUpLinuxHSAMachineForAparapi*
+
+* HSA Videos
+ * [http://www.youtube.com/watch?v=5ntILiXTuhE](http://www.youtube.com/watch?v=5ntILiXTuhE)
+ * [http://www.youtube.com/watch?v=caEPq4KvTTA](http://www.youtube.com/watch?v=caEPq4KvTTA)
+* HSA Articles
+ * [http://developer.amd.com/resources/heterogeneous-computing/what-is-heterogeneous-computing/](http://developer.amd.com/resources/heterogeneous-computing/what-is-heterogeneous-computing/)
+* HSA Foundation
+ * [https://github.com/HSAFoundation](https://github.com/HSAFoundation)
\ No newline at end of file
diff --git a/doc/settinguplinuxhsamachineforaparapi.md b/doc/settinguplinuxhsamachineforaparapi.md
deleted file mode 100644
index 8bf0981a091bfce0a09a1c6e6d395014eb1225e6..0000000000000000000000000000000000000000
--- a/doc/settinguplinuxhsamachineforaparapi.md
+++ /dev/null
@@ -1,213 +0,0 @@
-# Setting up Linus HSA machine for APARAPI
-*How to setup a Linux HSA machine for testing HSA enabled Aparapi Updated May 22, 2014 by frost.g...@gmail.com*
-## Introduction
-Now that HSA hardware is generally available I figured it was time to describe how to setup a HSA enabled Linux platform so that it can run Aparapi.
-
-Here is [a nice introduction to HSA](http://developer.amd.com/resources/heterogeneous-computing/what-is-heterogeneous-system-architecture-hsa/)
-
-But for Aparapi users the main advantage is that we are no longer limited to the GPU memory for running GPU tasks. Also because the CPU and the GPU can both see the same memory (the Java heap) Aparapi code can now access Java objects directly. This removes a number of Aparapi constraints. So more of your code can now run on the GPU.
-
-##Hardware Required
-These instructions were based on my experience setting up a platform using the following hardware.
-
-|Component | Suggested |
-|-----------|-------------------------------------------------------------------------------------------------------------|
-|APU | AMD A10-7850K APU [http://www.amd.com/us/products/desktop/processors/a-series/Pages/a-series-apu.aspx](http://www.amd.com/us/products/desktop/processors/a-series/Pages/a-series-apu.aspx) |
-| Motherboard | ASUS A88X-PRO or A88XM-A [http://www.asus.com/Motherboards/A88XPRO http://www.asus.com/Motherboards/A88XMA](http://www.asus.com/Motherboards/A88XPRO http://www.asus.com/Motherboards/A88XMA) |
-|Memory | G.SKILL Ripjaws X Series 16GB (2 x 8GB) 240-Pin DDR3 SDRAM DDR3 2133 |
-
-##Software Required
-We also have some software dependencies.
-
-|Component | Suggested |
-|-------------------------------------------------------|------------------------------------------------------------------------------|
-|Java 8 JDK | http://www.oracle.com/technetwork/java/javase/downloads/ea-jsp-142245.html |
-| Ubuntu 13.10 64-bit edition | http://www.ubuntu.com/download |
-| Ubuntu 13.10 64-bit edition HSA enabled kernel image | https://github.com/HSAFoundation/Linux-HSA-Drivers-And-Images-AMD |
-| OKRA HSA enabled runtime | https://github.com/HSAFoundation/Okra-Interface-to-HSA-Device |
-
-The hope is that the list of HW/SW support widens, but for early adopters this is the set of HW/SW we have been testing with.
-
-##Setting up your System
-Configure your BIOS to support IOMMU
-Once you have built your AMD A10-7850K APU based system you should make sure that your system is configured to use IOMMU.
-
-Remember HSA allows the GPU and CPU cores to share the same memory. IOMMU needs to be enabled for this.
-
-##For the A88X-PRO board
-For the recommended ASUS board above you will need to make sure that your BIOS is updated to version 0802. Here is a direct link to the 0802 version of the BIOS from ASUS's site as of 2/28/2014.
-
-[http://dlcdnet.asus.com/pub/ASUS/mb/SocketFM2/A88X-PRO/A88X-PRO-ASUS-0802.zip](http://dlcdnet.asus.com/pub/ASUS/mb/SocketFM2/A88X-PRO/A88X-PRO-ASUS-0802.zip)
-
-Once you have the latest BIOS you will need to enable IOMMU in the system BIOS. This is done using the "CPU Configuration" screen under "Advanced Mode" and then enabling IOMMU.
-
-##For the A88XM-A
-You will need the 1102 (or later) version of the BIOS
-
-[http://dlcdnet.asus.com/pub/ASUS/mb/SocketFM2/A88XM-A/A88XM-A-ASUS-1102.zip](http://dlcdnet.asus.com/pub/ASUS/mb/SocketFM2/A88XM-A/A88XM-A-ASUS-1102.zip)
-
-Once you have the latest BIOS you will need to enable IOMMU in the system BIOS. This is done using the "CPU Configuration" screen under "Advanced Mode" and then enabling IOMMU.
-
-##Installing Ubuntu 13.10
-Once you have your BIOS setup you need to install Ubuntu [http://www.ubuntu.com/download](http://www.ubuntu.com/download)
-
-Installing HSA enabled kernel + driver
-Until all of the HSA drivers and features are available in stock linux and have been pulled down into Ubuntu distro we will need a special HSA enabled kernel image.
-
-A Ubuntu compatible kernel can be pulled from github
-
- $ cd ~ # I put all of this in my home dir
- $ sudo apt-get install git
- $ git clone https://github.com/HSAFoundation/Linux-HSA-Drivers-And-Images-AMD.git
-
-Or you can pull the zip and unzip using curl if you don't have git
-
- $ cd ~ # I put all of this in my home dir
- $ curl -L https://github.com/HSAFoundation/Linux-HSA-Drivers-And-Images-AMD/archive/master.zip > drivers.zip
- $ unzip drivers.zip
-
-This will create the following subdir on your machine
-
- Linux-HSA-Drivers-And-Images-AMD/
- LICENSE
- README.md
- ubuntu12.10-based-alpha1/
- xorg.conf
- linux-image-3.13.0-kfd+_3.13.0-kfd+-2_amd64.deb
-
-
-From here we can install our new image and setup the HSA KFD (the driver for HSA)and reboot to the new kernel.
-
- $ cd ~/Linux-HSA-Drivers-And-Images-AMD
- $ echo "KERNEL==\"kfd\", MODE=\"0666\"" | sudo tee /etc/udev/rules.d/kfd.rules
- $ sudo dpkg -i ubuntu13.10-based-alpha1/linux-image-3.13.0-kfd+_3.13.0-kfd+-2_amd64.deb
- $ sudo cp ~/Linux-HSA-Drivers-And-Images-AMD/ubuntu13.10-based-alpha1/xorg.conf /etc/X11
- $ sudo reboot
-
-##Installing OKRA RT
-Now we need a runtime for executing HSAIL code. We share common infrastructure used by our sister OpenJDK project called Sumatra. Both Aparapi and Sumatra use OKRA to execute HSAIL code on a HSA enabled platform.
-
-We can get the latest version using of OKRA (Offloadable Kernel Runtime API) from another HSA foundation repository.
-
- $ cd ~ # I put all of this in my home dir
- $ git clone https://github.com/HSAFoundation/Okra-Interface-to-HSA-Device.git
-
-or if you prefer curl/unzip
-
- $ cd ~ # I put all of this in my home dir
- $ curl -L https://github.com/HSAFoundation/Okra-Interface-to-HSA-Device/archive/master.zip > okra.zip
- $ unzip okra.zip
-
-This will create the following dir structure.
-
- Okra-Interface-to-HSA-Device/
- README.md
- okra/
- README
- dist/
- okra.jar
- bin/
- libamdhsacl64.so
- libnewhsacore64.so
- libokra_x86_64.so
- include/
- common.h
- okraContext.h
-
- samples/
- dist/
- Squares
- Squares.hsail
- runSquares.sh
-
-OKRA offers a C API (for those that are so inclined ;) ) as well as a java jar file which contains JNI wrappers.
-
-##Sanity check your HSA and OKRA install
-So to sanity check your install you can run a small sample app (binary)
-
- $ cd ~/Okra-Interface-to-HSA-Device/okra/samples/
- $ sh runSquares.sh
-
-If everything is OK this should run the C Squares test app.
-
-Congratulations, you have executed your first HSA enabled app.
-
-##Getting OpenCL headers and libraries
-We need OpenCL headers and libraries to build Aparapi (remember we still support OpenCL).
-
-My recommendation is to download AMD-APP-SDK-v2.9-lnx64.tgz from [http://developer.amd.com/tools-and-sdks/heterogeneous-computing/amd-accelerated-parallel-processing-app-sdk/downloads](http://developer.amd.com/tools-and-sdks/heterogeneous-computing/amd-accelerated-parallel-processing-app-sdk/downloads) and extract the libraries and headers.
-
-Note that we have nested zipped jars in this archive.
-
- $ cd ~
- $ gunzip ~/Downloads/AMD-APP-SDK-v2.9-lnx64.tgz
- $ tar xvf ~/Downloads/AMD-APP-SDK-v2.9-lnx64.tar
- $ rm ~/default-install_lnx_64.pl ~/icd-registration.tgz ~/Install-AMD-APP.sh ~/ReadMe.txt
- $ gunzip ~/AMD-APP-SDK-v2.9-RC-lnx64.tgz
- $ tar xvf ~/AMD-APP-SDK-v2.9-RC-lnx64.tar
- $ rm ~/AMD-APP-SDK-v2.9-RC-lnx64.tar
- $ rm -rf AMD-APP-SDK-v2.9-RC-lnx64/samples
-
-Note where AMD-APP-SDK-v2.9-RC-lnx64 is located, you need this in the following step.
-
-##You will need Java 8
-Download Java 8 JDK from [https://jdk8.java.net/download.html](https://jdk8.java.net/download.html) I chose to download the zipped tar and not install with RPM so I can control the location of the install.
-
- >$ cd ~
- $ gunzip /home/gfrost/Downloads/jdk-8-fcs-bin-b132-linux-x64-04_mar_2014.tar.gz
- $ tar xvf ~/Downloads/jdk-8-fcs-bin-b132-linux-x64-04_mar_2014.tar
-
-I now have ~/jdk1.8.0 as my java 8 install dir.
-
-Alternatively the following will pull from Oracles site using curl
-
- $ cd ~
- $ curl http://download.java.net/jdk8/archive/b132/binaries/jdk-8-fcs-bin-b132-linux-x64-04_mar_2014.tar.gz?q=download/jdk8/archive/b132/binaries/jdk-8-fcs-bin-b132-linux-x64-04_mar_2014.tar.gz > jdk-8-fcs-bin-b132-linux-x64-04_mar_2014.tar.gz
- $ gunzip jdk-8-fcs-bin-b132-linux-x64-04_mar_2014.tar.gz
- $ tar xvf jdk-8-fcs-bin-b132-linux-x64-04_mar_2014.tar
-
-I now have ~/jdk1.8.0 as my java 8 install dir.
-
-You will need ant
- $ sudo apt-get install ant
-
-This takes a long time because in also installs a java7 jdk.
-
-You will need g++
-We use g++ to build the JNI side of Aparapi
-
- $ sudo apt-get install g++
-
-##Pulling the HSA enabled Aparapi branch and building
-Now we can pull the Aparapi lambda/HSA branch from SVN
-
- $ sudo apt-get install subversion
- $ svn checkout https://aparapi.googlecode.com/svn/branches/lambda aparapi-lambda
-
-If you are familiar with Aparapi structure then this tree should not be that much of a surprise but there are a few subtle changes.
-
-Specifically the build system has been changed to support OKRA, Aparapi JNI code is provided as a Java agent and the execution scripts all refer to ${APARAPI_HOME}/env.sh to setup a reasonable execution environment.
-
-You will need to edit env.sh and make sure that APARAPI_HOME, OKRA_HOME, OCL_HOME and JAVA_HOME correctly.
-
-Here are how I set my vars.
-
-|environment variable |value |
-|-----------------------|----------------------------------------------------|
-|JAVA_HOME |/home/${LOGNAME}/jdk1.8.0 |
-|OCL_HOME |/home/${LOGNAME}/AMD-APP-SDK-v2.9-RC-lnx64 |
-|APARAPI_HOME |/home/${LOGNAME}/aparapi-lambda |
-|OKRA_HOME |/home/${LOGNAME}/Okra-Interface-to-HSA-Device/okra/ |
-
-It is recommended (thanks notzed ;) ) that you test your env.sh using sh env.sh until it stops reporting errors. Once you have finished I recommend sourcing it into your current shell before building with ant.
-
- $ cd ~aparapi-lambda
- $ . env.sh
- $ ant
-
-If you get any problems check the env.sh vars first.
-
-If all is well you should be able to run some samples.
-
- $ cd ~/aparapi-lambda/samples/mandel
- $ sh hsailmandel.sh
\ No newline at end of file