gcc/ada/exp_pakd.ads

   1 ------------------------------------------------------------------------------
   2 --                                                                          --
   3 --                         GNAT COMPILER COMPONENTS                         --
   4 --                                                                          --
   5 --                             E X P _ P A K D                              --
   6 --                                                                          --
   7 --                                 S p e c                                  --
   8 --                                                                          --
   9 --                            $Revision: 1.1 $
  10 --                                                                          --
  11 --          Copyright (C) 1992-2001 Free Software Foundation, Inc.          --
  12 --                                                                          --
  13 -- GNAT is free software;  you can  redistribute it  and/or modify it under --
  14 -- terms of the  GNU General Public License as published  by the Free Soft- --
  15 -- ware  Foundation;  either version 2,  or (at your option) any later ver- --
  16 -- sion.  GNAT is distributed in the hope that it will be useful, but WITH- --
  17 -- OUT ANY WARRANTY;  without even the  implied warranty of MERCHANTABILITY --
  18 -- or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License --
  19 -- for  more details.  You should have  received  a copy of the GNU General --
  20 -- Public License  distributed with GNAT;  see file COPYING.  If not, write --
  21 -- to  the Free Software Foundation,  59 Temple Place - Suite 330,  Boston, --
  22 -- MA 02111-1307, USA.                                                      --
  23 --                                                                          --
  24 -- GNAT was originally developed  by the GNAT team at  New York University. --
  25 -- Extensive contributions were provided by Ada Core Technologies Inc.      --
  26 --                                                                          --
  27 ------------------------------------------------------------------------------
  28
  29 --  Expand routines for manipulation of packed arrays
  30
  31 with Types; use Types;
  32
  33 package Exp_Pakd is
  34
  35    -------------------------------------
  36    -- Implementation of Packed Arrays --
  37    -------------------------------------
  38
  39    --  When a packed array (sub)type is frozen, we create a corresponding
  40    --  type that will be used to hold the bits of the packed value, and
  41    --  store the entity for this type in the Packed_Array_Type field of the
  42    --  E_Array_Type or E_Array_Subtype entity for the packed array.
  43
  44    --  This packed array type has the name xxxPn, where xxx is the name
  45    --  of the packed type, and n is the component size. The expanded
  46    --  declaration declares a type that is one of the following:
  47
  48    --    For an unconstrained array with component size 1,2,4 or any other
  49    --    odd component size. These are the cases in which we do not need
  50    --    to align the underlying array.
  51
  52    --      type xxxPn is new Packed_Bytes1;
  53
  54    --    For an unconstrained array with component size that is divisible
  55    --    by 2, but not divisible by 4 (other than 2 itself). These are the
  56    --    cases in which we can generate better code if the underlying array
  57    --    is 2-byte aligned (see System.Pack_14 in file s-pack14 for example).
  58
  59    --      type xxxPn is new Packed_Bytes2;
  60
  61    --    For an unconstrained array with component size that is divisible
  62    --    by 4, other than powers of 2 (which either come under the 1,2,4
  63    --    exception above, or are not packed at all). These are cases where
  64    --    we can generate better code if the underlying array is 4-byte
  65    --    aligned (see System.Pack_20 in file s-pack20 for example).
  66
  67    --      type xxxPn is new Packed_Bytes4;
  68
  69    --    For a constrained array with a static index type where the number
  70    --    of bits does not exceed the size of Unsigned:
  71
  72    --      type xxxPn is new Unsigned range 0 .. 2 ** nbits - 1;
  73
  74    --    For a constrained array with a static index type where the number
  75    --    of bits is greater than the size of Unsigned, but does not exceed
  76    --    the size of Long_Long_Unsigned:
  77
  78    --       type xxxPn is new Long_Long_Unsigned range 0 .. 2 ** nbits - 1;
  79
  80    --    For all other constrained arrays, we use one of
  81
  82    --       type xxxPn is new Packed_Bytes1 (0 .. m);
  83    --       type xxxPn is new Packed_Bytes2 (0 .. m);
  84    --       type xxxPn is new Packed_Bytes4 (0 .. m);
  85
  86    --    where m is calculated (from the length of the original packed array)
  87    --    to hold the required number of bits, and the choice of the particular
  88    --    Packed_Bytes{1,2,4} type is made on the basis of alignment needs as
  89    --    described above for the unconstrained case.
  90
  91    --  When a variable of packed array type is allocated, gigi will allocate
  92    --  the amount of space indicated by the corresponding packed array type.
  93    --  However, we do NOT attempt to rewrite the types of any references or
  94    --  to retype the variable itself, since this would cause all kinds of
  95    --  semantic problems in the front end (remember that expansion proceeds
  96    --  at the same time as analysis).
  97
  98    --  For an indexed reference to a packed array, we simply convert the
  99    --  reference to the appropriate equivalent reference to the object
 100    --  of the packed array type (using unchecked conversion).
 101
 102    --  In some cases (for internally generated types, and for the subtypes
 103    --  for record fields that depend on a discriminant), the corresponding
 104    --  packed type cannot be easily generated in advance. In these cases,
 105    --  we generate the required subtype on the fly at the reference point.
 106
 107    --  For the modular case, any unused bits are initialized to zero, and
 108    --  all operations maintain these bits as zero (where necessary all
 109    --  unchecked conversions from corresponding array values require
 110    --  these bits to be clear, which is done automatically by gigi).
 111
 112    --  For the array cases, there can be unused bits in the last byte, and
 113    --  these are neither initialized, nor treated specially in operations
 114    --  (i.e. it is allowable for these bits to be clobbered, e.g. by not).
 115
 116    ---------------------------
 117    -- Endian Considerations --
 118    ---------------------------
 119
 120    --  The standard does not specify the way in which bits are numbered in
 121    --  a packed array. There are two reasonable rules for deciding this:
 122
 123    --    Store the first bit at right end (low order) word. This means
 124    --    that the scaled subscript can be used directly as a right shift
 125    --    count (if we put bit 0 at the left end, then we need an extra
 126    --    subtract to compute the shift count.
 127
 128    --    Layout the bits so that if the packed boolean array is overlaid on
 129    --    a record, using unchecked conversion, then bit 0 of the array is
 130    --    the same as the bit numbered bit 0 in a record representation
 131    --    clause applying to the record. For example:
 132
 133    --       type Rec is record
 134    --          C : Bits4;
 135    --          D : Bits7;
 136    --          E : Bits5;
 137    --       end record;
 138
 139    --       for Rec use record
 140    --          C at 0 range  0  .. 3;
 141    --          D at 0 range  4 .. 10;
 142    --          E at 0 range 11 .. 15;
 143    --       end record;
 144
 145    --       type P16 is array (0 .. 15) of Boolean;
 146    --       pragma Pack (P16);
 147
 148    --    Now if we use unchecked conversion to convert a value of the record
 149    --    type to the packed array type, according to this second criterion,
 150    --    we would expect field D to occupy bits 4..10 of the Boolean array.
 151
 152    --  Although not required, this correspondence seems a highly desirable
 153    --  property, and is one that GNAT decides to guarantee. For a little
 154    --  endian machine, we can also meet the first requirement, but for a
 155    --  big endian machine, it will be necessary to store the first bit of
 156    --  a Boolean array in the left end (most significant) bit of the word.
 157    --  This may cost an extra instruction on some machines, but we consider
 158    --  that a worthwhile price to pay for the consistency.
 159
 160    --  One more important point arises in the case where we have a constrained
 161    --  subtype of an unconstrained array. Take the case of 20-bits. For the
 162    --  unconstrained representation, we would use an array of bytes:
 163
 164    --     Little-endian case
 165    --       8-7-6-5-4-3-2-1  16-15-14-13-12-11-10-9  x-x-x-x-20-19-18-17
 166
 167    --     Big-endian case
 168    --       1-2-3-4-5-6-7-8  9-10-11-12-13-14-15-16  17-18-19-20-x-x-x-x
 169
 170    --   For the constrained case, we use a 20-bit modular value, but in
 171    --   general this value may well be stored in 32 bits. Let's look at
 172    --   what it looks like:
 173
 174    --     Little-endian case
 175
 176    --       x-x-x-x-x-x-x-x-x-x-x-x-20-19-18-17-...-10-9-8-7-6-5-4-3-2-1
 177
 178    --         which stored in memory looks like
 179
 180    --       8-7-...-2-1  16-15-...-10-9  x-x-x-x-20-19-18-17  x-x-x-x-x-x-x
 181
 182    --   An important rule is that the constrained and unconstrained cases
 183    --   must have the same bit representation in memory, since we will often
 184    --   convert from one to the other (e.g. when calling a procedure whose
 185    --   formal is unconstrained). As we see, that criterion is met for the
 186    --   little-endian case above. Now let's look at the big-endian case:
 187
 188    --     Big-endian case
 189
 190    --       x-x-x-x-x-x-x-x-x-x-x-x-1-2-3-4-5-6-7-8-9-10-...-17-18-19-20
 191
 192    --         which stored in memory looks like
 193
 194    --       x-x-x-x-x-x-x-x  x-x-x-x-1-2-3-4  5-6-...11-12  13-14-...-19-20
 195
 196    --   That won't do, the representation value in memory is NOT the same in
 197    --   the constrained and unconstrained case. The solution is to store the
 198    --   modular value left-justified:
 199
 200    --       1-2-3-4-5-6-7-8-9-10-...-17-18-19-20-x-x-x-x-x-x-x-x-x-x-x
 201
 202    --         which stored in memory looks like
 203
 204    --       1-2-...-7-8  9-10-...15-16  17-18-19-20-x-x-x-x  x-x-x-x-x-x-x-x
 205
 206    --   and now, we do indeed have the same representation. The special flag
 207    --   Is_Left_Justified_Modular is set in the modular type used as the
 208    --   packed array type in the big-endian case to ensure that this required
 209    --   left justification occurs.
 210
 211    -----------------
 212    -- Subprograms --
 213    -----------------
 214
 215    procedure Create_Packed_Array_Type (Typ  : Entity_Id);
 216    --  Typ is a array type or subtype to which pragma Pack applies. If the
 217    --  Packed_Array_Type field of Typ is already set, then the call has no
 218    --  effect, otherwise a suitable type or subtype is created and stored
 219    --  in the Packed_Array_Type field of Typ. This created type is an Itype
 220    --  so that Gigi will simply elaborate and freeze the type on first use
 221    --  (which is typically the definition of the corresponding array type).
 222    --
 223    --  Note: although this routine is included in the expander package for
 224    --  packed types, it is actually called unconditionally from Freeze,
 225    --  whether or not expansion (and code generation) is enabled. We do this
 226    --  since we want gigi to be able to properly compute type charactersitics
 227    --  (for the Data Decomposition Annex of ASIS, and possible other future
 228    --  uses) even if code generation is not active. Strictly this means that
 229    --  this procedure is not part of the expander, but it seems appropriate
 230    --  to keep it together with the other expansion routines that have to do
 231    --  with packed array types.
 232
 233    procedure Expand_Packed_Boolean_Operator (N : Node_Id);
 234    --  N is an N_Op_And, N_Op_Or or N_Op_Xor node whose operand type is a
 235    --  packed boolean array. This routine expands the appropriate operations
 236    --  to carry out the logical operation on the packed arrays. It handles
 237    --  both the modular and array representation cases.
 238
 239    procedure Expand_Packed_Element_Reference (N : Node_Id);
 240    --  N is an N_Indexed_Component node whose prefix is a packed array. In
 241    --  the bit packed case, this routine can only be used for the expression
 242    --  evaluation case not the assignment case, since the result is not a
 243    --  variable. See Expand_Bit_Packed_Element_Set for how he assignment case
 244    --  is handled in the bit packed case. For the enumeration case, the result
 245    --  of this call is always a variable, so the call can be used for both the
 246    --  expression evaluation and assignment cases.
 247
 248    procedure Expand_Bit_Packed_Element_Set (N : Node_Id);
 249    --  N is an N_Assignment_Statement node whose name is an indexed
 250    --  component of a bit-packed array. This procedure rewrites the entire
 251    --  assignment statement with appropriate code to set the referenced
 252    --  bits of the packed array type object. Note that this procedure is
 253    --  used only for the bit-packed case, not for the enumeration case.
 254
 255    procedure Expand_Packed_Eq (N : Node_Id);
 256    --  N is an N_Op_Eq node where the operands are packed arrays whose
 257    --  representation is an array-of-bytes type (the case where a modular
 258    --  type is used for the representation does not require any special
 259    --  handling, because in the modular case, unused bits are zeroes.
 260
 261    procedure Expand_Packed_Not (N : Node_Id);
 262    --  N is an N_Op_Not node where the operand is packed array of Boolean
 263    --  in standard representation (i.e. component size is one bit). This
 264    --  procedure expands the corresponding not operation. Note that the
 265    --  non-standard representation case is handled by using a loop through
 266    --  elements generated by the normal non-packed circuitry.
 267
 268    function Involves_Packed_Array_Reference (N : Node_Id) return Boolean;
 269    --  N is the node for a name. This function returns true if the name
 270    --  involves a packed array reference. A node involves a packed array
 271    --  reference if it is itself an indexed compoment referring to a bit-
 272    --  packed array, or it is a selected component whose prefix involves
 273    --  a packed array reference.
 274
 275    procedure Expand_Packed_Address_Reference (N : Node_Id);
 276    --  The node N is an attribute reference for the 'Address reference, where
 277    --  the prefix involves a packed array reference. This routine expands the
 278    --  necessary code for performing the address reference in this case.
 279
 280 end Exp_Pakd;