1------------------------------------------------------------------------------
2--                                                                          --
3--                 GNAT RUN-TIME LIBRARY (GNARL) COMPONENTS                 --
4--                                                                          --
5--                     S Y S T E M . I N T E R R U P T S                    --
6--                                                                          --
7--                                  S p e c                                 --
8--                                                                          --
9--          Copyright (C) 1992-2013, Free Software Foundation, Inc.         --
10--                                                                          --
11-- GNARL 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-- GNARL was developed by the GNARL team at Florida State University.       --
28-- Extensive contributions were provided by Ada Core Technologies, Inc.     --
29--                                                                          --
30------------------------------------------------------------------------------
31
32--  Note: the compiler generates direct calls to this interface, via Rtsfind.
33--  Any changes to this interface may require corresponding compiler changes.
34
35--  This package encapsulates the implementation of interrupt or signal
36--  handlers. It is logically an extension of the body of Ada.Interrupts. It
37--  is made a child of System to allow visibility of various runtime system
38--  internal data and operations.
39
40--  See System.Interrupt_Management for core interrupt/signal interfaces
41
42--  These two packages are separated to allow System.Interrupt_Management to be
43--  used without requiring the whole tasking implementation to be linked and
44--  elaborated.
45
46with System.Tasking;
47with System.Tasking.Protected_Objects.Entries;
48with System.OS_Interface;
49
50package System.Interrupts is
51
52   pragma Elaborate_Body;
53   --  Comment needed on why this is here ???
54
55   -------------------------
56   -- Constants and types --
57   -------------------------
58
59   Default_Interrupt_Priority : constant System.Interrupt_Priority :=
60     System.Interrupt_Priority'Last;
61   --  Default value used when a pragma Interrupt_Handler or Attach_Handler is
62   --  specified without an Interrupt_Priority pragma, see D.3(10).
63
64   type Ada_Interrupt_ID is range 0 .. System.OS_Interface.Max_Interrupt;
65   --  Avoid inheritance by Ada.Interrupts.Interrupt_ID of unwanted operations
66
67   type Interrupt_ID is range 0 .. System.OS_Interface.Max_Interrupt;
68
69   subtype System_Interrupt_Id is Interrupt_ID;
70   --  This synonym is introduced so that the type is accessible through
71   --  rtsfind, otherwise the name clashes with its homonym in Ada.Interrupts.
72
73   type Parameterless_Handler is access protected procedure;
74
75   ----------------------
76   -- General services --
77   ----------------------
78
79   --  Attempt to attach a Handler to an Interrupt to which an Entry is
80   --  already bound will raise a Program_Error.
81
82   function Is_Reserved (Interrupt : Interrupt_ID) return Boolean;
83
84   function Is_Entry_Attached (Interrupt : Interrupt_ID) return Boolean;
85
86   function Is_Handler_Attached (Interrupt : Interrupt_ID) return Boolean;
87
88   function Current_Handler
89     (Interrupt : Interrupt_ID) return Parameterless_Handler;
90
91   --  Calling the following procedures with New_Handler = null and Static =
92   --  true means that we want to modify the current handler regardless of the
93   --  previous handler's binding status. (i.e. we do not care whether it is a
94   --  dynamic or static handler)
95
96   procedure Attach_Handler
97     (New_Handler : Parameterless_Handler;
98      Interrupt   : Interrupt_ID;
99      Static      : Boolean := False);
100
101   procedure Exchange_Handler
102     (Old_Handler : out Parameterless_Handler;
103      New_Handler : Parameterless_Handler;
104      Interrupt   : Interrupt_ID;
105      Static      : Boolean := False);
106
107   procedure Detach_Handler
108     (Interrupt : Interrupt_ID;
109      Static    : Boolean := False);
110
111   function Reference
112     (Interrupt : Interrupt_ID) return System.Address;
113
114   --------------------------------
115   -- Interrupt Entries Services --
116   --------------------------------
117
118   --  Routines needed for Interrupt Entries
119
120   procedure Bind_Interrupt_To_Entry
121     (T       : System.Tasking.Task_Id;
122      E       : System.Tasking.Task_Entry_Index;
123      Int_Ref : System.Address);
124   --  Bind the given interrupt to the given entry. If the interrupt is
125   --  already bound to another entry, Program_Error will be raised.
126
127   procedure Detach_Interrupt_Entries (T : System.Tasking.Task_Id);
128   --  This procedure detaches all the Interrupt Entries bound to a task
129
130   ------------------------------
131   -- POSIX.5 Signals Services --
132   ------------------------------
133
134   --  Routines needed for POSIX dot5 POSIX_Signals
135
136   procedure Block_Interrupt (Interrupt : Interrupt_ID);
137   --  Block the Interrupt on the process level
138
139   procedure Unblock_Interrupt (Interrupt : Interrupt_ID);
140
141   function Unblocked_By
142     (Interrupt : Interrupt_ID) return System.Tasking.Task_Id;
143   --  It returns the ID of the last Task which Unblocked this Interrupt.
144   --  It returns Null_Task if no tasks have ever requested the Unblocking
145   --  operation or the Interrupt is currently Blocked.
146
147   function Is_Blocked (Interrupt : Interrupt_ID) return Boolean;
148   --  Comment needed ???
149
150   procedure Ignore_Interrupt (Interrupt : Interrupt_ID);
151   --  Set the sigaction for the interrupt to SIG_IGN
152
153   procedure Unignore_Interrupt (Interrupt : Interrupt_ID);
154   --  Comment needed ???
155
156   function Is_Ignored (Interrupt : Interrupt_ID) return Boolean;
157   --  Comment needed ???
158
159   --  Note : Direct calls to sigaction, sigprocmask, thr_sigsetmask or any
160   --  other low-level interface that changes the signal action or signal mask
161   --  needs a careful thought.
162
163   --  One may achieve the effect of system calls first making RTS blocked (by
164   --  calling Block_Interrupt) for the signal under consideration. This will
165   --  make all the tasks in RTS blocked for the Interrupt.
166
167   ----------------------
168   -- Protection Types --
169   ----------------------
170
171   --  Routines and types needed to implement Interrupt_Handler and
172   --  Attach_Handler.
173
174   --  There are two kinds of protected objects that deal with interrupts:
175
176   --  (1) Only Interrupt_Handler pragmas are used. We need to be able to tell
177   --  if an Interrupt_Handler applies to a given procedure, so
178   --  Register_Interrupt_Handler has to be called for all the potential
179   --  handlers, it should be done by calling Register_Interrupt_Handler with
180   --  the handler code address. On finalization, which can happen only has
181   --  part of library level finalization since PO with Interrupt_Handler
182   --  pragmas can only be declared at library level, nothing special needs to
183   --  be done since the default handlers have been restored as part of task
184   --  completion which is done just before global finalization.
185   --  Dynamic_Interrupt_Protection should be used in this case.
186
187   --  (2) Attach_Handler pragmas are used, and possibly Interrupt_Handler
188   --  pragma. We need to attach the handlers to the given interrupts when the
189   --  object is elaborated. This should be done by constructing an array of
190   --  pairs (interrupt, handler) from the pragmas and calling Install_Handlers
191   --  with it (types to be used are New_Handler_Item and New_Handler_Array).
192   --  On finalization, we need to restore the handlers that were installed
193   --  before the elaboration of the PO, so we need to store these previous
194   --  handlers. This is also done by Install_Handlers, the room for these
195   --  informations is provided by adding a discriminant which is the number
196   --  of Attach_Handler pragmas and an array of this size in the protection
197   --  type, Static_Interrupt_Protection.
198
199   procedure Register_Interrupt_Handler
200     (Handler_Addr : System.Address);
201   --  This routine should be called by the compiler to allow the handler be
202   --  used as an Interrupt Handler. That means call this procedure for each
203   --  pragma Interrupt_Handler providing the address of the handler (not
204   --  including the pointer to the actual PO, this way this routine is called
205   --  only once for each type definition of PO).
206
207   type Static_Handler_Index is range 0 .. Integer'Last;
208   subtype Positive_Static_Handler_Index is
209     Static_Handler_Index range 1 .. Static_Handler_Index'Last;
210   --  Comment needed ???
211
212   type Previous_Handler_Item is record
213      Interrupt : Interrupt_ID;
214      Handler   : Parameterless_Handler;
215      Static    : Boolean;
216   end record;
217   --  Contains all the information needed to restore a previous handler
218
219   type Previous_Handler_Array is array
220     (Positive_Static_Handler_Index range <>) of Previous_Handler_Item;
221
222   type New_Handler_Item is record
223      Interrupt : Interrupt_ID;
224      Handler   : Parameterless_Handler;
225   end record;
226   --  Contains all the information from an Attach_Handler pragma
227
228   type New_Handler_Array is
229     array (Positive_Static_Handler_Index range <>) of New_Handler_Item;
230   --  Comment needed ???
231
232   --  Case (1)
233
234   type Dynamic_Interrupt_Protection is new
235     Tasking.Protected_Objects.Entries.Protection_Entries with null record;
236
237   --  ??? Finalize is not overloaded since we currently have no
238   --  way to detach the handlers during library level finalization.
239
240   function Has_Interrupt_Or_Attach_Handler
241     (Object : access Dynamic_Interrupt_Protection) return Boolean;
242   --  Returns True
243
244   --  Case (2)
245
246   type Static_Interrupt_Protection
247     (Num_Entries        : Tasking.Protected_Objects.Protected_Entry_Index;
248      Num_Attach_Handler : Static_Handler_Index)
249   is new
250     Tasking.Protected_Objects.Entries.Protection_Entries (Num_Entries) with
251     record
252       Previous_Handlers : Previous_Handler_Array (1 .. Num_Attach_Handler);
253     end record;
254
255   function Has_Interrupt_Or_Attach_Handler
256     (Object : access Static_Interrupt_Protection) return Boolean;
257   --  Returns True
258
259   overriding procedure Finalize (Object : in out Static_Interrupt_Protection);
260   --  Restore previous handlers as required by C.3.1(12) then call
261   --  Finalize (Protection).
262
263   procedure Install_Handlers
264     (Object       : access Static_Interrupt_Protection;
265      New_Handlers : New_Handler_Array);
266   --  Store the old handlers in Object.Previous_Handlers and install
267   --  the new static handlers.
268
269   procedure Install_Restricted_Handlers
270     (Prio     : Any_Priority;
271      Handlers : New_Handler_Array);
272   --  Install the static Handlers for the given interrupts and do not
273   --  store previously installed handlers. This procedure is used when
274   --  the Ravenscar restrictions are in place since in that case there
275   --  are only library-level protected handlers that will be installed
276   --  at initialization and never be replaced.
277
278end System.Interrupts;
279