gcc/ada/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-2009, 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 -- As a special exception under Section 7 of GPL version 3, you are granted --
  19 -- additional permissions described in the GCC Runtime Library Exception,   --
  20 -- version 3.1, as published by the Free Software Foundation.               --
  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. These extensions basically consist in a set of
  38 --  128bit vector types together with a set of subprograms operating on such
  39 --  vectors. On a real Altivec capable target, vector objects map to hardware
  40 --  vector registers and the subprograms map to a set of specific hardware
  41 --  instructions.
  42
  43 --  Relevant documents are:
  44
  45 --  o AltiVec Technology, Programming Interface Manual (1999-06)
  46 --    to which we will refer as [PIM], describes the data types, the
  47 --    functional interface and the ABI conventions.
  48
  49 --  o AltiVec Technology, Programming Environments Manual (2002-02)
  50 --    to which we will refer as [PEM], describes the hardware architecture
  51 --    and instruction set.
  52
  53 --  These documents, as well as a number of others of general interest on the
  54 --  AltiVec technology, are available from the Motorola/AltiVec Web site at
  55
  56 --  http://www.motorola.com/altivec
  57
  58 --  We offer two versions of this binding: one for real AltiVec capable
  59 --  targets, and one for other targets. In the latter case, everything is
  60 --  emulated in software. We will refer to the two bindings as:
  61
  62 --  o The Hard binding for AltiVec capable targets (with the appropriate
  63 --    hardware support and corresponding instruction set)
  64
  65 --  o The Soft binding for other targets (with the low level primitives
  66 --    emulated in software).
  67
  68 --  The two versions of the binding are expected to be equivalent from the
  69 --  functional standpoint. The same client application code should observe no
  70 --  difference in operation results, even if the Soft version is used on a
  71 --  non-powerpc target. The Hard binding is naturally expected to run faster
  72 --  than the Soft version on the same target.
  73
  74 --  We also offer interfaces not strictly part of the base AltiVec API, such
  75 --  as vector conversions to/from array representations, which are of interest
  76 --  for client applications (e.g. for vector initialization purposes) and may
  77 --  also be used as implementation facilities.
  78
  79 -----------------------------------------
  80 -- General package architecture survey --
  81 -----------------------------------------
  82
  83 --  The various vector representations are all "containers" of elementary
  84 --  values, the possible types of which are declared in this root package to
  85 --  be generally accessible.
  86
  87 --  From the user standpoint, the two versions of the binding are available
  88 --  through a consistent hierarchy of units providing identical services:
  89
  90 --                             GNAT.Altivec
  91 --                           (component types)
  92 --                                   |
  93 --          o----------------o----------------o-------------o
  94 --          |                |                |             |
  95 --    Vector_Types   Vector_Operations   Vector_Views   Conversions
  96
  97 --  The user can manipulate vectors through two families of types: Vector
  98 --  types and View types.
  99
 100 --  Vector types are defined in the GNAT.Altivec.Vector_Types package
 101
 102 --  On these types, the user can apply the Altivec operations defined in
 103 --  GNAT.Altivec.Vector_Operations. Their layout is opaque and may vary across
 104 --  configurations, for it is typically target-endianness dependant.
 105
 106 --  Vector_Types and Vector_Operations implement the core binding to the
 107 --  AltiVec API, as described in [PIM-2.1 data types] and [PIM-4 AltiVec
 108 --  operations and predicates].
 109
 110 --  View types are defined in the GNAT.Altivec.Vector_Views package
 111
 112 --  These types do not represent Altivec vectors per se, in the sense that the
 113 --  Altivec_Operations are not available for them. They are intended to allow
 114 --  Vector initializations as well as access to the Vector component values.
 115
 116 --  The GNAT.Altivec.Conversions package is provided to convert a View to the
 117 --  corresponding Vector and vice-versa.
 118
 119 --  The two versions of the binding rely on a low level internal interface,
 120 --  and switching from one version to the other amounts to select one low
 121 --  level implementation instead of the other.
 122
 123 --  The bindings are provided as a set of sources together with a project file
 124 --  (altivec.gpr). The hard/soft binding selection is controlled by a project
 125 --  variable on targets where switching makes sense. See the example usage
 126 --  section below.
 127
 128 ---------------------------
 129 -- Underlying principles --
 130 ---------------------------
 131
 132 --  The general organization sketched above has been devised from a number
 133 --  of driving ideas:
 134
 135 --  o From the clients standpoint, the two versions of the binding should be
 136 --    as easily exchangeable as possible,
 137
 138 --  o From the maintenance standpoint, we want to avoid as much code
 139 --    duplication as possible.
 140
 141 --  o From both standpoints above, we want to maintain a clear interface
 142 --    separation between the base bindings to the Motorola API and the
 143 --    additional facilities.
 144
 145 --  The identification of the low level interface is directly inspired by the
 146 --  the base API organization, basically consisting of a rich set of functions
 147 --  around a core of low level primitives mapping to AltiVec instructions.
 148
 149 --  See for instance "vec_add" in [PIM-4.4 Generic and Specific AltiVec
 150 --  operations]: no less than six result/arguments combinations of byte vector
 151 --  types map to "vaddubm".
 152
 153 --  The "hard" version of the low level primitives map to real AltiVec
 154 --  instructions via the corresponding GCC builtins. The "soft" version is
 155 --  a software emulation of those.
 156
 157 -------------------
 158 -- Example usage --
 159 -------------------
 160
 161 --  Here is a sample program declaring and initializing two vectors, 'add'ing
 162 --  them and displaying the result components:
 163
 164 --  with GNAT.Altivec.Vector_Types;      use GNAT.Altivec.Vector_Types;
 165 --  with GNAT.Altivec.Vector_Operations; use GNAT.Altivec.Vector_Operations;
 166 --  with GNAT.Altivec.Vector_Views;      use GNAT.Altivec.Vector_Views;
 167 --  with GNAT.Altivec.Conversions;       use GNAT.Altivec.Conversions;
 168
 169 --  use GNAT.Altivec;
 170
 171 --  procedure Sample is
 172 --     Va : Vector_Unsigned_Int := To_Vector ((Values => (1, 2, 3, 4)));
 173 --     Vb : Vector_Unsigned_Int := To_Vector ((Values => (1, 2, 3, 4)));
 174
 175 --     Vs : Vector_Unsigned_Int;
 176 --     Vs_View : VUI_View;
 177 --  begin
 178 --     Vs := Vec_Add (Va, Vb);
 179 --     Vs_View := To_View (Vs);
 180
 181 --     for I in Vs_View.Values'Range loop
 182 --        Put_Line (Unsigned_Int'Image (Vs_View.Values (I)));
 183 --     end loop;
 184 --  end;
 185
 186 --  This currently requires the GNAT project management facilities to compile,
 187 --  to automatically retrieve the set of necessary sources and switches
 188 --  depending on your configuration. For the example above, customizing the
 189 --  switches to include -g also, this would be something like:
 190
 191 --  sample.gpr
 192 --
 193 --  with "altivec.gpr";
 194 --
 195 --  project Sample is
 196
 197 --    for Source_Dirs use (".");
 198 --    for Main use ("sample");
 199
 200 --    package Compiler is
 201 --       for Default_Switches ("Ada") use
 202 --           Altivec.Compiler'Default_Switches ("Ada") & "-g";
 203 --    end Compiler;
 204
 205 --  end Sample;
 206
 207 --  $ gnatmake -Psample
 208 --  [...]
 209 --  $ ./sample
 210 --  2
 211 --  4
 212 --  6
 213 --  8
 214
 215 ------------------------------------------------------------------------------
 216
 217 with System;
 218
 219 package GNAT.Altivec is
 220
 221    --  Definitions of constants and vector/array component types common to all
 222    --  the versions of the binding.
 223
 224    --  All the vector types are 128bits
 225
 226    VECTOR_BIT : constant := 128;
 227
 228    -------------------------------------------
 229    -- [PIM-2.3.1 Alignment of vector types] --
 230    -------------------------------------------
 231
 232    --  "A defined data item of any vector data type in memory is always
 233    --  aligned on a 16-byte boundary. A pointer to any vector data type always
 234    --  points to a 16-byte boundary. The compiler is responsible for aligning
 235    --  vector data types on 16-byte boundaries."
 236
 237    VECTOR_ALIGNMENT : constant := Natural'Min (16, Standard'Maximum_Alignment);
 238    --  This value is used to set the alignment of vector datatypes in both the
 239    --  hard and the soft binding implementations.
 240    --
 241    --  We want this value to never be greater than 16, because none of the
 242    --  binding implementations requires larger alignments and such a value
 243    --  would cause useless space to be allocated/wasted for vector objects.
 244    --  Furthermore, the alignment of 16 matches the hard binding leading to
 245    --  a more faithful emulation.
 246    --
 247    --  It needs to be exactly 16 for the hard binding, and the initializing
 248    --  expression is just right for this purpose since Maximum_Alignment is
 249    --  expected to be 16 for the real Altivec ABI.
 250    --
 251    --  The soft binding doesn't rely on strict 16byte alignment, and we want
 252    --  the value to be no greater than Standard'Maximum_Alignment in this case
 253    --  to ensure it is supported on every possible target.
 254
 255    -------------------------------------------------------
 256    -- [PIM-2.1] Data Types - Interpretation of contents --
 257    -------------------------------------------------------
 258
 259    ---------------------
 260    -- char components --
 261    ---------------------
 262
 263    CHAR_BIT    : constant := 8;
 264    SCHAR_MIN   : constant := -2 ** (CHAR_BIT - 1);
 265    SCHAR_MAX   : constant := 2 ** (CHAR_BIT - 1) - 1;
 266    UCHAR_MAX   : constant := 2 ** CHAR_BIT - 1;
 267
 268    type unsigned_char is mod UCHAR_MAX + 1;
 269    for unsigned_char'Size use CHAR_BIT;
 270
 271    type signed_char is range SCHAR_MIN .. SCHAR_MAX;
 272    for signed_char'Size use CHAR_BIT;
 273
 274    subtype bool_char is unsigned_char;
 275    --  ??? There is a difference here between what the Altivec Technology
 276    --  Programming Interface Manual says and what GCC says. In the manual,
 277    --  vector_bool_char is a vector_unsigned_char, while in altivec.h it
 278    --  is a vector_signed_char.
 279
 280    bool_char_True  : constant bool_char := bool_char'Last;
 281    bool_char_False : constant bool_char := 0;
 282
 283    ----------------------
 284    -- short components --
 285    ----------------------
 286
 287    SHORT_BIT   : constant := 16;
 288    SSHORT_MIN  : constant := -2 ** (SHORT_BIT - 1);
 289    SSHORT_MAX  : constant := 2 ** (SHORT_BIT - 1) - 1;
 290    USHORT_MAX  : constant := 2 ** SHORT_BIT - 1;
 291
 292    type unsigned_short is mod USHORT_MAX + 1;
 293    for unsigned_short'Size use SHORT_BIT;
 294
 295    subtype unsigned_short_int is unsigned_short;
 296
 297    type signed_short is range SSHORT_MIN .. SSHORT_MAX;
 298    for signed_short'Size use SHORT_BIT;
 299
 300    subtype signed_short_int is signed_short;
 301
 302    subtype bool_short is unsigned_short;
 303    --  ??? See bool_char
 304
 305    bool_short_True  : constant bool_short := bool_short'Last;
 306    bool_short_False : constant bool_short := 0;
 307
 308    subtype bool_short_int is bool_short;
 309
 310    --------------------
 311    -- int components --
 312    --------------------
 313
 314    INT_BIT     : constant := 32;
 315    SINT_MIN    : constant := -2 ** (INT_BIT - 1);
 316    SINT_MAX    : constant := 2 ** (INT_BIT - 1) - 1;
 317    UINT_MAX    : constant := 2 ** INT_BIT - 1;
 318
 319    type unsigned_int is mod UINT_MAX + 1;
 320    for unsigned_int'Size use INT_BIT;
 321
 322    type signed_int is range SINT_MIN .. SINT_MAX;
 323    for signed_int'Size use INT_BIT;
 324
 325    subtype bool_int is unsigned_int;
 326    --  ??? See bool_char
 327
 328    bool_int_True  : constant bool_int := bool_int'Last;
 329    bool_int_False : constant bool_int := 0;
 330
 331    ----------------------
 332    -- float components --
 333    ----------------------
 334
 335    FLOAT_BIT   : constant := 32;
 336    FLOAT_DIGIT : constant := 6;
 337    FLOAT_MIN   : constant := -16#0.FFFF_FF#E+32;
 338    FLOAT_MAX   : constant := 16#0.FFFF_FF#E+32;
 339
 340    type C_float is digits FLOAT_DIGIT range FLOAT_MIN .. FLOAT_MAX;
 341    for C_float'Size use FLOAT_BIT;
 342    --  Altivec operations always use the standard native floating-point
 343    --  support of the target. Note that this means that there may be
 344    --  minor differences in results between targets when the floating-
 345    --  point implementations are slightly different, as would happen
 346    --  with normal non-Altivec floating-point operations. In particular
 347    --  the Altivec simulations may yield slightly different results
 348    --  from those obtained on a true hardware Altivec target if the
 349    --  floating-point implementation is not 100% compatible.
 350
 351    ----------------------
 352    -- pixel components --
 353    ----------------------
 354
 355    subtype pixel is unsigned_short;
 356
 357    -----------------------------------------------------------
 358    -- Subtypes for variants found in the GCC implementation --
 359    -----------------------------------------------------------
 360
 361    subtype c_int is signed_int;
 362    subtype c_short is c_int;
 363
 364    LONG_BIT  : constant := 32;
 365    --  Some of the GCC builtins are built with "long" arguments and
 366    --  expect SImode to come in.
 367
 368    SLONG_MIN : constant := -2 ** (LONG_BIT - 1);
 369    SLONG_MAX : constant :=  2 ** (LONG_BIT - 1) - 1;
 370    ULONG_MAX : constant :=  2 ** LONG_BIT - 1;
 371
 372    type signed_long   is range SLONG_MIN .. SLONG_MAX;
 373    type unsigned_long is mod ULONG_MAX + 1;
 374
 375    subtype c_long is signed_long;
 376
 377    subtype c_ptr is System.Address;
 378
 379    ---------------------------------------------------------
 380    -- Access types, for the sake of some argument passing --
 381    ---------------------------------------------------------
 382
 383    type signed_char_ptr    is access all signed_char;
 384    type unsigned_char_ptr  is access all unsigned_char;
 385
 386    type short_ptr          is access all c_short;
 387    type signed_short_ptr   is access all signed_short;
 388    type unsigned_short_ptr is access all unsigned_short;
 389
 390    type int_ptr            is access all c_int;
 391    type signed_int_ptr     is access all signed_int;
 392    type unsigned_int_ptr   is access all unsigned_int;
 393
 394    type long_ptr           is access all c_long;
 395    type signed_long_ptr    is access all signed_long;
 396    type unsigned_long_ptr  is access all unsigned_long;
 397
 398    type float_ptr          is access all Float;
 399
 400    --
 401
 402    type const_signed_char_ptr    is access constant signed_char;
 403    type const_unsigned_char_ptr  is access constant unsigned_char;
 404
 405    type const_short_ptr          is access constant c_short;
 406    type const_signed_short_ptr   is access constant signed_short;
 407    type const_unsigned_short_ptr is access constant unsigned_short;
 408
 409    type const_int_ptr            is access constant c_int;
 410    type const_signed_int_ptr     is access constant signed_int;
 411    type const_unsigned_int_ptr   is access constant unsigned_int;
 412
 413    type const_long_ptr           is access constant c_long;
 414    type const_signed_long_ptr    is access constant signed_long;
 415    type const_unsigned_long_ptr  is access constant unsigned_long;
 416
 417    type const_float_ptr          is access constant Float;
 418
 419    --  Access to const volatile arguments need specialized types
 420
 421    type volatile_float is new Float;
 422    pragma Volatile (volatile_float);
 423
 424    type volatile_signed_char is new signed_char;
 425    pragma Volatile (volatile_signed_char);
 426
 427    type volatile_unsigned_char is new unsigned_char;
 428    pragma Volatile (volatile_unsigned_char);
 429
 430    type volatile_signed_short is new signed_short;
 431    pragma Volatile (volatile_signed_short);
 432
 433    type volatile_unsigned_short is new unsigned_short;
 434    pragma Volatile (volatile_unsigned_short);
 435
 436    type volatile_signed_int is new signed_int;
 437    pragma Volatile (volatile_signed_int);
 438
 439    type volatile_unsigned_int is new unsigned_int;
 440    pragma Volatile (volatile_unsigned_int);
 441
 442    type volatile_signed_long is new signed_long;
 443    pragma Volatile (volatile_signed_long);
 444
 445    type volatile_unsigned_long is new unsigned_long;
 446    pragma Volatile (volatile_unsigned_long);
 447
 448    type constv_char_ptr           is access constant volatile_signed_char;
 449    type constv_signed_char_ptr    is access constant volatile_signed_char;
 450    type constv_unsigned_char_ptr  is access constant volatile_unsigned_char;
 451
 452    type constv_short_ptr          is access constant volatile_signed_short;
 453    type constv_signed_short_ptr   is access constant volatile_signed_short;
 454    type constv_unsigned_short_ptr is access constant volatile_unsigned_short;
 455
 456    type constv_int_ptr            is access constant volatile_signed_int;
 457    type constv_signed_int_ptr     is access constant volatile_signed_int;
 458    type constv_unsigned_int_ptr   is access constant volatile_unsigned_int;
 459
 460    type constv_long_ptr           is access constant volatile_signed_long;
 461    type constv_signed_long_ptr    is access constant volatile_signed_long;
 462    type constv_unsigned_long_ptr  is access constant volatile_unsigned_long;
 463
 464    type constv_float_ptr  is access constant volatile_float;
 465
 466 private
 467
 468    -----------------------
 469    -- Various constants --
 470    -----------------------
 471
 472    CR6_EQ     : constant := 0;
 473    CR6_EQ_REV : constant := 1;
 474    CR6_LT     : constant := 2;
 475    CR6_LT_REV : constant := 3;
 476
 477 end GNAT.Altivec;