File : g-altive.ads
1 ------------------------------------------------------------------------------
2 -- --
3 -- GNAT COMPILER COMPONENTS --
4 -- --
5 -- G N A T . A L T I V E C --
6 -- --
7 -- S p e c --
8 -- --
9 -- Copyright (C) 2004-2011, Free Software Foundation, Inc. --
10 -- --
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 3, 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. --
17 -- --
18 -- --
19 -- --
20 -- --
21 -- --
22 -- You should have received a copy of the GNU General Public License and --
23 -- a copy of the GCC Runtime Library Exception along with this program; --
24 -- see the files COPYING3 and COPYING.RUNTIME respectively. If not, see --
25 -- <http://www.gnu.org/licenses/>. --
26 -- --
27 -- GNAT was originally developed by the GNAT team at New York University. --
28 -- Extensive contributions were provided by Ada Core Technologies Inc. --
29 -- --
30 ------------------------------------------------------------------------------
31
32 -------------------------
33 -- General description --
34 -------------------------
35
36 -- This is the root of a package hierarchy offering an Ada binding to the
37 -- PowerPC AltiVec extensions, a set of 128bit vector types together with a
38 -- set of subprograms operating on them. Relevant documents are:
39
40 -- o AltiVec Technology, Programming Interface Manual (1999-06)
41 -- to which we will refer as [PIM], describes the data types, the
42 -- functional interface and the ABI conventions.
43
44 -- o AltiVec Technology, Programming Environments Manual (2002-02)
45 -- to which we will refer as [PEM], describes the hardware architecture
46 -- and instruction set.
47
48 -- These documents, as well as a number of others of general interest on the
49 -- AltiVec technology, are available from the Motorola/AltiVec Web site at:
50
51 -- http://www.freescale.com/altivec
52
53 -- The binding interface is structured to allow alternate implementations:
54 -- for real AltiVec capable targets, and for other targets. In the latter
55 -- case, everything is emulated in software. The two versions are referred
56 -- to as:
57
58 -- o The Hard binding for AltiVec capable targets (with the appropriate
59 -- hardware support and corresponding instruction set)
60
61 -- o The Soft binding for other targets (with the low level primitives
62 -- emulated in software).
63
64 -- In addition, interfaces that are not strictly part of the base AltiVec API
65 -- are provided, such as vector conversions to and from array representations,
66 -- which are of interest for client applications (e.g. for vector
67 -- initialization purposes).
68
69 -- Only the soft binding is available today
70
71 -----------------------------------------
72 -- General package architecture survey --
73 -----------------------------------------
74
75 -- The various vector representations are all "containers" of elementary
76 -- values, the possible types of which are declared in this root package to
77 -- be generally accessible.
78
79 -- From the user standpoint, the binding materializes as a consistent
80 -- hierarchy of units:
81
82 -- GNAT.Altivec
83 -- (component types)
84 -- |
85 -- o----------------o----------------o-------------o
86 -- | | | |
87 -- Vector_Types Vector_Operations Vector_Views Conversions
88
89 -- The user can manipulate vectors through two families of types: Vector
90 -- types and View types.
91
92 -- Vector types are defined in the GNAT.Altivec.Vector_Types package
93
94 -- On these types, users can apply the Altivec operations defined in
95 -- GNAT.Altivec.Vector_Operations. Their layout is opaque and may vary across
96 -- configurations, for it is typically target-endianness dependant.
97
98 -- Vector_Types and Vector_Operations implement the core binding to the
99 -- AltiVec API, as described in [PIM-2.1 data types] and [PIM-4 AltiVec
100 -- operations and predicates].
101
102 -- View types are defined in the GNAT.Altivec.Vector_Views package
103
104 -- These types do not represent Altivec vectors per se, in the sense that the
105 -- Altivec_Operations are not available for them. They are intended to allow
106 -- Vector initializations as well as access to the Vector component values.
107
108 -- The GNAT.Altivec.Conversions package is provided to convert a View to the
109 -- corresponding Vector and vice-versa.
110
111 ---------------------------
112 -- Underlying principles --
113 ---------------------------
114
115 -- Internally, the binding relies on an abstraction of the Altivec API, a
116 -- rich set of functions around a core of low level primitives mapping to
117 -- AltiVec instructions. See for instance "vec_add" in [PIM-4.4 Generic and
118 -- Specific AltiVec operations], with no less than six result/arguments
119 -- combinations of byte vector types that map to "vaddubm".
120
121 -- The "soft" version is a software emulation of the low level primitives.
122
123 -- The "hard" version would map to real AltiVec instructions via GCC builtins
124 -- and inlining.
125
126 -------------------
127 -- Example usage --
128 -------------------
129
130 -- Here is a sample program declaring and initializing two vectors, 'add'ing
131 -- them and displaying the result components:
132
133 -- with GNAT.Altivec.Vector_Types; use GNAT.Altivec.Vector_Types;
134 -- with GNAT.Altivec.Vector_Operations; use GNAT.Altivec.Vector_Operations;
135 -- with GNAT.Altivec.Vector_Views; use GNAT.Altivec.Vector_Views;
136 -- with GNAT.Altivec.Conversions; use GNAT.Altivec.Conversions;
137
138 -- use GNAT.Altivec;
139
140 -- with Ada.Text_IO; use Ada.Text_IO;
141
142 -- procedure Sample is
143 -- Va : Vector_Unsigned_Int := To_Vector ((Values => (1, 2, 3, 4)));
144 -- Vb : Vector_Unsigned_Int := To_Vector ((Values => (1, 2, 3, 4)));
145
146 -- Vs : Vector_Unsigned_Int;
147 -- Vs_View : VUI_View;
148 -- begin
149 -- Vs := Vec_Add (Va, Vb);
150 -- Vs_View := To_View (Vs);
151
152 -- for I in Vs_View.Values'Range loop
153 -- Put_Line (Unsigned_Int'Image (Vs_View.Values (I)));
154 -- end loop;
155 -- end;
156
157 -- $ gnatmake sample.adb
158 -- [...]
159 -- $ ./sample
160 -- 2
161 -- 4
162 -- 6
163 -- 8
164
165 ------------------------------------------------------------------------------
166
167 with System;
168
169 package GNAT.Altivec is
170
171 -- Definitions of constants and vector/array component types common to all
172 -- the versions of the binding.
173
174 -- All the vector types are 128bits
175
176 VECTOR_BIT : constant := 128;
177
178 -------------------------------------------
179 -- [PIM-2.3.1 Alignment of vector types] --
180 -------------------------------------------
181
182 -- "A defined data item of any vector data type in memory is always
183 -- aligned on a 16-byte boundary. A pointer to any vector data type always
184 -- points to a 16-byte boundary. The compiler is responsible for aligning
185 -- vector data types on 16-byte boundaries."
186
187 VECTOR_ALIGNMENT : constant := Natural'Min (16, Standard'Maximum_Alignment);
188 -- This value is used to set the alignment of vector datatypes in both the
189 -- hard and the soft binding implementations.
190 --
191 -- We want this value to never be greater than 16, because none of the
192 -- binding implementations requires larger alignments and such a value
193 -- would cause useless space to be allocated/wasted for vector objects.
194 -- Furthermore, the alignment of 16 matches the hard binding leading to
195 -- a more faithful emulation.
196 --
197 -- It needs to be exactly 16 for the hard binding, and the initializing
198 -- expression is just right for this purpose since Maximum_Alignment is
199 -- expected to be 16 for the real Altivec ABI.
200 --
201 -- The soft binding doesn't rely on strict 16byte alignment, and we want
202 -- the value to be no greater than Standard'Maximum_Alignment in this case
203 -- to ensure it is supported on every possible target.
204
205 -------------------------------------------------------
206 -- [PIM-2.1] Data Types - Interpretation of contents --
207 -------------------------------------------------------
208
209 ---------------------
210 -- char components --
211 ---------------------
212
213 CHAR_BIT : constant := 8;
214 SCHAR_MIN : constant := -2 ** (CHAR_BIT - 1);
215 SCHAR_MAX : constant := 2 ** (CHAR_BIT - 1) - 1;
216 UCHAR_MAX : constant := 2 ** CHAR_BIT - 1;
217
218 type unsigned_char is mod UCHAR_MAX + 1;
219 for unsigned_char'Size use CHAR_BIT;
220
221 type signed_char is range SCHAR_MIN .. SCHAR_MAX;
222 for signed_char'Size use CHAR_BIT;
223
224 subtype bool_char is unsigned_char;
225 -- ??? There is a difference here between what the Altivec Technology
226 -- Programming Interface Manual says and what GCC says. In the manual,
227 -- vector_bool_char is a vector_unsigned_char, while in altivec.h it
228 -- is a vector_signed_char.
229
230 bool_char_True : constant bool_char := bool_char'Last;
231 bool_char_False : constant bool_char := 0;
232
233 ----------------------
234 -- short components --
235 ----------------------
236
237 SHORT_BIT : constant := 16;
238 SSHORT_MIN : constant := -2 ** (SHORT_BIT - 1);
239 SSHORT_MAX : constant := 2 ** (SHORT_BIT - 1) - 1;
240 USHORT_MAX : constant := 2 ** SHORT_BIT - 1;
241
242 type unsigned_short is mod USHORT_MAX + 1;
243 for unsigned_short'Size use SHORT_BIT;
244
245 subtype unsigned_short_int is unsigned_short;
246
247 type signed_short is range SSHORT_MIN .. SSHORT_MAX;
248 for signed_short'Size use SHORT_BIT;
249
250 subtype signed_short_int is signed_short;
251
252 subtype bool_short is unsigned_short;
253 -- ??? See bool_char
254
255 bool_short_True : constant bool_short := bool_short'Last;
256 bool_short_False : constant bool_short := 0;
257
258 subtype bool_short_int is bool_short;
259
260 --------------------
261 -- int components --
262 --------------------
263
264 INT_BIT : constant := 32;
265 SINT_MIN : constant := -2 ** (INT_BIT - 1);
266 SINT_MAX : constant := 2 ** (INT_BIT - 1) - 1;
267 UINT_MAX : constant := 2 ** INT_BIT - 1;
268
269 type unsigned_int is mod UINT_MAX + 1;
270 for unsigned_int'Size use INT_BIT;
271
272 type signed_int is range SINT_MIN .. SINT_MAX;
273 for signed_int'Size use INT_BIT;
274
275 subtype bool_int is unsigned_int;
276 -- ??? See bool_char
277
278 bool_int_True : constant bool_int := bool_int'Last;
279 bool_int_False : constant bool_int := 0;
280
281 ----------------------
282 -- float components --
283 ----------------------
284
285 FLOAT_BIT : constant := 32;
286 FLOAT_DIGIT : constant := 6;
287 FLOAT_MIN : constant := -16#0.FFFF_FF#E+32;
288 FLOAT_MAX : constant := 16#0.FFFF_FF#E+32;
289
290 type C_float is digits FLOAT_DIGIT range FLOAT_MIN .. FLOAT_MAX;
291 for C_float'Size use FLOAT_BIT;
292 -- Altivec operations always use the standard native floating-point
293 -- support of the target. Note that this means that there may be
294 -- minor differences in results between targets when the floating-
295 -- point implementations are slightly different, as would happen
296 -- with normal non-Altivec floating-point operations. In particular
297 -- the Altivec simulations may yield slightly different results
298 -- from those obtained on a true hardware Altivec target if the
299 -- floating-point implementation is not 100% compatible.
300
301 ----------------------
302 -- pixel components --
303 ----------------------
304
305 subtype pixel is unsigned_short;
306
307 -----------------------------------------------------------
308 -- Subtypes for variants found in the GCC implementation --
309 -----------------------------------------------------------
310
311 subtype c_int is signed_int;
312 subtype c_short is c_int;
313
314 LONG_BIT : constant := 32;
315 -- Some of the GCC builtins are built with "long" arguments and
316 -- expect SImode to come in.
317
318 SLONG_MIN : constant := -2 ** (LONG_BIT - 1);
319 SLONG_MAX : constant := 2 ** (LONG_BIT - 1) - 1;
320 ULONG_MAX : constant := 2 ** LONG_BIT - 1;
321
322 type signed_long is range SLONG_MIN .. SLONG_MAX;
323 type unsigned_long is mod ULONG_MAX + 1;
324
325 subtype c_long is signed_long;
326
327 subtype c_ptr is System.Address;
328
329 ---------------------------------------------------------
330 -- Access types, for the sake of some argument passing --
331 ---------------------------------------------------------
332
333 type signed_char_ptr is access all signed_char;
334 type unsigned_char_ptr is access all unsigned_char;
335
336 type short_ptr is access all c_short;
337 type signed_short_ptr is access all signed_short;
338 type unsigned_short_ptr is access all unsigned_short;
339
340 type int_ptr is access all c_int;
341 type signed_int_ptr is access all signed_int;
342 type unsigned_int_ptr is access all unsigned_int;
343
344 type long_ptr is access all c_long;
345 type signed_long_ptr is access all signed_long;
346 type unsigned_long_ptr is access all unsigned_long;
347
348 type float_ptr is access all Float;
349
350 --
351
352 type const_signed_char_ptr is access constant signed_char;
353 type const_unsigned_char_ptr is access constant unsigned_char;
354
355 type const_short_ptr is access constant c_short;
356 type const_signed_short_ptr is access constant signed_short;
357 type const_unsigned_short_ptr is access constant unsigned_short;
358
359 type const_int_ptr is access constant c_int;
360 type const_signed_int_ptr is access constant signed_int;
361 type const_unsigned_int_ptr is access constant unsigned_int;
362
363 type const_long_ptr is access constant c_long;
364 type const_signed_long_ptr is access constant signed_long;
365 type const_unsigned_long_ptr is access constant unsigned_long;
366
367 type const_float_ptr is access constant Float;
368
369 -- Access to const volatile arguments need specialized types
370
371 type volatile_float is new Float;
372 pragma Volatile (volatile_float);
373
374 type volatile_signed_char is new signed_char;
375 pragma Volatile (volatile_signed_char);
376
377 type volatile_unsigned_char is new unsigned_char;
378 pragma Volatile (volatile_unsigned_char);
379
380 type volatile_signed_short is new signed_short;
381 pragma Volatile (volatile_signed_short);
382
383 type volatile_unsigned_short is new unsigned_short;
384 pragma Volatile (volatile_unsigned_short);
385
386 type volatile_signed_int is new signed_int;
387 pragma Volatile (volatile_signed_int);
388
389 type volatile_unsigned_int is new unsigned_int;
390 pragma Volatile (volatile_unsigned_int);
391
392 type volatile_signed_long is new signed_long;
393 pragma Volatile (volatile_signed_long);
394
395 type volatile_unsigned_long is new unsigned_long;
396 pragma Volatile (volatile_unsigned_long);
397
398 type constv_char_ptr is access constant volatile_signed_char;
399 type constv_signed_char_ptr is access constant volatile_signed_char;
400 type constv_unsigned_char_ptr is access constant volatile_unsigned_char;
401
402 type constv_short_ptr is access constant volatile_signed_short;
403 type constv_signed_short_ptr is access constant volatile_signed_short;
404 type constv_unsigned_short_ptr is access constant volatile_unsigned_short;
405
406 type constv_int_ptr is access constant volatile_signed_int;
407 type constv_signed_int_ptr is access constant volatile_signed_int;
408 type constv_unsigned_int_ptr is access constant volatile_unsigned_int;
409
410 type constv_long_ptr is access constant volatile_signed_long;
411 type constv_signed_long_ptr is access constant volatile_signed_long;
412 type constv_unsigned_long_ptr is access constant volatile_unsigned_long;
413
414 type constv_float_ptr is access constant volatile_float;
415
416 private
417
418 -----------------------
419 -- Various constants --
420 -----------------------
421
422 CR6_EQ : constant := 0;
423 CR6_EQ_REV : constant := 1;
424 CR6_LT : constant := 2;
425 CR6_LT_REV : constant := 3;
426
427 end GNAT.Altivec;