1 ------------------------------------------------------------------------------
3 -- GNU ADA RUN-TIME LIBRARY (GNARL) COMPONENTS --
5 -- S Y S T E M . I N T E R R U P T S --
9 -- Copyright (C) 1992-2004 Free Software Foundation, Inc. --
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, 59 Temple Place - Suite 330, Boston, --
20 -- MA 02111-1307, USA. --
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. --
29 -- GNARL was developed by the GNARL team at Florida State University. --
30 -- Extensive contributions were provided by Ada Core Technologies, Inc. --
32 ------------------------------------------------------------------------------
34 -- Note: the compiler generates direct calls to this interface, via Rtsfind.
35 -- Any changes to this interface may require corresponding compiler changes.
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.
42 -- See System.Interrupt_Management for core interrupt/signal interfaces.
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.
51 with System.Tasking.Protected_Objects.Entries;
52 -- used for Protection_Entries
54 with System.OS_Interface;
55 -- used for Max_Interrupt
57 package System.Interrupts is
59 pragma Elaborate_Body;
60 -- Comment needed on why this is here ???
62 -------------------------
63 -- Constants and types --
64 -------------------------
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).
71 type Ada_Interrupt_ID is range 0 .. System.OS_Interface.Max_Interrupt;
72 -- Avoid inheritance by Ada.Interrupts.Interrupt_ID of unwanted operations
74 type Interrupt_ID is range 0 .. System.OS_Interface.Max_Interrupt;
76 -- The following renaming is introduced so that the type is accessible
77 -- through rtsfind, otherwise the name clashes with its homonym in
80 subtype System_Interrupt_Id is Interrupt_ID;
82 type Parameterless_Handler is access protected procedure;
84 ----------------------
85 -- General services --
86 ----------------------
88 -- Attempt to attach a Handler to an Interrupt to which an Entry is
89 -- already bound will raise a Program_Error.
91 function Is_Reserved (Interrupt : Interrupt_ID) return Boolean;
93 function Is_Entry_Attached (Interrupt : Interrupt_ID) return Boolean;
95 function Is_Handler_Attached (Interrupt : Interrupt_ID) return Boolean;
97 function Current_Handler
98 (Interrupt : Interrupt_ID)
99 return Parameterless_Handler;
101 -- Calling the following procedures with New_Handler = null
102 -- and Static = true means that we want to modify the current handler
103 -- regardless of the previous handler's binding status.
104 -- (i.e. we do not care whether it is a dynamic or static handler)
106 procedure Attach_Handler
107 (New_Handler : Parameterless_Handler;
108 Interrupt : Interrupt_ID;
109 Static : Boolean := False);
111 procedure Exchange_Handler
112 (Old_Handler : out Parameterless_Handler;
113 New_Handler : Parameterless_Handler;
114 Interrupt : Interrupt_ID;
115 Static : Boolean := False);
117 procedure Detach_Handler
118 (Interrupt : Interrupt_ID;
119 Static : Boolean := False);
122 (Interrupt : Interrupt_ID)
123 return System.Address;
125 --------------------------------
126 -- Interrupt Entries Services --
127 --------------------------------
129 -- Routines needed for Interrupt Entries
131 procedure Bind_Interrupt_To_Entry
132 (T : System.Tasking.Task_Id;
133 E : System.Tasking.Task_Entry_Index;
134 Int_Ref : System.Address);
135 -- Bind the given interrupt to the given entry. If the interrupt is
136 -- already bound to another entry, Program_Error will be raised.
138 procedure Detach_Interrupt_Entries (T : System.Tasking.Task_Id);
139 -- This procedure detaches all the Interrupt Entries bound to a task.
141 ------------------------------
142 -- POSIX.5 Signals Services --
143 ------------------------------
145 -- Routines needed for POSIX dot5 POSIX_Signals
147 procedure Block_Interrupt (Interrupt : Interrupt_ID);
148 -- Block the Interrupt on the process level
150 procedure Unblock_Interrupt (Interrupt : Interrupt_ID);
152 function Unblocked_By
153 (Interrupt : Interrupt_ID)
154 return System.Tasking.Task_Id;
155 -- It returns the ID of the last Task which Unblocked this Interrupt.
156 -- It returns Null_Task if no tasks have ever requested the
157 -- Unblocking operation or the Interrupt is currently Blocked.
159 function Is_Blocked (Interrupt : Interrupt_ID) return Boolean;
160 -- Comment needed ???
162 procedure Ignore_Interrupt (Interrupt : Interrupt_ID);
163 -- Set the sigacion for the interrupt to SIG_IGN.
165 procedure Unignore_Interrupt (Interrupt : Interrupt_ID);
166 -- Comment needed ???
168 function Is_Ignored (Interrupt : Interrupt_ID) return Boolean;
169 -- Comment needed ???
171 -- Note : Direct calls to sigaction, sigprocmask, thr_sigsetmask or any
172 -- other low-level interface that changes the signal action or signal mask
173 -- needs a careful thought.
175 -- One may acheive the effect of system calls first making RTS blocked
176 -- (by calling Block_Interrupt) for the signal under consideration.
177 -- This will make all the tasks in RTS blocked for the Interrupt.
179 ----------------------
180 -- Protection Types --
181 ----------------------
183 -- Routines and types needed to implement Interrupt_Handler and
186 -- There are two kinds of protected objects that deal with interrupts:
188 -- (1) Only Interrupt_Handler pragmas are used. We need to be able to
189 -- tell if an Interrupt_Handler applies to a given procedure, so
190 -- Register_Interrupt_Handler has to be called for all the potential
191 -- handlers, it should be done by calling Register_Interrupt_Handler
192 -- with the handler code address. On finalization, which can happen only
193 -- has part of library level finalization since PO with
194 -- Interrupt_Handler pragmas can only be declared at library level,
195 -- nothing special needs to be done since the default handlers have been
196 -- restored as part of task completion which is done just before global
197 -- finalization. Dynamic_Interrupt_Protection should be used in this
200 -- (2) Attach_Handler pragmas are used, and possibly Interrupt_Handler
201 -- pragma. We need to attach the handlers to the given interrupts when
202 -- the objet is elaborated. This should be done by constructing an array
203 -- of pairs (interrupt, handler) from the pragmas and calling
204 -- Install_Handlers with it (types to be used are New_Handler_Item and
205 -- New_Handler_Array). On finalization, we need to restore the handlers
206 -- that were installed before the elaboration of the PO, so we need to
207 -- store these previous handlers. This is also done by Install_Handlers,
208 -- the room for these informations is provided by adding a discriminant
209 -- which is the number of Attach_Handler pragmas and an array of this
210 -- size in the protection type, Static_Interrupt_Protection.
212 procedure Register_Interrupt_Handler
213 (Handler_Addr : System.Address);
214 -- This routine should be called by the compiler to allow the
215 -- handler be used as an Interrupt Handler. That means call this
216 -- procedure for each pragma Interrup_Handler providing the
217 -- address of the handler (not including the pointer to the
218 -- actual PO, this way this routine is called only once for
219 -- each type definition of PO).
221 type Static_Handler_Index is range 0 .. Integer'Last;
222 subtype Positive_Static_Handler_Index is
223 Static_Handler_Index range 1 .. Static_Handler_Index'Last;
224 -- Comment needed ???
226 type Previous_Handler_Item is record
227 Interrupt : Interrupt_ID;
228 Handler : Parameterless_Handler;
231 -- Contains all the information needed to restore a previous handler.
233 type Previous_Handler_Array is array
234 (Positive_Static_Handler_Index range <>) of Previous_Handler_Item;
236 type New_Handler_Item is record
237 Interrupt : Interrupt_ID;
238 Handler : Parameterless_Handler;
240 -- Contains all the information from an Attach_Handler pragma.
242 type New_Handler_Array is
243 array (Positive_Static_Handler_Index range <>) of New_Handler_Item;
244 -- Comment needed ???
248 type Dynamic_Interrupt_Protection is new
249 Tasking.Protected_Objects.Entries.Protection_Entries with null record;
251 -- ??? Finalize is not overloaded since we currently have no
252 -- way to detach the handlers during library level finalization.
254 function Has_Interrupt_Or_Attach_Handler
255 (Object : access Dynamic_Interrupt_Protection) return Boolean;
260 type Static_Interrupt_Protection
261 (Num_Entries : Tasking.Protected_Objects.Protected_Entry_Index;
262 Num_Attach_Handler : Static_Handler_Index)
264 Tasking.Protected_Objects.Entries.Protection_Entries (Num_Entries) with
266 Previous_Handlers : Previous_Handler_Array (1 .. Num_Attach_Handler);
269 function Has_Interrupt_Or_Attach_Handler
270 (Object : access Static_Interrupt_Protection)
274 procedure Finalize (Object : in out Static_Interrupt_Protection);
275 -- Restore previous handlers as required by C.3.1(12) then call
276 -- Finalize (Protection).
278 procedure Install_Handlers
279 (Object : access Static_Interrupt_Protection;
280 New_Handlers : in New_Handler_Array);
281 -- Store the old handlers in Object.Previous_Handlers and install
282 -- the new static handlers.
284 end System.Interrupts;