Jump to content

Debug Notifications

From EDM2
Revision as of 13:35, 10 March 2020 by Ak120 (talk | contribs)

DBG_N_ERROR

Debug Notification -1 - Error Notification

This notification returns:

  • Cmd= DBG_N_Error
  • Value= Any standard error code

An error was detected while attempting a DosDebug command.

Error codes are returned from DosDebug in different ways:

  1. Errors can be returned via the standard method (EAX = ERROR_CODE).
    This is only done when the DosDebug command failed to execute at all. An example of this would be ERROR_INTERRUPT when the debugger receives a signal. If DosDebug returns a nonzero value in the EAX register, the returned Debug buffer is invalid.
  2. Errors are also returned via the DBG_N_Error notification.
    This is used when the DosDebug command was attempted, but failed due to some internal DosDebug failure. Examples of error codes returned via this interface are ERROR_INVALID_PROCID and ERROR_INVALID_DATA. Generally, these errors are detected while in the context of the debuggee process, and may include ERROR_INTERRUPT.

DBG_N_Exception

Debug Notification -7 - General Exception Notification

This notification returns:

For the pre-first chance for a breakpoint exception:

  • Cmd= DBG_N_Exception
  • Value= 0 (DBG_X_PRE_FIRST_CHANCE)
  • Addr= Linear address of breakpoint
  • Buffer= Exception number (XCPT_BREAKPOINT) (0xC000009F)

For the pre-first chance for a single-step exception:

  • Cmd= DBG_N_Exception
  • Value= 0 (DBG_X_PRE_FIRST_CHANCE)
  • Addr= Linear address of instruction after Single Step
  • Buffer= Exception number (XCPT_SINGLE_STEP) (0xC00000A0)

For the first chance for all exceptions:

  • Cmd= DBG_N_Exception
  • Value= 1 (DBG_X_FIRST_CHANCE)
  • Addr= Linear address of exception
  • Buffer= Pointer to Exception Report Record in debuggee's context
  • Len= Pointer to Exception Context Record in debuggee's context

For the last chance for all exceptions:

  • Cmd= DBG_N_Exception
  • Value= 2 (DBG_X_LAST_CHANCE)
  • Addr= Linear address of exception
  • Buffer= Pointer to Exception Report Record in debuggee's context
  • Len= Pointer to Exception Context Record in debuggee's context

For an invalid stack notification:

  • Cmd= DBG_N_Exception
  • Value= 3 (DBG_X_STACK_INVALID)
  • Addr= Linear address of exception
  • Buffer= Exception number

The scenarios under which a debug exception is reported are pre-first, first, and last chance, and invalid stack notification. The Value field of the user debug buffer indicates the scenario.

DosDebug has detected an exception (a trap or a fault) at the specified address. The exception number in the exception structure identifies the exception that was detected.

Exception notifications are always returned from the context of the thread that detected the exception. That is, the exception structure reflects the state of the thread that caused the exception, at the time the exception was detected.

The debugger is given a maximum of two chances to handle exceptions other than single-step or breakpoint exceptions, which have a maximum of three chances. The order of operations for handling an exception is as follows:

  1. Debugger has the pre-first chance to handle the exception (for breakpoint and single-step exceptions).
  2. Debugger has the first chance to handle the exception, or to invoke an exception handler if it is present.
  3. Debugger has the last chance to handle the exception, or to invoke an exception handler if it is present.

An exception notification is returned for all exceptions, including those raised by the user via DosRaiseException.

An exception can have an informational, warning, or fatal severity. The severity is coded in the high-order three bits of the exception number for user-raised and system exceptions.

The debugger may dismiss the exception by returning XCPT_CONTINUE_EXECUTION, so that the user's context is restored, and execution continues at the point where the exception occurred. Otherwise, the debugger may return XCPT_CONTINUE_SEARCH. This causes the exception to be passed to the user's exception handlers (after the debugger's first chance), or causes the default action for the exception to occur (after the debugger's last chance).

For performance reasons, the single-step and breakpoint exceptions cause a "pre-first" notification. This is faster than the ordinary first exception notification. At the time of the notification, the debugger may decide if the single-step or breakpoint exception was an anticipated event. If it was anticipated, the debugger may return XCPT_CONTINUE_EXECUTION, as for an ordinary first notification. If it was not anticipated, the debugger may return XCPT_CONTINUE_SEARCH in order to raise an ordinary first notification for the single-step or breakpoint exception. With the second notification, this allows a maximum of three notifications for the single-step and breakpoint exceptions.

For breakpoint exceptions, the instruction pointer (EIP) of the debuggee is decremented to point to the breakpoint instruction.

Note
Do not confuse the family of floating point exceptions with the DBG_N_CoError error notification.
Restrictions
The error code may not be reliable in some situations for the page fault exception, due to hardware errors.

DBG_N_CoError

Debug Notification -9 - Coprocessor Error Notification

This notification returns:

  • Cmd= DBG_N_CoError
  • Value= Any standard Error Code

An error was detected while attempting a DosDebug command that attempted to access a Coprocessor.

DBG_N_CoError is similar to the DBG_N_Error notification, but is returned only after attempting an access to the coprocessor registers.

DBG_N_CoError is returned if any one of the following occurs:

  • The debuggee process is emulating the coprocessor.
  • The specified debuggee thread has not yet attempted to use the coprocessor.
  • The wrong coprocessor type is used.
  • The requested coprocessor type is not supported or available.

This notification should not be confused with any of the floating point exception notifications.

DBG_N_AsyncStop

Debug Notification -11 - Asynchronous Stop Notification

This notification returns:

  • Cmd= DBG_N_AsyncStop
  • Value= 0
  • Addr= 0

An Asynchronous Stop request has been detected.

The asynchronous stop command is used to get the attention of some debuggee thread, so that the debugger can again control the process. Because any notification results in the debuggee's coming under control of the debugger again, the asynchronous stop notification becomes redundant in that case, and is not returned.

The asynchronous stop request will be overridden and ignored if another notification can be performed instead, at the same time. An asynchronous stop notification never becomes a "pending" notification, in the sense that a library load notification becomes pending.

DBG_N_AliasFree

Debug Notification -13 - Alias Free Notification

This notification returns:

  • Cmd= DBG_N_AliasFree
  • Buffer= 32-bit offset to debugger alias region
  • Addr= 0

An object that contains an aliased region is about to be freed by the debuggee. This can also occur if the underlying memory object is about to be shrunk such that the alias would span memory outside the resultant object.

The alias region must be unmapped before the debugger may execute the debuggee again.

The DBG_C_UnMapAlias command is the proper response to an alias free notification.

If a debugger creates an alias to memory in another debugger, and that memory is itself an alias to the second debugger's debuggee, then the first debugger will not receive an alias free notification when the memory of the second debugger's debuggee is freed. The alias will be freed automatically. The second debugger will receive an alias free notification.

Retrieved from "https://www.edm2.com/index.php?title=Debug_Notifications&oldid=72657"