vBLAS.h File Reference

Header for the Basic Linear Algebra Subprograms, with Apple extensions. More...

#include <ConditionalMacros.h>

Go to the source code of this file.

Macros
#define	IsAlignedCount(n)   ((n > 0) && ((n & 3L) == 0))
#define	IsAlignedAddr(a)   (((long)a & 15L) == 0)

Typedefs
typedef enum CBLAS_ORDER	CBLAS_ORDER
typedef enum CBLAS_TRANSPOSE	CBLAS_TRANSPOSE
typedef enum CBLAS_UPLO	CBLAS_UPLO
typedef enum CBLAS_DIAG	CBLAS_DIAG
typedef enum CBLAS_SIDE	CBLAS_SIDE
typedef const char *	paramName
typedef const char const int *	paramPos
typedef const char const int const int *	paramValue

Enumerations
enum	CBLAS_ORDER { CblasRowMajor = 101 , CblasColMajor = 102 }
enum	CBLAS_TRANSPOSE { CblasNoTrans = 111 , CblasTrans = 112 , CblasConjTrans = 113 }
enum	CBLAS_UPLO { CblasUpper = 121 , CblasLower = 122 }
enum	CBLAS_DIAG { CblasNonUnit = 131 , CblasUnit = 132 }
enum	CBLAS_SIDE { CblasLeft = 141 , CblasRight = 142 }

Functions
float	cblas_sdot (int N, const float *X, int incX, const float *Y, int incY)
float	cblas_snrm2 (int N, const float *X, int incX)
float	cblas_sasum (int N, const float *X, int incX)
int	cblas_isamax (int N, const float *X, int incX)
void	cblas_sswap (int N, float *X, int incX, float *Y, int incY)
void	cblas_scopy (int N, const float *X, int incX, float *Y, int incY)
void	cblas_saxpy (int N, float alpha, const float *X, int incX, float *Y, int incY)
void	cblas_srot (int N, float *X, int incX, float *Y, int incY, float c, float s)
void	cblas_sscal (int N, float alpha, float *X, int incX)
void	cblas_sgemv (CBLAS_ORDER order, CBLAS_TRANSPOSE transA, int M, int N, float alpha, const float *A, int lda, const float *X, int incX, float beta, float *Y, int incY)
void	cblas_sgemm (CBLAS_ORDER order, CBLAS_TRANSPOSE transA, CBLAS_TRANSPOSE transB, int M, int N, int K, float alpha, const float *A, int lda, const float *B, int ldb, float beta, float *C, int ldc)
typedef	CALLBACK_API_C (void, BLASParamErrorProc)(const char *funcName
void	SetBLASParamErrorProc (BLASParamErrorProc ErrorProc)

Detailed Description

Header for the Basic Linear Algebra Subprograms, with Apple extensions.

Introduced In: All

Avaliable From: Universal Interfaces 3.4.1

Copyright: © 2000-2001 by Apple Computer, Inc., all rights reserved.

For bug reports, consult the following page on the World Wide Web:

http://developer.apple.com/bugreporter/

Macro Definition Documentation

IsAlignedCount

#define IsAlignedCount

(

n

)

((n > 0) && ((n & 3L) == 0))

---

IsAlignedCount - True if an integer is positive and a multiple of 4. Negative strides are considered unaligned. IsAlignedAddr - True if an address is a multiple of 16.

Enumeration Type Documentation

CBLAS_ORDER

enum CBLAS_ORDER

==========================================================================================================================

---

Definitions of the Basic Linear Algebra Subprograms (BLAS) as provided by Apple Computer. At present this is a subset of the "legacy" FORTRAN and C interfaces. Only single precision forms are provided, and only the most useful routines. For example only the general matrix forms are provided, not the symmetric, Hermitian, or triangular forms. A few additional functions, unique to Mac OS, have also been provided. These are clearly documented as Apple extensions. Documentation on the BLAS standard, including reference implementations, can be found on the web starting from the BLAS FAQ page at these URLs (at least as of August 2000): http://www.netlib.org/blas/faq.html

http://www.netlib.org/blas/blast-forum/blast-forum.html

---

Matrix shape and storage

Keeping the various matrix shape and storage parameters straight can be difficult. The BLAS documentation generally makes a distinction between the concpetual "matrix" and the physical "array". However there are a number of places where this becomes fuzzy because of the overall bias towards FORTRAN's column major storage. The confusion is made worse by style differences between the level 2 and level 3 functions. It is amplified further by the explicit choice of row or column major storage in the C interface. The storage order does not affect the actual computation that is performed. That is, it does not affect the results other than where they appear in memory. It does affect the values passed for so-called "leading dimension" parameters, such as lda in sgemv. These are always the major stride in storage, allowing operations on rectangular subsets of larger matrices. For row major storage this is the number of columns in the parent matrix, and for column major storage this is the number of rows in the parent matrix. For the level 2 functions, which deal with only a single matrix, the matrix shape parameters are always M and N. These are the logical shape of the matrix, M rows by N columns. The transpose parameter, such as transA in sgemv, defines whether the regular matrix or its transpose is used in the operation. This affects the implicit length of the input and output vectors. For example, if the regular matrix A is used in sgemv, the input vector X has length N, the number of columns of A, and the output vector Y has length M, the number of rows of A. The length of the input and output vectors is not affected by the storage order of the matrix. The level 3 functions deal with 2 input matrices and one output matrix, the matrix shape parameters are M, N, and K. The logical shape of the output matrix is always M by N, while K is the common dimension of the input matrices. Like level 2, the transpose parameters, such as transA and transB in sgemm, define whether the regular input or its transpose is used in the operation. However unlike level 2, in level 3 the transpose parameters affect the implicit shape of the input matrix. Consider sgemm, which computes "C = (alpha * A * B) + (beta * C)", where A and B might be regular or transposed. The logical shape of C is always M rows by N columns. The physical shape depends on the storage order parameter. Using column major storage the declaration of C (the array) in C (the language) would be something like "float C[N][M]". The logical shape of A without transposition is M by K, and B is K by N. The one storage order parameter affects all three matrices. For those readers still wondering about the style differences between level 2 and level 3, they involve whether the input or output shapes are explicit. For level 2, the input matrix shape is always M by N. The input and output vector lengths are implicit and vary according to the transpose parameter. For level 3, the output matrix shape is always M by N. The input matrix shapes are implicit and vary according to the transpose

parameters.

==========================================================================================================================

---

Types and constants

Function Documentation

CALLBACK_API_C()

typedef CALLBACK_API_C	(	void	,
		BLASParamErrorProc
	)		const

---

Level 3 Double Precision Functions

*** TBD

---

Level 3 Complex Single Precision Functions

*** TBD

---

==========================================================================================================================

Latest Standard BLAS Functions

========================================================================================================================== *** TBD

---

==========================================================================================================================

Additional Functions from Apple

==========================================================================================================================

---

These routines provide optimized, AltiVec-only support for common small matrix multiplications. They do not check for the availability of AltiVec instructions or parameter errors. They just do the multiplication as fast as possible. Matrices are presumed to use row major storage. Because these are all square, column major matrices can be multiplied by simply reversing the parameters.

---

Error handling

---

The BLAS standard requires that parameter errors be reported and cause the program to terminate. The default behavior for the Mac OS implementation of the BLAS is to print a message in English to stdout using printf and call exit with EXIT_FAILURE as the status. If this is adequate, then you need do nothing more or worry about error handling. The BLAS standard also mentions a function, cblas_xerbla, suggesting that a program provide its own implementation to override the default error handling. This will not work in the shared library environment of Mac OS 9. Instead the Mac OS implementation provides a means to install an error handler. There can only be one active error handler, installing a new one causes any previous handler to be forgotten. Passing a null function pointer installs the default handler. The default handler is automatically installed at startup and implements the default behavior defined above. An error handler may return, it need not abort the program. If the error handler returns, the BLAS routine also returns immediately without performing any processing. Level 1 functions that return a numeric value return zero if the error handler returns.

cblas_isamax()

int cblas_isamax	(	int	N,
		const float *	X,
		int	incX
	)

cblas_isamax()

Non-Carbon CFM: in vecLib 1.0.2 and later

Carbon Lib: not in Carbon, but vecLib is compatible with Carbon

Mac OS X: in version 10.0 and later

cblas_sasum()

float cblas_sasum	(	int	N,
		const float *	X,
		int	incX
	)

cblas_sasum()

Non-Carbon CFM: in vecLib 1.0.2 and later

Carbon Lib: not in Carbon, but vecLib is compatible with Carbon

Mac OS X: in version 10.0 and later

cblas_saxpy()

void cblas_saxpy	(	int	N,
		float	alpha,
		const float *	X,
		int	incX,
		float *	Y,
		int	incY
	)

cblas_saxpy()

Non-Carbon CFM: in vecLib 1.0.2 and later

Carbon Lib: not in Carbon, but vecLib is compatible with Carbon

Mac OS X: in version 10.0 and later

cblas_scopy()

void cblas_scopy	(	int	N,
		const float *	X,
		int	incX,
		float *	Y,
		int	incY
	)

cblas_scopy()

Non-Carbon CFM: in vecLib 1.0.2 and later

Carbon Lib: not in Carbon, but vecLib is compatible with Carbon

Mac OS X: in version 10.0 and later

cblas_sdot()

float cblas_sdot	(	int	N,
		const float *	X,
		int	incX,
		const float *	Y,
		int	incY
	)

---

==========================================================================================================================

Legacy BLAS Functions

==========================================================================================================================

---

Level 1 Single Precision Functions

cblas_sdot()

Non-Carbon CFM: in vecLib 1.0.2 and later

Carbon Lib: not in Carbon, but vecLib is compatible with Carbon

Mac OS X: in version 10.0 and later

cblas_sgemm()

void cblas_sgemm	(	CBLAS_ORDER	order,
		CBLAS_TRANSPOSE	transA,
		CBLAS_TRANSPOSE	transB,
		int	M,
		int	N,
		int	K,
		float	alpha,
		const float *	A,
		int	lda,
		const float *	B,
		int	ldb,
		float	beta,
		float *	C,
		int	ldc
	)

---

Level 2 Double Precision Functions

*** TBD

---

Level 2 Complex Single Precision Functions

*** TBD

---

Level 3 Single Precision Functions

cblas_sgemm()

Non-Carbon CFM: in vecLib 1.0.2 and later

Carbon Lib: not in Carbon, but vecLib is compatible with Carbon

Mac OS X: in version 10.0 and later

cblas_sgemv()

void cblas_sgemv	(	CBLAS_ORDER	order,
		CBLAS_TRANSPOSE	transA,
		int	M,
		int	N,
		float	alpha,
		const float *	A,
		int	lda,
		const float *	X,
		int	incX,
		float	beta,
		float *	Y,
		int	incY
	)

---

Level 1 Double Precision Functions

*** TBD

---

Level 1 Complex Single Precision Functions

*** TBD

---

Level 2 Single Precision Functions

cblas_sgemv()

Non-Carbon CFM: in vecLib 1.0.2 and later

Carbon Lib: not in Carbon, but vecLib is compatible with Carbon

Mac OS X: in version 10.0 and later

cblas_snrm2()

float cblas_snrm2	(	int	N,
		const float *	X,
		int	incX
	)

cblas_snrm2()

Non-Carbon CFM: in vecLib 1.0.2 and later

Carbon Lib: not in Carbon, but vecLib is compatible with Carbon

Mac OS X: in version 10.0 and later

cblas_srot()

void cblas_srot	(	int	N,
		float *	X,
		int	incX,
		float *	Y,
		int	incY,
		float	c,
		float	s
	)

cblas_srot()

Non-Carbon CFM: in vecLib 1.0.2 and later

Carbon Lib: not in Carbon, but vecLib is compatible with Carbon

Mac OS X: in version 10.0 and later

cblas_sscal()

void cblas_sscal	(	int	N,
		float	alpha,
		float *	X,
		int	incX
	)

cblas_sscal()

Non-Carbon CFM: in vecLib 1.0.2 and later

Carbon Lib: not in Carbon, but vecLib is compatible with Carbon

Mac OS X: in version 10.0 and later

cblas_sswap()

void cblas_sswap	(	int	N,
		float *	X,
		int	incX,
		float *	Y,
		int	incY
	)

cblas_sswap()

Non-Carbon CFM: in vecLib 1.0.2 and later

Carbon Lib: not in Carbon, but vecLib is compatible with Carbon

Mac OS X: in version 10.0 and later

SetBLASParamErrorProc()

void SetBLASParamErrorProc

(

BLASParamErrorProc

ErrorProc

)

SetBLASParamErrorProc()

Non-Carbon CFM: in vecLib 1.0.2 and later

Carbon Lib: not in Carbon, but vecLib is compatible with Carbon

Mac OS X: in version 10.0 and later