gcc/ada/sem_mech.ads

   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
  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,
  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
 178 end Sem_Mech;