This is the mail archive of the
gcc-patches@gcc.gnu.org
mailing list for the GCC project.
A bit of vector extension documentation
- To: <gcc-patches at gcc dot gnu dot org>
- Subject: A bit of vector extension documentation
- From: Bernd Schmidt <bernds at redhat dot com>
- Date: Wed, 26 Sep 2001 15:15:20 +0100 (BST)
I noticed that internals of the vector extension code are pretty well
documentated, but there's hardly anything that would tell the user
how to use them. Below is a patch that improves this a bit (I suppose
there'll need to be additional port-specific documentation).
Before I check it in - any comments from the regular documentation
maintainers? Also, I was wondering whether we actually want to
document the use of __attribute__((mode)); so far it is undocumented
(presumably since it's a low-level interface that we typically don't
want users to see). Should we instead create standard header files to
provide the necessary types?
Bernd
Index: extend.texi
===================================================================
RCS file: /cvs/gcc/egcs/gcc/doc/extend.texi,v
retrieving revision 1.25
diff -c -p -r1.25 extend.texi
*** extend.texi 2001/09/21 01:27:06 1.25
--- extend.texi 2001/09/26 14:05:50
*************** extensions, accepted by GCC in C89 mode
*** 430,435 ****
--- 430,436 ----
* Function Names:: Printable strings which are the name of the current
function.
* Return Address:: Getting the return or frame address of a function.
+ * Vector Extensions:: Using vector instructions through built-in functions.
* Other Builtins:: Other built-in functions.
* Pragmas:: Pragmas accepted by GCC.
@end menu
*************** extensions, accepted by GCC in C89 mode
*** 483,488 ****
--- 484,490 ----
* Function Names:: Printable strings which are the name of the current
function.
* Return Address:: Getting the return or frame address of a function.
+ * Vector Extensions:: Using vector instructions through built-in functions.
* Other Builtins:: Other built-in functions.
* Pragmas:: Pragmas accepted by GCC.
@end menu
*************** the first frame pointer is properly init
*** 4146,4151 ****
--- 4148,4218 ----
This function should only be used with a non-zero argument for debugging
purposes.
@end deftypefn
+
+ @node Vector Extensions
+ @section Using vector instructions through built-in functions
+
+ On some targets, the instruction set contains SIMD vector instructions that
+ operate on multiple values contained in one large register at the same time.
+ For example, on the i386 the MMX, 3Dnow! and SSE extensions can be used
+ this way.
+
+ The first step in using these extensions is to provide the necessary data
+ types. This should be done using an appropriate @code{typedef}:
+
+ @example
+ typedef int v4si __attribute__ ((mode(V4SI)));
+ @end example
+
+ The base type @code{int} is effectively ignored by the compiler, the
+ actual properties of the new type @code{v4si} are defined by the
+ @code{__attribute__}. It defines the machine mode to be used; for vector
+ types these have the form @code{VnB}; @code{n} should be the number of
+ elements in the vector, and @code{B} should be the base mode of the
+ individual elements. The following can be used as base modes:
+
+ @table @code
+ @item QI
+ An integer that is as wide as the smallest addressable unit, usually 8 bits.
+ @item HI
+ An integer, twice as wide as a QI mode integer, usually 16 bits.
+ @item SI
+ An integer, four times as wide as a QI mode integer, usually 32 bits.
+ @item DI
+ An integer, eight times as wide as a QI mode integer, usually 64 bits.
+ @item SF
+ A floating point value, as wide as a SI mode integer, usually 32 bits.
+ @item DF
+ A floating point value, as wide as a DI mode integer, usually 64 bits.
+ @end table
+
+ Not all base types or combinations are always valid; which modes can be used
+ is determined by the target machine. For example, if targetting the i386 MMX
+ extensions, only V8QI, V4HI and V2SI are allowed modes.
+
+ There are no @code{V1xx} vector modes - they would be identical to the
+ corresponding base mode.
+
+ The types defined in this manner are somewhat special, they cannot be
+ used with most normal C operations (i.e., a vector addition can @emph{not}
+ be represented by a normal addition of two vector type variables). You
+ can only declare variables and use them in function calls and returns, as
+ well as in some casts. It is possible to cast from one vector type to
+ another, provided they are of the same size (in fact, you can also cast
+ vectors to and from other datatypes of the same size).
+
+ A port that supports vector operations provides a set of built-in functions
+ that can be used to operate on vectors. For example, a function to add two
+ vectors and multiply the result by a third could look like this:
+
+ @example
+ v4si f (v4si a, v4si b, v4si c)
+ @{
+ v4si tmp = __builtin_addv4si (a, b);
+ return __builtin_mulv4si (tmp, c);
+ @}
+
+ @end example
@node Other Builtins
@section Other built-in functions provided by GCC