diff --git a/doc/README.md b/doc/README.md new file mode 100644 index 0000000000000000000000000000000000000000..03f54fbb0af1f7761258653d0951c661af7f0b25 --- /dev/null +++ b/doc/README.md @@ -0,0 +1,45 @@ +APARAPI Documentation +====================== + + +* [PrivateMemorySpace](privatememoryspace.md) Using __private memory space in Aparapi kernels. Sep 2014 barneydp...@gmail.com +* SettingUpLinuxHSAMachineForAparapi How to setup a Linux HSA machine for testing HSA enabled Aparapi May 2014 frost.g...@gmail.com +* PossibleAparapiLambdaSyntaxOptions syntax suggestions for HSA enabled Aparapi Mar 2014 frost.g...@gmail.com +* HSAEnablementOfLambdaBranchSidebar Sidebar for HSAEnablementOfLambdaBranchAparapi Feb 2014 frost.g...@gmail.com +* HSAEnablementOfLambdaBranch Adding HSA Support to Aparapi lambda branch Feb 2014 frost.g...@gmail.com +* UsingAparapiLambdaBranchWithHSASimulator One-sentence summary of this page. Feb 2014 frost.g...@gmail.com +* SettingUpLinuxHSAMachineForAparapiSidebar Sidebar for SettingUpLinuxHSAMachineForAparapi Feb 2014 frost.g...@gmail.com +* HSASidebar Feb 2014 frost.g...@gmail.com +* AddingLambdasToAparapi Adding Java 8 Lambda Support to Aparapi Jun 2013 frost.g...@gmail.com +* ProfilingKernelExecution Using Aparapi's built in profiling APIs May 2013 frost.g...@gmail.com +* HowToAddUML How to add plantuml docs to wiki pages Apr 2013 frost.g...@gmail.com +* LIbraryAgentDuality Aparapi libraries can now be loaded as JVMTI agents. Jan 2013 frost.g...@gmail.com +* FrequentlyAskedQuestions Frequently Asked Questions Oct 2012 frost.g...@gmail.com +* HomePageSuggestions Oct 2012 ryan.lam...@gmail.com +* ChoosingSpecificDevicesForExecution Using the new Device API's to choose Kernel execution on a specific device. Sep 2012 frost.g...@gmail.com +* Gadgets Gadgetorium Aug 2012 frost.g...@gmail.com +* ConvertingBytecodeToOpenCL How Aparapi converts bytecode to OpenCL Aug 2012 frost.g...@gmail.com +* DevelopersGuideLinux Developer guide for Linux. Aug 2012 frost.g...@gmail.com +* DevelopersGuideWindows Developers guide for Windows. Aug 2012 frost.g...@gmail.com +* EmulatingMultipleEntrypointsUsingCurrentAPI How to emulate multiple entrypoints using existing Aparapi APIs Jul 2012 frost.g...@gmail.com +* MultipleEntryPointSupportProposal How to extend Aparapi to allow multiple entrypoints for kernels Jul 2012 frost.g...@gmail.com +* ExplicitBufferHandling How to minimize buffer transfers Jul 2012 frost.g...@gmail.com +* AparapiPatterns Examples and code fragments to demonstrate Aparapi fetaures. Jul 2012 frost.g...@gmail.com +* ProfilingKernelsFromEclipse Profiling Kernels with AMD profiler in Eclipse (Indigo) May 2012 frost.g...@gmail.com +* DeviceProposal How we might use the extension mechanism devices for general Kernel execution. May 2012 frost.g...@gmail.com +* NewOpenCLBinding How to use new OpenCL binding mechanism. Mar 2012 frost.g...@gmail.com +* AparapiExtensionProposal A proposed aparapi extension mechanism. Feb 2012 frost.g...@gmail.com +* UsingConstantMemory How to make use of constant memory in a Kernel Feb 2012 frost.g...@gmail.com +* UsingLocalMemory How to make use of local memory in a Kernel Feb 2012 frost.g...@gmail.com +* UsingMultiDimExecutionRanges How to use the new Range class (for multi-dim range access) Feb 2012 frost.g...@gmail.com +* AccessingMultiDimNDRangeProposal A proposal for accessing multi-dim ND range execution Dec 2011 frost.g...@gmail.com +* LocalMemoryAndBarrierProposal A proposal for handling local memory and barriers Dec 2011 frost.g...@gmail.com +* AddressSpacesUsingBuffers Proposal For OpenCL address space support using java Buffers instead of arrays. Dec 2011 frost.g...@gmail.com +* BuildingNBody How to build the NBody example. Nov 2011 frost.g...@gmail.com +* UnitTestGuide Unit test Guide Find out how to run Junit tests and how to add new tests. Sep 2011 frost.g...@gmail.com +* NewFeatures New Features added to this open source release of Aparapi. Sep 2011 frost.g...@gmail.com +* UsersGuide Aparapi User's Guide. Sep 2011 frost.g...@gmail.com +* DevelopersGuide Aparapi developers guide. Sep 2011 frost.g...@gmail.com +* ContributionGuide How to contribute (bug fix or features). Sep 2011 frost.g...@gmail.com +* JavaKernelGuidelines What code can and can't be converted to OpenCL by Aparapi. Sep 2011 frost.g...@gmail.com +* Attribution Attribution \ No newline at end of file diff --git a/doc/privatememoryspace.md b/doc/privatememoryspace.md new file mode 100644 index 0000000000000000000000000000000000000000..8c4d304255884134d918b38c296126a38dbc4744 --- /dev/null +++ b/doc/privatememoryspace.md @@ -0,0 +1,32 @@ +PrivateMemorySpace +================== + +## Introduction +The private memory space identifier (just "private" is also recognised) can be applied to struct fields in order to indicate that the data is not shared with/accessible to other kernel instances. Whilst this is the default for non-array data, it must be explicitly applied to array fields in order to make them private. Aparapi now supports arrays in the private memory space. + +The private memory space is generally only suitable for smallish arrays, but is required for certain algorithms, e.g. for those which must mutate (for example, sort or partially sort) an exclusive copy of an array/subarray. + +##Details +In Aparapi there are two mechanisms available to mark a Kernel class member as belonging to the private memory space when mapped to OpenCL code (matching the equivalent functionality for marking items as belonging to the local memory space). Either the field can be named with a suffix plus buffer size, for example + +> protected short[] myBuffer_$private$32 = new short[32]; +or using the Annotation Kernel.PrivateMemorySpace, for example + +> protected @PrivateMemorySpace(32) short[] myBuffer = new short[32]; +The latter should be used in preference to the former. + +Note that OpenCL requires that the size of a private array be fixed at compile time for any kernel. Thus it is not possible for a single Kernel subclass to support private buffers of varying size. Unfortunately this may entail creating multiple subclasses with varying buffer sizes in order to most efficiently support varying private buffer sizes. + +Of course, a single Kernel class can be created which has a private buffer large enough for all use cases, though this may be suboptimal if only a small fraction of the maximum buffer size is commonly required. + +Because private buffers are unshared, they require much more of a GPU's memory than a local or global buffer of the same size, and should therefore be used sparingly and kept as small as possible, as overuse of large private arrays might cause GPU execution to fail on lower-end graphics cards. + +However, private memory space is the fastest of all OpenCls memory spaces, so may in some limited cases might be used to increase execution speed even when the kernel does not need to modify the array and a shared (local or global) array would suffice - for example to provide a smallish lookup-table to replace an expensive function call. + +Without modification, an Aparapi kernel which uses private buffers may fail to work when invoked in Java Threadpool (JTP) mode, because the buffer will be shared across multiple threads. However a simple mechanism exists which allows such buffers to be used safely in JTP execution mode. + +The Kernel.NoCL annotation exists to allow specialised code to be executed when running in Java (or JTP) which is not invoked when running on the GPU. A NoCL method can be inserted at the begining of a Kernel's run() method which sets the private array to a value obtained from a static ThreadLocal<foo[]> where foo is the primitive type of the array in question. This will have no effect upon OpenCL execution, but will allow threadsafe execution when running in java. + +In the project samples, there is a package com.amd.aparapi.sample.median which gives an example of a median image filter which uses a private array of pixel data to apply a distructive median algorithm to a "window" of local pixels. This sample also demonstrates how to use the ThreadLocal trick to allow correct behaviour when running in JTP execution mode. + +[http://code.google.com/p/aparapi/source/browse/trunk/samples/median/src/com/amd/aparapi/sample/median/MedianDemo.java](http://code.google.com/p/aparapi/source/browse/trunk/samples/median/src/com/amd/aparapi/sample/median/MedianDemo.java) \ No newline at end of file