HOWTO: Remotely Debug a Win32s Application using WinDBG

ID: Q133061

The information in this article applies to:

SUMMARY

Debugging Win32-based applications under Windows 3.1 with Win32s can be difficult because the debugging tools are complex and the procedure is not well documented. There are several choices in debugging a Win32s application that are listed in the following Knowledge Base article:

   ARTICLE ID: Q102430
   TITLE     : HOWTO: Debug 32-bit Applications under Win32s

This article describes one of the choices, namely how to remotely debug a Win32s application using the remote WinDbg tool (Wdbg32s.exe). Remote debugging requires two machines: a Win32s machine to run the Win32-based application and the remote debugger, Wdbg32s.exe and a Windows NT machine to run the WinDbg debugger.

Note that this method (remote debugging a Win32s application using WinDBG) only works with WinDBG that is included in the Win32 Software Development Kit (SDK) shipped with Windows NT version 3.51. The Win32 SDK that is shipped with Windows NT version 4.0 does not support remote debugging a Win32s application using WinDBG. This version of the SDK does not include the required Win32s components of WinDBG for remote debugging. In addition, future versions of the Win32 SDK will also not contain these components required for remotely debugging a Win32s application.

You can also remotely debug your Win32s application using the Remote Debug Monitor tool (Msvcmon.exe) that is only shipped with the Win32s files that are included with Visual 32-bit Edition versions 2.x, 4.0, and 4.1. For more information on this method, please refer to the following Knowledge Base article:

   ARTICLE ID: Q131058
   TITLE     : Tips for Remote Debugging with Visual C++ 2.x and 4.0

MORE INFORMATION

Preliminary Issues

First, before you start to remotely debug a Win32-based application under Win32s, make sure that it runs correctly under Windows NT and track down any problems using either the WinDbg or NTSD debugger that ships with the Win32 Software Development Kit (SDK) or the Visual C++ debugger. In addition, explore some of the other choices of debugging the Win32s application as described in the article referenced above. If none of these methods work for you, then you should remotely debug your application using the method described here.

Second, you must use a null modem (3-wire) cable to create a valid connection between the two machines (the host Windows NT machine and the target or remote Win32s machine) and make sure that the cable is set up exactly as specified in the Win32s Programmer's Reference.

Third, you must make sure you have a valid connection between the two machines you are using. One way you can test this functionality is by using the terminal emulator found in the Accessories group. If you can send text over the serial line then you have a valid connection. If you do not have a valid connection, make sure the correct COM ports are selected, and verify that the baud speed is the same on both machines.

Finally, for debugging with WinDBG, your Win32-based application and/or DLL must be built with certain compiler and linker switches so that debugging information is included. These switches can be found in the $(cdebug) and $(ldebug) macros, respectively, which are defined in Ntwin32.mak. It is also important to disable optimization with -Od or locals will not be available in the locals window and line numbers may not match the source. For more information on debugging with WinDBG, please refer to the following Knowledge Base article:

   ARTICLE ID: Q97908
   TITLE: Debugging DLLs Using WinDbg

Procedure for Remote Debugging

Note that remote debugging with WinDBG only works for serial transports. The following steps outline the procedure:

1. Make sure Win32s is installed correctly on the Windows 3.x machine.

2. Make sure you have the following files in your Window 3.x System

   subdirectory:

      Wdbg32s.exe
      Dm32s.dll
      Tlser32s.dll

   You can copy these files from the Microsoft Win32 Software Development
   Kit (SDK) or from your Windows NT machine if you have installed
   Windbg.exe from the Win32 SDK. Note the "s" in Tlser32s.dll and
   Dm32s.dll indicating that these files are for Win32s only (as opposed to
   Tlser32.dll and Dm32.dll which are for Windows NT only).

3. Place your Win32 executable with the debug information in a suitable
   directory on the Windows 3.x machine. Note the path to the executable
   because this information is used in step 4.

4. On your Windows NT machine, start the WinDBG debugger and click Open on
   the Program menu. Click New in the dialog box, and DO NOT BROWSE FOR
   THE FILE. In the Edit box, type the path that you noted in step 3.
   Windbg.exe needs the path of your remote executable because Windbg.exe
   looks for a remote executable.

5. Select the appropriate serial connection (for example, ser96 means use
   COM1 at 9600 baud). You can modify these parameters by clicking the
   Change button located at the bottom right of the dialog box. Refer to
   the documentation on Windbg debugger for more information on modifying
   the default COM port and baud rates.

6. Change the default transport DLL for WinDBG (typically, Tlser.dll)
   to Tlser32.dll since you are remotely debugging a Win32s application.
   To do this, click Change with the Transport Layer edit box highlighted.
   An edit box labeled PATH with the name of the DLL is displayed. Verify
   that this box contains Tlser32.dll.

7. WinDbg on Windows NT supports XON/XOFF (software) flow control. To
   enable XON/XOFF, you must specify the XON flag in the serial transport
   parameters on both WinDbg and remote WinDbg. Make sure to add XON to
   the end of the Parameters line: "COM1:19200 XON" in the Change dialog
   box above.

8. On the Windows 3.11 machine, start the remote WinDBG tool, Wdbg32s.exe
   and make sure the connection settings are the same as on the Windows NT
   side. Select Options to bring up the Transport dynamic-link library
   (DLL) dialog box and make sure that the transport DLL is Tlser32s.dll.
   Then choose the serial transport and other parameters.  Also, make sure
   to place the XON flag at the end of the Parameters box ("COM1:19200
   XON") similar to WinDBG on the Windows NT machine.

9. Click Connect on the remote WinDBG tool on the Widows 3.11 machine.
   The Connect option should be dimmed and the Disconnect menu option
   should be highlighted.

10. On your Windows NT machine, click Go on the Run menu. You can now
   start remotely debugging your Win32s application.

It is very important that both sides of the debugger use the same protocol. If they do not, both debuggers will probably hang. Also, the remote debugging environment requires that binaries be located on the same drive/directory on both the development and target systems. For example, if Win32app.exe is built from sources in a C:\Dev\Win32app directory, the binary should be located in this directory on both systems. If you build your source files by specifying fully qualified paths for the compiler, the compiler will place this information with the debug records which allows WinDbg to automatically locate the appropriate source files.

Additional query words: thunk tshoot trace windbg windbgrm wdbg dbwin

Keywords          : kbprg kbtool kbtshoot kbWin32s TlsDbg TlsDbgWin 
Version           : 1.25 1.3 1.3a 1.3c
Platform          : WINDOWS
Issue type        : kbhowto

Last Reviewed: October 12, 1997