111
|
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 -- --
|
131
|
9 -- Copyright (C) 1992-2018, Free Software Foundation, Inc. --
|
111
|
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
|
|
46 with System.Tasking;
|
|
47 with System.Tasking.Protected_Objects.Entries;
|
|
48 with System.OS_Interface;
|
|
49
|
|
50 package 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 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 this
|
|
195 -- information 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
|
|
278 end System.Interrupts;
|