Controlling the System From the Debugging Console

Having set up the Kernel Debugger for a Local or Remote debug session the system is ready to be controlled from the debugging console. The console is used in two modes, which for convenience we refer to as:

Monitor mode, and

Command mode

In Monitor mode the console acts merely as a output device for displaying diagnostic messages from the debug kernel and debug versions any other of system modules that write messages to the debugger's COM port. In this mode it is not possible to enter Kernel Debugger commands without having first switched to command mode. In monitor mode the system runs more or less as a retail system except for the performance overheads imparted by the additional diagnostic code.

Monitor mode is in effect initially unless a KDB.INI file is defined.

The console switches to monitor mode after G command is executed.

In Command mode normal system execution is suspended. The debug component of the kernel monitors the debugging console for command input and indicates this with using one of the following command prompts:

>

Signifies that the system has been suspended while in real mode.

Signifies that the system has been suspended while in protect mode with paging disabled.

Signifies that the system has been suspended while in V86 mode with paging disabled.

Signifies that the system has been suspended while in protect mode with paging enabled.

Signifies that the system has been suspended while in V86 mode with paging enabled.

In addition to these prompts the Kernel Debugger also uses a data prompt when a commands require additional input. This is signified by a single colon prompt :. Commands such as R and E may use a data prompt.

Command mode is entered when one of the following events occur:

A fatal exception while executing in ring 0

Any unrecoverable exception occurring in a device driver, file system driver or the OS/2 kernel will result in a fatal error if it is allowed to be intercepted by the system exception handlers. When this occurs it is usually not possible to restore the system to a running state.

The VTF command may be used to intercept potentially fatal exceptions before the system's exception handlers receive control. If the exception condition is corrected manually then the system may continue to run after the G command is entered. See Trap and Exception Processing for further information.

Internal processing errors are unrecoverable conditions that are detected by the OS/2 kernel. Some of these are exceptions (described in the previous bullet); others are inconsistencies that arise from invalid logical conditions or invalid system data. Under the retail kernel IPEs result in the system halting. Under the debug kernel the console enters command mode after an error message is displayed. IPE messages may be suppressed from displaying as a hard error popups by setting the byte at symbol: fDebugOnly to a non-zero value. Under the debug kernel some IPEs are generated for recoverable conditions and allow the system to continue execution after the G command is entered. An example of a recoverable IPE is where the loader detects a bad or mismatched symbol file for a module it is loading. When this occurs the system displays message:

    Internal Symbol Error

Command mode is entered. If the G command is subsequently issued the system will be allowed to continue execution without the bad symbol file being activated.

Sticky breakpoints are set using the BP and BR commands. The system is may be returned to a running state after the G command is entered.

NMIs normally signal hardware error conditions. Under the RETAIL kernel these usually result in TRAP 2 fatal exceptions unless an NMI handler has been registered by a device driver. Under the debug kernel, unhandled NMIs cause control to be given to the debugging console from which it is possible to return the system to a running state using the G command.

NMIs are may be generated from several sources, which include:

Channel Check

This occurs when an I/O card activates the channel check signal.
Memory parity error
This occurs when memory capable of parity bit generation, detects a parity discrepancy as memory is fetched from RAM.
DMA bus time-out.
This occurs when a DMA-driven device uses the bus for longer than the maximum allowed period of 7.8 microseconds.
The watchdog timer interrupt.
This occurs when the NMI watchdog (NWD) is enabled and timer interrupts (IRQ 0) are disabled causing loss of timer ticks. OS/2 maintains an NWD count, which If exceeds a maximum value then an IPE is generated. Some hardware/BIOS also maintains an NWD counter, but the precise details of the NWD mechanism are machine specific. For some systems the NWD may not be supported. For further information refer to the appropriate hardware and BIOS reference literature for the machine type under consideration.
Unless the NMI is masked off using by setting mask bit 0x80 in I/O port 0x70, the NMI channel check provides a means of breaking into the system even when it is disabled for (maskable) interrupts, that is, when the CLI instruction has been used to clear the interrupt flag in the EFLAGS register. An an ISA-bus system a prototype card may be used to implement the following circuit, which provides an NMI push-button switch:

               (-IOCHK)
         A1  ────────────┐
                         │
                           ├─   (NMI Push switch)
                         │
         B1  ────────────┘
               (Ground)

Note:

OS/2 normally only disables NMIs during system initialisation and when the Kernel Debugger is running in command mode. However, the Kernel Debugger will allow only one attempt to break in using a channel check NMI, after which NMIs are disabled until the system is re-booted.

INT 3 instructions are used by the system to implement tracing (see The System Trace Facility) and software breakpoints. However any program may use INT 3 instructions freely under the Kernel Debugger to cause system execution to be suspended and the debugging console to switch to command mode.

Note:

Under the RETAIL kernel, INT 3 instructions other than those implemented by the system for tracing cause code to be terminated with a TRAP 3 exception.

Unless the system is in a disabled state, the user may type Ctrl-C from the debugging console at any time to cause immediate suspension of normal system execution and the console to switch to command mode.

If the r-key is held down at system initialisation time the debugging console will switch to command mode shortly after the OS2KRNL has entered real-mode for the first time. At this time no symbols have been loaded, paging has never been enabled and the KDB.INI file has not been processed.

Note:

In real-mode many of the Kernel Debugger external commands are not available (because the rely on Virtual Memory Management to be initialised). Attempts to use them may cause unpredictable results or even total system failure.

If the p-key is held down at system initialisation time the debugging console will switch to command mode shortly after the OS2KRNL has entered protect-mode for the first time. At this time no symbols have been loaded, paging is disabled and the KDB.INI file has not been processed.

If the space-bar is held down at system initialisation time the debugging console will switch to command mode shortly after the OS2KRNL has entered protect-mode and fully initialised. At this time OS2KRNL symbols have been loaded and paging is enabled but the KDB.INI file has not been processed.

If the KDB.INI file is present then the Kernel Debugger effectively enters command mode by executing Kernel Debugger commands from the KDB.INI file. After the last command is executed, the command prompt appears at the debugging console, unless that last command was a G command.