annotate agent/src/os/win32/README.txt @ 0:a61af66fc99e

Initial load
author duke
date Sat, 01 Dec 2007 00:00:00 +0000
rev   line source
duke@0 1 This is a "Simple Windows Debug Server" written for the purpose of
duke@0 2 enabling the Serviceability Agent on Win32. It has backends both for
duke@0 3 Windows NT 4.0 (using internal Windows APIs for a few routines) as
duke@0 4 well as for 95/98/ME/2000 via the Tool Help APIs.
duke@0 5
duke@0 6 The reason this debug server is necessary is that the Win32 debug APIs
duke@0 7 by design tear down the target process when the debugger exits (see
duke@0 8 knowledge base article Q164205 on On Solaris, one
duke@0 9 can attach to and detach from a process with no effect; this is key to
duke@0 10 allowing dbx and gcore to work.
duke@0 11
duke@0 12 The Simple Windows Debug Server effectively implements attach/detach
duke@0 13 functionality for arbitrary debug clients. This allows the SA to
duke@0 14 attach non-destructively to a process, and will enable gcore for Win32
duke@0 15 to be written shortly. While the debugger (the "client" in all of the
duke@0 16 source code) is attached, the target process is suspended. (Note that
duke@0 17 the debug server could be extended to support resumption of the target
duke@0 18 process and transmission of debug events over to the debugger, but
duke@0 19 this has been left for the future.)
duke@0 20
duke@0 21 The makefile (type "nmake") builds two executables: SwDbgSrv.exe,
duke@0 22 which is the server process, and SwDbgSub.exe, which is forked by the
duke@0 23 server and should not be directly invoked by the user.
duke@0 24
duke@0 25 The intent is that these two executables can be installed into
duke@0 26 C:\WINNT\SYSTEM32 and SwDbgSrv installed to run as a service (on NT),
duke@0 27 for example using ServiceInstaller (
duke@0 28 However, SwDbgSrv can also be run from the command line. It generates
duke@0 29 no text output unless the source code is changed to enable debugging
duke@0 30 printouts. As long as any processes which have been attached to by the
duke@0 31 SA are alive, the SwDbgSrv and any forked SwDbgSub processes must be
duke@0 32 left running. Terminating them will cause termination of the target
duke@0 33 processes.
duke@0 34
duke@0 35 The debug server opens port 27000 and accepts incoming connections
duke@0 36 from localhost only. The security model assumes that if one can run a
duke@0 37 process on the given machine then one basically has access to most or
duke@0 38 all of the machine's facilities; this seems to be in line with the
duke@0 39 standard Windows security model. The protocol used is text-based, so
duke@0 40 one can debug the debug server using telnet. See README-commands.txt
duke@0 41 for documentation on the supported commands.
duke@0 42
duke@0 43 Testing indicates that the performance impact of attaching to a
duke@0 44 process (and therefore permanently attaching a debugger) is minimal.
duke@0 45 Some serious performance problems had been seen which ultimately
duke@0 46 appeared to be a lack of physical memory on the machine running the
duke@0 47 system.
duke@0 48
duke@0 49 Bugs:
duke@0 50
duke@0 51 This debug server is fundamentally incompatible with the Visual C++
duke@0 52 debugger. Once the debug server is used to attach to a process, the
duke@0 53 Visual C++ IDE will not be able to attach to the same process (even if
duke@0 54 the debug server is "detached" from that process). Note that this
duke@0 55 system is designed to work with the same primitives that C and C++
duke@0 56 debuggers use (like "symbol lookup" and "read from process memory")
duke@0 57 and exposes these primitives to Java, so in the long term we could
duke@0 58 solve this problem by implementing platform-specific debug symbol
duke@0 59 parsing and a platform-independent C++ debugger in Java.
duke@0 60
duke@0 61 Note:
duke@0 62
duke@0 63 The files IOBuf.cpp and IOBuf.hpp are also used in
duke@0 64 building src/os/solaris/agent.