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-2020, 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 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 278end System.Interrupts; 279