TOC PREV NEXT INDEX DOC LIST MASTER INDEX



Signal/Interrupt Handling (Package V_Interrupts)

This chapter contains an overview of this package.followed by a detailed description of each subprogram in this package.

The following topics are covered in this section:


Package Overview

Description

The package V_Interrupts provides interrupt processing support for the user interface through user-defined interrupt service routines (Isrs).

Note: On your operating system, Interrupts are host OS signals and the interrupt status mask is the signal mask. The same package specification is used for both self-host and cross-target applications (this applies for all VADS Exec packages). This allows prototyping and testing of cross-target application code to take place on the host. Throughout, an interrupt or interrupt vector is a host OS signal and the interrupt status mask is the host OS signal mask.

The VADS Exec interface supports only signal handlers installed as an Isr with the Attach_Isr service. Alternatively, install signal handlers as a task interrupt entry. Avoid direct use of the host OS sigvec or signal services. Upon entry to an Isr, the program performs the following actions:

The Isr performs user-defined signal handling actions. (Floating-point operations cannot be executed within an Isr unless your host OS implementation saves and restores floating-point context for signals.) The Isr returns to enable VADS Exec to complete signal handling and restore the saved context.

A generic procedure Isr provides a wrapper for the signal handler. The procedure should be instantiated with a parameterless procedure that performs the user-defined signal handling actions.

Pass the address of the procedure created by the Isr instantiation to Attach_Isr to attach the interrupt service routine to the appropriate signal. The Isr is subsequently detached by a call to Detach_Isr.

Data References in Isrs

The user-defined interrupt handler must not reference non-local stack-relative data (including tasks declared within a subprogram). Instead, all references must be to objects declared in library-level package specifications or bodies, in the interrupt handler, or in subprograms called by the handler.

Exception Propagation in Isrs

Exceptions raised in an interrupt handler must be handled locally. Another exception handler should be provided to prevent attempting to propagate an exception from an interrupt handler. If you do not provide a handler for a raised exception (e.g., Numeric_Error), the entire program is abandoned.

Isr/Ada Task Interaction

An Isr executes in the context of the task it interrupted. Since the Isr does not have its own task state, it must not perform any Ada tasking operations that affect the state of the interrupted task. Consequently, these Ada operations cannot be performed from inside an Isr:

In addition, the Isr cannot invoke any VADS Exec service that might block the interrupted task

If the Isr attempts to call a service that would block, the Tasking_Error exception is raised.

The Isr may, however, invoke any nonblocking VADS Exec service, including these

Floating-point registers do not need to be saved before invoking VADS Exec services from an Isr.

VADS Exec tasking and interrupt services support preemptive task scheduling. If a call to VADS Exec service from an interrupt handler causes a task with a priority higher than that of the interrupted task to become ready to run, the higher-priority task runs immediately upon return from the outermost interrupt service routine.

If the Isr calls only the kernel service Isr_Enter and Isr_Complete, control is returned directly to the interrupted task.

Procedures and Functions

Table 1 lists the procedures and functions in package V_Interrupts with a brief description of each subprogram.

Table 1 Procedures and Functions
Name
Description
procedure/function Attach_Isr
Attach an interrupt service routine to a given interrupt vector and return the previously attached Isr
function Current_Interrupt_Status
Retrieve the current CPU interrupt status mask or priority level (This function is not supported.)
function Current_Supervisor_State
Return the supervisor/user state
function/procedure Detach_Isr
Detach an interrupt service routine from a given interrupt vector and return the previously attached Isr
procedure Enter_Supervisor_State
Enter the supervisor state for the current task, enabling execution of privileged instructions. (This procedure is not supported for native).
generic procedure Fast_Isr
Provide a faster version of the Isr. However, restrictions are imposed on the interrupt handler code
generic procedure Float_Wrapper
Save and restore the floating-point coprocessor. (This generic procedure is not supported for native; it raises a Tasking_Error exception).
function Get_Isr
Return address of currently attached Isr
function Get_Ivt
Return address of current Interrupt Vector Table (IVT)
generic procedure Isr
Provide the entry and exit code required of all interrupt service routines and perform all processing required upon entering and exiting an Isr
procedure Leave_Supervisor_State
Exit the supervisor state for the current task, disabling execution of privileged instructions (This procedure is not supported for native.)
generic procedure Mips_Isr - MIPS Only
Passes the vector id and exception frame parameters through to the instantiated Isr.
function Set_Interrupt_Status
Change the current interrupt status and return the previous interrupt status (This function is not supported.)
function Set_Supervisor_State
Set the supervisor/user state of the current task

Types

Table 2 lists the types in package V_Interrupts.

Table 2 Types
Name
Description
Vector_Id
Specifies the valid range for signal numbers
Interrupt_Status_T
Specifies the interrupt status

Constants

Table 3 lists the constants in package V_Interrupts.

Table 3 Constants
Name
Description
Disable_Interrupt
Passed to Set_Interrupt_Status to disable all interrupts
Enable_Interrupt
Passed to Set_Interrupt_Status to enable all interrupts

Exceptions

Table 4 lists the exceptions in package V_Interrupts.

Table 4 Exceptions
Name
Description
Invalid_Interrupt_Vector
The vector number passed to an operation is an invalid vector number
Unexpected_V_Interrupts_Error
An unexpected error occurs in a V_Interrupts routine
Vector_in_Use
You are attempting to attach an Isr to a vector already attached to an Isr

Package Specification

Note: Special cases and differences in the specifications for different targets are included in the descriptions of each procedure or function.

Example


Power Architecture for Apex Embedded using Rational Exec

For some processors a nested interrupt model with priorities is an integral part of the CPU(m68k supports an IPL range 0..7 and mips supports an interrupt mask). Because these are processor specific and not board specific it is possible to describe the interrupt status as part of the processor specific V_Interrupts package.

The Power processor architecture has a very simple internal interrupt model which only allows one level of interrupt using the MSR(EE) bit (all interrupts are either enabled or disabled). In the internal interrupt model the Interrupt_Status_T represents a single bit (the processors EE bit).

The kernel configuration also allows the use of an external interrupt controller. In this model masking/unmasking of interrupts is done with configuration code supplied in the kernel configuration (v_krn_conf). This allows external interrupts to be nested and masked by the user supplied kernel configuration.

The implementation of the external and internal controller models effects the following areas in the V_Interrupts package.

The internal or external interrupt model is selected in the kernel configuration using the following flags (cut/pasted from v_krn_conf.1.ada) If the INTR_PRIORITY_ENABLED flag is set to TRUE then the External model is being used.

By default the model for most Rational supported boards is to use the External Interrupt controller model thus allowing nesting of prioritized interrupts. The instruction set simulator configuration (issimppc_conf) uses the Internal model.

The values and meaning of the Interrupt_Status_T when using the external interrupt controller model cannot be known at the time that the rts_vads_exec.ss view is compiled. Instead it is up to the engineer that designs the interrupt controller software in the kernel configuration to make the values of Interrupt_Status_T available to the application programs. For the Rational Supplied board configurations these values are found in the board_common.ss subsystem in the io_conf.1.ada package. io_conf.ALL_INTR_MASK can be used instead of V_Interrupts.Disable_Interrupt.

Here is some example code that demonstrates the usage of Set_Interrupt_Status for the external interrupt controller model:


Procedures and Functions in Package V_Interrupts

procedure/function Attach_Isr

Syntax

Arguments

Description

procedure Attach_Isr is used to attach the ISR at isr to the interrupt vector indicated by vector.

function Attach_Isr attaches the Isr and returns the address of the previously attached Isr.

Exceptions

Threaded Runtime

Attach_Isr is layered on Ada_Krn_I.Isr_Attach.

function Current_Interrupt_Status

Syntax

Description

Current_Interrupt_Status returns the current CPU interrupt status mask or priority level.

Threaded Runtime

Current_Interrupt_Status is layered on Ada_Krn_I.Interrupts_Get_Status.


Warning: Current_Interrupt_Status is not supported for all systems.

function Current_Supervisor_State

Syntax

Description

Current_Supervisor_State returns the supervisor/user state of the current task. If the task is in supervisor state, True is returned. If the task is in user state, False is returned.

Threaded Runtime

Current_Supervisor_State is layered on Ada_Krn_I.Task_Get_Supervisor_State.

Note: Currently not supported by LynxOS, as such it always returns false.

function/procedure Detach_Isr

Syntax

Arguments

Description

procedure Detach_Isr detaches an interrupt routine from a specified interrupt vector. The attachment is performed during kernel initialization if the vector is given an initial value in the interrupt vector table.

(Embedded Only) The interrupt service routine V_Default_Isr defined in package V_Krn_Conf is attached to the vector.

The default handler is reinstated.

function Detach_Isr detaches the Isr and returns the address of the previously attached Isr.

Exceptions

Threaded Runtime

Detach_Isr is layered upon Ada_Krn_I.Isr_Detach.

procedure Enter_Supervisor_State


Warning: Enter_Supervisor_State is not supported for native, Tornado or LynxOS. Calls to this routine are silently ignored.

Syntax

Description

Enter_Supervisor_State enables you to enter the supervisor state for the current task. While in supervisor state, you can execute privileged instructions

(Embedded Only) If the configuration variable V_Krn_Conf.Supervisor_Tasks_Enabled is True, all tasks are in supervisor mode all the time. In this situation, the procedure Enter_Supervisor_State has no effect. For the MIPS, this call has no effect since all programs run in kernel mode.

Threaded Runtime

Enter_Supervisor_State is layered upon Ada_Krn_I.Task_Enter_Supervisor_State.

generic procedure Fast_Isr

Syntax

Description

The generic procedure Fast_Isr is instantiated with a parameterless procedure that provides the handler for a particular interrupt. The address of the resulting instantiation is passed to Attach_Isr to attach the interrupt service routine to a particular vector.

Fast_Isr is identical to the Isr generic.

Fast_Isr is provided only for compatibility with other targets. It is not faster than Isr.

Special Cases

Syntax for M68000 Family Targets

For M68000 Targets, procedure Interrupt_Handler has a single parameter.

generic procedure Float_Wrapper


Warning: Float_Wrapper is not supported for native or LynxOS.

Syntax

Description

Float_Wrapper saves and restores the floating-point state. Before procedure Float_Handler is called, the floating-point state is reset and float exceptions enabled according to the Floating_Point_Control parameter in the kernel program configuration package V_Krn_Conf. (This generic procedure is not supported; it raises a Tasking_Error exception).

Special Cases

Syntax for M68000 Family Targets

function Get_Isr

Syntax

Arguments

Description

function Get_Isr returns the address of the currently attached Isr for the given interrupt vector.

Exceptions

function Get_Ivt

Syntax

Description

function Get_Ivt returns the address of the current Interrupt Vector Table (IVT). Normally, the IVT is an array of Isr addresses. However, the IVT representation is CPU dependent.

generic procedure Isr

Syntax

Description

Isr provides the wrapper required for all interrupt service routines. It can be instantiated with a parameterless procedure that provides the handler for a particular interrupt. The address of the resulting instantiation is passed to Attach_Isr to attach the interrupt service routine to a particular vector.


Warning: This wrapper does not save/restore the floating-point context. The generic must be instantiated at the library package level.

Special Cases

Syntax for M68000 Family Targets

For M68000 Family targets, procedure Interrupt_Handler has a single parameter.

procedure Leave_Supervisor_State


Warning: Leave_Supervisor_State is not supported for native, Tornado, or LynxOS, calls to this routine are silently ignored.

Syntax

Description

Leave_Supervisor_State exits you from the supervisor state for the current task. After exiting the supervisor state, you can no longer execute privileged instructions. Any attempt to execute a privileged instruction when you are not in supervisor state causes a CPU exception.

If the configuration variable V_Krn_Conf.Supervisor_Tasks_Enabled is True, all tasks are in supervisor state all the time. In this situation, the procedure Leave_Supervisor_State has no effect. For the MIPS, this call has no effect since all programs run in kernel mode.

Threaded Runtime

Leave_Supervisor_State is layered on Ada_Krn_I.Task_Leave_Supervisor_State.

generic procedure Parameters_Isr - MIPS Only

Syntax

Arguments

Description

Parameters_Isr provides an alternative wrapper for interrupt service routines. This routine is specific to the MIPS architecture and passes the vector id and exception frame to the instantiated procedure which provides the handler for a particular interrupt. The address of the resulting instantiation should be passed to Attach_Isr to attach the interrupt service routine to a particular vector.

generic procedure Mips_Isr - MIPS Only

Syntax

Arguments

Description

Mips_Isr provides an alternative wrapper for interrupt service routines. This routine is specific to the MIPS architecture and passes the vector id and exception frame to the instantiated procedure which provides the handler for a particular interrupt. The address of the resulting instantiation should be passed to Attach_Isr to attach the interrupt service routine to a particular vector.


Warning: This wrapper doesn't save/restore the floating point context. This generic must be instantiated at the library package level.

function Set_Interrupt_Status

Syntax

Arguments

Description

The function Set_Interrupt_Status changes the setting of the interrupt status mask or priority and returns the previous interrupt status.

Threaded Runtime

Set_Interrupt_Status is layered on Ada_Krn_I.Interrupts_Set_Status.


Warning: Set_Interrupt_Status is not supported for native.

function Set_Supervisor_State


Warning: Set_Supervisor_State is not supported for native, Tornado, or LynxOS, calls to this routine always return false.

Syntax

Arguments

Description

The function Set_Supervisor_State changes the supervisor/user state for the current task. The previous state is returned.

Threaded Runtime

Set_Supervisor_State is layered on the following services in package Ada_Krn_I:


Rational Software Corporation 
http://www.rational.com
support@rational.com
techpubs@rational.com
Copyright © 1993-2003, Rational Software Corporation. All rights reserved.
TOC PREV NEXT INDEX DOC LIST MASTER INDEX TECHNOTES APEX TIPS