Initial check-in of open source clBLAS code

janboeye · Aug 13, 2013 · db35dbd · db35dbd
commit db35dbd
Show file tree

Hide file tree

Showing 540 changed files with 214,287 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,19 @@
+# Compiled Object files
+*.slo
+*.lo
+*.o
+*.obj
+
+# Compiled Dynamic libraries
+*.so
+*.dylib
+*.dll
+
+# Compiled Static libraries
+*.lai
+*.la
+*.a
+*.lib
+
+# Generated kernel template files
+*.clT
diff --git a/CHANGELOG b/CHANGELOG
@@ -0,0 +1,276 @@
+# ########################################################################
+# 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.
+# ########################################################################
+
+clBLAS Readme
+
+Version:       1.10
+Release Date:  April 2013
+
+ChangeLog:
+____________
+Current Version:
+New:
+  * New Level 1 routines added (an 'x' implies all 4 precisions)
+        xSWAP, xCOPY, xSCAL, CSSCAL, ZDSCAL, xAXPY, SDOT, DDOT, 
+        CDOTU, ZDOTU, CDOTC, ZDOTC, xROTG, SROTMG, DROTMG,
+		SROT, DROT, CSROT, ZDROT, SROTM, DROTM, SNRM2, DNRM2,
+		SCNRM2, DZNRM2, ixAMAX, SASUM, DASUM, SCASUM, DZASUM
+  * Samples have been added for the new functions 
+  * This release tested using the 9.012 runtime driver and the 2.8 APPSDK
+Fixed:
+  * Failures in *trsm functions with clMAGMA tests
+Known Issues:
+  * Failures & hangs in ztrmm, *trsv, *tpsv functions on Southern Island GPU devices
+  * Failures in zgemm functions on Northern Island GPU devices
+  * Failures & hangs are expected to be fixed in the upcoming AMD graphics driver versions.
+		It is strongly recommended that users keep their graphics driver versions up to date. 
+
+____________
+Version 1.8.291:
+Fixed:
+  * Failures in the following functions: ssyr2, ssyr2k, strsm, strsv, ssyrk, cher, 
+        ctrsv, csymm, cher2, ztrmm on Southern Island GPU devices.
+  * Failures in the following functions: dsyr, dsyr2, dgemv, dsyrk,
+        dsyr2k, zsyr2k on Trinity platforms. 
+Known Issues:
+  * Failures in *trsm functions with clMAGMA tests
+
+____________
+Version 1.8.269 (Beta, clMAGMA support):
+New:
+  * No new routines
+  * This release tested using the 8.961 runtime driver and the 2.6 APPSDK
+
+Known Issues:
+  * The clBLASTune executable has been observed to hang on Windows.  If 
+        this happens, abort execution of the tune program; it is not required 
+        for correct operation of the BLAS routines (as of 8.872).
+  * clBLAS can return invalid results on CPU devices (as 
+        of 8.961).  The CPU device is primarily a test/debug device, and GPU 
+		devices are unaffected.
+  * clBLAS can return invalid results for double precision functions (dsyr, 
+        dsyr2, dgemv, dsyrk, dsyr2k, zsyr2k) on Trinity platforms (as of 
+        8.961).
+  * clBLAS can return invalid results (ssyr2, ssyr2k, strsm, strsv, ssyrk, cher, 
+        ctrsv, csymm, cher2, ztrmm) on Southern Island GPU devices (as of 8.961).
+
+____________
+Version 1.7 (Beta, clMAGMA support):
+New:
+  * New Level 3 routines added (an 'x' implies all 4 precisions)
+		CHER2K, ZHER2K
+  * New Level 2 routines added (an 'x' implies all 4 precisions)
+        xTPMV, xTPSV, SSPVM, DSPMV, CHPMV, ZHPMV, SSPR, DSPR, CHPR, ZHPR, 
+        SSPR2, DSPR2, CHPR2, ZHPR2, xGBMV, CHBMV, ZHBMV, SSBMV, DSBMV, 
+        xTBMV, xTBSV
+  * Samples have been added for the new functions, but are not fully tested 
+  * This release tested using the 8.951 runtime driver and the 2.6 APPSDK
+  * Note that documentation is incomplete for the new functions
+
+Known Issues:
+  * The clBLASTune executable has been observed to hang on Windows.  If 
+        this happens, abort execution of the tune program; it is not required 
+        for correct operation of the BLAS routines (as of 8.872).
+  * clBLAS can return invalid results on CPU devices that support AVX (as 
+        of 8.951).  CPU devices that support up to SSE3 are unaffected.  The 
+        CPU device is primarily a test/debug device, and GPU devices are 
+        unaffected.
+  * clBLAS can return invalid results for double precision functions (dsyr, 
+        dsyr2, dgemv, dsyrk, dsyr2k, zsyr2k) on Trinity platforms (as of 
+        8.951).
+  * clBLAS can return invalid results (ssyr, ssyr2, strsv, ctrsv, ssyrk, 
+        ssyr2k, ztrmm) on Southern Island GPU devices (as of 8.951).
+
+____________
+Version 1.6:
+New:
+  * New Level 3 routines added (an 'x' implies all 4 precisions)
+        CSYRK, ZSYRK, CSYR2K, ZSYR2K, CHEMM, ZHEMM, CHERK, ZHERK, xSYMM
+  * New Level 2 routines added (an 'x' implies all 4 precisions)
+        CGEMV, ZGEMV, xTRMV, xTRSV, CHEMV, ZHEMV, SGER, DGER, CGERU, ZGERU, 
+		CGERC, ZGERC, CHER, ZHER, CHER2, ZHER2, SSYR, DSYR, SSYR2, DSYR2
+  * For all the original functions prior to 1.6, a new API has been introduced
+        with an *Ex suffix.  These extended API's add new parameters that allow
+		users to specify an offset to a matrix argument.  This allows efficient
+		sub-matrix indexing within a clBLAS routine without requiring expensive
+		sub-matrix copy operations.
+  * Samples have been added for the new functions
+  * Preview: Support for AMD Radeon� HD7000 series GPUs
+  * This release tested using the 8.92 runtime driver and the 2.6 APP SDK
+
+Known Issues:
+  * The clBLASTune executable has been observed to hang on Windows.  If this
+        happens, abort execution of the tune program; it is not required for 
+		correct operation of the BLAS routines (as of 8.872).
+  * The CPU device for clBLAS is not functioning for this release (as of 
+        8.872).  The CPU device is primarily a test/debug device, and GPU 
+		devices are unaffected.
+
+____________
+Version 1.4:
+New:
+  * New Level 3 routines added
+        SSYRK, DSYRK, SSYR2K, DSYR2K
+  * New Level 2 routines added
+        SGEMV, DGEMV, SSYMV, DSYMV
+  * The image support functions (clblasAddScratchImage, 
+        clblasRemoveScratchImage) have been deprecated.  Images are no 
+		longer required for the highest performance.
+  * InstallShield is now used for APPML libraries.  The default install 
+        location has changed from c:\amd\clBLAS to 
+		C:\Program Files (x86)\AMD\clBLAS.  It is recommended that previous 
+		versions of clBLAS are uninstalled first.
+  * Samples have been added for the new functions
+  * This release tested using the 8.872 runtime driver and the 2.5 APP SDK
+
+Known Issues:
+  * The clBLASTune executable has been observed to hang on Windows.  If this
+        happens, abort execution of the tune program; it is not required for 
+		correct operation of the BLAS routines (as of 8.872).
+  * The CPU device for clBLAS is not functioning for this release (as of 
+        8.872).  The CPU device is primarily a test/debug device, and GPU 
+		devices are unaffected.
+
+
+____________
+Version 1.2:
+  * The library now supports both 32- and 64-bit Windows and Linux operating 
+        systems.
+  * xTRSM routines are available in 1.2.
+  * clBLAS routines return clBLASStatus error codes, instead of native 
+        OpenCL error codes
+
+Fixed:
+  * xTRMM routines were not properly handling implicit unit diagonal 
+        elements and implicit off-diagonal zero values specified by the BLAS 
+        parameters SIDE, UPLO and DIAG.
+  * Possible crash with CPU device on 32-bit systems.
+  * clblasDgemm routine return an invalid event as its last argument.
+  * clBLAS routines return clblasStatus error codes, instead of 
+        native OpenCL error codes.
+
+Known Issues:
+  * The clBLASTune executable has been observed to hang on Windows.  If this
+        happens, abort execution of the tune program; it is not required for 
+		correct operation of the BLAS routines (as of 8.872).
+  * The CPU device for clBLAS is not functioning for this release (as of 
+        8.872).  The CPU device is primarily a test/debug device, and GPU 
+		devices are unaffected.
+
+____________________
+Version 1.0:
+  * Initial release
+
+Known Issues:
+  * Available only on Linux64.
+  * xTRMM routines were not properly handling implicit unit diagonal elements 
+        and implicit off-diagonal zero values specified by the BLAS parameters
+		SIDE, UPLO and DIAG
+  * clblasDgemm returned an invalid event as its last argument
+
+_____________
+Building the Samples:
+
+To install the Linux versions of clBLAS, uncompress the initial download, then 
+execute the install script.
+
+For example:
+
+	tar -xf clBLAS-${version}-Linux.tar.gz
+		- This installs three files into the local directory, one being an 
+            executable bash script.
+
+	sudo mkdir /opt/clBLAS-${version}
+		- This pre-creates the install directory with proper permissions 
+            in /opt if it is to be installed there. (This is the default.)
+
+	./install-clBLAS-${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}:${clBLASLibDir}
+		- Be sure to export library dependencies to resolve all external 
+            linkages to the client program; you can create a bash script to 
+			help automate this procedure.
+
+	./example_sgemm
+		- Run a simple client; one example is provided for each supported 
+                  main BLAS function family.
+
+The sample program does not ship with native build files; instead, a CMake 
+file is shipped, and the user generates a native build file for their system.
+
+For example:
+
+	cd ${installDir}
+
+	mkdir samplesBin/
+		- This creates a sister directory to the samples directory that 
+                  houses 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'.
+		- After dependencies are satisfied, hit 'c' again to finalize 
+                  configuration. Then, hit 'g' to generate a makefile and 
+                  exit ccmake.
+
+	make help
+		- Look at the options available for make.
+
+	make
+		- Build the sample client program.
+
+	./example_sgemm
+		- Run a simple client; one example is provided for each supported main 
+		BLAS function family.
+_______________________________________________________________________________
+(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/clBLAS/wiki/Build )
+* cannot break existing test cases
+    * we encourage contributors to [run the test-short]( https://github.com/kknox/clBLAS/wiki/Testing ) suite of tests 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.
+