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, 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
38with Ada.Unchecked_Conversion;
39with Ada.Exceptions;
40
41package 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. Do not use convention C as on VMS this
151   --  would imply the use of 32-bits pointers.
152
153   procedure Unwind_DeleteException (Excp : not null GCC_Exception_Access);
154   pragma Import (C, Unwind_DeleteException, "_Unwind_DeleteException");
155   --  Procedure to free any GCC exception
156
157   --------------------------------------------------------------
158   -- GNAT Specific Entities To Deal With The GCC EH Circuitry --
159   --------------------------------------------------------------
160
161   --  A GNAT exception object to be dealt with by the personality routine
162   --  called by the GCC unwinding runtime.
163
164   type GNAT_GCC_Exception is record
165      Header : Unwind_Exception;
166      --  ABI Exception header first
167
168      Occurrence : aliased Ada.Exceptions.Exception_Occurrence;
169      --  The Ada occurrence
170   end record;
171
172   pragma Convention (C, GNAT_GCC_Exception);
173
174   type GNAT_GCC_Exception_Access is access all GNAT_GCC_Exception;
175
176   function To_GCC_Exception is new
177     Ada.Unchecked_Conversion (System.Address, GCC_Exception_Access);
178
179   function To_GNAT_GCC_Exception is new
180     Ada.Unchecked_Conversion
181       (GCC_Exception_Access, GNAT_GCC_Exception_Access);
182
183   function New_Occurrence return GNAT_GCC_Exception_Access is
184      (new GNAT_GCC_Exception'
185        (Header     => (Class   => GNAT_Exception_Class,
186                        Cleanup => Null_Address,
187                        others  => 0),
188         Occurrence => <>));
189   --  Allocate and initialize a machine occurrence
190
191end System.Exceptions.Machine;
192