]>
Commit | Line | Data |
---|---|---|
996ae0b0 RK |
1 | ------------------------------------------------------------------------------ |
2 | -- -- | |
3 | -- GNAT COMPILER COMPONENTS -- | |
4 | -- -- | |
5 | -- S E M _ M E C H -- | |
6 | -- -- | |
7 | -- S p e c -- | |
8 | -- -- | |
4b490c1e | 9 | -- Copyright (C) 1996-2020, Free Software Foundation, Inc. -- |
996ae0b0 RK |
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- -- | |
b5c84c3c | 13 | -- ware Foundation; either version 3, or (at your option) any later ver- -- |
996ae0b0 RK |
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 -- | |
b5c84c3c RD |
18 | -- Public License distributed with GNAT; see file COPYING3. If not, go to -- |
19 | -- http://www.gnu.org/licenses for a complete copy of the license. -- | |
996ae0b0 RK |
20 | -- -- |
21 | -- GNAT was originally developed by the GNAT team at New York University. -- | |
71ff80dc | 22 | -- Extensive contributions were provided by Ada Core Technologies Inc. -- |
996ae0b0 RK |
23 | -- -- |
24 | ------------------------------------------------------------------------------ | |
25 | ||
26 | -- This package contains the routine used to establish calling mechanisms | |
27 | -- The reason we separate this off into its own package is that it is | |
28 | -- entirely possible that it may need some target specific specialization. | |
29 | ||
30 | with Types; use Types; | |
31 | ||
32 | package Sem_Mech is | |
33 | ||
34 | ------------------------------------------------- | |
35 | -- Definitions for Parameter Mechanism Control -- | |
36 | ------------------------------------------------- | |
37 | ||
38 | -- For parameters passed to subprograms, and for function return values, | |
28e18b4f | 39 | -- a passing mechanism is defined. The entity attribute Mechanism returns |
996ae0b0 RK |
40 | -- an indication of the mechanism, and Set_Mechanism can be used to set |
41 | -- the mechanism. At the program level, there are three ways to explicitly | |
42 | -- set the mechanism: | |
43 | ||
44 | -- An Import_xxx or Export_xxx pragma (where xxx is Function, Procedure, | |
45 | -- or Valued_Procedure) can explicitly set the mechanism for either a | |
46 | -- parameter or a function return value. A mechanism explicitly set by | |
47 | -- such a pragma overrides the effect of C_Pass_By_Copy described below. | |
48 | ||
49 | -- If convention C_Pass_By_Copy is set for a record, and the record type | |
50 | -- is used as the formal type of a subprogram with a foreign convention, | |
51 | -- then the mechanism is set to By_Copy. | |
52 | ||
53 | -- If a pragma C_Pass_By_Copy applies, and a record type has Convention | |
54 | -- C, and the record type is used as the formal type of a subprogram | |
55 | -- with a foreign convention, then the mechanism is set to use By_Copy | |
56 | -- if the size of the record is sufficiently small (as determined by | |
57 | -- the value of the parameter to pragma C_Pass_By_Copy). | |
58 | ||
59 | -- The subtype Mechanism_Type (declared in Types) is used to describe | |
60 | -- the mechanism to be used. The following special values of this type | |
61 | -- specify the mechanism, as follows. | |
62 | ||
63 | Default_Mechanism : constant Mechanism_Type := 0; | |
64 | -- The default setting indicates that the backend will choose the proper | |
65 | -- default mechanism. This depends on the convention of the subprogram | |
66 | -- involved, and is generally target dependent. In the compiler, the | |
67 | -- backend chooses the mechanism in this case in accordance with any | |
68 | -- requirements imposed by the ABI. Note that Default is never used for | |
69 | -- record types on foreign convention subprograms, since By_Reference | |
70 | -- is forced for such types unless one of the above described approaches | |
71 | -- is used to explicitly force By_Copy. | |
72 | ||
73 | By_Copy : constant Mechanism_Type := -1; | |
74 | -- Passing by copy is forced. The exact meaning of By_Copy (e.g. whether | |
75 | -- at a low level the value is passed in registers, or the value is copied | |
76 | -- and a pointer is passed), is determined by the backend in accordance | |
77 | -- with requirements imposed by the ABI. Note that in the extended import | |
78 | -- and export pragma mechanisms, this is called Value, rather than Copy. | |
79 | ||
80 | By_Reference : constant Mechanism_Type := -2; | |
81 | -- Passing by reference is forced. This is always equivalent to passing | |
82 | -- a simple pointer in the case of subprograms with a foreign convention. | |
83 | -- For unconstrained arrays passed to foreign convention subprograms, the | |
84 | -- address of the first element of the array is passed. For convention | |
85 | -- Ada, the result is logically to pass a reference, but the precise | |
86 | -- mechanism (e.g. to pass bounds of unconstrained types and other needed | |
87 | -- special information) is determined by the backend in accordance with | |
88 | -- requirements imposed by the ABI as interpreted for Ada. | |
89 | ||
7a5b62b0 | 90 | pragma Assert (Mechanism_Type'First = -2); |
28e18b4f | 91 | -- Check definition in types is right! |
996ae0b0 | 92 | |
996ae0b0 RK |
93 | -- All the above special values are non-positive. Positive values for |
94 | -- Mechanism_Type values have a special meaning. They are used only in | |
95 | -- the case of records, as a result of the use of the C_Pass_By_Copy | |
96 | -- pragma, and the meaning is that if the size of the record is known | |
97 | -- at compile time and does not exceed the mechanism type value, then | |
98 | -- By_Copy passing is forced, otherwise By_Reference is forced. | |
99 | ||
100 | ---------------------- | |
101 | -- Global Variables -- | |
102 | ---------------------- | |
103 | ||
104 | Default_C_Record_Mechanism : Mechanism_Type := By_Reference; | |
105 | -- This value is the default mechanism used for C convention records | |
106 | -- in foreign-convention subprograms if no mechanism is otherwise | |
107 | -- specified. This value is modified appropriately by the occurrence | |
108 | -- of a C_Pass_By_Copy configuration pragma. | |
109 | ||
110 | ----------------- | |
111 | -- Subprograms -- | |
112 | ----------------- | |
113 | ||
114 | procedure Set_Mechanisms (E : Entity_Id); | |
115 | -- E is a subprogram or subprogram type that has been frozen, so the | |
116 | -- convention of the subprogram and all its formal types and result | |
117 | -- type in the case of a function are established. The function of | |
118 | -- this call is to set mechanism values for formals and for the | |
119 | -- function return if they have not already been explicitly set by | |
120 | -- a use of an extended Import or Export pragma. The idea is to set | |
f3d57416 | 121 | -- mechanism values wherever the semantics is dictated by either |
996ae0b0 RK |
122 | -- requirements or implementation advice in the RM, and to leave |
123 | -- the mechanism set to Default if there is no requirement, so that | |
124 | -- the back-end is free to choose the most efficient method. | |
125 | ||
126 | procedure Set_Mechanism_Value (Ent : Entity_Id; Mech_Name : Node_Id); | |
127 | -- Mech is a parameter passing mechanism (see Import_Function syntax | |
128 | -- for MECHANISM_NAME). This routine checks that the mechanism argument | |
129 | -- has the right form, and if not issues an error message. If the | |
130 | -- argument has the right form then the Mechanism field of Ent is | |
131 | -- set appropriately. It also performs some error checks. Note that | |
132 | -- the mechanism name has not been analyzed (and cannot indeed be | |
133 | -- analyzed, since it is semantic nonsense), so we get it in the | |
134 | -- exact form created by the parser. | |
135 | ||
136 | procedure Set_Mechanism_With_Checks | |
137 | (Ent : Entity_Id; | |
138 | Mech : Mechanism_Type; | |
139 | Enod : Node_Id); | |
140 | -- Sets the mechanism of Ent to the given Mech value, after first checking | |
141 | -- that the request makes sense. If it does not make sense, a warning is | |
142 | -- posted on node Enod, and the Mechanism of Ent is unchanged. | |
143 | ||
144 | end Sem_Mech; |