Debian Codegraph @

gcc/ada/doc/gnat_rm/representation_clauses_and_pragmas.rst

raw
1 .. role:: switch(samp)
2
3 .. _Representation_Clauses_and_Pragmas:
4
5 **********************************
6 Representation Clauses and Pragmas
7 **********************************
8
9 .. index:: Representation Clauses
10
11 .. index:: Representation Clause
12
13 .. index:: Representation Pragma
14
15 .. index:: Pragma, representation
16
17 This section describes the representation clauses accepted by GNAT, and
18 their effect on the representation of corresponding data objects.
19
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.
25
26 .. _Alignment_Clauses:
27
28 Alignment Clauses
29 =================
30
31 .. index:: Alignment Clause
32
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
35 same as specifying 1.
36
37 The default alignment values are as follows:
38
39 * *Elementary Types*.
40
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`.)
46
47 .. index:: Maximum_Alignment attribute
48
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
53 aligned.
54
55 * *Arrays*.
56
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.
66
67 * *Records*.
68
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.
75
76 A special case is when:
77
78 * the size of the record is given explicitly, or a
79 full record representation clause is given, and
80
81 * the size of the record is 2, 4, or 8 bytes.
82
83 In this case, an alignment is chosen to match the
84 size of the record. For example, if we have:
85
86 .. code-block:: ada
87
88 type Small is record
89 A, B : Character;
90 end record;
91 for Small'Size use 16;
92
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
96 strict alignment.
97
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
103
104 .. code-block:: ada
105
106 type V is record
107 A : Integer;
108 end record;
109
110 for V'alignment use 1;
111
112 .. index:: Alignment, default
113
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.
117
118 .. index:: Alignment, subtypes
119
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:
124
125 .. code-block:: ada
126
127 type R is range 1 .. 10_000;
128 for R'Alignment use 1;
129 subtype RS is R range 1 .. 1000;
130
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.
135
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``.
141
142 .. _Size_Clauses:
143
144 Size Clauses
145 ============
146
147 .. index:: Size Clause
148
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
154 ``T'Object_Size``)
155 is a multiple of ``T'Alignment * Storage_Unit``.
156
157 For example:
158
159 .. code-block:: ada
160
161 type Smallint is range 1 .. 6;
162
163 type Rec is record
164 Y1 : integer;
165 Y2 : boolean;
166 end record;
167
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.
177
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):
184
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)."
189
190 An explicit size clause may be used to override the default size by
191 increasing it. For example, if we have:
192
193 .. code-block:: ada
194
195 type My_Boolean is new Boolean;
196 for My_Boolean'Size use 32;
197
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.
204
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
207 to be generated.
208
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
214 type Integer.
215
216
217 .. _Storage_Size_Clauses:
218
219 Storage_Size Clauses
220 ====================
221
222 .. index:: Storage_Size Clause
223
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:
231
232 .. code-block:: ada
233
234 pragma Storage_Size (Default_Stack_Size);
235
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.
239
240 You can also use the *-d* binder switch to modify the default stack
241 size.
242
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.
251
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:
257
258 .. code-block:: ada
259
260 procedure p is
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
265
266 y : P;
267
268 procedure g (m : P);
269 pragma Import (C, g);
270
271 -- ...
272
273 begin
274 -- ...
275 y := new R;
276 end;
277
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:
281
282 ::
283
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
286
287
288 Of course in practice, there will not be any explicit allocators in the
289 case of such an access declaration.
290
291 .. _Size_of_Variant_Record_Objects:
292
293 Size of Variant Record Objects
294 ==============================
295
296 .. index:: Size, variant record objects
297
298 .. index:: Variant record objects, size
299
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
303
304 .. code-block:: ada
305
306 with Text_IO; use Text_IO;
307 procedure q is
308 type R1 (A : Boolean := False) is record
309 case A is
310 when True => X : Character;
311 when False => null;
312 end case;
313 end record;
314
315 V1 : R1 (False);
316 V2 : R1;
317
318 begin
319 Put_Line (Integer'Image (V1'Size));
320 Put_Line (Integer'Image (V2'Size));
321 end q;
322
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
327 program is:
328
329 ::
330
331 8
332 16
333
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.
342
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
348 language in the RM.
349
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).
356
357 Consider the following modified version of the above program:
358
359 .. code-block:: ada
360
361 with Text_IO; use Text_IO;
362 procedure q is
363 type R1 (A : Boolean := False) is record
364 case A is
365 when True => X : Character;
366 when False => null;
367 end case;
368 end record;
369
370 V2 : R1;
371
372 function Size (V : R1) return Integer is
373 begin
374 return V'Size;
375 end Size;
376
377 begin
378 Put_Line (Integer'Image (V2'Size));
379 Put_Line (Integer'Image (Size (V2)));
380 V2 := (True, 'x');
381 Put_Line (Integer'Image (V2'Size));
382 Put_Line (Integer'Image (Size (V2)));
383 end q;
384
385 The output from this program is
386
387 ::
388
389 16
390 8
391 16
392 16
393
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
397 variant value.
398
399
400 .. _Biased_Representation:
401
402 Biased Representation
403 =====================
404
405 .. index:: Size for biased representation
406
407 .. index:: Biased representation
408
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.
414
415 For example, suppose we have the declaration:
416
417 .. code-block:: ada
418
419 type Small is range -7 .. -4;
420 for Small'Size use 2;
421
422 Although the default size of type ``Small`` is 4, the ``Size``
423 clause is accepted by GNAT and results in the following representation
424 scheme:
425
426 ::
427
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#
432
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.
437
438
439 .. _Value_Size_and_Object_Size_Clauses:
440
441 Value_Size and Object_Size Clauses
442 ==================================
443
444 .. index:: Value_Size
445 .. index:: Object_Size
446 .. index:: Size, of objects
447
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,
454 ``Natural'Size`` is
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:
457
458 .. code-block:: ada
459
460 type Rec is record
461 A : Natural;
462 B : Natural;
463 end record;
464
465 for Rec use record
466 A at 0 range 0 .. Natural'Size - 1;
467 B at 0 range Natural'Size .. 2 * Natural'Size - 1;
468 end record;
469
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.
475
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.
481
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.
489
490 The default rules for the value of ``Object_Size`` for
491 discrete types are as follows:
492
493 *
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
498 to be stored.
499
500 *
501 The ``Object_Size`` of a subtype is the same as the
502 ``Object_Size`` of
503 the type from which it is obtained.
504
505 *
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.
509
510 The ``Value_Size`` attribute
511 is the (minimum) number of bits required to store a value
512 of the type.
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
517 target dependent).
518
519 The default rules for the value of ``Value_Size`` are as follows:
520
521 *
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).
525
526 *
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".)
531
532 *
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
537
538 The RM defined attribute ``Size`` corresponds to the
539 ``Value_Size`` attribute.
540
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.
550
551 ``Value_Size`` and
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.
560
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):
563
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 +---------------------------------------------+-------------+-------------+
582
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.
587
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:
592
593 *
594 Component size for packed arrays or records
595
596 *
597 Value of the attribute ``Size`` for a type
598
599 *
600 Warning about sizes not matching for unchecked conversion
601
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:
605
606
607 .. code-block:: ada
608
609 type R is record
610 X : Integer;
611 Y : Character;
612 end record;
613
614
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.
621
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.
632
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.
636
637 Note that ``Value_Size`` can be used to force biased representation
638 for a particular subtype. Consider this example:
639
640
641 .. code-block:: ada
642
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;
646
647
648 By default, ``RAB``
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:
654
655
656 .. code-block:: ada
657
658 for REF'Value_Size use 1;
659
660
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`.
666
667 .. _Component_Size_Clauses:
668
669 Component_Size Clauses
670 ======================
671
672 .. index:: Component_Size Clause
673
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.
678
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:
685
686
687 .. code-block:: ada
688
689 type r is array (1 .. 8) of Natural;
690 for r'Component_Size use 31;
691
692
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:
698
699
700 .. code-block:: ada
701
702 type r is record
703 i : Integer;
704 j : Integer;
705 b : Boolean;
706 end record;
707
708 type a is array (1 .. 8) of r;
709 for a'Component_Size use 72;
710
711
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.
714
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.
718
719 .. _Bit_Order_Clauses:
720
721 Bit_Order Clauses
722 =================
723
724 .. index:: Bit_Order Clause
725
726 .. index:: bit ordering
727
728 .. index:: ordering, of bits
729
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).
735
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:
740
741
742 * Components fitting within a single storage unit.
743
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
747 the same effect:
748
749
750 ::
751
752 type R1 is record
753 A : Boolean;
754 B : Integer range 1 .. 120;
755 end record;
756
757 for R1 use record
758 A at 0 range 0 .. 0;
759 B at 0 range 1 .. 7;
760 end record;
761
762 type R2 is record
763 A : Boolean;
764 B : Integer range 1 .. 120;
765 end record;
766
767 for R2'Bit_Order use High_Order_First;
768
769 for R2 use record
770 A at 0 range 7 .. 7;
771 B at 0 range 0 .. 6;
772 end record;
773
774
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.
778
779 * Components occupying an integral number of bytes.
780
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
785 does not work:
786
787
788 ::
789
790 type R2 is record
791 A : Integer;
792 end record;
793
794 for R2'Bit_Order use High_Order_First;
795
796 for R2 use record
797 A at 0 range 0 .. 31;
798 end record;
799
800
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``.
806
807 * Components that are positioned across byte boundaries.
808
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.
814
815
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.
822
823 .. _Effect_of_Bit_Order_on_Byte_Ordering:
824
825 Effect of Bit_Order on Byte Ordering
826 ====================================
827
828 .. index:: byte ordering
829
830 .. index:: ordering, of bytes
831
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
838 Reference Manual:
839
840 "2 A bit ordering is a method of interpreting the meaning of
841 the storage place attributes."
842
843 To understand the precise definition of storage place attributes in
844 this context, we visit section 13.5.1 of the manual:
845
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."
851
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:
856
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
864 least significant."
865
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.
869
870 We can make the effect clearer by giving an example.
871
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.
875
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.
879
880 On a big-endian machine, we can write the following representation clause
881
882
883 .. code-block:: ada
884
885 type Data is record
886 Master_Control : Bit;
887 Master_V1 : Bit;
888 Master_V2 : Bit;
889 Master_V3 : Bit;
890 Master_V4 : Bit;
891 Master_V5 : Bit;
892 Master_V6 : Bit;
893 Master_V7 : Bit;
894 Slave_Control : Bit;
895 Slave_V1 : Bit;
896 Slave_V2 : Bit;
897 Slave_V3 : Bit;
898 Slave_V4 : Bit;
899 Slave_V5 : Bit;
900 Slave_V6 : Bit;
901 Slave_V7 : Bit;
902 end record;
903
904 for Data use record
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;
921 end record;
922
923
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:
926
927
928 .. code-block:: ada
929
930 for Data use record
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;
947 end record;
948
949
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
958
959
960 .. code-block:: ada
961
962 for Data'Bit_Order use High_Order_First;
963
964
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
967 machine.
968
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
973 example as:
974
975
976 .. code-block:: ada
977
978 for Data'Bit_Order use High_Order_First;
979 for Data use record
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;
996 end record;
997
998
999 This is exactly equivalent to saying (a repeat of the first example):
1000
1001
1002 .. code-block:: ada
1003
1004 for Data'Bit_Order use High_Order_First;
1005 for Data use record
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;
1022 end record;
1023
1024
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.
1030
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.
1036
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.
1042
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:
1046
1047 .. code-block:: ada
1048
1049 Master_Byte_First constant Boolean := ...;
1050
1051 Master_Byte : constant Natural :=
1052 1 - Boolean'Pos (Master_Byte_First);
1053 Slave_Byte : constant Natural :=
1054 Boolean'Pos (Master_Byte_First);
1055
1056 for Data'Bit_Order use High_Order_First;
1057 for Data use record
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;
1074 end record;
1075
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.
1079
1080 .. _Pragma_Pack_for_Arrays:
1081
1082 Pragma Pack for Arrays
1083 ======================
1084
1085 .. index:: Pragma Pack (for arrays)
1086
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:
1090
1091 * Any elementary type.
1092
1093 * Any small packed array type with a static size.
1094
1095 * Any small simple record type with a static size.
1096
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.
1101
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.
1104
1105 For example if we have:
1106
1107 .. code-block:: ada
1108
1109 type r is range 0 .. 17;
1110
1111 type ar is array (1 .. 8) of r;
1112 pragma Pack (ar);
1113
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).
1116
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.
1127
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
1135 multiple of 8 bits.
1136
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:
1143
1144 .. code-block:: ada
1145
1146 type R is range 1 .. 3;
1147 type S is array (1 .. 31) of R;
1148 for S'Component_Size use 2;
1149 for S'Size use 62;
1150 for S'Alignment use 1;
1151
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.
1160
1161 .. index:: Pragma Pack (for type Natural)
1162
1163 .. index:: Pragma Pack warning
1164
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:
1168
1169 .. code-block:: ada
1170
1171 type Arr is array (1 .. 32) of Natural;
1172 pragma Pack (Arr);
1173
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.
1177
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
1183 explicitly:
1184
1185 .. code-block:: ada
1186
1187 type Arr is array (1 .. 32) of Natural;
1188 for Arr'Component_Size use 31;
1189
1190 Here 31-bit packing is achieved as required, and no warning is generated,
1191 since in this case the programmer intention is clear.
1192
1193 .. _Pragma_Pack_for_Records:
1194
1195 Pragma Pack for Records
1196 =======================
1197
1198 .. index:: Pragma Pack (for records)
1199
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:
1205
1206 * Components of an elementary type are packable unless they are aliased,
1207 independent or atomic.
1208
1209 * Small packed arrays, where the size is statically known, are represented
1210 internally as modular integers, and so they are also packable.
1211
1212 * Small simple records, where the size is statically known, are also packable.
1213
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.
1218
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.
1221
1222 For example, consider the record
1223
1224 .. code-block:: ada
1225
1226 type Rb1 is array (1 .. 13) of Boolean;
1227 pragma Pack (Rb1);
1228
1229 type Rb2 is array (1 .. 65) of Boolean;
1230 pragma Pack (Rb2);
1231
1232 type AF is new Float with Atomic;
1233
1234 type X2 is record
1235 L1 : Boolean;
1236 L2 : Duration;
1237 L3 : AF;
1238 L4 : Boolean;
1239 L5 : Rb1;
1240 L6 : Rb2;
1241 end record;
1242 pragma Pack (X2);
1243
1244 The representation for the record ``X2`` is as follows on 32-bit targets:
1245
1246 .. code-block:: ada
1247
1248 for X2'Size use 224;
1249 for X2 use record
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;
1256 end record;
1257
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.
1263
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.
1269
1270 .. _Record_Representation_Clauses:
1271
1272 Record Representation Clauses
1273 =============================
1274
1275 .. index:: Record Representation Clause
1276
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
1280 of the component.
1281
1282 .. index:: Component Clause
1283
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.
1288
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:
1293
1294 .. code-block:: ada
1295
1296 type R is array (1 .. 49) of Boolean;
1297 pragma Pack (R);
1298 for R'Size use 49;
1299
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.
1302
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.
1309
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.
1314
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.
1318
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
1322 proper alignment
1323
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.
1327
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:
1331
1332 .. code-block:: ada
1333
1334 type R is array (1 .. 10) of Boolean;
1335 for R'Size use 80;
1336
1337 type Q is record
1338 G, H : Boolean;
1339 L, M : R;
1340 end record;
1341
1342 for Q use record
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;
1347 end record;
1348
1349 .. _Handling_of_Records_with_Holes:
1350
1351 Handling of Records with Holes
1352 ==============================
1353
1354 .. index:: Handling of Records with Holes
1355
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.
1359
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).
1368
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
1373
1374 .. code-block:: ada
1375
1376 type HRec is record
1377 C : Character;
1378 I : Integer;
1379 end record;
1380
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:
1386
1387 .. code-block:: ada
1388
1389 type Base is record
1390 Dummy1, Dummy2 : Integer := 0;
1391 end record;
1392
1393 BaseVar : Base;
1394 RealVar : Hrec;
1395 for RealVar'Address use BaseVar'Address;
1396
1397
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
1400 holes, as in:
1401
1402 .. code-block:: ada
1403
1404 type HRec is record
1405 C : Character;
1406 Dummy1 : Short_Short_Integer := 0;
1407 Dummy2 : Short_Short_Integer := 0;
1408 Dummy3 : Short_Short_Integer := 0;
1409 I : Integer;
1410 end record;
1411
1412 And to make absolutely sure that the intent of this is followed, you
1413 can use representation clauses:
1414
1415 .. code-block:: ada
1416
1417 for Hrec use record
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;
1423 end record;
1424 for Hrec'Size use 64;
1425
1426
1427 .. _Enumeration_Clauses:
1428
1429 Enumeration Clauses
1430 ===================
1431
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:
1435
1436 .. code-block:: ada
1437
1438 System.Min_Int .. System.Max_Int
1439
1440 For the unsigned case, where all values are nonnegative, the values must
1441 be in the range:
1442
1443 .. code-block:: ada
1444
1445 0 .. System.Max_Binary_Modulus;
1446
1447
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.
1454
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:
1458
1459 .. code-block:: ada
1460
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;
1464
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).
1470
1471
1472 .. _Address_Clauses:
1473
1474 Address Clauses
1475 ===============
1476 .. index:: Address Clause
1477
1478 The reference manual allows a general restriction on representation clauses,
1479 as found in RM 13.1(22):
1480
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."
1487
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):
1491
1492 22.a Reason: This is to avoid the following sort of thing:
1493
1494 22.b X : Integer := F(...);
1495 Y : Address := G(...);
1496 for X'Address use Y;
1497
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.
1502
1503 22.d The above code should instead be written
1504 like this:
1505
1506 22.e Y : constant Address := G(...);
1507 X : Integer := F(...);
1508 for X'Address use Y;
1509
1510 22.f This allows the expression 'Y' to be safely
1511 evaluated before X is created.
1512
1513 22.g The constant could be a formal parameter of mode in.
1514
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
1519 cases.
1520
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:
1527
1528 *
1529 The type of the item is non-elementary (e.g., a record or array).
1530
1531 *
1532 There is explicit or implicit initialization required for the object.
1533 Note that access values are always implicitly initialized.
1534
1535 *
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.
1539
1540 ::
1541
1542 Anchor : Some_Initialized_Type;
1543 Overlay : Some_Initialized_Type;
1544 for Overlay'Address use Anchor'Address;
1545
1546 However, the prefix of the address clause cannot be an array component, or
1547 a component of a discriminated record.
1548
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:
1554
1555 .. index:: Attribute
1556 .. index:: To_Address
1557
1558 .. code-block:: ada
1559
1560 To_Address (16#1234_0000#)
1561 System'To_Address (16#1234_0000#);
1562
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.
1565
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
1569 ``To_Address``.
1570
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.
1577
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).
1587
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
1594
1595 .. code-block:: ada
1596
1597 X : String := Some_Function_Call;
1598 -- String has no constraint, so bounds for X come from function call
1599
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.
1602
1603 .. index:: Export
1604
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.
1609
1610 .. index:: Import
1611
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.
1618
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:
1624
1625 ::
1626
1627 with System;
1628 package G is
1629 type R is record
1630 M : Integer := 0;
1631 end record;
1632
1633 Ext : R;
1634 for Ext'Address use System'To_Address (16#1234_1234#);
1635 |
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))
1640
1641 end G;
1642
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):
1647
1648 .. code-block:: ada
1649
1650 with System;
1651 package G is
1652 type R is record
1653 M : Integer := 0;
1654 end record;
1655
1656 Ext : R;
1657 for Ext'Address use System'To_Address (16#1234_1234#);
1658 pragma Import (Ada, Ext);
1659 end G;
1660
1661
1662 A final issue with address clauses involves their use for overlaying
1663 variables, as in the following example:
1664
1665 .. index:: Overlaying of objects
1666
1667 .. code-block:: ada
1668
1669 A : Integer;
1670 B : Integer;
1671 for B'Address use A'Address;
1672
1673
1674 or alternatively, using the form recommended by the RM:
1675
1676 .. code-block:: ada
1677
1678 A : Integer;
1679 Addr : constant Address := A'Address;
1680 B : Integer;
1681 for B'Address use Addr;
1682
1683
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)):
1692
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."
1696
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.
1701
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.
1706
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:
1709
1710 ::
1711
1712 package Overwrite_Record is
1713 type R is record
1714 A : Character := 'C';
1715 B : Character := 'A';
1716 end record;
1717 X : Short_Integer := 3;
1718 Y : R;
1719 for Y'Address use X'Address;
1720 |
1721 >>> warning: default initialization of "Y" may
1722 modify "X", use pragma Import for "Y" to
1723 suppress initialization (RM B.1(24))
1724
1725 end Overwrite_Record;
1726
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:
1731
1732 .. code-block:: ada
1733
1734 package Overwrite_Record is
1735 type R is record
1736 A : Character := 'C';
1737 B : Character := 'A';
1738 end record;
1739 X : Short_Integer := 3;
1740 Y : R;
1741 for Y'Address use X'Address;
1742 pragma Import (Ada, Y);
1743 end Overwrite_Record;
1744
1745
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):
1753
1754 ::
1755
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);
1761 A : Arr;
1762 for A'Address use X'Address;
1763 |
1764 >>> warning: default initialization of "A" may
1765 modify "X", use pragma Import for "A" to
1766 suppress initialization (RM B.1(24))
1767
1768 begin
1769 if X /= Arr'(others => 1) then
1770 Put_Line ("X was clobbered");
1771 else
1772 Put_Line ("X was not clobbered");
1773 end if;
1774 end Overwrite_Array;
1775
1776 The above program generates the warning as shown, and at execution
1777 time, prints ``X was clobbered``. If the ``pragma Import`` is
1778 added as suggested:
1779
1780 .. code-block:: ada
1781
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);
1787 A : Arr;
1788 for A'Address use X'Address;
1789 pragma Import (Ada, A);
1790 begin
1791 if X /= Arr'(others => 1) then
1792 Put_Line ("X was clobbered");
1793 else
1794 Put_Line ("X was not clobbered");
1795 end if;
1796 end Overwrite_Array;
1797
1798 then the program compiles without the warning and when run will generate
1799 the output ``X was not clobbered``.
1800
1801
1802 .. _Use_of_Address_Clauses_for_Memory-Mapped_I/O:
1803
1804 Use of Address Clauses for Memory-Mapped I/O
1805 ============================================
1806
1807 .. index:: Memory-mapped I/O
1808
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:
1812
1813 .. code-block:: ada
1814
1815 type Mem_Word is record
1816 A,B,C,D : Byte;
1817 end record;
1818 pragma Atomic (Mem_Word);
1819 for Mem_Word_Size use 32;
1820
1821 Mem : Mem_Word;
1822 for Mem'Address use some-address;
1823 ...
1824 Temp := Mem;
1825 Temp.A := 32;
1826 Mem := Temp;
1827
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.
1831
1832 A problem arises with a component access such as:
1833
1834 .. code-block:: ada
1835
1836 Mem.A := 32;
1837
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:
1845
1846 ::
1847
1848 Mem.A := 32;
1849 |
1850 >>> warning: access to non-atomic component of atomic array,
1851 may cause unexpected accesses to atomic object
1852
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.
1859
1860
1861 .. _Effect_of_Convention_on_Representation:
1862
1863 Effect of Convention on Representation
1864 ======================================
1865
1866 .. index:: Convention, effect on representation
1867
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)
1873 has no effect.
1874
1875 There are four exceptions to this general rule:
1876
1877 * *Convention Fortran and array subtypes*.
1878
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.
1883
1884 * *Convention C and enumeration types*
1885
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
1888 type declared by:
1889
1890 ::
1891
1892 type Color is (Red, Green, Blue);
1893
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.
1900
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.
1908
1909 * *Convention C/Fortran and Boolean types*
1910
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.
1915
1916 Fortran has a similar convention for ``LOGICAL`` values (any nonzero
1917 value represents true).
1918
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:
1921
1922 ::
1923
1924 type C_Switch is new Boolean;
1925 pragma Convention (C, C_Switch);
1926
1927
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.
1931
1932
1933 .. _Conventions_and_Anonymous_Access_Types:
1934
1935 Conventions and Anonymous Access Types
1936 ======================================
1937
1938 .. index:: Anonymous access types
1939
1940 .. index:: Convention for anonymous access types
1941
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.
1946
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!
1954
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.
1958
1959 The following program shows these conventions in action:
1960
1961 ::
1962
1963 package ConvComp is
1964 type Foo is range 1 .. 10;
1965 type T1 is record
1966 A : access function (X : Foo) return Integer;
1967 B : Integer;
1968 end record;
1969 pragma Convention (C, T1);
1970
1971 type T2 is record
1972 A : access function (X : Foo) return Integer;
1973 pragma Convention (C, A);
1974 B : Integer;
1975 end record;
1976 pragma Convention (COBOL, T2);
1977
1978 type T3 is record
1979 A : access function (X : Foo) return Integer;
1980 pragma Convention (COBOL, A);
1981 B : Integer;
1982 end record;
1983 pragma Convention (C, T3);
1984
1985 type T4 is record
1986 A : access function (X : Foo) return Integer;
1987 B : Integer;
1988 end record;
1989 pragma Convention (COBOL, T4);
1990
1991 function F (X : Foo) return Integer;
1992 pragma Convention (C, F);
1993
1994 function F (X : Foo) return Integer is (13);
1995
1996 TV1 : T1 := (F'Access, 12); -- OK
1997 TV2 : T2 := (F'Access, 13); -- OK
1998
1999 TV3 : T3 := (F'Access, 13); -- ERROR
2000 |
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
2004 |
2005 >>> subprogram "F" has wrong convention
2006 >>> does not match access to subprogram declared at line 24
2007 39. end ConvComp;
2008
2009
2010 .. _Determining_the_Representations_chosen_by_GNAT:
2011
2012 Determining the Representations chosen by GNAT
2013 ==============================================
2014
2015 .. index:: Representation, determination of
2016
2017 .. index:: -gnatR (gcc)
2018
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.
2022
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.
2033
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:
2038
2039 .. code-block:: ada
2040
2041 package q is
2042 type r (x : boolean) is tagged record
2043 case x is
2044 when True => S : String (1 .. 100);
2045 when False => null;
2046 end case;
2047 end record;
2048
2049 type r2 is new r (false) with record
2050 y2 : integer;
2051 end record;
2052
2053 for r2 use record
2054 y2 at 16 range 0 .. 31;
2055 end record;
2056
2057 type x is record
2058 y : character;
2059 end record;
2060
2061 type x1 is array (1 .. 10) of x;
2062 for x1'component_size use 11;
2063
2064 type ia is access integer;
2065
2066 type Rb1 is array (1 .. 13) of Boolean;
2067 pragma Pack (rb1);
2068
2069 type Rb2 is array (1 .. 65) of Boolean;
2070 pragma Pack (rb2);
2071
2072 type x2 is record
2073 l1 : Boolean;
2074 l2 : Duration;
2075 l3 : Float;
2076 l4 : Boolean;
2077 l5 : Rb1;
2078 l6 : Rb2;
2079 end record;
2080 pragma Pack (x2);
2081 end q;
2082
2083 using the switch *-gnatR* we obtain the following output:
2084
2085 .. code-block:: ada
2086
2087 Representation information for unit q
2088 -------------------------------------
2089
2090 for r'Size use ??;
2091 for r'Alignment use 4;
2092 for r use record
2093 x at 4 range 0 .. 7;
2094 _tag at 0 range 0 .. 31;
2095 s at 5 range 0 .. 799;
2096 end record;
2097
2098 for r2'Size use 160;
2099 for r2'Alignment use 4;
2100 for r2 use record
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;
2105 end record;
2106
2107 for x'Size use 8;
2108 for x'Alignment use 1;
2109 for x use record
2110 y at 0 range 0 .. 7;
2111 end record;
2112
2113 for x1'Size use 112;
2114 for x1'Alignment use 1;
2115 for x1'Component_Size use 11;
2116
2117 for rb1'Size use 13;
2118 for rb1'Alignment use 2;
2119 for rb1'Component_Size use 1;
2120
2121 for rb2'Size use 72;
2122 for rb2'Alignment use 1;
2123 for rb2'Component_Size use 1;
2124
2125 for x2'Size use 224;
2126 for x2'Alignment use 4;
2127 for x2 use record
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;
2134 end record;
2135
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.
2140
2141 The Alignment values show the actual alignment chosen by the compiler
2142 for each record or array type.
2143
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).
2147
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.
2151
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
2155 this record type.
2156
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.