1<html lang="en"> 2<head> 3<title>Vector Extensions - Using the GNU Compiler Collection (GCC)</title> 4<meta http-equiv="Content-Type" content="text/html"> 5<meta name="description" content="Using the GNU Compiler Collection (GCC)"> 6<meta name="generator" content="makeinfo 4.13"> 7<link title="Top" rel="start" href="index.html#Top"> 8<link rel="up" href="C-Extensions.html#C-Extensions" title="C Extensions"> 9<link rel="prev" href="Return-Address.html#Return-Address" title="Return Address"> 10<link rel="next" href="Offsetof.html#Offsetof" title="Offsetof"> 11<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage"> 12<!-- 13Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 141998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 152010 Free Software Foundation, Inc. 16 17Permission is granted to copy, distribute and/or modify this document 18under the terms of the GNU Free Documentation License, Version 1.3 or 19any later version published by the Free Software Foundation; with the 20Invariant Sections being ``Funding Free Software'', the Front-Cover 21Texts being (a) (see below), and with the Back-Cover Texts being (b) 22(see below). A copy of the license is included in the section entitled 23``GNU Free Documentation License''. 24 25(a) The FSF's Front-Cover Text is: 26 27 A GNU Manual 28 29(b) The FSF's Back-Cover Text is: 30 31 You have freedom to copy and modify this GNU Manual, like GNU 32 software. Copies published by the Free Software Foundation raise 33 funds for GNU development.--> 34<meta http-equiv="Content-Style-Type" content="text/css"> 35<style type="text/css"><!-- 36 pre.display { font-family:inherit } 37 pre.format { font-family:inherit } 38 pre.smalldisplay { font-family:inherit; font-size:smaller } 39 pre.smallformat { font-family:inherit; font-size:smaller } 40 pre.smallexample { font-size:smaller } 41 pre.smalllisp { font-size:smaller } 42 span.sc { font-variant:small-caps } 43 span.roman { font-family:serif; font-weight:normal; } 44 span.sansserif { font-family:sans-serif; font-weight:normal; } 45--></style> 46<link rel="stylesheet" type="text/css" href="../cs.css"> 47</head> 48<body> 49<div class="node"> 50<a name="Vector-Extensions"></a> 51<p> 52Next: <a rel="next" accesskey="n" href="Offsetof.html#Offsetof">Offsetof</a>, 53Previous: <a rel="previous" accesskey="p" href="Return-Address.html#Return-Address">Return Address</a>, 54Up: <a rel="up" accesskey="u" href="C-Extensions.html#C-Extensions">C Extensions</a> 55<hr> 56</div> 57 58<h3 class="section">6.49 Using vector instructions through built-in functions</h3> 59 60<p>On some targets, the instruction set contains SIMD vector instructions that 61operate on multiple values contained in one large register at the same time. 62For example, on the i386 the MMX, 3DNow! and SSE extensions can be used 63this way. 64 65 <p>The first step in using these extensions is to provide the necessary data 66types. This should be done using an appropriate <code>typedef</code>: 67 68<pre class="smallexample"> typedef int v4si __attribute__ ((vector_size (16))); 69</pre> 70 <p>The <code>int</code> type specifies the base type, while the attribute specifies 71the vector size for the variable, measured in bytes. For example, the 72declaration above causes the compiler to set the mode for the <code>v4si</code> 73type to be 16 bytes wide and divided into <code>int</code> sized units. For 74a 32-bit <code>int</code> this means a vector of 4 units of 4 bytes, and the 75corresponding mode of <code>foo</code> will be <acronym>V4SI</acronym>. 76 77 <p>The <code>vector_size</code> attribute is only applicable to integral and 78float scalars, although arrays, pointers, and function return values 79are allowed in conjunction with this construct. 80 81 <p>All the basic integer types can be used as base types, both as signed 82and as unsigned: <code>char</code>, <code>short</code>, <code>int</code>, <code>long</code>, 83<code>long long</code>. In addition, <code>float</code> and <code>double</code> can be 84used to build floating-point vector types. 85 86 <p>Specifying a combination that is not valid for the current architecture 87will cause GCC to synthesize the instructions using a narrower mode. 88For example, if you specify a variable of type <code>V4SI</code> and your 89architecture does not allow for this specific SIMD type, GCC will 90produce code that uses 4 <code>SIs</code>. 91 92 <p>The types defined in this manner can be used with a subset of normal C 93operations. Currently, GCC will allow using the following operators 94on these types: <code>+, -, *, /, unary minus, ^, |, &, ~, %</code>. 95 96 <p>The operations behave like C++ <code>valarrays</code>. Addition is defined as 97the addition of the corresponding elements of the operands. For 98example, in the code below, each of the 4 elements in <var>a</var> will be 99added to the corresponding 4 elements in <var>b</var> and the resulting 100vector will be stored in <var>c</var>. 101 102<pre class="smallexample"> typedef int v4si __attribute__ ((vector_size (16))); 103 104 v4si a, b, c; 105 106 c = a + b; 107</pre> 108 <p>Subtraction, multiplication, division, and the logical operations 109operate in a similar manner. Likewise, the result of using the unary 110minus or complement operators on a vector type is a vector whose 111elements are the negative or complemented values of the corresponding 112elements in the operand. 113 114 <p>In C it is possible to use shifting operators <code><<</code>, <code>>></code> on 115integer-type vectors. The operation is defined as following: <code>{a0, 116a1, ..., an} >> {b0, b1, ..., bn} == {a0 >> b0, a1 >> b1, 117..., an >> bn}</code>. Vector operands must have the same number of 118elements. Additionally second operands can be a scalar integer in which 119case the scalar is converted to the type used by the vector operand (with 120possible truncation) and each element of this new vector is the scalar's 121value. 122Consider the following code. 123 124<pre class="smallexample"> typedef int v4si __attribute__ ((vector_size (16))); 125 126 v4si a, b; 127 128 b = a >> 1; /* b = a >> {1,1,1,1}; */ 129</pre> 130 <p>In C vectors can be subscripted as if the vector were an array with 131the same number of elements and base type. Out of bound accesses 132invoke undefined behavior at runtime. Warnings for out of bound 133accesses for vector subscription can be enabled with 134<samp><span class="option">-Warray-bounds</span></samp>. 135 136 <p>You can declare variables and use them in function calls and returns, as 137well as in assignments and some casts. You can specify a vector type as 138a return type for a function. Vector types can also be used as function 139arguments. It is possible to cast from one vector type to another, 140provided they are of the same size (in fact, you can also cast vectors 141to and from other datatypes of the same size). 142 143 <p>You cannot operate between vectors of different lengths or different 144signedness without a cast. 145 146 <p>A port that supports hardware vector operations, usually provides a set 147of built-in functions that can be used to operate on vectors. For 148example, a function to add two vectors and multiply the result by a 149third could look like this: 150 151<pre class="smallexample"> v4si f (v4si a, v4si b, v4si c) 152 { 153 v4si tmp = __builtin_addv4si (a, b); 154 return __builtin_mulv4si (tmp, c); 155 } 156 157</pre> 158 </body></html> 159 160