gcc/ada/s-excmac-gcc.ads

   1 ------------------------------------------------------------------------------
   2 --                                                                          --
   3 --                         GNAT COMPILER COMPONENTS                         --
   4 --                                                                          --
   5 --              S Y S T E M . E X C E P T I O N S . M A C H I N E           --
   6 --                                                                          --
   7 --                                 S p e c                                  --
   8 --                                                                          --
   9 --          Copyright (C) 2013-2017, 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.                                     --
  17 --                                                                          --
  18 -- As a special exception under Section 7 of GPL version 3, you are granted --
  19 -- additional permissions described in the GCC Runtime Library Exception,   --
  20 -- version 3.1, as published by the Free Software Foundation.               --
  21 --                                                                          --
  22 -- You should have received a copy of the GNU General Public License and    --
  23 -- a copy of the GCC Runtime Library Exception along with this program;     --
  24 -- see the files COPYING3 and COPYING.RUNTIME respectively.  If not, see    --
  25 -- <http://www.gnu.org/licenses/>.                                          --
  26 --                                                                          --
  27 -- GNAT was originally developed  by the GNAT team at  New York University. --
  28 -- Extensive contributions were provided by Ada Core Technologies Inc.      --
  29 --                                                                          --
  30 ------------------------------------------------------------------------------
  31
  32 --  Declaration of the machine exception and some associated facilities. The
  33 --  machine exception is the object that is propagated by low level routines
  34 --  and that contains the Ada exception occurrence.
  35
  36 --  This is the version using the GCC EH mechanism
  37
  38 with Ada.Unchecked_Conversion;
  39 with Ada.Exceptions;
  40
  41 package System.Exceptions.Machine is
  42    pragma Preelaborate;
  43
  44    ------------------------------------------------
  45    -- Entities to interface with the GCC runtime --
  46    ------------------------------------------------
  47
  48    --  These come from "C++ ABI for Itanium: Exception handling", which is
  49    --  the reference for GCC.
  50
  51    --  Return codes from the GCC runtime functions used to propagate
  52    --  an exception.
  53
  54    type Unwind_Reason_Code is
  55      (URC_NO_REASON,
  56       URC_FOREIGN_EXCEPTION_CAUGHT,
  57       URC_PHASE2_ERROR,
  58       URC_PHASE1_ERROR,
  59       URC_NORMAL_STOP,
  60       URC_END_OF_STACK,
  61       URC_HANDLER_FOUND,
  62       URC_INSTALL_CONTEXT,
  63       URC_CONTINUE_UNWIND);
  64
  65    pragma Unreferenced
  66      (URC_NO_REASON,
  67       URC_FOREIGN_EXCEPTION_CAUGHT,
  68       URC_PHASE2_ERROR,
  69       URC_PHASE1_ERROR,
  70       URC_NORMAL_STOP,
  71       URC_END_OF_STACK,
  72       URC_HANDLER_FOUND,
  73       URC_INSTALL_CONTEXT,
  74       URC_CONTINUE_UNWIND);
  75
  76    pragma Convention (C, Unwind_Reason_Code);
  77
  78    --  Phase identifiers
  79
  80    type Unwind_Action is new Integer;
  81    pragma Convention (C, Unwind_Action);
  82
  83    UA_SEARCH_PHASE  : constant Unwind_Action := 1;
  84    UA_CLEANUP_PHASE : constant Unwind_Action := 2;
  85    UA_HANDLER_FRAME : constant Unwind_Action := 4;
  86    UA_FORCE_UNWIND  : constant Unwind_Action := 8;
  87    UA_END_OF_STACK  : constant Unwind_Action := 16;  --  GCC extension
  88
  89    pragma Unreferenced
  90      (UA_SEARCH_PHASE,
  91       UA_CLEANUP_PHASE,
  92       UA_HANDLER_FRAME,
  93       UA_FORCE_UNWIND,
  94       UA_END_OF_STACK);
  95
  96    --  Mandatory common header for any exception object handled by the
  97    --  GCC unwinding runtime.
  98
  99    type Exception_Class is mod 2 ** 64;
 100
 101    GNAT_Exception_Class : constant Exception_Class := 16#474e552d41646100#;
 102    --  "GNU-Ada\0"
 103
 104    type Unwind_Word is mod 2 ** System.Word_Size;
 105    for Unwind_Word'Size use System.Word_Size;
 106    --  Map the corresponding C type used in Unwind_Exception below
 107
 108    type Unwind_Exception is record
 109       Class    : Exception_Class;
 110       Cleanup  : System.Address;
 111       Private1 : Unwind_Word;
 112       Private2 : Unwind_Word;
 113
 114       --  Usual exception structure has only two private fields, but the SEH
 115       --  one has six. To avoid making this file more complex, we use six
 116       --  fields on all platforms, wasting a few bytes on some.
 117
 118       Private3 : Unwind_Word;
 119       Private4 : Unwind_Word;
 120       Private5 : Unwind_Word;
 121       Private6 : Unwind_Word;
 122    end record;
 123    pragma Convention (C, Unwind_Exception);
 124    --  Map the GCC struct used for exception handling
 125
 126    for Unwind_Exception'Alignment use Standard'Maximum_Alignment;
 127    --  The C++ ABI mandates the common exception header to be at least
 128    --  doubleword aligned, and the libGCC implementation actually makes it
 129    --  maximally aligned (see unwind.h). See additional comments on the
 130    --  alignment below.
 131
 132    --  There is a subtle issue with the common header alignment, since the C
 133    --  version is aligned on BIGGEST_ALIGNMENT, the Ada version is aligned on
 134    --  Standard'Maximum_Alignment, and those two values don't quite represent
 135    --  the same concepts and so may be decoupled someday. One typical reason
 136    --  is that BIGGEST_ALIGNMENT may be larger than what the underlying system
 137    --  allocator guarantees, and there are extra costs involved in allocating
 138    --  objects aligned to such factors.
 139
 140    --  To deal with the potential alignment differences between the C and Ada
 141    --  representations, the Ada part of the whole structure is only accessed
 142    --  by the personality routine through accessors. Ada specific fields are
 143    --  thus always accessed through consistent layout, and we expect the
 144    --  actual alignment to always be large enough to avoid traps from the C
 145    --  accesses to the common header. Besides, accessors alleviate the need
 146    --  for a C struct whole counterpart, both painful and error-prone to
 147    --  maintain anyway.
 148
 149    type GCC_Exception_Access is access all Unwind_Exception;
 150    --  Pointer to a GCC exception
 151
 152    procedure Unwind_DeleteException (Excp : not null GCC_Exception_Access);
 153    pragma Import (C, Unwind_DeleteException, "_Unwind_DeleteException");
 154    --  Procedure to free any GCC exception
 155
 156    --------------------------------------------------------------
 157    -- GNAT Specific Entities To Deal With The GCC EH Circuitry --
 158    --------------------------------------------------------------
 159
 160    --  A GNAT exception object to be dealt with by the personality routine
 161    --  called by the GCC unwinding runtime.
 162
 163    type GNAT_GCC_Exception is record
 164       Header : Unwind_Exception;
 165       --  ABI Exception header first
 166
 167       Occurrence : aliased Ada.Exceptions.Exception_Occurrence;
 168       --  The Ada occurrence
 169    end record;
 170
 171    pragma Convention (C, GNAT_GCC_Exception);
 172
 173    type GNAT_GCC_Exception_Access is access all GNAT_GCC_Exception;
 174
 175    function To_GCC_Exception is new
 176      Ada.Unchecked_Conversion (System.Address, GCC_Exception_Access);
 177
 178    function To_GNAT_GCC_Exception is new
 179      Ada.Unchecked_Conversion
 180        (GCC_Exception_Access, GNAT_GCC_Exception_Access);
 181
 182    function New_Occurrence return GNAT_GCC_Exception_Access;
 183    --  Allocate and initialize a machine occurrence
 184
 185 end System.Exceptions.Machine;