OSDN Git Service

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