Three of the header files are Apple’s versions of well-known libraries which are described in detail in external references:
vblas.hare the interfaces to Apple’s implementations of BLAS. You can find reference documentation in BLAS. Additional documentation on the BLAS standard, including reference implementations, can be found on the web starting from the BLAS FAQ page at these URLs: http://www.netlib.org/blas/faq.html and http://www.netlib.org/blas/blast-forum/blast-forum.html.
clapack.h is the interface to Apple’s implementation of LAPACK. Documentation of the LAPACK interfaces, including reference implementations, can be found on the web starting from the LAPACK FAQ page at this URL: http://netlib.org/lapack/faq.html
This document describes the functions declared in the remaining header files:
vBigNum.h. These files support the vector mathematical functions library (also called “vMathLib”), which runs on vector processing hardware if available.
This library abstracts the vector processing capability so that code written for it will execute appropriate instructions for the processor available at runtime. For this reason, unless you are writing specialized code that targets a single CPU, you should generally use these functions rather than directly using vector instructions. By using these functions, your code does not have to deal with subtle differences in vector instruction availability between different microarchitectures, freeing you to focus on the problem you are trying to solve. Also, code written using vecLib tends to be easier to port to different CPU architectures (porting your core libraries to ARM on iOS, for example).
The vecLibTypes.h header file defines a set of vector data types (
vUInt32, etc.), which represent 128-bit vectors containing values of type
UInt32, etc. The vBasicOps.h and vfp.h headers make use of these types.
The type names all begin with the letter “v,” followed by a mnemonic for the scalar data type used for elements of the vector. For example,
vBasicOps.h declares a set of basic arithmetic and logical functions on 128-bit vectors, using the integer types from vecLibTypes.h.
The function names begin with “v,” followed by a mnemonic for the type of operation, e.g. “S” or “U” for signed or unsigned, then the width of the operation, then the name of the operation. For example,
vS8Divide performs division of signed 8-bit values packed into 128-bit vectors.
vfp.h declares a set of floating-point arithmetic, transcendental and trigonometric functions, on 128-bit vectors, using the floating-point types from vecLibTypes.h.
These functions are named with their customary mathematical names, prefixed with the letter “v”, and all except
vtablelookup() have the suffix “f” to indicate that they work with single-precision floating-point data. For example,
vcosf is the single-precision cosine function.
vForce.h declares a set of trigonometric and transcendental functions in terms of C arrays (
double * or
float *), which can be of any desired length. Internally, the C arrays are converted piecewise into collections of 128-bit vectors, if appropriate for the current architecture.
The functions declared in vForce.h are named with the customary mathematical names, but with the prefix “vv.” Each mathematical function is available in two variants: one for single-precision floating-point data and one for double-precision data. The single-precision forms have the suffix “f”, while the double-precision forms have no suffix. For example,
vvcosf is the single-precision cosine function, while
vvcos is the double-precision variant.
All of the vForce.h functions follow a common format:
The return type is
The first parameter points to an array to hold the results. (The only exceptions are
vvsincos(), which have two result arrays pointed to by the first two parameters.)
One or more parameters point to operand arrays, the same length as the result array.
The last parameter is the array length.
vectorOps.h declares a set of vector and matrix BLAS functions on arrays of 128-bit vectors containing single-precision floating-point values. The arrays can be of any desired length, but the number of
float elements must be a multiple of 4.
vBigNum.h provides arithmetic and logical operations on large integers, which may be 128, 256, 512, or 1024 bits in length. It defines types for these values, and internally processes them as collections of 128-bit vectors.
vBigNum.h defines its own set of data types to represent large integer quantities, such as
vS128 for a signed, 128-bit integer or
vU1024 for an unsigned, 1024-bit integer. The function names begin with the data type name, followed by the name of the operation. For example,
vS512Add performs addition of two 128-bit signed integers.
The functions perform logical and arithmetic operations on scalar values that may be 128, 256, 512, or 1024 bits in width. These values are implemented as structures of one, two, four, or eight 128-bit vectors, and the operations execute on the available vector-processing hardware if possible.
The functions have names that are compatible with those in vBasicOps.h.
In versions of vecLib prior to OS X v10.7, many vecLib routines used multiple POSIX threads to improve performance. In some cases, this could cause performance problems in applications that use large numbers of POSIX threads.
An application can limit the number of threads used by vecLib by setting the environment variable
VECLIB_MAXIMUM_THREADS as follows:
To remove the limit, you can unset the environment variable as follows:
In OS X v10.7, these routines use Grand Central Dispatch, so the use of this environment variable should no longer be necessary.
For More Information
For information about membership in Apple’s developer program, go to this URL:
For information about the Velocity Engine, go to this URL:
For general technical support from Apple, go to this URL: