3 .. _Representation_Clauses_and_Pragmas:
5 **********************************
6 Representation Clauses and Pragmas
7 **********************************
9 .. index:: Representation Clauses
11 .. index:: Representation Clause
13 .. index:: Representation Pragma
15 .. index:: Pragma, representation
17 This section describes the representation clauses accepted by GNAT, and
18 their effect on the representation of corresponding data objects.
20 GNAT fully implements Annex C (Systems Programming). This means that all
21 the implementation advice sections in chapter 13 are fully implemented.
22 However, these sections only require a minimal level of support for
23 representation clauses. GNAT provides much more extensive capabilities,
24 and this section describes the additional capabilities provided.
26 .. _Alignment_Clauses:
31 .. index:: Alignment Clause
33 GNAT requires that all alignment clauses specify 0 or a power of 2, and
34 all default alignments are always a power of 2. Specifying 0 is the
37 The default alignment values are as follows:
41 For elementary types, the alignment is the minimum of the actual size of
42 objects of the type divided by ``Storage_Unit``,
43 and the maximum alignment supported by the target.
44 (This maximum alignment is given by the GNAT-specific attribute
45 ``Standard'Maximum_Alignment``; see :ref:`Attribute_Maximum_Alignment`.)
47 .. index:: Maximum_Alignment attribute
49 For example, for type ``Long_Float``, the object size is 8 bytes, and the
50 default alignment will be 8 on any target that supports alignments
51 this large, but on some targets, the maximum alignment may be smaller
52 than 8, in which case objects of type ``Long_Float`` will be maximally
57 For arrays, the alignment is equal to the alignment of the component type
58 for the normal case where no packing or component size is given. If the
59 array is packed, and the packing is effective (see separate section on
60 packed arrays), then the alignment will be either 4, 2, or 1 for long packed
61 arrays or arrays whose length is not known at compile time, depending on
62 whether the component size is divisible by 4, 2, or is odd. For short packed
63 arrays, which are handled internally as modular types, the alignment
64 will be as described for elementary types, e.g. a packed array of length
65 31 bits will have an object size of four bytes, and an alignment of 4.
69 For the normal unpacked case, the alignment of a record is equal to
70 the maximum alignment of any of its components. For tagged records, this
71 includes the implicit access type used for the tag. If a pragma ``Pack``
72 is used and all components are packable (see separate section on pragma
73 ``Pack``), then the resulting alignment is 1, unless the layout of the
74 record makes it profitable to increase it.
76 A special case is when:
78 * the size of the record is given explicitly, or a
79 full record representation clause is given, and
81 * the size of the record is 2, 4, or 8 bytes.
83 In this case, an alignment is chosen to match the
84 size of the record. For example, if we have:
91 for Small'Size use 16;
93 then the default alignment of the record type ``Small`` is 2, not 1. This
94 leads to more efficient code when the record is treated as a unit, and also
95 allows the type to specified as ``Atomic`` on architectures requiring
98 An alignment clause may specify a larger alignment than the default value
99 up to some maximum value dependent on the target (obtainable by using the
100 attribute reference ``Standard'Maximum_Alignment``). It may also specify
101 a smaller alignment than the default value for enumeration, integer and
102 fixed point types, as well as for record types, for example
110 for V'alignment use 1;
112 .. index:: Alignment, default
114 The default alignment for the type ``V`` is 4, as a result of the
115 Integer field in the record, but it is permissible, as shown, to
116 override the default alignment of the record with a smaller value.
118 .. index:: Alignment, subtypes
120 Note that according to the Ada standard, an alignment clause applies only
121 to the first named subtype. If additional subtypes are declared, then the
122 compiler is allowed to choose any alignment it likes, and there is no way
123 to control this choice. Consider:
127 type R is range 1 .. 10_000;
128 for R'Alignment use 1;
129 subtype RS is R range 1 .. 1000;
131 The alignment clause specifies an alignment of 1 for the first named subtype
132 ``R`` but this does not necessarily apply to ``RS``. When writing
133 portable Ada code, you should avoid writing code that explicitly or
134 implicitly relies on the alignment of such subtypes.
136 For the GNAT compiler, if an explicit alignment clause is given, this
137 value is also used for any subsequent subtypes. So for GNAT, in the
138 above example, you can count on the alignment of ``RS`` being 1. But this
139 assumption is non-portable, and other compilers may choose different
140 alignments for the subtype ``RS``.
147 .. index:: Size Clause
149 The default size for a type ``T`` is obtainable through the
150 language-defined attribute ``T'Size`` and also through the
151 equivalent GNAT-defined attribute ``T'Value_Size``.
152 For objects of type ``T``, GNAT will generally increase the type size
153 so that the object size (obtainable through the GNAT-defined attribute
155 is a multiple of ``T'Alignment * Storage_Unit``.
161 type Smallint is range 1 .. 6;
168 In this example, ``Smallint'Size`` = ``Smallint'Value_Size`` = 3,
169 as specified by the RM rules,
170 but objects of this type will have a size of 8
171 (``Smallint'Object_Size`` = 8),
172 since objects by default occupy an integral number
173 of storage units. On some targets, notably older
174 versions of the Digital Alpha, the size of stand
175 alone objects of this type may be 32, reflecting
176 the inability of the hardware to do byte load/stores.
178 Similarly, the size of type ``Rec`` is 40 bits
179 (``Rec'Size`` = ``Rec'Value_Size`` = 40), but
180 the alignment is 4, so objects of this type will have
181 their size increased to 64 bits so that it is a multiple
182 of the alignment (in bits). This decision is
183 in accordance with the specific Implementation Advice in RM 13.3(43):
185 "A ``Size`` clause should be supported for an object if the specified
186 ``Size`` is at least as large as its subtype's ``Size``, and corresponds
187 to a size in storage elements that is a multiple of the object's
188 ``Alignment`` (if the ``Alignment`` is nonzero)."
190 An explicit size clause may be used to override the default size by
191 increasing it. For example, if we have:
195 type My_Boolean is new Boolean;
196 for My_Boolean'Size use 32;
198 then values of this type will always be 32-bit long. In the case of discrete
199 types, the size can be increased up to 64 bits on 32-bit targets and 128 bits
200 on 64-bit targets, with the effect that the entire specified field is used to
201 hold the value, sign- or zero-extended as appropriate. If more than 64 bits
202 or 128 bits resp. is specified, then padding space is allocated after the
203 value, and a warning is issued that there are unused bits.
205 Similarly the size of records and arrays may be increased, and the effect
206 is to add padding bits after the value. This also causes a warning message
209 The largest Size value permitted in GNAT is 2**31-1. Since this is a
210 Size in bits, this corresponds to an object of size 256 megabytes (minus
211 one). This limitation is true on all targets. The reason for this
212 limitation is that it improves the quality of the code in many cases
213 if it is known that a Size value can be accommodated in an object of
217 .. _Storage_Size_Clauses:
222 .. index:: Storage_Size Clause
224 For tasks, the ``Storage_Size`` clause specifies the amount of space
225 to be allocated for the task stack. This cannot be extended, and if the
226 stack is exhausted, then ``Storage_Error`` will be raised (if stack
227 checking is enabled). Use a ``Storage_Size`` attribute definition clause,
228 or a ``Storage_Size`` pragma in the task definition to set the
229 appropriate required size. A useful technique is to include in every
230 task definition a pragma of the form:
234 pragma Storage_Size (Default_Stack_Size);
236 Then ``Default_Stack_Size`` can be defined in a global package, and
237 modified as required. Any tasks requiring stack sizes different from the
238 default can have an appropriate alternative reference in the pragma.
240 You can also use the *-d* binder switch to modify the default stack
243 For access types, the ``Storage_Size`` clause specifies the maximum
244 space available for allocation of objects of the type. If this space is
245 exceeded then ``Storage_Error`` will be raised by an allocation attempt.
246 In the case where the access type is declared local to a subprogram, the
247 use of a ``Storage_Size`` clause triggers automatic use of a special
248 predefined storage pool (``System.Pool_Size``) that ensures that all
249 space for the pool is automatically reclaimed on exit from the scope in
250 which the type is declared.
252 A special case recognized by the compiler is the specification of a
253 ``Storage_Size`` of zero for an access type. This means that no
254 items can be allocated from the pool, and this is recognized at compile
255 time, and all the overhead normally associated with maintaining a fixed
256 size storage pool is eliminated. Consider the following example:
261 type R is array (Natural) of Character;
262 type P is access all R;
263 for P'Storage_Size use 0;
264 -- Above access type intended only for interfacing purposes
269 pragma Import (C, g);
278 As indicated in this example, these dummy storage pools are often useful in
279 connection with interfacing where no object will ever be allocated. If you
280 compile the above example, you get the warning:
284 p.adb:16:09: warning: allocation from empty storage pool
285 p.adb:16:09: warning: Storage_Error will be raised at run time
288 Of course in practice, there will not be any explicit allocators in the
289 case of such an access declaration.
291 .. _Size_of_Variant_Record_Objects:
293 Size of Variant Record Objects
294 ==============================
296 .. index:: Size, variant record objects
298 .. index:: Variant record objects, size
300 In the case of variant record objects, there is a question whether Size gives
301 information about a particular variant, or the maximum size required
302 for any variant. Consider the following program
306 with Text_IO; use Text_IO;
308 type R1 (A : Boolean := False) is record
310 when True => X : Character;
319 Put_Line (Integer'Image (V1'Size));
320 Put_Line (Integer'Image (V2'Size));
323 Here we are dealing with a variant record, where the True variant
324 requires 16 bits, and the False variant requires 8 bits.
325 In the above example, both V1 and V2 contain the False variant,
326 which is only 8 bits long. However, the result of running the
334 The reason for the difference here is that the discriminant value of
335 V1 is fixed, and will always be False. It is not possible to assign
336 a True variant value to V1, therefore 8 bits is sufficient. On the
337 other hand, in the case of V2, the initial discriminant value is
338 False (from the default), but it is possible to assign a True
339 variant value to V2, therefore 16 bits must be allocated for V2
340 in the general case, even fewer bits may be needed at any particular
341 point during the program execution.
343 As can be seen from the output of this program, the ``'Size``
344 attribute applied to such an object in GNAT gives the actual allocated
345 size of the variable, which is the largest size of any of the variants.
346 The Ada Reference Manual is not completely clear on what choice should
347 be made here, but the GNAT behavior seems most consistent with the
350 In some cases, it may be desirable to obtain the size of the current
351 variant, rather than the size of the largest variant. This can be
352 achieved in GNAT by making use of the fact that in the case of a
353 subprogram parameter, GNAT does indeed return the size of the current
354 variant (because a subprogram has no way of knowing how much space
355 is actually allocated for the actual).
357 Consider the following modified version of the above program:
361 with Text_IO; use Text_IO;
363 type R1 (A : Boolean := False) is record
365 when True => X : Character;
372 function Size (V : R1) return Integer is
378 Put_Line (Integer'Image (V2'Size));
379 Put_Line (Integer'Image (Size (V2)));
381 Put_Line (Integer'Image (V2'Size));
382 Put_Line (Integer'Image (Size (V2)));
385 The output from this program is
394 Here we see that while the ``'Size`` attribute always returns
395 the maximum size, regardless of the current variant value, the
396 ``Size`` function does indeed return the size of the current
400 .. _Biased_Representation:
402 Biased Representation
403 =====================
405 .. index:: Size for biased representation
407 .. index:: Biased representation
409 In the case of scalars with a range starting at other than zero, it is
410 possible in some cases to specify a size smaller than the default minimum
411 value, and in such cases, GNAT uses an unsigned biased representation,
412 in which zero is used to represent the lower bound, and successive values
413 represent successive values of the type.
415 For example, suppose we have the declaration:
419 type Small is range -7 .. -4;
420 for Small'Size use 2;
422 Although the default size of type ``Small`` is 4, the ``Size``
423 clause is accepted by GNAT and results in the following representation
428 -7 is represented as 2#00#
429 -6 is represented as 2#01#
430 -5 is represented as 2#10#
431 -4 is represented as 2#11#
433 Biased representation is only used if the specified ``Size`` clause
434 cannot be accepted in any other manner. These reduced sizes that force
435 biased representation can be used for all discrete types except for
436 enumeration types for which a representation clause is given.
439 .. _Value_Size_and_Object_Size_Clauses:
441 Value_Size and Object_Size Clauses
442 ==================================
444 .. index:: Value_Size
445 .. index:: Object_Size
446 .. index:: Size, of objects
448 In Ada 95 and Ada 2005, ``T'Size`` for a type ``T`` is the minimum
449 number of bits required to hold values of type ``T``.
450 Although this interpretation was allowed in Ada 83, it was not required,
451 and this requirement in practice can cause some significant difficulties.
452 For example, in most Ada 83 compilers, ``Natural'Size`` was 32.
453 However, in Ada 95 and Ada 2005,
455 typically 31. This means that code may change in behavior when moving
456 from Ada 83 to Ada 95 or Ada 2005. For example, consider:
466 A at 0 range 0 .. Natural'Size - 1;
467 B at 0 range Natural'Size .. 2 * Natural'Size - 1;
470 In the above code, since the typical size of ``Natural`` objects
471 is 32 bits and ``Natural'Size`` is 31, the above code can cause
472 unexpected inefficient packing in Ada 95 and Ada 2005, and in general
473 there are cases where the fact that the object size can exceed the
474 size of the type causes surprises.
476 To help get around this problem GNAT provides two implementation
477 defined attributes, ``Value_Size`` and ``Object_Size``. When
478 applied to a type, these attributes yield the size of the type
479 (corresponding to the RM defined size attribute), and the size of
480 objects of the type respectively.
482 The ``Object_Size`` is used for determining the default size of
483 objects and components. This size value can be referred to using the
484 ``Object_Size`` attribute. The phrase 'is used' here means that it is
485 the basis of the determination of the size. The backend is free to
486 pad this up if necessary for efficiency, e.g., an 8-bit stand-alone
487 character might be stored in 32 bits on a machine with no efficient
488 byte access instructions such as the Alpha.
490 The default rules for the value of ``Object_Size`` for
491 discrete types are as follows:
494 The ``Object_Size`` for base subtypes reflect the natural hardware
495 size in bits (run the compiler with *-gnatS* to find those values
496 for numeric types). Enumeration types and fixed-point base subtypes have
497 8, 16, 32, or 64 bits for this size, depending on the range of values
501 The ``Object_Size`` of a subtype is the same as the
503 the type from which it is obtained.
506 The ``Object_Size`` of a derived base type is copied from the parent
507 base type, and the ``Object_Size`` of a derived first subtype is copied
508 from the parent first subtype.
510 The ``Value_Size`` attribute
511 is the (minimum) number of bits required to store a value
513 This value is used to determine how tightly to pack
514 records or arrays with components of this type, and also affects
515 the semantics of unchecked conversion (unchecked conversions where
516 the ``Value_Size`` values differ generate a warning, and are potentially
519 The default rules for the value of ``Value_Size`` are as follows:
522 The ``Value_Size`` for a base subtype is the minimum number of bits
523 required to store all values of the type (including the sign bit
524 only if negative values are possible).
527 If a subtype statically matches the first subtype of a given type, then it has
528 by default the same ``Value_Size`` as the first subtype. (This is a
529 consequence of RM 13.1(14): "if two subtypes statically match,
530 then their subtype-specific aspects are the same".)
533 All other subtypes have a ``Value_Size`` corresponding to the minimum
534 number of bits required to store all values of the subtype. For
535 dynamic bounds, it is assumed that the value can range down or up
536 to the corresponding bound of the ancestor
538 The RM defined attribute ``Size`` corresponds to the
539 ``Value_Size`` attribute.
541 The ``Size`` attribute may be defined for a first-named subtype. This sets
542 the ``Value_Size`` of
543 the first-named subtype to the given value, and the
544 ``Object_Size`` of this first-named subtype to the given value padded up
545 to an appropriate boundary. It is a consequence of the default rules
546 above that this ``Object_Size`` will apply to all further subtypes. On the
547 other hand, ``Value_Size`` is affected only for the first subtype, any
548 dynamic subtypes obtained from it directly, and any statically matching
549 subtypes. The ``Value_Size`` of any other static subtypes is not affected.
552 ``Object_Size`` may be explicitly set for any subtype using
553 an attribute definition clause. Note that the use of these attributes
554 can cause the RM 13.1(14) rule to be violated. If two access types
555 reference aliased objects whose subtypes have differing ``Object_Size``
556 values as a result of explicit attribute definition clauses, then it
557 is illegal to convert from one access subtype to the other. For a more
558 complete description of this additional legality rule, see the
559 description of the ``Object_Size`` attribute.
561 To get a feel for the difference, consider the following examples (note
562 that in each case the base is ``Short_Short_Integer`` with a size of 8):
564 +---------------------------------------------+-------------+-------------+
565 |Type or subtype declaration | Object_Size | Value_Size|
566 +=============================================+=============+=============+
567 |``type x1 is range 0 .. 5;`` | 8 | 3 |
568 +---------------------------------------------+-------------+-------------+
569 |``type x2 is range 0 .. 5;`` | 16 | 12 |
570 |``for x2'size use 12;`` | | |
571 +---------------------------------------------+-------------+-------------+
572 |``subtype x3 is x2 range 0 .. 3;`` | 16 | 2 |
573 +---------------------------------------------+-------------+-------------+
574 |``subtype x4 is x2'base range 0 .. 10;`` | 8 | 4 |
575 +---------------------------------------------+-------------+-------------+
576 |``dynamic : x2'Base range -64 .. +63;`` | | |
577 +---------------------------------------------+-------------+-------------+
578 |``subtype x5 is x2 range 0 .. dynamic;`` | 16 | 3* |
579 +---------------------------------------------+-------------+-------------+
580 |``subtype x6 is x2'base range 0 .. dynamic;``| 8 | 7* |
581 +---------------------------------------------+-------------+-------------+
583 Note: the entries marked '*' are not actually specified by the Ada
584 Reference Manual, which has nothing to say about size in the dynamic
585 case. What GNAT does is to allocate sufficient bits to accommodate any
586 possible dynamic values for the bounds at run-time.
588 So far, so good, but GNAT has to obey the RM rules, so the question is
589 under what conditions must the RM ``Size`` be used.
590 The following is a list
591 of the occasions on which the RM ``Size`` must be used:
594 Component size for packed arrays or records
597 Value of the attribute ``Size`` for a type
600 Warning about sizes not matching for unchecked conversion
602 For record types, the ``Object_Size`` is always a multiple of the
603 alignment of the type (this is true for all types). In some cases the
604 ``Value_Size`` can be smaller. Consider:
615 On a typical 32-bit architecture, the X component will occupy four bytes
616 and the Y component will occupy one byte, for a total of 5 bytes. As a
617 result ``R'Value_Size`` will be 40 (bits) since this is the minimum size
618 required to store a value of this type. For example, it is permissible
619 to have a component of type R in an array whose component size is
620 specified to be 40 bits.
622 However, ``R'Object_Size`` will be 64 (bits). The difference is due to
623 the alignment requirement for objects of the record type. The X
624 component will require four-byte alignment because that is what type
625 Integer requires, whereas the Y component, a Character, will only
626 require 1-byte alignment. Since the alignment required for X is the
627 greatest of all the components' alignments, that is the alignment
628 required for the enclosing record type, i.e., 4 bytes or 32 bits. As
629 indicated above, the actual object size must be rounded up so that it is
630 a multiple of the alignment value. Therefore, 40 bits rounded up to the
631 next multiple of 32 yields 64 bits.
633 For all other types, the ``Object_Size``
634 and ``Value_Size`` are the same (and equivalent to the RM attribute ``Size``).
635 Only ``Size`` may be specified for such types.
637 Note that ``Value_Size`` can be used to force biased representation
638 for a particular subtype. Consider this example:
643 type R is (A, B, C, D, E, F);
644 subtype RAB is R range A .. B;
645 subtype REF is R range E .. F;
649 has a size of 1 (sufficient to accommodate the representation
650 of ``A`` and ``B``, 0 and 1), and ``REF``
651 has a size of 3 (sufficient to accommodate the representation
652 of ``E`` and ``F``, 4 and 5). But if we add the
653 following ``Value_Size`` attribute definition clause:
658 for REF'Value_Size use 1;
661 then biased representation is forced for ``REF``,
662 and 0 will represent ``E`` and 1 will represent ``F``.
663 A warning is issued when a ``Value_Size`` attribute
664 definition clause forces biased representation. This
665 warning can be turned off using :switch:`-gnatw.B`.
667 .. _Component_Size_Clauses:
669 Component_Size Clauses
670 ======================
672 .. index:: Component_Size Clause
674 Normally, the value specified in a component size clause must be consistent
675 with the subtype of the array component with regard to size and alignment.
676 In other words, the value specified must be at least equal to the size
677 of this subtype, and must be a multiple of the alignment value.
679 In addition, component size clauses are allowed which cause the array
680 to be packed, by specifying a smaller value. A first case is for
681 component size values in the range 1 through 63 on 32-bit targets,
682 and 1 through 127 on 64-bit targets. The value specified may not
683 be smaller than the Size of the subtype. GNAT will accurately
684 honor all packing requests in this range. For example, if we have:
689 type r is array (1 .. 8) of Natural;
690 for r'Component_Size use 31;
693 then the resulting array has a length of 31 bytes (248 bits = 8 * 31).
694 Of course access to the components of such an array is considerably
695 less efficient than if the natural component size of 32 is used.
696 A second case is when the subtype of the component is a record type
697 padded because of its default alignment. For example, if we have:
708 type a is array (1 .. 8) of r;
709 for a'Component_Size use 72;
712 then the resulting array has a length of 72 bytes, instead of 96 bytes
713 if the alignment of the record (4) was obeyed.
715 Note that there is no point in giving both a component size clause
716 and a pragma Pack for the same array type. if such duplicate
717 clauses are given, the pragma Pack will be ignored.
719 .. _Bit_Order_Clauses:
724 .. index:: Bit_Order Clause
726 .. index:: bit ordering
728 .. index:: ordering, of bits
730 For record subtypes, GNAT permits the specification of the ``Bit_Order``
731 attribute. The specification may either correspond to the default bit
732 order for the target, in which case the specification has no effect and
733 places no additional restrictions, or it may be for the non-standard
734 setting (that is the opposite of the default).
736 In the case where the non-standard value is specified, the effect is
737 to renumber bits within each byte, but the ordering of bytes is not
738 affected. There are certain
739 restrictions placed on component clauses as follows:
742 * Components fitting within a single storage unit.
744 These are unrestricted, and the effect is merely to renumber bits. For
745 example if we are on a little-endian machine with ``Low_Order_First``
746 being the default, then the following two declarations have exactly
754 B : Integer range 1 .. 120;
764 B : Integer range 1 .. 120;
767 for R2'Bit_Order use High_Order_First;
775 The useful application here is to write the second declaration with the
776 ``Bit_Order`` attribute definition clause, and know that it will be treated
777 the same, regardless of whether the target is little-endian or big-endian.
779 * Components occupying an integral number of bytes.
781 These are components that exactly fit in two or more bytes. Such component
782 declarations are allowed, but have no effect, since it is important to realize
783 that the ``Bit_Order`` specification does not affect the ordering of bytes.
784 In particular, the following attempt at getting an endian-independent integer
794 for R2'Bit_Order use High_Order_First;
797 A at 0 range 0 .. 31;
801 This declaration will result in a little-endian integer on a
802 little-endian machine, and a big-endian integer on a big-endian machine.
803 If byte flipping is required for interoperability between big- and
804 little-endian machines, this must be explicitly programmed. This capability
805 is not provided by ``Bit_Order``.
807 * Components that are positioned across byte boundaries.
809 but do not occupy an integral number of bytes. Given that bytes are not
810 reordered, such fields would occupy a non-contiguous sequence of bits
811 in memory, requiring non-trivial code to reassemble. They are for this
812 reason not permitted, and any component clause specifying such a layout
813 will be flagged as illegal by GNAT.
816 Since the misconception that Bit_Order automatically deals with all
817 endian-related incompatibilities is a common one, the specification of
818 a component field that is an integral number of bytes will always
819 generate a warning. This warning may be suppressed using ``pragma Warnings (Off)``
820 if desired. The following section contains additional
821 details regarding the issue of byte ordering.
823 .. _Effect_of_Bit_Order_on_Byte_Ordering:
825 Effect of Bit_Order on Byte Ordering
826 ====================================
828 .. index:: byte ordering
830 .. index:: ordering, of bytes
832 In this section we will review the effect of the ``Bit_Order`` attribute
833 definition clause on byte ordering. Briefly, it has no effect at all, but
834 a detailed example will be helpful. Before giving this
835 example, let us review the precise
836 definition of the effect of defining ``Bit_Order``. The effect of a
837 non-standard bit order is described in section 13.5.3 of the Ada
840 "2 A bit ordering is a method of interpreting the meaning of
841 the storage place attributes."
843 To understand the precise definition of storage place attributes in
844 this context, we visit section 13.5.1 of the manual:
846 "13 A record_representation_clause (without the mod_clause)
847 specifies the layout. The storage place attributes (see 13.5.2)
848 are taken from the values of the position, first_bit, and last_bit
849 expressions after normalizing those values so that first_bit is
850 less than Storage_Unit."
852 The critical point here is that storage places are taken from
853 the values after normalization, not before. So the ``Bit_Order``
854 interpretation applies to normalized values. The interpretation
855 is described in the later part of the 13.5.3 paragraph:
857 "2 A bit ordering is a method of interpreting the meaning of
858 the storage place attributes. High_Order_First (known in the
859 vernacular as 'big endian') means that the first bit of a
860 storage element (bit 0) is the most significant bit (interpreting
861 the sequence of bits that represent a component as an unsigned
862 integer value). Low_Order_First (known in the vernacular as
863 'little endian') means the opposite: the first bit is the
866 Note that the numbering is with respect to the bits of a storage
867 unit. In other words, the specification affects only the numbering
868 of bits within a single storage unit.
870 We can make the effect clearer by giving an example.
872 Suppose that we have an external device which presents two bytes, the first
873 byte presented, which is the first (low addressed byte) of the two byte
874 record is called Master, and the second byte is called Slave.
876 The left most (most significant) bit is called Control for each byte, and
877 the remaining 7 bits are called V1, V2, ... V7, where V7 is the rightmost
878 (least significant) bit.
880 On a big-endian machine, we can write the following representation clause
886 Master_Control : Bit;
905 Master_Control at 0 range 0 .. 0;
906 Master_V1 at 0 range 1 .. 1;
907 Master_V2 at 0 range 2 .. 2;
908 Master_V3 at 0 range 3 .. 3;
909 Master_V4 at 0 range 4 .. 4;
910 Master_V5 at 0 range 5 .. 5;
911 Master_V6 at 0 range 6 .. 6;
912 Master_V7 at 0 range 7 .. 7;
913 Slave_Control at 1 range 0 .. 0;
914 Slave_V1 at 1 range 1 .. 1;
915 Slave_V2 at 1 range 2 .. 2;
916 Slave_V3 at 1 range 3 .. 3;
917 Slave_V4 at 1 range 4 .. 4;
918 Slave_V5 at 1 range 5 .. 5;
919 Slave_V6 at 1 range 6 .. 6;
920 Slave_V7 at 1 range 7 .. 7;
924 Now if we move this to a little endian machine, then the bit ordering within
925 the byte is backwards, so we have to rewrite the record rep clause as:
931 Master_Control at 0 range 7 .. 7;
932 Master_V1 at 0 range 6 .. 6;
933 Master_V2 at 0 range 5 .. 5;
934 Master_V3 at 0 range 4 .. 4;
935 Master_V4 at 0 range 3 .. 3;
936 Master_V5 at 0 range 2 .. 2;
937 Master_V6 at 0 range 1 .. 1;
938 Master_V7 at 0 range 0 .. 0;
939 Slave_Control at 1 range 7 .. 7;
940 Slave_V1 at 1 range 6 .. 6;
941 Slave_V2 at 1 range 5 .. 5;
942 Slave_V3 at 1 range 4 .. 4;
943 Slave_V4 at 1 range 3 .. 3;
944 Slave_V5 at 1 range 2 .. 2;
945 Slave_V6 at 1 range 1 .. 1;
946 Slave_V7 at 1 range 0 .. 0;
950 It is a nuisance to have to rewrite the clause, especially if
951 the code has to be maintained on both machines. However,
952 this is a case that we can handle with the
953 ``Bit_Order`` attribute if it is implemented.
954 Note that the implementation is not required on byte addressed
955 machines, but it is indeed implemented in GNAT.
956 This means that we can simply use the
957 first record clause, together with the declaration
962 for Data'Bit_Order use High_Order_First;
965 and the effect is what is desired, namely the layout is exactly the same,
966 independent of whether the code is compiled on a big-endian or little-endian
969 The important point to understand is that byte ordering is not affected.
970 A ``Bit_Order`` attribute definition never affects which byte a field
971 ends up in, only where it ends up in that byte.
972 To make this clear, let us rewrite the record rep clause of the previous
978 for Data'Bit_Order use High_Order_First;
980 Master_Control at 0 range 0 .. 0;
981 Master_V1 at 0 range 1 .. 1;
982 Master_V2 at 0 range 2 .. 2;
983 Master_V3 at 0 range 3 .. 3;
984 Master_V4 at 0 range 4 .. 4;
985 Master_V5 at 0 range 5 .. 5;
986 Master_V6 at 0 range 6 .. 6;
987 Master_V7 at 0 range 7 .. 7;
988 Slave_Control at 0 range 8 .. 8;
989 Slave_V1 at 0 range 9 .. 9;
990 Slave_V2 at 0 range 10 .. 10;
991 Slave_V3 at 0 range 11 .. 11;
992 Slave_V4 at 0 range 12 .. 12;
993 Slave_V5 at 0 range 13 .. 13;
994 Slave_V6 at 0 range 14 .. 14;
995 Slave_V7 at 0 range 15 .. 15;
999 This is exactly equivalent to saying (a repeat of the first example):
1004 for Data'Bit_Order use High_Order_First;
1006 Master_Control at 0 range 0 .. 0;
1007 Master_V1 at 0 range 1 .. 1;
1008 Master_V2 at 0 range 2 .. 2;
1009 Master_V3 at 0 range 3 .. 3;
1010 Master_V4 at 0 range 4 .. 4;
1011 Master_V5 at 0 range 5 .. 5;
1012 Master_V6 at 0 range 6 .. 6;
1013 Master_V7 at 0 range 7 .. 7;
1014 Slave_Control at 1 range 0 .. 0;
1015 Slave_V1 at 1 range 1 .. 1;
1016 Slave_V2 at 1 range 2 .. 2;
1017 Slave_V3 at 1 range 3 .. 3;
1018 Slave_V4 at 1 range 4 .. 4;
1019 Slave_V5 at 1 range 5 .. 5;
1020 Slave_V6 at 1 range 6 .. 6;
1021 Slave_V7 at 1 range 7 .. 7;
1025 Why are they equivalent? Well take a specific field, the ``Slave_V2``
1026 field. The storage place attributes are obtained by normalizing the
1027 values given so that the ``First_Bit`` value is less than 8. After
1028 normalizing the values (0,10,10) we get (1,2,2) which is exactly what
1029 we specified in the other case.
1031 Now one might expect that the ``Bit_Order`` attribute might affect
1032 bit numbering within the entire record component (two bytes in this
1033 case, thus affecting which byte fields end up in), but that is not
1034 the way this feature is defined, it only affects numbering of bits,
1035 not which byte they end up in.
1037 Consequently it never makes sense to specify a starting bit number
1038 greater than 7 (for a byte addressable field) if an attribute
1039 definition for ``Bit_Order`` has been given, and indeed it
1040 may be actively confusing to specify such a value, so the compiler
1041 generates a warning for such usage.
1043 If you do need to control byte ordering then appropriate conditional
1044 values must be used. If in our example, the slave byte came first on
1045 some machines we might write:
1049 Master_Byte_First constant Boolean := ...;
1051 Master_Byte : constant Natural :=
1052 1 - Boolean'Pos (Master_Byte_First);
1053 Slave_Byte : constant Natural :=
1054 Boolean'Pos (Master_Byte_First);
1056 for Data'Bit_Order use High_Order_First;
1058 Master_Control at Master_Byte range 0 .. 0;
1059 Master_V1 at Master_Byte range 1 .. 1;
1060 Master_V2 at Master_Byte range 2 .. 2;
1061 Master_V3 at Master_Byte range 3 .. 3;
1062 Master_V4 at Master_Byte range 4 .. 4;
1063 Master_V5 at Master_Byte range 5 .. 5;
1064 Master_V6 at Master_Byte range 6 .. 6;
1065 Master_V7 at Master_Byte range 7 .. 7;
1066 Slave_Control at Slave_Byte range 0 .. 0;
1067 Slave_V1 at Slave_Byte range 1 .. 1;
1068 Slave_V2 at Slave_Byte range 2 .. 2;
1069 Slave_V3 at Slave_Byte range 3 .. 3;
1070 Slave_V4 at Slave_Byte range 4 .. 4;
1071 Slave_V5 at Slave_Byte range 5 .. 5;
1072 Slave_V6 at Slave_Byte range 6 .. 6;
1073 Slave_V7 at Slave_Byte range 7 .. 7;
1076 Now to switch between machines, all that is necessary is
1077 to set the boolean constant ``Master_Byte_First`` in
1078 an appropriate manner.
1080 .. _Pragma_Pack_for_Arrays:
1082 Pragma Pack for Arrays
1083 ======================
1085 .. index:: Pragma Pack (for arrays)
1087 Pragma ``Pack`` applied to an array has an effect that depends upon whether the
1088 component type is *packable*. For a component type to be *packable*, it must
1089 be one of the following cases:
1091 * Any elementary type.
1093 * Any small packed array type with a static size.
1095 * Any small simple record type with a static size.
1097 For all these cases, if the component subtype size is in the range
1098 1 through 63 on 32-bit targets, and 1 through 127 on 64-bit targets,
1099 then the effect of the pragma ``Pack`` is exactly as though a
1100 component size were specified giving the component subtype size.
1102 All other types are non-packable, they occupy an integral number of storage
1103 units and the only effect of pragma Pack is to remove alignment gaps.
1105 For example if we have:
1109 type r is range 0 .. 17;
1111 type ar is array (1 .. 8) of r;
1114 Then the component size of ``ar`` will be set to 5 (i.e., to ``r'size``,
1115 and the size of the array ``ar`` will be exactly 40 bits).
1117 Note that in some cases this rather fierce approach to packing can produce
1118 unexpected effects. For example, in Ada 95 and Ada 2005,
1119 subtype ``Natural`` typically has a size of 31, meaning that if you
1120 pack an array of ``Natural``, you get 31-bit
1121 close packing, which saves a few bits, but results in far less efficient
1122 access. Since many other Ada compilers will ignore such a packing request,
1123 GNAT will generate a warning on some uses of pragma ``Pack`` that it guesses
1124 might not be what is intended. You can easily remove this warning by
1125 using an explicit ``Component_Size`` setting instead, which never generates
1126 a warning, since the intention of the programmer is clear in this case.
1128 GNAT treats packed arrays in one of two ways. If the size of the array is
1129 known at compile time and is at most 64 bits on 32-bit targets, and at most
1130 128 bits on 64-bit targets, then internally the array is represented as a
1131 single modular type, of exactly the appropriate number of bits. If the
1132 length is greater than 64 bits on 32-bit targets, and greater than 128
1133 bits on 64-bit targets, or is not known at compile time, then the packed
1134 array is represented as an array of bytes, and its length is always a
1137 Note that to represent a packed array as a modular type, the alignment must
1138 be suitable for the modular type involved. For example, on typical machines
1139 a 32-bit packed array will be represented by a 32-bit modular integer with
1140 an alignment of four bytes. If you explicitly override the default alignment
1141 with an alignment clause that is too small, the modular representation
1142 cannot be used. For example, consider the following set of declarations:
1146 type R is range 1 .. 3;
1147 type S is array (1 .. 31) of R;
1148 for S'Component_Size use 2;
1150 for S'Alignment use 1;
1152 If the alignment clause were not present, then a 62-bit modular
1153 representation would be chosen (typically with an alignment of 4 or 8
1154 bytes depending on the target). But the default alignment is overridden
1155 with the explicit alignment clause. This means that the modular
1156 representation cannot be used, and instead the array of bytes
1157 representation must be used, meaning that the length must be a multiple
1158 of 8. Thus the above set of declarations will result in a diagnostic
1159 rejecting the size clause and noting that the minimum size allowed is 64.
1161 .. index:: Pragma Pack (for type Natural)
1163 .. index:: Pragma Pack warning
1165 One special case that is worth noting occurs when the base type of the
1166 component size is 8/16/32 and the subtype is one bit less. Notably this
1167 occurs with subtype ``Natural``. Consider:
1171 type Arr is array (1 .. 32) of Natural;
1174 In all commonly used Ada 83 compilers, this pragma Pack would be ignored,
1175 since typically ``Natural'Size`` is 32 in Ada 83, and in any case most
1176 Ada 83 compilers did not attempt 31 bit packing.
1178 In Ada 95 and Ada 2005, ``Natural'Size`` is required to be 31. Furthermore,
1179 GNAT really does pack 31-bit subtype to 31 bits. This may result in a
1180 substantial unintended performance penalty when porting legacy Ada 83 code.
1181 To help prevent this, GNAT generates a warning in such cases. If you really
1182 want 31 bit packing in a case like this, you can set the component size
1187 type Arr is array (1 .. 32) of Natural;
1188 for Arr'Component_Size use 31;
1190 Here 31-bit packing is achieved as required, and no warning is generated,
1191 since in this case the programmer intention is clear.
1193 .. _Pragma_Pack_for_Records:
1195 Pragma Pack for Records
1196 =======================
1198 .. index:: Pragma Pack (for records)
1200 Pragma ``Pack`` applied to a record will pack the components to reduce
1201 wasted space from alignment gaps and by reducing the amount of space
1202 taken by components. We distinguish between *packable* components and
1203 *non-packable* components.
1204 Components of the following types are considered packable:
1206 * Components of an elementary type are packable unless they are aliased,
1207 independent or atomic.
1209 * Small packed arrays, where the size is statically known, are represented
1210 internally as modular integers, and so they are also packable.
1212 * Small simple records, where the size is statically known, are also packable.
1214 For all these cases, if the ``'Size`` value is in the range 1 through 64 on
1215 32-bit targets, and 1 through 128 on 64-bit targets, the components occupy
1216 the exact number of bits corresponding to this value and are packed with no
1217 padding bits, i.e. they can start on an arbitrary bit boundary.
1219 All other types are non-packable, they occupy an integral number of storage
1220 units and the only effect of pragma ``Pack`` is to remove alignment gaps.
1222 For example, consider the record
1226 type Rb1 is array (1 .. 13) of Boolean;
1229 type Rb2 is array (1 .. 65) of Boolean;
1232 type AF is new Float with Atomic;
1244 The representation for the record ``X2`` is as follows on 32-bit targets:
1248 for X2'Size use 224;
1250 L1 at 0 range 0 .. 0;
1251 L2 at 0 range 1 .. 64;
1252 L3 at 12 range 0 .. 31;
1253 L4 at 16 range 0 .. 0;
1254 L5 at 16 range 1 .. 13;
1255 L6 at 18 range 0 .. 71;
1258 Studying this example, we see that the packable fields ``L1``
1259 and ``L2`` are of length equal to their sizes, and placed at
1260 specific bit boundaries (and not byte boundaries) to eliminate
1261 padding. But ``L3`` is of a non-packable float type (because
1262 it is aliased), so it is on the next appropriate alignment boundary.
1264 The next two fields are fully packable, so ``L4`` and ``L5`` are
1265 minimally packed with no gaps. However, type ``Rb2`` is a packed
1266 array that is longer than 64 bits, so it is itself non-packable on
1267 32-bit targets. Thus the ``L6`` field is aligned to the next byte
1268 boundary, and takes an integral number of bytes, i.e., 72 bits.
1270 .. _Record_Representation_Clauses:
1272 Record Representation Clauses
1273 =============================
1275 .. index:: Record Representation Clause
1277 Record representation clauses may be given for all record types, including
1278 types obtained by record extension. Component clauses are allowed for any
1279 static component. The restrictions on component clauses depend on the type
1282 .. index:: Component Clause
1284 For all components of an elementary type, the only restriction on component
1285 clauses is that the size must be at least the ``'Size`` value of the type
1286 (actually the Value_Size). There are no restrictions due to alignment,
1287 and such components may freely cross storage boundaries.
1289 Packed arrays with a size up to and including 64 bits on 32-bit targets,
1290 and up to and including 128 bits on 64-bit targets, are represented
1291 internally using a modular type with the appropriate number of bits, and
1292 thus the same lack of restriction applies. For example, if you declare:
1296 type R is array (1 .. 49) of Boolean;
1300 then a component clause for a component of type ``R`` may start on any
1301 specified bit boundary, and may specify a value of 49 bits or greater.
1303 For packed bit arrays that are longer than 64 bits on 32-bit targets,
1304 and longer than 128 bits on 64-bit targets, there are two cases. If the
1305 component size is a power of 2 (1,2,4,8,16,32,64 bits), including the
1306 important case of single bits or boolean values, then there are no
1307 limitations on placement of such components, and they may start and
1308 end at arbitrary bit boundaries.
1310 If the component size is not a power of 2 (e.g., 3 or 5), then an array
1311 of this type must always be placed on on a storage unit (byte) boundary
1312 and occupy an integral number of storage units (bytes). Any component
1313 clause that does not meet this requirement will be rejected.
1315 Any aliased component, or component of an aliased type, must have its
1316 normal alignment and size. A component clause that does not meet this
1317 requirement will be rejected.
1319 The tag field of a tagged type always occupies an address sized field at
1320 the start of the record. No component clause may attempt to overlay this
1321 tag. When a tagged type appears as a component, the tag field must have
1324 In the case of a record extension ``T1``, of a type ``T``, no component
1325 clause applied to the type ``T1`` can specify a storage location that
1326 would overlap the first ``T'Object_Size`` bits of the record.
1328 For all other component types, including non-bit-packed arrays,
1329 the component can be placed at an arbitrary bit boundary,
1330 so for example, the following is permitted:
1334 type R is array (1 .. 10) of Boolean;
1343 G at 0 range 0 .. 0;
1344 H at 0 range 1 .. 1;
1345 L at 0 range 2 .. 81;
1346 R at 0 range 82 .. 161;
1349 .. _Handling_of_Records_with_Holes:
1351 Handling of Records with Holes
1352 ==============================
1354 .. index:: Handling of Records with Holes
1356 As a result of alignment considerations, records may contain "holes"
1357 or gaps which do not correspond to the data bits of any of the components.
1358 Record representation clauses can also result in holes in records.
1360 GNAT does not attempt to clear these holes, so in record objects,
1361 they should be considered to hold undefined rubbish. The generated
1362 equality routine just tests components so does not access these
1363 undefined bits, and assignment and copy operations may or may not
1364 preserve the contents of these holes (for assignments, the holes
1365 in the target will in practice contain either the bits that are
1366 present in the holes in the source, or the bits that were present
1367 in the target before the assignment).
1369 If it is necessary to ensure that holes in records have all zero
1370 bits, then record objects for which this initialization is desired
1371 should be explicitly set to all zero values using Unchecked_Conversion
1372 or address overlays. For example
1381 On typical machines, integers need to be aligned on a four-byte
1382 boundary, resulting in three bytes of undefined rubbish following
1383 the 8-bit field for C. To ensure that the hole in a variable of
1384 type HRec is set to all zero bits,
1385 you could for example do:
1390 Dummy1, Dummy2 : Integer := 0;
1395 for RealVar'Address use BaseVar'Address;
1398 Now the 8-bytes of the value of RealVar start out containing all zero
1399 bits. A safer approach is to just define dummy fields, avoiding the
1406 Dummy1 : Short_Short_Integer := 0;
1407 Dummy2 : Short_Short_Integer := 0;
1408 Dummy3 : Short_Short_Integer := 0;
1412 And to make absolutely sure that the intent of this is followed, you
1413 can use representation clauses:
1418 C at 0 range 0 .. 7;
1419 Dummy1 at 1 range 0 .. 7;
1420 Dummy2 at 2 range 0 .. 7;
1421 Dummy3 at 3 range 0 .. 7;
1422 I at 4 range 0 .. 31;
1424 for Hrec'Size use 64;
1427 .. _Enumeration_Clauses:
1432 The only restriction on enumeration clauses is that the range of values
1433 must be representable. For the signed case, if one or more of the
1434 representation values are negative, all values must be in the range:
1438 System.Min_Int .. System.Max_Int
1440 For the unsigned case, where all values are nonnegative, the values must
1445 0 .. System.Max_Binary_Modulus;
1448 A *confirming* representation clause is one in which the values range
1449 from 0 in sequence, i.e., a clause that confirms the default representation
1450 for an enumeration type.
1451 Such a confirming representation
1452 is permitted by these rules, and is specially recognized by the compiler so
1453 that no extra overhead results from the use of such a clause.
1455 If an array has an index type which is an enumeration type to which an
1456 enumeration clause has been applied, then the array is stored in a compact
1457 manner. Consider the declarations:
1461 type r is (A, B, C);
1462 for r use (A => 1, B => 5, C => 10);
1463 type t is array (r) of Character;
1465 The array type t corresponds to a vector with exactly three elements and
1466 has a default size equal to ``3*Character'Size``. This ensures efficient
1467 use of space, but means that accesses to elements of the array will incur
1468 the overhead of converting representation values to the corresponding
1469 positional values, (i.e., the value delivered by the ``Pos`` attribute).
1472 .. _Address_Clauses:
1476 .. index:: Address Clause
1478 The reference manual allows a general restriction on representation clauses,
1479 as found in RM 13.1(22):
1481 "An implementation need not support representation
1482 items containing nonstatic expressions, except that
1483 an implementation should support a representation item
1484 for a given entity if each nonstatic expression in the
1485 representation item is a name that statically denotes
1486 a constant declared before the entity."
1488 In practice this is applicable only to address clauses, since this is the
1489 only case in which a nonstatic expression is permitted by the syntax. As
1490 the AARM notes in sections 13.1 (22.a-22.h):
1492 22.a Reason: This is to avoid the following sort of thing:
1494 22.b X : Integer := F(...);
1495 Y : Address := G(...);
1496 for X'Address use Y;
1498 22.c In the above, we have to evaluate the
1499 initialization expression for X before we
1500 know where to put the result. This seems
1501 like an unreasonable implementation burden.
1503 22.d The above code should instead be written
1506 22.e Y : constant Address := G(...);
1507 X : Integer := F(...);
1508 for X'Address use Y;
1510 22.f This allows the expression 'Y' to be safely
1511 evaluated before X is created.
1513 22.g The constant could be a formal parameter of mode in.
1515 22.h An implementation can support other nonstatic
1516 expressions if it wants to. Expressions of type
1517 Address are hardly ever static, but their value
1518 might be known at compile time anyway in many
1521 GNAT does indeed permit many additional cases of nonstatic expressions. In
1522 particular, if the type involved is elementary there are no restrictions
1523 (since in this case, holding a temporary copy of the initialization value,
1524 if one is present, is inexpensive). In addition, if there is no implicit or
1525 explicit initialization, then there are no restrictions. GNAT will reject
1526 only the case where all three of these conditions hold:
1529 The type of the item is non-elementary (e.g., a record or array).
1532 There is explicit or implicit initialization required for the object.
1533 Note that access values are always implicitly initialized.
1536 The address value is nonstatic. Here GNAT is more permissive than the
1537 RM, and allows the address value to be the address of a previously declared
1538 stand-alone variable, as long as it does not itself have an address clause.
1542 Anchor : Some_Initialized_Type;
1543 Overlay : Some_Initialized_Type;
1544 for Overlay'Address use Anchor'Address;
1546 However, the prefix of the address clause cannot be an array component, or
1547 a component of a discriminated record.
1549 As noted above in section 22.h, address values are typically nonstatic. In
1550 particular the To_Address function, even if applied to a literal value, is
1551 a nonstatic function call. To avoid this minor annoyance, GNAT provides
1552 the implementation defined attribute 'To_Address. The following two
1553 expressions have identical values:
1555 .. index:: Attribute
1556 .. index:: To_Address
1560 To_Address (16#1234_0000#)
1561 System'To_Address (16#1234_0000#);
1563 except that the second form is considered to be a static expression, and
1564 thus when used as an address clause value is always permitted.
1566 Additionally, GNAT treats as static an address clause that is an
1567 unchecked_conversion of a static integer value. This simplifies the porting
1568 of legacy code, and provides a portable equivalent to the GNAT attribute
1571 Another issue with address clauses is the interaction with alignment
1572 requirements. When an address clause is given for an object, the address
1573 value must be consistent with the alignment of the object (which is usually
1574 the same as the alignment of the type of the object). If an address clause
1575 is given that specifies an inappropriately aligned address value, then the
1576 program execution is erroneous.
1578 Since this source of erroneous behavior can have unfortunate effects on
1579 machines with strict alignment requirements, GNAT
1580 checks (at compile time if possible, generating a warning, or at execution
1581 time with a run-time check) that the alignment is appropriate. If the
1582 run-time check fails, then ``Program_Error`` is raised. This run-time
1583 check is suppressed if range checks are suppressed, or if the special GNAT
1584 check Alignment_Check is suppressed, or if
1585 ``pragma Restrictions (No_Elaboration_Code)`` is in effect. It is also
1586 suppressed by default on non-strict alignment machines (such as the x86).
1588 In some cases, GNAT does not support an address specification (using either
1589 form of aspect specification syntax) for the declaration of an object that has
1590 an indefinite nominal subtype. An object declaration has an indefinite
1591 nominal subtype if it takes its bounds (for an array type), discriminant
1592 values (for a discriminated type whose discriminants lack defaults), or tag
1593 (for a class-wide type) from its initial value, as in
1597 X : String := Some_Function_Call;
1598 -- String has no constraint, so bounds for X come from function call
1600 This restriction does not apply if the size of the object's initial value is
1601 known at compile time and the type of the object is not class-wide.
1605 An address clause cannot be given for an exported object. More
1606 understandably the real restriction is that objects with an address
1607 clause cannot be exported. This is because such variables are not
1608 defined by the Ada program, so there is no external object to export.
1612 It is permissible to give an address clause and a pragma Import for the
1613 same object. In this case, the variable is not really defined by the
1614 Ada program, so there is no external symbol to be linked. The link name
1615 and the external name are ignored in this case. The reason that we allow this
1616 combination is that it provides a useful idiom to avoid unwanted
1617 initializations on objects with address clauses.
1619 When an address clause is given for an object that has implicit or
1620 explicit initialization, then by default initialization takes place. This
1621 means that the effect of the object declaration is to overwrite the
1622 memory at the specified address. This is almost always not what the
1623 programmer wants, so GNAT will output a warning:
1634 for Ext'Address use System'To_Address (16#1234_1234#);
1636 >>> warning: implicit initialization of "Ext" may
1637 modify overlaid storage
1638 >>> warning: use pragma Import for "Ext" to suppress
1639 initialization (RM B(24))
1643 As indicated by the warning message, the solution is to use a (dummy) pragma
1644 Import to suppress this initialization. The pragma tell the compiler that the
1645 object is declared and initialized elsewhere. The following package compiles
1646 without warnings (and the initialization is suppressed):
1657 for Ext'Address use System'To_Address (16#1234_1234#);
1658 pragma Import (Ada, Ext);
1662 A final issue with address clauses involves their use for overlaying
1663 variables, as in the following example:
1665 .. index:: Overlaying of objects
1671 for B'Address use A'Address;
1674 or alternatively, using the form recommended by the RM:
1679 Addr : constant Address := A'Address;
1681 for B'Address use Addr;
1684 In both of these cases, ``A`` and ``B`` become aliased to one another
1685 via the address clause. This use of address clauses to overlay
1686 variables, achieving an effect similar to unchecked conversion
1687 was erroneous in Ada 83, but in Ada 95 and Ada 2005
1688 the effect is implementation defined. Furthermore, the
1689 Ada RM specifically recommends that in a situation
1690 like this, ``B`` should be subject to the following
1691 implementation advice (RM 13.3(19)):
1693 "19 If the Address of an object is specified, or it is imported
1694 or exported, then the implementation should not perform
1695 optimizations based on assumptions of no aliases."
1697 GNAT follows this recommendation, and goes further by also applying
1698 this recommendation to the overlaid variable (``A`` in the above example)
1699 in this case. This means that the overlay works "as expected", in that
1700 a modification to one of the variables will affect the value of the other.
1702 More generally, GNAT interprets this recommendation conservatively for
1703 address clauses: in the cases other than overlays, it considers that the
1704 object is effectively subject to pragma ``Volatile`` and implements the
1705 associated semantics.
1707 Note that when address clause overlays are used in this way, there is an
1708 issue of unintentional initialization, as shown by this example:
1712 package Overwrite_Record is
1714 A : Character := 'C';
1715 B : Character := 'A';
1717 X : Short_Integer := 3;
1719 for Y'Address use X'Address;
1721 >>> warning: default initialization of "Y" may
1722 modify "X", use pragma Import for "Y" to
1723 suppress initialization (RM B.1(24))
1725 end Overwrite_Record;
1727 Here the default initialization of ``Y`` will clobber the value
1728 of ``X``, which justifies the warning. The warning notes that
1729 this effect can be eliminated by adding a ``pragma Import``
1730 which suppresses the initialization:
1734 package Overwrite_Record is
1736 A : Character := 'C';
1737 B : Character := 'A';
1739 X : Short_Integer := 3;
1741 for Y'Address use X'Address;
1742 pragma Import (Ada, Y);
1743 end Overwrite_Record;
1746 Note that the use of ``pragma Initialize_Scalars`` may cause variables to
1747 be initialized when they would not otherwise have been in the absence
1748 of the use of this pragma. This may cause an overlay to have this
1749 unintended clobbering effect. The compiler avoids this for scalar
1750 types, but not for composite objects (where in general the effect
1751 of ``Initialize_Scalars`` is part of the initialization routine
1752 for the composite object):
1756 pragma Initialize_Scalars;
1757 with Ada.Text_IO; use Ada.Text_IO;
1758 procedure Overwrite_Array is
1759 type Arr is array (1 .. 5) of Integer;
1760 X : Arr := (others => 1);
1762 for A'Address use X'Address;
1764 >>> warning: default initialization of "A" may
1765 modify "X", use pragma Import for "A" to
1766 suppress initialization (RM B.1(24))
1769 if X /= Arr'(others => 1) then
1770 Put_Line ("X was clobbered");
1772 Put_Line ("X was not clobbered");
1774 end Overwrite_Array;
1776 The above program generates the warning as shown, and at execution
1777 time, prints ``X was clobbered``. If the ``pragma Import`` is
1782 pragma Initialize_Scalars;
1783 with Ada.Text_IO; use Ada.Text_IO;
1784 procedure Overwrite_Array is
1785 type Arr is array (1 .. 5) of Integer;
1786 X : Arr := (others => 1);
1788 for A'Address use X'Address;
1789 pragma Import (Ada, A);
1791 if X /= Arr'(others => 1) then
1792 Put_Line ("X was clobbered");
1794 Put_Line ("X was not clobbered");
1796 end Overwrite_Array;
1798 then the program compiles without the warning and when run will generate
1799 the output ``X was not clobbered``.
1802 .. _Use_of_Address_Clauses_for_Memory-Mapped_I/O:
1804 Use of Address Clauses for Memory-Mapped I/O
1805 ============================================
1807 .. index:: Memory-mapped I/O
1809 A common pattern is to use an address clause to map an atomic variable to
1810 a location in memory that corresponds to a memory-mapped I/O operation or
1811 operations, for example:
1815 type Mem_Word is record
1818 pragma Atomic (Mem_Word);
1819 for Mem_Word_Size use 32;
1822 for Mem'Address use some-address;
1828 For a full access (reference or modification) of the variable (Mem) in this
1829 case, as in the above examples, GNAT guarantees that the entire atomic word
1830 will be accessed, in accordance with the RM C.6(15) clause.
1832 A problem arises with a component access such as:
1838 Note that the component A is not declared as atomic. This means that it is
1839 not clear what this assignment means. It could correspond to full word read
1840 and write as given in the first example, or on architectures that supported
1841 such an operation it might be a single byte store instruction. The RM does
1842 not have anything to say in this situation, and GNAT does not make any
1843 guarantee. The code generated may vary from target to target. GNAT will issue
1844 a warning in such a case:
1850 >>> warning: access to non-atomic component of atomic array,
1851 may cause unexpected accesses to atomic object
1853 It is best to be explicit in this situation, by either declaring the
1854 components to be atomic if you want the byte store, or explicitly writing
1855 the full word access sequence if that is what the hardware requires.
1856 Alternatively, if the full word access sequence is required, GNAT also
1857 provides the pragma ``Volatile_Full_Access`` which can be used in lieu of
1858 pragma ``Atomic`` and will give the additional guarantee.
1861 .. _Effect_of_Convention_on_Representation:
1863 Effect of Convention on Representation
1864 ======================================
1866 .. index:: Convention, effect on representation
1868 Normally the specification of a foreign language convention for a type or
1869 an object has no effect on the chosen representation. In particular, the
1870 representation chosen for data in GNAT generally meets the standard system
1871 conventions, and for example records are laid out in a manner that is
1872 consistent with C. This means that specifying convention C (for example)
1875 There are four exceptions to this general rule:
1877 * *Convention Fortran and array subtypes*.
1879 If pragma Convention Fortran is specified for an array subtype, then in
1880 accordance with the implementation advice in section 3.6.2(11) of the
1881 Ada Reference Manual, the array will be stored in a Fortran-compatible
1882 column-major manner, instead of the normal default row-major order.
1884 * *Convention C and enumeration types*
1886 GNAT normally stores enumeration types in 8, 16, or 32 bits as required
1887 to accommodate all values of the type. For example, for the enumeration
1892 type Color is (Red, Green, Blue);
1894 8 bits is sufficient to store all values of the type, so by default, objects
1895 of type ``Color`` will be represented using 8 bits. However, normal C
1896 convention is to use 32 bits for all enum values in C, since enum values
1897 are essentially of type int. If pragma ``Convention C`` is specified for an
1898 Ada enumeration type, then the size is modified as necessary (usually to
1899 32 bits) to be consistent with the C convention for enum values.
1901 Note that this treatment applies only to types. If Convention C is given for
1902 an enumeration object, where the enumeration type is not Convention C, then
1903 Object_Size bits are allocated. For example, for a normal enumeration type,
1904 with less than 256 elements, only 8 bits will be allocated for the object.
1905 Since this may be a surprise in terms of what C expects, GNAT will issue a
1906 warning in this situation. The warning can be suppressed by giving an explicit
1907 size clause specifying the desired size.
1909 * *Convention C/Fortran and Boolean types*
1911 In C, the usual convention for boolean values, that is values used for
1912 conditions, is that zero represents false, and nonzero values represent
1913 true. In Ada, the normal convention is that two specific values, typically
1914 0/1, are used to represent false/true respectively.
1916 Fortran has a similar convention for ``LOGICAL`` values (any nonzero
1917 value represents true).
1919 To accommodate the Fortran and C conventions, if a pragma Convention specifies
1920 C or Fortran convention for a derived Boolean, as in the following example:
1924 type C_Switch is new Boolean;
1925 pragma Convention (C, C_Switch);
1928 then the GNAT generated code will treat any nonzero value as true. For truth
1929 values generated by GNAT, the conventional value 1 will be used for True, but
1930 when one of these values is read, any nonzero value is treated as True.
1933 .. _Conventions_and_Anonymous_Access_Types:
1935 Conventions and Anonymous Access Types
1936 ======================================
1938 .. index:: Anonymous access types
1940 .. index:: Convention for anonymous access types
1942 The RM is not entirely clear on convention handling in a number of cases,
1943 and in particular, it is not clear on the convention to be given to
1944 anonymous access types in general, and in particular what is to be
1945 done for the case of anonymous access-to-subprogram.
1947 In GNAT, we decide that if an explicit Convention is applied
1948 to an object or component, and its type is such an anonymous type,
1949 then the convention will apply to this anonymous type as well. This
1950 seems to make sense since it is anomolous in any case to have a
1951 different convention for an object and its type, and there is clearly
1952 no way to explicitly specify a convention for an anonymous type, since
1953 it doesn't have a name to specify!
1955 Furthermore, we decide that if a convention is applied to a record type,
1956 then this convention is inherited by any of its components that are of an
1957 anonymous access type which do not have an explicitly specified convention.
1959 The following program shows these conventions in action:
1964 type Foo is range 1 .. 10;
1966 A : access function (X : Foo) return Integer;
1969 pragma Convention (C, T1);
1972 A : access function (X : Foo) return Integer;
1973 pragma Convention (C, A);
1976 pragma Convention (COBOL, T2);
1979 A : access function (X : Foo) return Integer;
1980 pragma Convention (COBOL, A);
1983 pragma Convention (C, T3);
1986 A : access function (X : Foo) return Integer;
1989 pragma Convention (COBOL, T4);
1991 function F (X : Foo) return Integer;
1992 pragma Convention (C, F);
1994 function F (X : Foo) return Integer is (13);
1996 TV1 : T1 := (F'Access, 12); -- OK
1997 TV2 : T2 := (F'Access, 13); -- OK
1999 TV3 : T3 := (F'Access, 13); -- ERROR
2001 >>> subprogram "F" has wrong convention
2002 >>> does not match access to subprogram declared at line 17
2003 38. TV4 : T4 := (F'Access, 13); -- ERROR
2005 >>> subprogram "F" has wrong convention
2006 >>> does not match access to subprogram declared at line 24
2010 .. _Determining_the_Representations_chosen_by_GNAT:
2012 Determining the Representations chosen by GNAT
2013 ==============================================
2015 .. index:: Representation, determination of
2017 .. index:: -gnatR (gcc)
2019 Although the descriptions in this section are intended to be complete, it is
2020 often easier to simply experiment to see what GNAT accepts and what the
2021 effect is on the layout of types and objects.
2023 As required by the Ada RM, if a representation clause is not accepted, then
2024 it must be rejected as illegal by the compiler. However, when a
2025 representation clause or pragma is accepted, there can still be questions
2026 of what the compiler actually does. For example, if a partial record
2027 representation clause specifies the location of some components and not
2028 others, then where are the non-specified components placed? Or if pragma
2029 ``Pack`` is used on a record, then exactly where are the resulting
2030 fields placed? The section on pragma ``Pack`` in this chapter can be
2031 used to answer the second question, but it is often easier to just see
2032 what the compiler does.
2034 For this purpose, GNAT provides the option *-gnatR*. If you compile
2035 with this option, then the compiler will output information on the actual
2036 representations chosen, in a format similar to source representation
2037 clauses. For example, if we compile the package:
2042 type r (x : boolean) is tagged record
2044 when True => S : String (1 .. 100);
2049 type r2 is new r (false) with record
2054 y2 at 16 range 0 .. 31;
2061 type x1 is array (1 .. 10) of x;
2062 for x1'component_size use 11;
2064 type ia is access integer;
2066 type Rb1 is array (1 .. 13) of Boolean;
2069 type Rb2 is array (1 .. 65) of Boolean;
2083 using the switch *-gnatR* we obtain the following output:
2087 Representation information for unit q
2088 -------------------------------------
2091 for r'Alignment use 4;
2093 x at 4 range 0 .. 7;
2094 _tag at 0 range 0 .. 31;
2095 s at 5 range 0 .. 799;
2098 for r2'Size use 160;
2099 for r2'Alignment use 4;
2101 x at 4 range 0 .. 7;
2102 _tag at 0 range 0 .. 31;
2103 _parent at 0 range 0 .. 63;
2104 y2 at 16 range 0 .. 31;
2108 for x'Alignment use 1;
2110 y at 0 range 0 .. 7;
2113 for x1'Size use 112;
2114 for x1'Alignment use 1;
2115 for x1'Component_Size use 11;
2117 for rb1'Size use 13;
2118 for rb1'Alignment use 2;
2119 for rb1'Component_Size use 1;
2121 for rb2'Size use 72;
2122 for rb2'Alignment use 1;
2123 for rb2'Component_Size use 1;
2125 for x2'Size use 224;
2126 for x2'Alignment use 4;
2128 l1 at 0 range 0 .. 0;
2129 l2 at 0 range 1 .. 64;
2130 l3 at 12 range 0 .. 31;
2131 l4 at 16 range 0 .. 0;
2132 l5 at 16 range 1 .. 13;
2133 l6 at 18 range 0 .. 71;
2136 The Size values are actually the Object_Size, i.e., the default size that
2137 will be allocated for objects of the type.
2138 The ``??`` size for type r indicates that we have a variant record, and the
2139 actual size of objects will depend on the discriminant value.
2141 The Alignment values show the actual alignment chosen by the compiler
2142 for each record or array type.
2144 The record representation clause for type r shows where all fields
2145 are placed, including the compiler generated tag field (whose location
2146 cannot be controlled by the programmer).
2148 The record representation clause for the type extension r2 shows all the
2149 fields present, including the parent field, which is a copy of the fields
2150 of the parent type of r2, i.e., r1.
2152 The component size and size clauses for types rb1 and rb2 show
2153 the exact effect of pragma ``Pack`` on these arrays, and the record
2154 representation clause for type x2 shows how pragma `Pack` affects
2157 In some cases, it may be useful to cut and paste the representation clauses
2158 generated by the compiler into the original source to fix and guarantee
2159 the actual representation to be used.