1------------------------------------------------------------------------------ 2-- -- 3-- GNAT COMPILER COMPONENTS -- 4-- -- 5-- S E M _ M E C H -- 6-- -- 7-- S p e c -- 8-- -- 9-- Copyright (C) 1996-2008, Free Software Foundation, Inc. -- 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 3, 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 COPYING3. If not, go to -- 19-- http://www.gnu.org/licenses for a complete copy of the license. -- 20-- -- 21-- GNAT was originally developed by the GNAT team at New York University. -- 22-- Extensive contributions were provided by Ada Core Technologies Inc. -- 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 30with Types; use Types; 31 32package Sem_Mech is 33 34 ------------------------------------------------- 35 -- Definitions for Parameter Mechanism Control -- 36 ------------------------------------------------- 37 38 -- For parameters passed to subprograms, and for function return values, 39 -- as passing mechanism is defined. The entity attribute Mechanism returns 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 90 By_Descriptor : constant Mechanism_Type := -3; 91 By_Descriptor_UBS : constant Mechanism_Type := -4; 92 By_Descriptor_UBSB : constant Mechanism_Type := -5; 93 By_Descriptor_UBA : constant Mechanism_Type := -6; 94 By_Descriptor_S : constant Mechanism_Type := -7; 95 By_Descriptor_SB : constant Mechanism_Type := -8; 96 By_Descriptor_A : constant Mechanism_Type := -9; 97 By_Descriptor_NCA : constant Mechanism_Type := -10; 98 By_Short_Descriptor : constant Mechanism_Type := -11; 99 By_Short_Descriptor_UBS : constant Mechanism_Type := -12; 100 By_Short_Descriptor_UBSB : constant Mechanism_Type := -13; 101 By_Short_Descriptor_UBA : constant Mechanism_Type := -14; 102 By_Short_Descriptor_S : constant Mechanism_Type := -15; 103 By_Short_Descriptor_SB : constant Mechanism_Type := -16; 104 By_Short_Descriptor_A : constant Mechanism_Type := -17; 105 By_Short_Descriptor_NCA : constant Mechanism_Type := -18; 106 -- These values are used only in OpenVMS ports of GNAT. Pass by descriptor 107 -- is forced, as described in the OpenVMS ABI. The suffix indicates the 108 -- descriptor type: 109 -- 110 -- UBS unaligned bit string 111 -- UBSB aligned bit string with arbitrary bounds 112 -- UBA unaligned bit array 113 -- S string, also a scalar or access type parameter 114 -- SB string with arbitrary bounds 115 -- A contiguous array 116 -- NCA non-contiguous array 117 -- 118 -- Note: the form with no suffix is used if the Import/Export pragma 119 -- uses the simple form of the mechanism name where no descriptor 120 -- type is supplied. In this case the back end assigns a descriptor 121 -- type based on the Ada type in accordance with the OpenVMS ABI. 122 123 subtype Descriptor_Codes is Mechanism_Type 124 range By_Short_Descriptor_NCA .. By_Descriptor; 125 -- Subtype including all descriptor mechanisms 126 127 -- All the above special values are non-positive. Positive values for 128 -- Mechanism_Type values have a special meaning. They are used only in 129 -- the case of records, as a result of the use of the C_Pass_By_Copy 130 -- pragma, and the meaning is that if the size of the record is known 131 -- at compile time and does not exceed the mechanism type value, then 132 -- By_Copy passing is forced, otherwise By_Reference is forced. 133 134 ---------------------- 135 -- Global Variables -- 136 ---------------------- 137 138 Default_C_Record_Mechanism : Mechanism_Type := By_Reference; 139 -- This value is the default mechanism used for C convention records 140 -- in foreign-convention subprograms if no mechanism is otherwise 141 -- specified. This value is modified appropriately by the occurrence 142 -- of a C_Pass_By_Copy configuration pragma. 143 144 ----------------- 145 -- Subprograms -- 146 ----------------- 147 148 procedure Set_Mechanisms (E : Entity_Id); 149 -- E is a subprogram or subprogram type that has been frozen, so the 150 -- convention of the subprogram and all its formal types and result 151 -- type in the case of a function are established. The function of 152 -- this call is to set mechanism values for formals and for the 153 -- function return if they have not already been explicitly set by 154 -- a use of an extended Import or Export pragma. The idea is to set 155 -- mechanism values wherever the semantics is dictated by either 156 -- requirements or implementation advice in the RM, and to leave 157 -- the mechanism set to Default if there is no requirement, so that 158 -- the back-end is free to choose the most efficient method. 159 160 procedure Set_Mechanism_Value (Ent : Entity_Id; Mech_Name : Node_Id); 161 -- Mech is a parameter passing mechanism (see Import_Function syntax 162 -- for MECHANISM_NAME). This routine checks that the mechanism argument 163 -- has the right form, and if not issues an error message. If the 164 -- argument has the right form then the Mechanism field of Ent is 165 -- set appropriately. It also performs some error checks. Note that 166 -- the mechanism name has not been analyzed (and cannot indeed be 167 -- analyzed, since it is semantic nonsense), so we get it in the 168 -- exact form created by the parser. 169 170 procedure Set_Mechanism_With_Checks 171 (Ent : Entity_Id; 172 Mech : Mechanism_Type; 173 Enod : Node_Id); 174 -- Sets the mechanism of Ent to the given Mech value, after first checking 175 -- that the request makes sense. If it does not make sense, a warning is 176 -- posted on node Enod, and the Mechanism of Ent is unchanged. 177 178end Sem_Mech; 179