OpenCores
URL https://opencores.org/ocsvn/openrisc_2011-10-31/openrisc_2011-10-31/trunk

Subversion Repositories openrisc_2011-10-31

[/] [openrisc/] [trunk/] [gnu-src/] [gcc-4.5.1/] [gcc/] [ada/] [g-bytswa.ads] - Blame information for rev 404

Go to most recent revision | Details | Compare with Previous | View Log

Line No. Rev Author Line
1 281 jeremybenn
------------------------------------------------------------------------------
2
--                                                                          --
3
--                         GNAT RUN-TIME COMPONENTS                         --
4
--                                                                          --
5
--                    G N A T . B Y T E _ S W A P P I N G                   --
6
--                                                                          --
7
--                                 S p e c                                  --
8
--                                                                          --
9
--                     Copyright (C) 2006-2007, AdaCore                     --
10
--                                                                          --
11
-- GNAT is free software;  you can  redistribute it  and/or modify it under --
12
-- terms of the  GNU General Public License as published  by the Free Soft- --
13
-- ware  Foundation;  either version 2,  or (at your option) any later ver- --
14
-- sion.  GNAT is distributed in the hope that it will be useful, but WITH- --
15
-- OUT ANY WARRANTY;  without even the  implied warranty of MERCHANTABILITY --
16
-- or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License --
17
-- for  more details.  You should have  received  a copy of the GNU General --
18
-- Public License  distributed with GNAT;  see file COPYING.  If not, write --
19
-- to  the  Free Software Foundation,  51  Franklin  Street,  Fifth  Floor, --
20
-- Boston, MA 02110-1301, USA.                                              --
21
--                                                                          --
22
-- As a special exception,  if other files  instantiate  generics from this --
23
-- unit, or you link  this unit with other files  to produce an executable, --
24
-- this  unit  does not  by itself cause  the resulting  executable  to  be --
25
-- covered  by the  GNU  General  Public  License.  This exception does not --
26
-- however invalidate  any other reasons why  the executable file  might be --
27
-- covered by the  GNU Public License.                                      --
28
--                                                                          --
29
-- GNAT was originally developed  by the GNAT team at  New York University. --
30
-- Extensive contributions were provided by Ada Core Technologies Inc.      --
31
--                                                                          --
32
------------------------------------------------------------------------------
33
 
34
--  Simple routines for swapping the bytes of 16-, 32-, and 64-bit objects
35
 
36
--  The generic functions should be instantiated with types that are of a size
37
--  in bytes corresponding to the name of the generic. For example, a 2-byte
38
--  integer type would be compatible with Swapped2, 4-byte integer with
39
--  Swapped4, and so on. Failure to do so will result in a warning when
40
--  compiling the instantiation; this warning should be heeded. Ignoring this
41
--  warning can result in unexpected results.
42
 
43
--  An example of proper usage follows:
44
 
45
--     declare
46
--        type Short_Integer is range -32768 .. 32767;
47
--        for Short_Integer'Size use 16; -- for confirmation
48
 
49
--        X : Short_Integer := 16#7FFF#;
50
 
51
--        function Swapped is new Byte_Swapping.Swapped2 (Short_Integer);
52
 
53
--     begin
54
--        Put_Line (X'Img);
55
--        X := Swapped (X);
56
--        Put_Line (X'Img);
57
--     end;
58
 
59
--  Note that the generic actual types need not be scalars, but must be
60
--  'definite' types. They can, for example, be constrained subtypes of
61
--  unconstrained array types as long as the size is correct. For instance,
62
--  a subtype of String with length of 4 would be compatible with the
63
--  Swapped4 generic:
64
 
65
--     declare
66
--        subtype String4 is String (1 .. 4);
67
--        function Swapped is new Byte_Swapping.Swapped4 (String4);
68
--        S : String4 := "ABCD";
69
--     begin
70
--        Put_Line (S);
71
--        S := Swapped (S);
72
--        Put_Line (S);
73
--     end;
74
 
75
--  Similarly, a constrained array type is also acceptable:
76
 
77
--     declare
78
--        type Mask is array (0 .. 15) of Boolean;
79
--        for Mask'Component_Size use Boolean'Size;
80
--        X : Mask := (0 .. 7 => True, others => False);
81
--        function Swapped is new Byte_Swapping.Swapped2 (Mask);
82
--     begin
83
--        ...
84
--        X := Swapped (X);
85
--        ...
86
--     end;
87
 
88
--  A properly-sized record type will also be acceptable, and so forth
89
 
90
--  However, as described, a size mismatch must be avoided. In the following we
91
--  instantiate one of the generics with a type that is too large. The result
92
--  of the function call is undefined, such that assignment to an object can
93
--  result in garbage values.
94
 
95
--     Wrong: declare
96
--        subtype String16 is String (1 .. 16);
97
 
98
--        function Swapped is new Byte_Swapping.Swapped8 (String16);
99
--        --  Instantiation generates a compiler warning about
100
--        --  mismatched sizes
101
 
102
--        S : String16;
103
 
104
--     begin
105
--        S := "ABCDEFGHDEADBEEF";
106
--
107
--        Put_Line (S);
108
--
109
--        --  the following assignment results in garbage in S after the
110
--        --  first 8 bytes
111
--
112
--        S := Swapped (S);
113
--
114
--        Put_Line (S);
115
--     end Wrong;
116
 
117
--  When the size of the type is larger than 8 bytes, the use of the non-
118
--  generic procedures is an alternative because no function result is
119
--  involved; manipulation of the object is direct.
120
 
121
--  The procedures are passed the address of an object to manipulate. They will
122
--  swap the first N bytes of that object corresponding to the name of the
123
--  procedure.  For example:
124
 
125
--     declare
126
--        S2 : String := "AB";
127
--        for S2'Alignment use 2;
128
--        S4 : String := "ABCD";
129
--        for S4'Alignment use 4;
130
--        S8 : String := "ABCDEFGH";
131
--        for S8'Alignment use 8;
132
 
133
--     begin
134
--        Swap2 (S2'Address);
135
--        Put_Line (S2);
136
 
137
--        Swap4 (S4'Address);
138
--        Put_Line (S4);
139
 
140
--        Swap8 (S8'Address);
141
--        Put_Line (S8);
142
--     end;
143
 
144
--  If an object of a type larger than N is passed, the remaining bytes of the
145
--  object are undisturbed. For example:
146
 
147
--     declare
148
--        subtype String16 is String (1 .. 16);
149
 
150
--        S : String16;
151
--        for S'Alignment use 8;
152
 
153
--     begin
154
--        S  := "ABCDEFGHDEADBEEF";
155
--        Put_Line (S);
156
--        Swap8 (S'Address);
157
--        Put_Line (S);
158
--     end;
159
 
160
with System;
161
 
162
package GNAT.Byte_Swapping is
163
   pragma Pure;
164
 
165
   --  NB: all the routines in this package treat the application objects as
166
   --  unsigned (modular) types of a size in bytes corresponding to the routine
167
   --  name. For example, the generic function Swapped2 manipulates the object
168
   --  passed to the formal parameter Input as a value of an unsigned type that
169
   --  is 2 bytes long. Therefore clients are responsible for the compatibility
170
   --  of application types manipulated by these routines and these modular
171
   --  types, in terms of both size and alignment. This requirement applies to
172
   --  the generic actual type passed to the generic formal type Item in the
173
   --  generic functions, as well as to the type of the object implicitly
174
   --  designated by the address passed to the non-generic procedures. Use of
175
   --  incompatible types can result in implementation- defined effects.
176
 
177
   generic
178
      type Item is limited private;
179
   function Swapped2 (Input : Item) return Item;
180
   --  Return the 2-byte value of Input with the bytes swapped
181
 
182
   generic
183
      type Item is limited private;
184
   function Swapped4 (Input : Item) return Item;
185
   --  Return the 4-byte value of Input with the bytes swapped
186
 
187
   generic
188
      type Item is limited private;
189
   function Swapped8 (Input : Item) return Item;
190
   --  Return the 8-byte value of Input with the bytes swapped
191
 
192
   procedure Swap2 (Location : System.Address);
193
   --  Swap the first 2 bytes of the object starting at the address specified
194
   --  by Location.
195
 
196
   procedure Swap4 (Location : System.Address);
197
   --  Swap the first 4 bytes of the object starting at the address specified
198
   --  by Location.
199
 
200
   procedure Swap8 (Location : System.Address);
201
   --  Swap the first 8 bytes of the object starting at the address specified
202
   --  by Location.
203
 
204
   pragma Inline (Swap2, Swap4, Swap8, Swapped2, Swapped4, Swapped8);
205
 
206
end GNAT.Byte_Swapping;

powered by: WebSVN 2.1.0

© copyright 1999-2024 OpenCores.org, equivalent to Oliscience, all rights reserved. OpenCores®, registered trademark.