The Package Interrupts

{AI05-0167-1} {AI12-0241-1} {AI12-0302-1} with System;
with System.Multiprocessors;
package Ada.Interrupts
   with Nonblocking, Global => in out synchronized is
   type Interrupt_Id is implementation-defined;
   type Parameterless_Handler is
      access protected procedure
      with Nonblocking => False;

This paragraph was deleted.

function Is_Reserved (Interrupt : Interrupt_Id)
return Boolean;

function Is_Attached (Interrupt : Interrupt_Id)
return Boolean;

function Current_Handler (Interrupt : Interrupt_Id)
return Parameterless_Handler;

   procedure Attach_Handler
      (New_Handler : in Parameterless_Handler;
       Interrupt   : in Interrupt_Id);

   procedure Exchange_Handler
      (Old_Handler : out Parameterless_Handler;
       New_Handler : in Parameterless_Handler;
       Interrupt   : in Interrupt_Id);

procedure Detach_Handler
(Interrupt : in Interrupt_Id);

function Reference (Interrupt : Interrupt_Id)
return System.Address;

{AI05-0167-1} function Get_CPU (Interrupt : Interrupt_Id)
return System.Multiprocessors.CPU_Range;

private
... -- not specified by the language
end Ada.Interrupts;

{AI12-0302-1} package Ada.Interrupts.Names
   with Nonblocking, Global => null is
   implementation-defined : constant Interrupt_Id :=
     implementation-defined;
      . . .
   implementation-defined : constant Interrupt_Id :=
     implementation-defined;
end Ada.Interrupts.Names;

Dynamic Semantics

The Is_Attached function returns True if and only if a user-specified interrupt handler is attached to the interrupt.

{8652/0069} {AI95-00166-01} The Current_Handler function returns a value that represents the attached handler of the interrupt. If no user-defined handler is attached to the interrupt, Current_Handler returns null.

{AI05-0229-1} The Attach_Handler procedure attaches the specified handler to the interrupt, overriding any existing treatment (including a user handler) in effect for that interrupt. If New_Handler is null, the default treatment is restored. If New_Handler designates a protected procedure for which the aspect Interrupt_Handler is False, Program_Error is raised. In this case, the operation does not modify the existing interrupt treatment.

{8652/0069} {AI95-00166-01} The Exchange_Handler procedure operates in the same manner as Attach_Handler with the addition that the value returned in Old_Handler designates the previous treatment for the specified interrupt. If the previous treatment is not a user-defined handler, null is returned.

Ramification: Calling Attach_Handler or Exchange_Handler with this value for New_Handler restores the previous handler.

{8652/0069} {AI95-00166-01} If the application uses only parameterless procedures as handlers (other types of handlers may be provided by the implementation, but are not required by the standard), then if Old_Handler is not null, it may be called to execute the previous handler. This provides a way to cascade application interrupt handlers. However, the default handler cannot be cascaded this way (Old_Handler must be null for the default handler).

For all operations defined in this package that take a parameter of type Interrupt_Id, with the exception of Is_Reserved and Reference, a check is made that the specified interrupt is not reserved. Program_Error is raised if this check fails.

{AI05-0229-1} If, by using the Attach_Handler, Detach_Handler, or Exchange_Handler procedures, an attempt is made to detach a handler that was attached statically (using the aspect Attach_Handler), the handler is not detached and Program_Error is raised.

{AI95-00434-01} The Reference function returns a value of type System.Address that can be used to attach a task entry via an address clause (see J.7.1) to the interrupt specified by Interrupt. This function raises Program_Error if attaching task entries to interrupts (or to this particular interrupt) is not supported.

{AI05-0153-3} The function Get_CPU returns the processor on which the handler for Interrupt is executed. If the handler can execute on more than one processor the value System.Multiprocessors.Not_A_Specific_CPU is returned.

Implementation Requirements

At no time during attachment or exchange of handlers shall the current handler of the corresponding interrupt be undefined.

Documentation Requirements

{AI95-00434-01} {AI05-0229-1} {AI12-0320-1} {AI12-0444-1} The implementation shall document, when the Ceiling_Locking policy (see D.3) is in effect, the default ceiling priority assigned to a protected object that contains a protected procedure that specifies either the Attach_Handler or Interrupt_Handler aspects, but does not specify the Interrupt_Priority aspect. [This default can be different for different interrupts.]

Documentation Requirement: If the Ceiling_Locking policy is in effect, the default ceiling priority for a protected object that specifies an interrupt handler aspect.

Implementation Advice

If implementation-defined forms of interrupt handler procedures are supported, such as protected procedures with parameters, then for each such form of a handler, a type analogous to Parameterless_Handler should be specified in a child package of Interrupts, with the same operations as in the predefined package Interrupts.

Implementation Advice: If implementation-defined forms of interrupt handler procedures are supported, then for each such form of a handler, a type analogous to Parameterless_Handler should be specified in a child package of Interrupts, with the same operations as in the predefined package Interrupts.

NOTE The package Interrupts.Names contains implementation-defined names (and constant values) for the interrupts that are supported by the implementation.

Examples

{AI05-0229-1} {AI12-0178-1} Device_Priority : constant
  array (Ada.Interrupts.Interrupt_Id range 1..5) of
    System.Interrupt_Priority := ( ... );
protected type Device_Interface
  (Int_Id : Ada.Interrupts.Interrupt_Id)
     with Interrupt_Priority => Device_Priority(Int_Id) is
  procedure Handler
     with Attach_Handler => Int_Id;
  ...
end Device_Interface;
  ...
Device_1_Driver : Device_Interface(1);
  ...
Device_5_Driver : Device_Interface(5);
  ...

Wording Changes from Ada 95

{8652/0069} {AI95-00166-01} Corrigendum: Clarified that the value returned by Current_Handler and Exchange_Handler for the default treatment is null.

Incompatibilities With Ada 2005

{AI05-0167-1} Function Get_CPU is added to Interrupts. If Interrupts is referenced in a use_clause, and an entity E with a defining_identifier of Get_CPU is defined in a package that is also referenced in a use_clause, the entity E may no longer be use-visible, resulting in errors. This should be rare and is easily fixed if it does occur.

C.3.2 The Package Interrupts