Trap and Exception Processing

The fine detail of exception management by OS/2 is complex. However the principles are easy to grasp. This section gives an overview of OS/2 Exception Management sufficient to provide the reader with a technique for intercepting exceptions in user code under the Kernel Debugger.

Exception Definition

Exceptions may be summarised as follows:

• Exceptions refer either to:

  Hardware Traps and Faults - INTEL defined.

  Software generated exceptions - OS/2 and User defined.

  
  Each Hardware Exception has an associated vector, which the processor uses to index the IDT to give control to the appropriate system exception handler.
  
  OS/2 Converts Traps and Faults to software exceptions. For example, traps 0xd and 0xe are converted to exception 0xc0000005.
  
  Software exceptions are generated from three sources:

  • Converted Hardware Traps and Faults.

  • Software Signals.

  • Software Exceptions from DosRaiseException.
  
  Exceptions occur for both normal and abnormal reasons. In the normal case additional processing is required to be executed in a manner transparent to the main line code. Examples of this are:

  Page fault exceptions.

  Trap 1 and 3 for system trace

  387 Co-processor emulation

  VDM privileged instruction emulation

  In the abnormal case, an error condition has been detected. If the error cannot be corrected then either a process or the system dies depending on whether the error can be isolated to a particular process. Usually traps and faults in ring 0 code result in system termination. Bad parameters passed in system APIs may cause the kernel to trap. The system recovers by directing an exception 0xc0000005 to a process. Unless the process can handle this exception, it dies.
  
  Full details of OS/2 defined exceptions are given in OS/2 System Exception Codes.

  Exception Logic

  The essential logic for exception handling is as follows:

  • If the processor generates a hardware exception then control is given to the first level exception handler pointed to by the IDT descriptor that corresponds to the hardware exception vector.

  • If the Kernel Debugger Vector Commands have been specified without the fatal flag then first level exception handlers have been replaced by the Kernel Debugger routines. These may give control to the debugging console or enter the normal system handlers if interception criteria are not satisfied.

  • The non-debugger first level routines perform any specific processing for the current exception, for example processing single step and breakpoint traps.

  • If full recovery is possible then the first level routines exit with an IRET instruction.

  • In most cases control passes from the first level trap handlers to TrapCommonFaultEntry. This performs common processing for all hardware exceptions. If recovery is possible, for example by satisfying a page fault or making a segment present, then this is done and control returned to the interrupted code.

    If recovery is not directly possible or further special processing is required then control passes to one of the following second level exception handlers:

    V8086 Emulation for instruction emulation.

    VDM Exception Handler to reflect non-fatal exceptions back to the VDM using its IDT.

    Process Fatal Fault Handler (_TRAPProcessFatalFault) for non-kernel mode code (InDos=0).

    Kernel Fault Handler for kernel code (InDos=1)

    Special handlers for Co-processor handling, NMIs etc..

    
    The Kernel Fault Handler checks for the presence of a local fault handler by inspecting TSDpfnFault. If this is non-zero then passes control to the local fault handler, otherwise it passes to the System Fatal Fault handler (SystemFatalFault).
    
    Ths System Fatal Fault handler will enter the Kernel Debugger (if in a non-RETAIL kernel), otherwise it will call and Device Drivers that have registered for notification of fatal system faults, then exit to the panic routine with a formatted message - usually the IPE trap screen. Once in panic the system will not dispatch any more threads. If TRAPDUMP or REIPL are specified then these are acted on otherwise the system waits to be re-booted.
    
    The Process Fatal Fault handler will check for fatal fault interception by the Kernel Debugger (VSF command) and enter the kernel debugger if interception criteria are satisfied. Otherwise user exception processing begins, if it is not possible to dispatch user exception handlers then DelayHardErr is called immediately to build the trap screen and wake the Hard Error process. Normally control passes to the _XCPTBuildR3DispatcherStack.
    
    _XCPTBuildR3DispatcherStack is entry-point for all kernel initiated exceptions to be sent to user. It is responsible for massaging the users stack so that when the kernel exits, control returns to the Exception Dispatcher (Dos32R3ExceptionDispatcher in DOSCALL1.DLL).

    The parameters to XCPTBuildR3DispatcherStack are:

    Trap number or 0x0000ffff for S/W generated exceptions Exception number
    Count of exception info parameters
    Pointer to the array of exception info parameters
    Boolean, if true then exception is non-contnueable.
    Pointer to any additional nested report record

    The parameters to Dos32R3ExceptionDispatcher are:

    Trap number
    Pointer to the exception report record
    Pointer to the exception context record

    If no exception registration records exist for the current thread then the thread enters termination and the Exception Dispatcher is not called.
    
    The Exception Dispatcher runs the chain of exception registration records, anchored from the TIB of the current thread. Each registered user exception handler is called in turn (via an intermediate routine, _xcptExecuteUserExceptionHandler). The return code (excetion disposition) passed back by the exception handler is examined. If it specifies XCPT_CONTINUE_EXECUTION then control returns to the kernel via Dos32ExceptionCallBack, whereupon the thread's stack is prepared for returning to the interrupted program. If XCPT_CONTINUE_SEARCH is specified then the next exception handler in the chain is dispatched. When the last exception handler has been dispatched (and all have returned XCPT_CONTINUE_SEARCH) then control passes to the kernel via Dos32ExceptionCallBack and the thread is terminated. XCPT_CONTINUE_STOP) may be returned by a debugger via DosDebug to indicate that debugger handler the exception and that exception handler scheduling should be halted immediately.

    The values for the various return codes are as follows:

    ┌───────────────────────┬──────────┬─────────────────────┐
    │Name                   │Bit Mask  │Description          │
    ├───────────────────────┼──────────┼─────────────────────┤
    │XCPT_CONTINUE_SEARCH   │0x00000000│Exception not handled│
    ├───────────────────────┼──────────┼─────────────────────┤
    │XCPT_CONTINUE_EXECUTION│0xFFFFFFFF│Exception handled    │
    ├───────────────────────┼──────────┼─────────────────────┤
    │XCPT_CONTINUE_STOP     │0x00716668│Exception handled by │
    │                       │          │debugger (via        │
    │                       │          │DosDebug)            │
    └───────────────────────┴──────────┴─────────────────────┘
    

    The following additional return codes are used by internal excfeption handlers to manage nested exceptions.

    ┌───────────────┬──────────┬────────────────────────────────────────┐
    │Name           │Bit Mask  │Description                             │
    ├───────────────┼──────────┼────────────────────────────────────────┤
    │NESTED         │0xf0f0f0f0│An exception occurred while an exception│
    │               │          │was active                              │
    ├───────────────┼──────────┼────────────────────────────────────────┤
    │COLLIDED_UNWIND│0x0f0f0f0f│Indicates collided unwinds              │
    ├───────────────┼──────────┼────────────────────────────────────────┤
    │EXIT_UNWIND    │0x65796C4B│Indicates the end of an exit unwind     │
    └───────────────┴──────────┴────────────────────────────────────────┘
    

    
    Dos32ExeptionCallBack is the kernel entry-point that is called after all user exception handlers have been called. It is passed the following parameters:

    Trap number
    Pointer to the exception report record
    Pointer to the exception context record
    Exception disposition

    This entry-point calls _xcptExceptionCallBack which either takes the default action according to the exception disposition and the exception type (fatal or non-fatal). The either user's context is retored from the exception context record or control passes to _xctDefaultAction. The latter action usually implies proces termination but also may result in a process or system dump being initiated.

    For fatal exceptions _xctDefaultAction. calls DelayHardError to format the trap screen information from the context record and wake the Hard Error process. It also writes the POPUPLOG.OS2 entry and calls the Kernel Debugger if the VSU command has been specified.

    
    Local Fault Handlers are exception handlers registered by kernel routines. Typically one is registered on entry to the kernel by an API call, and de-registered on exit. If a Local Fault Handler cannot resolve the fault then it will call panic if a serious system fault has occurred, or _XCPTBuildR3DispatcherStack if user code is at fault, for example when a bad parameter supplied to an API by an application program causes the kernel to trap.
    
    Multiple nested Local Exception Handlers may be registered. When the system calls a Local Exception Handler, the current handler deregisters itself and reinstates the previous nested handler. This is done by restoring the previous handler address from the top-most long-jump buffer saved in TSDpljmp and updating TSDpfnFault. The register values saved in the long-jump buffer are restore then then fault handler returns to the main-line code that registered. EAX is set by the fault handler to indicate that an error occurred. When no more local exception handlers are registed then TSDpfnFault. is zeroed, thereby de-registering all local exception handlers. Local Exception Handlers are always deregistered on exiting the kernel.
    
    The DosRaiseException API is called to create a user exception. This passes control to _xcptExceptionCallBack and normal user exception processing follows.

    These details are summarised in the following diagrams:

    Exception Registration Records

    OS/2 Exception Exception Management - Overview

    Exception Handler Stack Frames

    ---

    [Back: Kernel Debugger Breakpoints]
    [Next: Exception Registration Records]