wdbgrem.gml

开放源码的编译器open watcom 1.6.0版的源代码

.chap *refid=vidrem Remote Debugging
.*
.if &e'&dohelp eq 0 .do begin
.section Overview
.do end
.*
.np
.ix 'remote debugging'
.ix 'debugging' 'remote'
Remote debugging allows you to run the debugger on one side of a
communication link and the application being debugged on the other.
Remote debugging is required when there is not enough memory to run
both the debugger and the application on the same machine. Remote
debugging may also be required for debugging graphical applications.
.np
The DOS debugger runs in protected mode (above the 1M mark), with a
small memory footprint in the first 640k. Newer operating systems such
as OS/2 and Windows NT/9x have eliminated the 640k barrier, so there
is little need for remote debugging due to memory limitations alone.
However, remote debugging is often helpful when debugging graphical
or interactive application where the debugger interferes with the user
application.
Remote debugging is also required to debug Novell NetWare applications,
or specialized embedded systems that cannot run the entire debugger.
.np
There are many different communication links supported. Some
communicate between two machines. In this case an external
communication medium is used. Some links communicate between two
operating systems shells on the same machine. In either case, the
concepts are the same.
.np
While remote debugging, you may want to reference a file that is found
on one machine or the other. See the section entitled
:HDREF refid='rfxfile'. for details about remote and local file names.
.np
The debugger is broken down into 4 parts.
.begnote
.note The Debugger
This is the portion of the debugger that contains the user interface.
It is the largest part of the debugger.
Its name is either &dbgcmdup..EXE, &dbgcmdup.W.EXE or &dbgcmdup.C.EXE
.note The Debug Kernel
.ix 'debug kernel'
The debugger interprets your requests and sends low level requests to
the debug kernel. It is a small executable that is dynamically loaded
by the debugger or a remote debug server and used to control your
application. It can be called STD.TRP, STD.DLL, RSI.TRP or PLS.TRP
.note Remote Trap Files&mdash.
.ix 'remote trap files'
.ix 'trap file' 'remote'
These are versions of the debug kernel file that take requests and
send them across a communications link to a remote debug server. You
choose a trap file using the debugger's "trap" option.
.refalso comopt
Trap files have a 3 letter file name that represents the name of the
communications layer being used. The file extension is TRP or DLL.
.note Remote Debug Servers&mdash.
These executable files receive requests from a communications link and
pass them to a debug kernel. Remote debug server names all start with
???SERV. The first 3 letters represent the communication layer being
used and correspond to the trap file that is used on the other side of
the link.
.endnote
.np
In the following examples,
.millust begin
A>cmd1
B>cmd2
.millust end
.pc
indicates that
.monoon
cmd1
.monooff
is to be run on one machine and
.monoon
cmd2
.monooff
is to be run on the other.
.np
A normal non-remote debugging session just uses the user interface and
the debug kernel. All components run on the same machine. This simple
debugging session would be started with the command:
.millust begin
A>&dbgcmd. app

+-----------+ +----------+     +----------+
|  WD.EXE   | | STD.TRP  |     | APP.EXE  |
|          / /           |     |          |
|          \ \           |     |          |
|           | |          |     |          |
+-----------+ +----------+     +----------+
.millust end
.np
Debugging a Tenberry Software DOS/4GW (32-bit extended DOS)
application is the same except you must use a different trap file to
control the application.
.millust begin
A>&dbgcmd. /trap=rsi app

+-----------+ +----------+     +----------+
|  WD.EXE   | | RSI.TRP  |     | APP.EXE  |
|          / /           |     |          |
|          \ \           |     |          |
|           | |          |     |          |
+-----------+ +----------+     +----------+
.millust end
.np
A remote debugging session adds a remote debug server and a remote
trap file as well. For example, using the parallel port to debug
between two machines would be accomplished using the following
components:
.millust begin
A>parserv
B>&dbgcmd. /tr=par app

+-----------+ +----------+
|  WD.EXE   | | PAR.TRP  |
|          / /           |
|          \ \           |
|           | |          |
+-----------+ +----------+
                  |
   +-- parallel --+
   |   cable
   |
+-----------+ +----------+     +----------+
|  PARSERV  | | STD.TRP  |     | APP.EXE  |
|  .EXE    / /           |     |          |
|          \ \           |     |          |
|           | |          |     |          |
+-----------+ +----------+     +----------+
.millust end
.np
In order to start the above remote debugging session, you must follow
these steps.
.autopoint
.point
Connect the two machines with a parallel cable.
.refalso vidwire
.point
Start the remote debug server (PARSERV) on one machine.
.point
Start the debugger with the option "/trap=PAR" on the other machine.
This causes the debugger to load the remote trap file (PAR). This will
communicate across the remote link to PARSERV.EXE, which will in turn
communicate with the debug kernel (STD) in order to debug the
application.
.endpoint
.np
The rest of the debugger command line is identical to the command you
would type if you were debugging the application locally.
.np
You must start the remote debug server first. If you do not, the
remote trap file will not be able to establish a communication link
and the debugger will refuse to start.
.np
It is important to realize that the application to be debugged must
reside on the debug server machine.
It must be possible for the debug server to locate the application
to be debugged.  It can be in the current working directory of the
debugger server machine, or in the
.ev PATH,
or a path to locate the application on the debug server machine can
be specified on the debugger command line. Alternatively, you can ask
the debugger to download the application to the debug server machine
if the application resides on the debugger machine.
.millust begin
A>parserv
B>&dbgcmd. /down /tr=par app
.millust end
See the description of the "download" option in the
section entitled :HDREF refid='comopt'..
.np
If you are remote debugging a 32-bit application, you must
.bi use the correct trap file on the remote debug server side
of the link. The trap file specification must come first before any
other arguments on the command line.
.millust begin
A>serserv /tr=rsi
B>&dbgcmd. /tr=ser app

+-----------+ +----------+
|  WD.EXE   | | SER.TRP  |
|          / /           |
|          \ \           |
|           | |          |
+-----------+ +----------+
                  |
   +--- serial ---+
   |    cable
   |
+-----------+ +----------+     +----------+
|  SERSERV  | | RSI.TRP  |     | APP.EXE  |
|  .EXE    / /           |     |          |
|          \ \           |     |          |
|           | |          |     |          |
+-----------+ +----------+     +----------+
.millust end
.np
Following is an example of an internal remote link. This example shows
you how to use the OS/2 version of the debugger to debug a DOS
application.
.millust begin
+-----------+ +----------+
|  WD.EXE   | | NMP.DLL  |
|          / /           |
|          \ \           |
|           | |          |
+-----------+ +----------+
                     |
   +-- OS/2 NP API --+
   |
+-----------+ +----------+     +----------+
|  NMPSERV  | | STD.DLL  |     | APP.EXE  |
|  .EXE    / /           |     |          |
|          \ \           |     |          |
|           | |          |     |          |
+-----------+ +----------+     +----------+
.millust end
.np
The communication medium employed in this case is OS/2 Named Pipes.
.np
The debugger provides the following remote link capabilities:
.begnote
.note NOV
This link uses Novell's SPX layer for communication.
Supported under DOS, OS/2, Windows 3.x, Windows NT/2000/XP and NetWare.
.note NET
This link uses NetBIOS to communicate. If your network software
supports NetBIOS, you can use this link.
Supported under DOS, OS/2, Windows 3.x, and NetWare.
.note PAR
This link supports communication using the parallel or printer port.
Several different cable configurations are supported.
.refalso vidwire
Supported under DOS, OS/2, Windows 3.x, Windows 9x, Windows NT/2000/XP, NetWare, Linux and QNX 4.
.note SER
This link uses a serial port to communicate. Rates of up to 115K
BAUD are supported.
.refalso vidwire
Supported under DOS, OS/2, Windows 9x, Windows NT/2000/XP and QNX 4.
.note WIN
This link will communicate between two Windows DOS boxes.
Supported under Windows 3.x and Windows 9x (for DOS applications
only).
.note NMP
This link will use Named Pipes to communicate internally between OS/2
sessions. OS/2, DOS and Win-OS/2 sessions are supported. If your
network supports Named Pipes, and you have at least one OS/2 machine
on the network, you can communicate between OS/2, DOS and Windows 3.x
machines on the network.
Supported under OS/2 (DOS, OS/2 and Windows 3.x applications).
.note VDM
This link is a subset of the NMP link. It is supported under OS/2
and Windows NT.
The application being debugged must be a DOS or seamless Win-OS/2
application.
Supported under OS/2 and Windows NT (DOS, OS/2 and Windows 3.x
applications).
.note TCP
This link will use TCP/IP to communicate internally or over a network
between sessions.
Supported under DOS, OS/2, Windows 9x, Windows NT/2000/XP, Linux and QNX.
.endnote
.np
Communication parameters may be passed to the remote trap file and the
remote server. They are passed to the remote trap file by following
the name of the trap file with a semi-colon and the parameter. For
example:
.millust begin
A>serserv 2.4800
.millust end
.pc
passes the parameter 2.4800 to the remote debug server. To pass the
same parameter to the remote trap file, use:
.millust begin
B>&dbgcmd. /tr=ser;2.4800 app
.millust end
.np
These link parameters are specific to each remote link and are
described in the following section.
.np
.ix 'Once argument'
.ix 'remote debugging' 'Once argument'
Each of the debug servers can accept an optional "Once" parameter. The
"Once" parameter is used by the &wide.. Usually, a server stays
running until terminated by the user. If the "Once" option is
specified, the remote server will terminate itself as soon as the
debugger disconnects from it.
.*
.section Link Descriptions
.*
.np
The following communication links are described:
.begbull
.bull
:HDREF refid='remnov'.
.bull
:HDREF refid='remnet'.
.bull
:HDREF refid='rempar'.
.bull
:HDREF refid='remser'.
.bull
:HDREF refid='remwin'.
.bull
:HDREF refid='remnmp'.
.bull
:HDREF refid='remvdm'.
.bull
:HDREF refid='remtcp'.
.endbull
.*
.beglevel
.*