1 ------------------------------------------------------------------------------
3 -- GNAT COMPILER COMPONENTS --
5 -- G N A T . A L T I V E C --
9 -- Copyright (C) 2004-2005, Free Software Foundation, Inc. --
11 -- GNAT is free software; you can redistribute it and/or modify it under --
12 -- terms of the GNU General Public License as published by the Free Soft- --
13 -- ware Foundation; either version 2, or (at your option) any later ver- --
14 -- sion. GNAT is distributed in the hope that it will be useful, but WITH- --
15 -- OUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY --
16 -- or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License --
17 -- for more details. You should have received a copy of the GNU General --
18 -- Public License distributed with GNAT; see file COPYING. If not, write --
19 -- to the Free Software Foundation, 59 Temple Place - Suite 330, Boston, --
20 -- MA 02111-1307, USA. --
22 -- As a special exception, if other files instantiate generics from this --
23 -- unit, or you link this unit with other files to produce an executable, --
24 -- this unit does not by itself cause the resulting executable to be --
25 -- covered by the GNU General Public License. This exception does not --
26 -- however invalidate any other reasons why the executable file might be --
27 -- covered by the GNU Public License. --
29 -- GNAT was originally developed by the GNAT team at New York University. --
30 -- Extensive contributions were provided by Ada Core Technologies Inc. --
32 ------------------------------------------------------------------------------
34 -------------------------
35 -- General description --
36 -------------------------
38 -- This is the root of a package hierarchy offering an Ada binding to the
39 -- PowerPC AltiVec extensions. These extensions basically consist in a set of
40 -- 128bit vector types together with a set of subprograms operating on such
41 -- vectors. On a real Altivec capable target, vector objects map to hardware
42 -- vector registers and the subprograms map to a set of specific hardware
45 -- Relevant documents are:
47 -- o AltiVec Technology, Programming Interface Manual (1999-06)
48 -- to which we will refer as [PIM], describes the data types, the
49 -- functional interface and the ABI conventions.
51 -- o AltiVec Technology, Programming Environments Manual (2002-02)
52 -- to which we will refer as [PEM], describes the hardware architecture
53 -- and instruction set.
55 -- These documents, as well as a number of others of general interest on the
56 -- AltiVec technology, are available from the Motorola/AltiVec Web site at
58 -- http://www.motorola.com/altivec
60 -- We offer two versions of this binding: one for real AltiVec capable
61 -- targets, and one for other targets. In the latter case, everything is
62 -- emulated in software. We will refer to the two bindings as:
64 -- o The Hard binding for AltiVec capable targets (with the appropriate
65 -- hardware support and corresponding instruction set)
67 -- o The Soft binding for other targets (with the low level primitives
68 -- emulated in software).
70 -- The two versions of the binding are expected to be equivalent from the
71 -- functional standpoint. The same client application code should observe no
72 -- difference in operation results, even if the Soft version is used on a
73 -- non-powerpc target. The Hard binding is naturally expected to run faster
74 -- than the Soft version on the same target.
76 -- We also offer interfaces not strictly part of the base AltiVec API, such
77 -- as vector conversions to/from array representations, which are of interest
78 -- for client applications (e.g. for vector initialization purposes) and may
79 -- also be used as implementation facilities.
81 -----------------------------------------
82 -- General package architecture survey --
83 -----------------------------------------
85 -- The various vector representations are all "containers" of elementary
86 -- values, the possible types of which are declared in this root package to
87 -- be generally accessible.
89 -- From the user standpoint, the two versions of the binding are available
90 -- through a consistent hierarchy of units providing identical services:
95 -- o----------------o----------------o-------------o
97 -- Vector_Types Vector_Operations Vector_Views Conversions
99 -- The user can manipulate vectors through two families of types: Vector
100 -- types and View types.
102 -- Vector types are defined in the GNAT.Altivec.Vector_Types package
104 -- On these types, the user can apply the Altivec operations defined in
105 -- GNAT.Altivec.Vector_Operations. Their layout is opaque and may vary across
106 -- configurations, for it is typically target-endianness dependant.
108 -- Vector_Types and Vector_Operations implement the core binding to the
109 -- AltiVec API, as described in [PIM-2.1 data types] and [PIM-4 AltiVec
110 -- operations and predicates].
112 -- View types are defined in the GNAT.Altivec.Vector_Views package
114 -- These types do not represent Altivec vectors per se, in the sense that the
115 -- Altivec_Operations are not available for them. They are intended to allow
116 -- Vector initializations as well as access to the Vector component values.
118 -- The GNAT.Altivec.Conversions package is provided to convert a View to the
119 -- corresponding Vector and vice-versa.
121 -- The two versions of the binding rely on a low level internal interface,
122 -- and switching from one version to the other amounts to select one low
123 -- level implementation instead of the other.
125 -- The bindings are provided as a set of sources together with a project file
126 -- (altivec.gpr). The hard/soft binding selection is controlled by a project
127 -- variable on targets where switching makes sense. See the example usage
130 ---------------------------
131 -- Underlying principles --
132 ---------------------------
134 -- The general organization sketched above has been devised from a number
137 -- o From the clients standpoint, the two versions of the binding should be
138 -- as easily exchangable as possible,
140 -- o From the maintenance standpoint, we want to avoid as much code
141 -- duplication as possible.
143 -- o From both standpoints above, we want to maintain a clear interface
144 -- separation between the base bindings to the Motorola API and the
145 -- additional facilities.
147 -- The identification of the low level interface is directly inspired by the
148 -- the base API organization, basically consisting of a rich set of functions
149 -- around a core of low level primitives mapping to AltiVec instructions.
151 -- See for instance "vec_add" in [PIM-4.4 Generic and Specific AltiVec
152 -- operations]: no less than six result/arguments combinations of byte vector
153 -- types map to "vaddubm".
155 -- The "hard" version of the low level primitives map to real AltiVec
156 -- instructions via the corresponding GCC builtins. The "soft" version is
157 -- a software emulation of those.
163 -- Here is a sample program declaring and initializing two vectors, 'add'ing
164 -- them and displaying the result components:
166 -- with GNAT.Altivec.Vector_Types; use GNAT.Altivec.Vector_Types;
167 -- with GNAT.Altivec.Vector_Operations; use GNAT.Altivec.Vector_Operations;
168 -- with GNAT.Altivec.Vector_Views; use GNAT.Altivec.Vector_Views;
169 -- with GNAT.Altivec.Conversions; use GNAT.Altivec.Conversions;
173 -- procedure Sample is
174 -- Va : Vector_Unsigned_Int := To_Vector ((Values => (1, 2, 3, 4)));
175 -- Vb : Vector_Unsigned_Int := To_Vector ((Values => (1, 2, 3, 4)));
177 -- Vs : Vector_Unsigned_Int;
178 -- Vs_View : VUI_View;
180 -- Vs := Vec_Add (Va, Vb);
181 -- Vs_View := To_View (Vs);
183 -- for I in Vs_View.Values'Range loop
184 -- Put_Line (Unsigned_Int'Image (Vs_View.Values (I)));
188 -- This currently requires the GNAT project management facilities to compile,
189 -- to automatically retrieve the set of necessary sources and switches
190 -- depending on your configuration. For the example above, customizing the
191 -- switches to include -g also, this would be something like:
195 -- with "altivec.gpr";
199 -- for Source_Dirs use (".");
200 -- for Main use ("sample");
202 -- package Compiler is
203 -- for Default_Switches ("Ada") use
204 -- Altivec.Compiler'Default_Switches ("Ada") & "-g";
209 -- $ gnatmake -Psample
217 ------------------------------------------------------------------------------
221 package GNAT.Altivec is
223 -- Definitions of constants and vector/array component types common to all
224 -- the versions of the binding.
226 -- All the vector types are 128bits
228 VECTOR_BIT : constant := 128;
230 -------------------------------------------
231 -- [PIM-2.3.1 Alignment of vector types] --
232 -------------------------------------------
234 -- "A defined data item of any vector data type in memory is always
235 -- aligned on a 16-byte boundary. A pointer to any vector data type always
236 -- points to a 16-byte boundary. The compiler is responsible for aligning
237 -- vector data types on 16-byte boundaries."
239 VECTOR_ALIGNMENT : constant := 16;
241 -------------------------------------------------------
242 -- [PIM-2.1] Data Types - Interpretation of contents --
243 -------------------------------------------------------
245 ---------------------
246 -- char components --
247 ---------------------
249 CHAR_BIT : constant := 8;
250 SCHAR_MIN : constant := -2 ** (CHAR_BIT - 1);
251 SCHAR_MAX : constant := 2 ** (CHAR_BIT - 1) - 1;
252 UCHAR_MAX : constant := 2 ** CHAR_BIT - 1;
254 type unsigned_char is mod UCHAR_MAX + 1;
255 for unsigned_char'Size use CHAR_BIT;
257 type signed_char is range SCHAR_MIN .. SCHAR_MAX;
258 for signed_char'Size use CHAR_BIT;
260 subtype bool_char is unsigned_char;
261 -- ??? There is a difference here between what the Altivec Technology
262 -- Programming Interface Manual says and what GCC says. In the manual,
263 -- vector_bool_char is a vector_unsigned_char, while in altivec.h it
264 -- is a vector_signed_char.
266 bool_char_True : constant bool_char := bool_char'Last;
267 bool_char_False : constant bool_char := 0;
269 ----------------------
270 -- short components --
271 ----------------------
273 SHORT_BIT : constant := 16;
274 SSHORT_MIN : constant := -2 ** (SHORT_BIT - 1);
275 SSHORT_MAX : constant := 2 ** (SHORT_BIT - 1) - 1;
276 USHORT_MAX : constant := 2 ** SHORT_BIT - 1;
278 type unsigned_short is mod USHORT_MAX + 1;
279 for unsigned_short'Size use SHORT_BIT;
281 subtype unsigned_short_int is unsigned_short;
283 type signed_short is range SSHORT_MIN .. SSHORT_MAX;
284 for signed_short'Size use SHORT_BIT;
286 subtype signed_short_int is signed_short;
288 subtype bool_short is unsigned_short;
291 bool_short_True : constant bool_short := bool_short'Last;
292 bool_short_False : constant bool_short := 0;
294 subtype bool_short_int is bool_short;
300 INT_BIT : constant := 32;
301 SINT_MIN : constant := -2 ** (INT_BIT - 1);
302 SINT_MAX : constant := 2 ** (INT_BIT - 1) - 1;
303 UINT_MAX : constant := 2 ** INT_BIT - 1;
305 type unsigned_int is mod UINT_MAX + 1;
306 for unsigned_int'Size use INT_BIT;
308 type signed_int is range SINT_MIN .. SINT_MAX;
309 for signed_int'Size use INT_BIT;
311 subtype bool_int is unsigned_int;
314 bool_int_True : constant bool_int := bool_int'Last;
315 bool_int_False : constant bool_int := 0;
317 ----------------------
318 -- float components --
319 ----------------------
321 FLOAT_BIT : constant := 32;
322 FLOAT_DIGIT : constant := 6;
323 FLOAT_MIN : constant := -16#0.FFFF_FF#E+32;
324 FLOAT_MAX : constant := 16#0.FFFF_FF#E+32;
326 type C_float is digits FLOAT_DIGIT range FLOAT_MIN .. FLOAT_MAX;
327 for C_float'Size use FLOAT_BIT;
329 ----------------------
330 -- pixel components --
331 ----------------------
333 subtype pixel is unsigned_short;
335 -----------------------------------------------------------
336 -- Subtypes for variants found in the GCC implementation --
337 -----------------------------------------------------------
339 subtype c_int is signed_int;
340 subtype c_short is c_int;
342 LONG_BIT : constant := 32;
343 -- Some of the GCC builtins are built with "long" arguments and
344 -- expect SImode to come in.
346 SLONG_MIN : constant := -2 ** (LONG_BIT - 1);
347 SLONG_MAX : constant := 2 ** (LONG_BIT - 1) - 1;
348 ULONG_MAX : constant := 2 ** LONG_BIT - 1;
350 type signed_long is range SLONG_MIN .. SLONG_MAX;
351 type unsigned_long is mod ULONG_MAX + 1;
353 subtype c_long is signed_long;
355 subtype c_ptr is System.Address;
357 ---------------------------------------------------------
358 -- Access types, for the sake of some argument passing --
359 ---------------------------------------------------------
361 type signed_char_ptr is access all signed_char;
362 type unsigned_char_ptr is access all unsigned_char;
364 type short_ptr is access all c_short;
365 type signed_short_ptr is access all signed_short;
366 type unsigned_short_ptr is access all unsigned_short;
368 type int_ptr is access all c_int;
369 type signed_int_ptr is access all signed_int;
370 type unsigned_int_ptr is access all unsigned_int;
372 type long_ptr is access all c_long;
373 type signed_long_ptr is access all signed_long;
374 type unsigned_long_ptr is access all unsigned_long;
376 type float_ptr is access all Float;
380 type const_signed_char_ptr is access constant signed_char;
381 type const_unsigned_char_ptr is access constant unsigned_char;
383 type const_short_ptr is access constant c_short;
384 type const_signed_short_ptr is access constant signed_short;
385 type const_unsigned_short_ptr is access constant unsigned_short;
387 type const_int_ptr is access constant c_int;
388 type const_signed_int_ptr is access constant signed_int;
389 type const_unsigned_int_ptr is access constant unsigned_int;
391 type const_long_ptr is access constant c_long;
392 type const_signed_long_ptr is access constant signed_long;
393 type const_unsigned_long_ptr is access constant unsigned_long;
395 type const_float_ptr is access constant Float;
397 -- Access to const volatile arguments need specialized types
399 type volatile_float is new Float;
400 pragma Volatile (volatile_float);
402 type volatile_signed_char is new signed_char;
403 pragma Volatile (volatile_signed_char);
405 type volatile_unsigned_char is new unsigned_char;
406 pragma Volatile (volatile_unsigned_char);
408 type volatile_signed_short is new signed_short;
409 pragma Volatile (volatile_signed_short);
411 type volatile_unsigned_short is new unsigned_short;
412 pragma Volatile (volatile_unsigned_short);
414 type volatile_signed_int is new signed_int;
415 pragma Volatile (volatile_signed_int);
417 type volatile_unsigned_int is new unsigned_int;
418 pragma Volatile (volatile_unsigned_int);
420 type volatile_signed_long is new signed_long;
421 pragma Volatile (volatile_signed_long);
423 type volatile_unsigned_long is new unsigned_long;
424 pragma Volatile (volatile_unsigned_long);
426 type constv_char_ptr is access constant volatile_signed_char;
427 type constv_signed_char_ptr is access constant volatile_signed_char;
428 type constv_unsigned_char_ptr is access constant volatile_unsigned_char;
430 type constv_short_ptr is access constant volatile_signed_short;
431 type constv_signed_short_ptr is access constant volatile_signed_short;
432 type constv_unsigned_short_ptr is access constant volatile_unsigned_short;
434 type constv_int_ptr is access constant volatile_signed_int;
435 type constv_signed_int_ptr is access constant volatile_signed_int;
436 type constv_unsigned_int_ptr is access constant volatile_unsigned_int;
438 type constv_long_ptr is access constant volatile_signed_long;
439 type constv_signed_long_ptr is access constant volatile_signed_long;
440 type constv_unsigned_long_ptr is access constant volatile_unsigned_long;
442 type constv_float_ptr is access constant volatile_float;
446 -----------------------
447 -- Various constants --
448 -----------------------
450 CR6_EQ : constant := 0;
451 CR6_EQ_REV : constant := 1;
452 CR6_LT : constant := 2;
453 CR6_LT_REV : constant := 3;