gcc/ada/strub.ads

   1 ------------------------------------------------------------------------------
   2 --                                                                          --
   3 --                         GNAT COMPILER COMPONENTS                         --
   4 --                                                                          --
   5 --                                S T R U B                                 --
   6 --                                                                          --
   7 --                                 S p e c                                  --
   8 --                                                                          --
   9 --            Copyright (C) 2021-2023, 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 --  Package containing utility procedures related to Stack Scrubbing
  27
  28 with Types; use Types;
  29
  30 package Strub is
  31    type Strub_Mode is
  32      (Disabled,        --  Subprogram cannot be called from strub contexts
  33       At_Calls,        --  Subprogram strubbed by caller
  34       Internal,        --  Subprogram strubbed by wrapper
  35       Callable,        --  Subprogram safe to call despite no strub
  36       Unspecified,     --  Subprogram or data without strub annotation
  37       Enabled,         --  Data (variable or constant) that enables strub
  38       Not_Applicable); --  Entities that are not strub-capable
  39    --  This is the type that expresses decoded strub annotations
  40
  41    --  We compare strub modes in the following circumstances:
  42
  43    --  * subprogram definition vs specification
  44    --  * overriding vs overridden dispatch subprograms
  45    --  * implementation vs interface dispatch subprogram
  46    --  * renaming vs renamed subprogram
  47    --  * type resolution
  48    --  * explicit conversions
  49
  50    --  Explicit conversions can convert between strub modes other than
  51    --  at-calls (see Compatible_Strub_Modes), but for the other cases
  52    --  above, we insist on identity of the strub modes (see
  53    --  Check_Same_Strub_Mode). Anything else would be
  54    --  troublesome.
  55
  56    --  E.g., overriding a callable subprogram with a strub-disabled
  57    --  implementation would enable a subprogram that's unsafe to call
  58    --  in strub contexts to be called through a dispatching
  59    --  interface. An explicitly strub-disabled subprogram shall not be
  60    --  called from strub contexts, and a callable overriding
  61    --  subprogram would still seem not-callable, so accepting
  62    --  different modes would be surprising.
  63
  64    --  We could relax the requirement for overriders from equality to
  65    --  compatibility, with the understanding that the dispatching ABI
  66    --  is what prevails. For renaming, however, if we don't require
  67    --  equality, it would have to encompass an implicit conversion.
  68
  69    procedure Check_Same_Strub_Mode
  70      (Dest, Src : Entity_Id;
  71       Report    : Boolean := True);
  72    --  Check whether Dest and Src are subprograms or subprogram types
  73    --  annotated (or not) with the same strub mode. If Report is
  74    --  requested, and the strub modes are not equivalent, an error
  75    --  message is issued. Unspecified and Internal are considered
  76    --  equivalent, because Internal is an internal implementation
  77    --  detail. Unspecified decays to Disabled or Callable depending on
  78    --  -fstrub=(strict|relaxed), but this procedure does not take this
  79    --  decay into account, which avoids turning strub-equivalent
  80    --  declarations into incompatible ones at command-line changes.
  81
  82    function Compatible_Strub_Modes
  83      (Dest, Src : Entity_Id) return Boolean;
  84    --  Return True if Dest and Src are subprograms or subprogram types
  85    --  annotated (or not) with ABI-compatible strub modes. At-calls is
  86    --  incompatible to other strub modes, because the back end
  87    --  internally modifies the signature of such subprograms, adding
  88    --  hidden parameters. Calling a subprogram through an
  89    --  access-to-subprogram object converted between strub-at-calls
  90    --  and other strub modes should be deemed equivalent to
  91    --  dereferencing an uninitialized access-to-data object, though
  92    --  one-way conversions might seem to work in some circumstances.
  93    --
  94    --  Unspecified, Disabled, Internal and Callable
  95    --  (access-to-)subprograms, on the other hand, can be safely but
  96    --  explicitly converted to each other, because these strub modes
  97    --  do not require signature changes; so it is possible to alter
  98    --  the caller-side stack scrubbing semantics of the call (e.g. to
  99    --  call a subprogram that isn't strub-callable from within a strub
 100    --  context, or to prevent it from being called through an access
 101    --  object) without any incompatibilities.
 102
 103    procedure Copy_Strub_Mode (Dest, Src : Entity_Id);
 104    --  Copy the strub mode from Src to Dest, subprograms or subprogram
 105    --  types. Dest is required to not have a strub mode already set.
 106
 107    function Explicit_Strub_Mode (Id : Entity_Id) return Strub_Mode;
 108    --  Return the strub mode associated with Id, that should refer to
 109    --  a subprogram, a data object, or a type.
 110
 111    function Strub_Pragma_P (Item : Node_Id) return Boolean;
 112    --  Return True iff Item is a strub annotation, specifically, one
 113    --  introduced by pragma Machine_Attribute (Entity, "strub"[, "mode"]).
 114
 115 end Strub;