------------------------------------------------------------------------------ -- -- -- GNAT RUN-TIME LIBRARY (GNARL) COMPONENTS -- -- -- -- S Y S T E M . I N T E R R U P T S -- -- -- -- S p e c -- -- -- -- Copyright (C) 1992-2018, Free Software Foundation, Inc. -- -- -- -- GNARL is free software; you can redistribute it and/or modify it under -- -- terms of the GNU General Public License as published by the Free Soft- -- -- ware Foundation; either version 3, or (at your option) any later ver- -- -- sion. GNAT is distributed in the hope that it will be useful, but WITH- -- -- OUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY -- -- or FITNESS FOR A PARTICULAR PURPOSE. -- -- -- -- As a special exception under Section 7 of GPL version 3, you are granted -- -- additional permissions described in the GCC Runtime Library Exception, -- -- version 3.1, as published by the Free Software Foundation. -- -- -- -- You should have received a copy of the GNU General Public License and -- -- a copy of the GCC Runtime Library Exception along with this program; -- -- see the files COPYING3 and COPYING.RUNTIME respectively. If not, see -- -- . -- -- -- -- GNARL was developed by the GNARL team at Florida State University. -- -- Extensive contributions were provided by Ada Core Technologies, Inc. -- -- -- ------------------------------------------------------------------------------ -- Note: the compiler generates direct calls to this interface, via Rtsfind. -- Any changes to this interface may require corresponding compiler changes. -- This package encapsulates the implementation of interrupt or signal -- handlers. It is logically an extension of the body of Ada.Interrupts. It -- is made a child of System to allow visibility of various runtime system -- internal data and operations. -- See System.Interrupt_Management for core interrupt/signal interfaces -- These two packages are separated to allow System.Interrupt_Management to be -- used without requiring the whole tasking implementation to be linked and -- elaborated. with System.Tasking; with System.Tasking.Protected_Objects.Entries; with System.OS_Interface; package System.Interrupts is pragma Elaborate_Body; -- Comment needed on why this is here ??? ------------------------- -- Constants and types -- ------------------------- Default_Interrupt_Priority : constant System.Interrupt_Priority := System.Interrupt_Priority'Last; -- Default value used when a pragma Interrupt_Handler or Attach_Handler is -- specified without an Interrupt_Priority pragma, see D.3(10). type Ada_Interrupt_ID is range 0 .. System.OS_Interface.Max_Interrupt; -- Avoid inheritance by Ada.Interrupts.Interrupt_ID of unwanted operations type Interrupt_ID is range 0 .. System.OS_Interface.Max_Interrupt; subtype System_Interrupt_Id is Interrupt_ID; -- This synonym is introduced so that the type is accessible through -- rtsfind, otherwise the name clashes with its homonym in Ada.Interrupts. type Parameterless_Handler is access protected procedure; ---------------------- -- General services -- ---------------------- -- Attempt to attach a Handler to an Interrupt to which an Entry is -- already bound will raise a Program_Error. function Is_Reserved (Interrupt : Interrupt_ID) return Boolean; function Is_Entry_Attached (Interrupt : Interrupt_ID) return Boolean; function Is_Handler_Attached (Interrupt : Interrupt_ID) return Boolean; function Current_Handler (Interrupt : Interrupt_ID) return Parameterless_Handler; -- Calling the following procedures with New_Handler = null and Static = -- true means that we want to modify the current handler regardless of the -- previous handler's binding status. (i.e. we do not care whether it is a -- dynamic or static handler) procedure Attach_Handler (New_Handler : Parameterless_Handler; Interrupt : Interrupt_ID; Static : Boolean := False); procedure Exchange_Handler (Old_Handler : out Parameterless_Handler; New_Handler : Parameterless_Handler; Interrupt : Interrupt_ID; Static : Boolean := False); procedure Detach_Handler (Interrupt : Interrupt_ID; Static : Boolean := False); function Reference (Interrupt : Interrupt_ID) return System.Address; -------------------------------- -- Interrupt Entries Services -- -------------------------------- -- Routines needed for Interrupt Entries procedure Bind_Interrupt_To_Entry (T : System.Tasking.Task_Id; E : System.Tasking.Task_Entry_Index; Int_Ref : System.Address); -- Bind the given interrupt to the given entry. If the interrupt is -- already bound to another entry, Program_Error will be raised. procedure Detach_Interrupt_Entries (T : System.Tasking.Task_Id); -- This procedure detaches all the Interrupt Entries bound to a task ------------------------------ -- POSIX.5 Signals Services -- ------------------------------ -- Routines needed for POSIX dot5 POSIX_Signals procedure Block_Interrupt (Interrupt : Interrupt_ID); -- Block the Interrupt on the process level procedure Unblock_Interrupt (Interrupt : Interrupt_ID); function Unblocked_By (Interrupt : Interrupt_ID) return System.Tasking.Task_Id; -- It returns the ID of the last Task which Unblocked this Interrupt. -- It returns Null_Task if no tasks have ever requested the Unblocking -- operation or the Interrupt is currently Blocked. function Is_Blocked (Interrupt : Interrupt_ID) return Boolean; -- Comment needed ??? procedure Ignore_Interrupt (Interrupt : Interrupt_ID); -- Set the sigaction for the interrupt to SIG_IGN procedure Unignore_Interrupt (Interrupt : Interrupt_ID); -- Comment needed ??? function Is_Ignored (Interrupt : Interrupt_ID) return Boolean; -- Comment needed ??? -- Note : Direct calls to sigaction, sigprocmask, thr_sigsetmask, or any -- other low-level interface that changes the signal action or signal mask -- needs careful thought. -- One may achieve the effect of system calls first making RTS blocked (by -- calling Block_Interrupt) for the signal under consideration. This will -- make all the tasks in RTS blocked for the Interrupt. ---------------------- -- Protection Types -- ---------------------- -- Routines and types needed to implement Interrupt_Handler and -- Attach_Handler. -- There are two kinds of protected objects that deal with interrupts: -- (1) Only Interrupt_Handler pragmas are used. We need to be able to tell -- if an Interrupt_Handler applies to a given procedure, so -- Register_Interrupt_Handler has to be called for all the potential -- handlers, it should be done by calling Register_Interrupt_Handler with -- the handler code address. On finalization, which can happen only has -- part of library level finalization since PO with Interrupt_Handler -- pragmas can only be declared at library level, nothing special needs to -- be done since the default handlers have been restored as part of task -- completion which is done just before global finalization. -- Dynamic_Interrupt_Protection should be used in this case. -- (2) Attach_Handler pragmas are used, and possibly Interrupt_Handler -- pragma. We need to attach the handlers to the given interrupts when the -- object is elaborated. This should be done by constructing an array of -- pairs (interrupt, handler) from the pragmas and calling Install_Handlers -- with it (types to be used are New_Handler_Item and New_Handler_Array). -- On finalization, we need to restore the handlers that were installed -- before the elaboration of the PO, so we need to store these previous -- handlers. This is also done by Install_Handlers, the room for this -- information is provided by adding a discriminant which is the number -- of Attach_Handler pragmas and an array of this size in the protection -- type, Static_Interrupt_Protection. procedure Register_Interrupt_Handler (Handler_Addr : System.Address); -- This routine should be called by the compiler to allow the handler be -- used as an Interrupt Handler. That means call this procedure for each -- pragma Interrupt_Handler providing the address of the handler (not -- including the pointer to the actual PO, this way this routine is called -- only once for each type definition of PO). type Static_Handler_Index is range 0 .. Integer'Last; subtype Positive_Static_Handler_Index is Static_Handler_Index range 1 .. Static_Handler_Index'Last; -- Comment needed ??? type Previous_Handler_Item is record Interrupt : Interrupt_ID; Handler : Parameterless_Handler; Static : Boolean; end record; -- Contains all the information needed to restore a previous handler type Previous_Handler_Array is array (Positive_Static_Handler_Index range <>) of Previous_Handler_Item; type New_Handler_Item is record Interrupt : Interrupt_ID; Handler : Parameterless_Handler; end record; -- Contains all the information from an Attach_Handler pragma type New_Handler_Array is array (Positive_Static_Handler_Index range <>) of New_Handler_Item; -- Comment needed ??? -- Case (1) type Dynamic_Interrupt_Protection is new Tasking.Protected_Objects.Entries.Protection_Entries with null record; -- ??? Finalize is not overloaded since we currently have no -- way to detach the handlers during library level finalization. function Has_Interrupt_Or_Attach_Handler (Object : access Dynamic_Interrupt_Protection) return Boolean; -- Returns True -- Case (2) type Static_Interrupt_Protection (Num_Entries : Tasking.Protected_Objects.Protected_Entry_Index; Num_Attach_Handler : Static_Handler_Index) is new Tasking.Protected_Objects.Entries.Protection_Entries (Num_Entries) with record Previous_Handlers : Previous_Handler_Array (1 .. Num_Attach_Handler); end record; function Has_Interrupt_Or_Attach_Handler (Object : access Static_Interrupt_Protection) return Boolean; -- Returns True overriding procedure Finalize (Object : in out Static_Interrupt_Protection); -- Restore previous handlers as required by C.3.1(12) then call -- Finalize (Protection). procedure Install_Handlers (Object : access Static_Interrupt_Protection; New_Handlers : New_Handler_Array); -- Store the old handlers in Object.Previous_Handlers and install -- the new static handlers. procedure Install_Restricted_Handlers (Prio : Any_Priority; Handlers : New_Handler_Array); -- Install the static Handlers for the given interrupts and do not -- store previously installed handlers. This procedure is used when -- the Ravenscar restrictions are in place since in that case there -- are only library-level protected handlers that will be installed -- at initialization and never be replaced. end System.Interrupts;