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-2009, 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
  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 a 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 these
 195    --  informations 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    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 (Handlers : New_Handler_Array);
 270    --  Install the static Handlers for the given interrupts and do not store
 271    --  previously installed handlers. This procedure is used when the Ravenscar
 272    --  restrictions are in place since in that case there are only
 273    --  library-level protected handlers that will be installed at
 274    --  initialization and never be replaced.
 275
 276 end System.Interrupts;