Initial check-in of open source clFFT code

clMathLibraries · Aug 13, 2013 · 1e4a52d · 1e4a52d
commit 1e4a52d
Show file tree

Hide file tree

Showing 99 changed files with 52,467 additions and 0 deletions.
diff --git a/.gitattributes b/.gitattributes
@@ -0,0 +1,22 @@
+# Auto detect text files and perform LF normalization
+* text=auto
+
+# Custom for Visual Studio
+*.cs     diff=csharp
+*.sln    merge=union
+*.csproj merge=union
+*.vbproj merge=union
+*.fsproj merge=union
+*.dbproj merge=union
+
+# Standard to msysgit
+*.doc	 diff=astextplain
+*.DOC	 diff=astextplain
+*.docx diff=astextplain
+*.DOCX diff=astextplain
+*.dot  diff=astextplain
+*.DOT  diff=astextplain
+*.pdf  diff=astextplain
+*.PDF	 diff=astextplain
+*.rtf	 diff=astextplain
+*.RTF	 diff=astextplain
diff --git a/.gitignore b/.gitignore
@@ -0,0 +1,13 @@
+# Compiled Object files
+*.slo
+*.lo
+*.o
+
+# Compiled Dynamic libraries
+*.so
+*.dylib
+
+# Compiled Static libraries
+*.lai
+*.la
+*.a
diff --git a/CHANGELOG b/CHANGELOG
@@ -0,0 +1,204 @@
+# ########################################################################
+# Copyright 2013 Advanced Micro Devices, Inc.
+# 
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+# 
+# http://www.apache.org/licenses/LICENSE-2.0
+# 
+# Unless required by applicable law or agreed to in writing, software
+# 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.
+# ########################################################################
+
+clFFT Readme
+
+Version:       1.10
+Release Date:  April 2013
+
+ChangeLog:
+
+____________
+Current Version:
+  * This release tested using the 9.012 runtime driver and the 2.8 APPSDK
+
+____________
+Version 1.8.291:
+Fixed:
+  * Memory leaks affecting use cases where 'clfftEnqueueTransform' is used in a loop
+
+____________
+Version 1.8.269 (beta):
+New:
+  * clFFT now supports real-to-complex and complex-to-real transforms;
+      refer to documentation for details
+  * This release tested using the 12.4 Catalyst software suite
+
+Known Issues:
+  * Some degradation in performance of real transforms due to known
+      runtime/driver issues
+  * Failures in real transforms have been seen on 7xxx series GPUs with certain
+      problem sizes involving powers of 3 and 5  
+
+____________
+Version 1.6.244:
+Fixed:
+  * Failures observed in v1.6.236 in backward transforms of certain power of 2
+      (involving radix 4 and radix 8) problem sizes.
+
+____________
+Version 1.6.236:
+New:
+  * Performance of the FFT library has been improved for Radix-2 1D and 2D transforms
+  * Support for R4XXX GPUs is deprecated and no longer tested
+  * Preview: Support for AMD Radeon� HD7000 series GPUs
+  * This release tested using the 8.92 runtime driver and the 2.6 APP SDK
+____________
+Version 1.4:
+New:
+  * clFFT now supports transform lengths whose factors consist exclusively 
+      of powers of 2, 3, and 5
+  * clFFT supports double precision data types
+  * clFFT executes on OpenCL 1.0 compliant devices
+  * This release tested using the 8.872 runtime driver and the 2.5 APP SDK
+  * A helper bash script appmlEnv.sh has been added to the root installation
+      directory to assist in properly setting up a terminal environment to 
+      execute clFFT samples
+
+Fixed:
+  * If the library is required to allocate a temporary buffer, and the user does
+      not specify a temporary buffer on the Enqueue call, the library will 
+      allocate a temporary buffer internally and the lifetime of that temporary 
+      buffer is managed by the lifetime of the FFT plan; deleting the plan will 
+      release the buffer.
+  * Test failures on CPU device for 32-bit systems  (Windows/Linux) 
+
+Known Issues:
+  * Failures have been seen on graphics cards using R4550 (RV710) GPUs.
+
+____________
+Version 1.2:
+New:
+  * Reduced the number of internal LDS bank conflicts for our 1D FFT transforms,
+      increasing performance.
+  * Padded reads/writes to global memory, decreasing bank conflicts and 
+      increasing performance on 2D transforms.
+  * This release tested using the 8.841 runtime driver and the 2.4 APP SDK
+
+Fixed:
+  * Failures have been seen attempting to queue work on the second GPU device on
+      a multi GPU 5970 card on Linux.
+
+Known Issues:
+  * It is recommended that users query for and explicitely create an 
+      intermediate buffer if clFFT requires one.  If the library creates the 
+      intermediate buffer internally, a race condition may occur on freeing the 
+      buffer on lower end hardware.
+  * Failures have been seen on graphics cards using R4550 (RV710) GPUs.
+  * Test failures on CPU device for 32-bit systems  (Windows/Linux) 
+  * It is recommended that windows users uninstall previous version of clFFT 
+      before installing newer versions.  Otherwise, Add/Remove programs only 
+      removes the latest version.  Linux users can delete the install directory.
+
+____________
+Version 1.0:
+  * Initial release, available on all platforms
+
+Known Issues:
+  * Failures have been seen attempting to queue work on the second GPU device on
+      a multi GPU 5970 card on Linux.
+_____________________
+Building the Samples:
+
+To install the Linux versions of clFFT, uncompress the initial download and 
+  then execute the install script.
+
+For example:
+  tar -xf clFFT-${version}.tar.gz
+      - This installs three files into the local directory, one being an 
+        executable bash script.
+
+  sudo mkdir /opt/clFFT-${version}
+      - This pre-creates the install directory with proper permissions in /opt 
+        if it is to be installed there (This is the default).
+
+  ./install-clFFT-${version}.sh
+      - This prints an EULA and uncompresses files into the chosen install 
+        directory.
+
+  cd ${installDir}/bin64
+    export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:${OpenCLLibDir}:${clfftLibDir}
+      - Export library dependencies to resolve all external linkages to the 
+        client program. The user can create a bash script to help automate this 
+        procedure.
+
+  ./Client -h
+      - Understand the command line options that are available to the user 
+        through the sample client.
+
+  ./Client -iv
+      - Watch for the version strings to print out; watch for 
+        'Client Test *****PASS*****' to print out.
+
+The sample program does not ship with native build files. Instead, a CMake
+file is shipped, and users generate a native build file for their system.
+
+For example:
+  cd ${installDir}
+  mkdir samplesBin/
+      - This creates a sister directory to the samples directory that will house
+        the native makefiles and the generated files from the build.
+
+  cd samplesBin/
+  ccmake ../samples/
+      - ccmake is a curses-based cmake program. It takes a parameter that 
+        specifies the location of the source code to compile.
+      - Hit 'c' to configure for the platform; ensure that the dependencies to 
+        external libraries are satisfied, including paths to 'ATI Stream SDK' 
+        and 'Boost'.
+      - After dependencies are satisfied, hit 'c' again to finalize configure 
+        step, then hit 'g' to generate makefile and exit ccmake.
+
+  make help
+      - Look at the available options for make.
+
+  make
+      - Build the sample client program.
+
+  ./clfft.Sample -iv
+      - Watch for the version strings to print out; watch for 
+        'Client Test *****PASS*****' to print out.
+_______________________________________________________________________________
+(C) 2010-2013 Advanced Micro Devices, Inc. All rights reserved. AMD, the AMD 
+Arrow logo, ATI, the ATI logo, Radeon, FireStream, FireGL, Catalyst, and 
+combinations thereof are trademarks of Advanced Micro Devices, Inc. Microsoft 
+(R), Windows, and Windows Vista (R) are registered trademarks of Microsoft 
+Corporation in the U.S. and/or other jurisdictions. OpenCL and the OpenCL logo 
+are trademarks of Apple Inc. used by permission by Khronos. Other names are for 
+informational purposes only and may be trademarks of their respective owners.
+
+The contents of this document are provided in connection with Advanced Micro 
+Devices, Inc. ("AMD") products. AMD makes no representations or warranties with 
+respect to the accuracy or completeness of the contents of this publication and 
+reserves the right to make changes to specifications and product descriptions 
+at any time without notice. The information contained herein may be of a 
+preliminary or advance nature and is subject to change without notice. No 
+license, whether express, implied, arising by estoppel or otherwise, to any 
+intellectual property rights is granted by this publication. Except as set forth
+in AMD's Standard Terms and Conditions of Sale, AMD assumes no liability 
+whatsoever, and disclaims any express or implied warranty, relating to its 
+products including, but not limited to, the implied warranty of 
+merchantability, fitness for a particular purpose, or infringement of any 
+intellectual property right.
+
+AMD's products are not designed, intended, authorized or warranted for use as 
+components in systems intended for surgical implant into the body, or in other 
+applications intended to support or sustain life, or in any other application 
+in which the failure of AMD's product could create a situation where personal 
+injury, death, or severe property or environmental damage may occur. AMD 
+reserves the right to discontinue or make changes to its products at any time 
+without notice.
+_______________________________________________________________________________
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,36 @@
+## Contributor guidelines
+
+Contributing code to this project is intended to be light weight and intuitive to users familiar with GitHub to actively encourage contributions, but a process is documented and should be followed to prevent chaos, confusion and despair.  
+
+## The mechanics of contributing code
+Firstly, in order to contribute code to this project, a contributor must have a valid and current [GitHub account](https://help.github.com/articles/set-up-git) available to use.  Given an account,
+* The potential contributor forks this project into his/her account following the traditional [forking](https://help.github.com/articles/fork-a-repo) model native to GitHub
+* After forking, the contributor [clones their repository](https://help.github.com/articles/create-a-repo) locally on their machine
+* Code is developed and checked into the contributor's repository.  These commits are eventually pushed upstream to their GitHub repository
+* The contributor then issues a [pull-request](https://help.github.com/articles/using-pull-requests) against the **develop** branch of this repository, which is the [git flow](http://nvie.com/posts/a-successful-git-branching-model/) workflow which is well suited for working with GitHub
+    * A [git extention](https://github.com/nvie/gitflow) has been developed to ease the use of the 'git flow' methodology, but requires manual installation by the user.  Refer to the projects wiki
+
+At this point, the repository maintainers will be notified by GitHub that a 'pull request' exists pending against their repository.  A code review should be completed within a few days, depending on the scope of submitted code, and the code will either be accepted, rejected or commented on for extra feedback.
+
+## Code submission guidelines
+We want to ensure that the project code base maintains a level of quality over time, such that future contributors find it as easy to jump into the code as hopefully it is today.  As such, pull requests should 
+* remember that clMath is a project licensed under the [Apache License, Version 2.0]( http://www.apache.org/licenses/LICENSE-2.0 ).  If you are not already familiar, please review the license before issuing a pull request.  We intend this project to be open to external contributors, and encourage developers to contribute code back that they believe will provide value to the overall community.  We will interpret an explicit 'pull request' back to this repository as an implicit acknowledgement from the contributor that they wish to share the code with the community under the terms of the Apache license v2.0.
+* follow the [code style guidelines]( ) of the project as posted to the project wiki.  Unfortunately, there was no unifying code guidelines defined between the BLAS & FFT projects, but code submissions should not mix styles within an individual file.  We have since defined and posted a code style guideline for the projects and we expect the code to slowly transition to the new
+guidelines over time
+    *  separate check-ins that modify a files style from the ones that add/change/delete code.
+* target the **develop** branch in the repository
+* ensure that the [code properly builds]( https://github.com/kknox/clFFT/wiki/Build )
+* cannot break existing test cases
+    * we encourage contributors to [run all tests]( https://github.com/kknox/clFFT/wiki/Testing ) on their end before the pull-request
+        * if possible, upload the test results associated with the pull request to a personal [gist repository]( https://gist.github.com/ ) and insert a link to the test results in the pull request so that collaborators can browse the results
+        * if no test results are provided with the pull request, official collaborators will run the test suite on their test machines against the patch before we will accept the pull-request
+            * if we detect failing test cases, we will request that the code associated with the pull request be fixed before the pull request will be merged
+    * if new functionality is introduced with the pull request, sufficient test cases should be added to verify the new functionality is correct
+        * new tests should integrate with the existing [googletest framework]( https://code.google.com/p/googletest/wiki/Primer ) located in the src/tests directory of the repo
+        * if the collaborators feel the new tests do not provide sufficient coverage, feedback on the pull request will be left with suggestions on how to improve the tests before the pull request will be merged
+
+Pull requests will be reviewed by the set of collaborators that are assigned for the repository.  Pull requests may be accepted, declined or a conversation may start on the pull request thread with feedback.  If the pull request is trivial and all the submission guidelines defined above are honored, the pull request may be accepted without delay.  If the pull request is good, but the guidelines defined above are not followed, the collaborators may leave feedback on the pull request and engage in a conversation with the contributor with what they can do to improve the pull request.  At any time, collaborators may decline a pull request if they decide the contribution is not appropriate for the project, or the feedback from reviewers on a pull request is not being addressed in an appropriate amount of time.
+
+## Is it possible to become an official collaborator of the repository?
+Yes, we hope to promote trusted members of the community, who have proven themselves to be competent and request to take on the extra responsibility to be official collaborators of the project.  When an individual requests to be an official collaborator, current project collaborators will browse through the history of the requester's prior pull requests and take a vote amongst themselves if the requester should be promoted to collaborator.  These individuals will then have the right to approve/decline pull requests and help shape the path that the project goes.  It is worth noting, that on GitHub everybody has read-only access to the source and that everybody has the ability to issue a pull request to contribute to the project.  The benefit of being a repository collaborator allows you to be able to be able to manage other peoples pull requests.
+