QLINK is a DOS linker and analysis tool designed to link together MS-DOS \n compatible .OBJ files. It can replace the MS-DOS LINK.EXE program \n when producing MS-DOS compatible .EXE and .COM files.
\n\nMake a directory (e.g., C:\\QLINK), copy the zip file to that \n directory, and unzip the files:
\n\nMD C:\\QLINK
\n CD C:\\QLINK
\n COPY A:\\QLINK.ZIP
\n PKUNZIP QLINK.ZIP
If you'll be running QLINK under Windows 3.1x (see below for Win95 instructions), \n copy the file WINDPMI.386 to your Windows system directory. \n For example, if you installed Windows into the directory C:\\WINDOWS, \n copy WINDPMI.386 to C:\\WINDOWS\\SYSTEM. Then edit \n your Windows SYSTEM.INI file to insert a line such as the following in \n the [386ENH] section:
\n\ndevice=windpmi.386
\n\nYou should first ensure that no other similar line already appears in \n your SYSTEM.INI file. For example, you might already have a line \n such as
\n\ndevice=c:\\bc4\\bin\\windpmi.386
\n\nIf this is the case, do not insert another call to the same driver; you \n need only one. This VxD does not work with Win9x.
\n\nIf you'll be running QLINK under Win9x, follow the above procedure using \n the file W95DPMI.386 instead of WINDPMI.386.
\n\nFor the most part, just call QLINK instead of LINK or TLINK as appropriate. \n Borland users should note that a number of Borland specific Object Module \n Formats (OMFs) are not implemented as yet (I'm waiting for the documentation \n from Borland). Several MS link switches are not supported as yet \n (e.g., /PACKC). If there are switches you particularly \n need which are not supported, let me know. For an explanation of \n the old linker switches, see your linker manual.
\n\nTo take advantage of the detailed error processing in QLINK, use the \n assembler switches which generate types and line numbers. For MASM \n and TASM these switches are /Zd and /Zi.
\n\nThe order in which segments appear in the executable file depends on \n several factors. The first is whether or not the /DOSSEG \n switch appears explicitly on the command line or implicitly in a OMF record \n in one of the .OBJ files.
\n\nIf /DOSSEG is specified, the segment order is as follows:
\n\nOtherwise, the segment order is as follows:
\n\nThere are a number of switches specific to QLINK which are documented \n in the file QLINK.CFG. These switches control the processing of \n error messages from QLINK. All error messages begin with either
\n\n==> WARN:
\n\nor
\n\n==> FAIL:
\n\nMessages which begin with WARN are warnings and do not halt \n the linker. Messages which being with FAIL cause the linker \n to stop immediately and not continue processing the input files.
\n\nIf an error message is followed by a name such as FIXOVF or \n GRPEXT0 in parentheses, then that error can be controlled by \n the switches /I:switch, /W:switch, and \n /F:switch, where switch is the name in parentheses \n in the error message.
\n\nIf you wish to ignore this error (meaning the linker takes a default \n action and continues processing), use /I:switch. \n To warn about an error (meaning an error message is displayed, the linker \n takes a default action, and continues processing), use /W:switch. \n The default settings for all error messages are described in the file \n QLINK.CFG.
\n\nThis same file (QLINK.CFG) is consulted when QLINK begins execution. \n Any switches found there (including switches such as /MAP, /LINE, \n etc.) are processed before the command line is parsed. Switches \n only may be contained in QLINK.CFG, not names of .OBJ files, etc. \n Even earlier in the process, the environment variable QLINK= \n is consulted, and it too may contain only switches.
\n\nThus the order of processing of switches is first, those contained in \n the environment variable QLINK=, then those in the file QLINK.CFG \n (first in the current directory, and if not found there in the directory \n from which QLINK is loaded), and finally those found on the command line \n to QLINK. Switches processed later in the sequence override ones \n processed earlier.
\n\nOccasionally, you want to link together .OBJ modules from different projects \n which use different naming conventions. For example, in one project \n code segments are in class CODE and in others they are in class \n PROG. Previously, you would have to edit the source code, \n make the changes, and re-compile. With the Name Substitution feature \n of QLINK, it's a snap.
\n\nTo substitute names on the fly within the .OBJ file, place the switch \n /NS before the reference to each .OBJ file whose names are to \n be substituted. For example, use /NS:PROG-CODE to tell \n QLINK that the name PROG is to be changed to CODE.
\n\nEach substitution is effective for all .OBJ files which appear after \n it until that substitution (or all substitutions) are halted. Use \n the form /NS:name to halt substitutions on name; \n use /NS with no arguments to halt all substitutions.
\n\nNote that this means that the occurrences of /NS are sensitive \n to the position and order in which they appear. Be sure to place \n occurrences of /NS before the reference to the .OBJ file \n to which they apply.
\n\nTo swap two symbols in the same file, use (say) /NS:A-B:B-A.
\n\nThe substitution is made on all references to the name regardless of \n context. Thus if you have a file with a segment named PROG \n and a class named PROG, substituting CODE for PROG \n changes both references.
\n\nThe full syntax is
\n\nNameset: (empty) \n ; Halt substitution on all names
\n | name \n ; Halt substitution on this name
\n | name \n '-' name \n ; Substitute the second name for the first name
Namedef: Nameset
\n | Namedef \n ':' Nameset
Switch: '/NS:' Namedef
\n\nThe keyword /NS may appear in the QLINK environment variable, \n the QLINK.CFG configuration file, the automatic response file, and the \n QLINK command line.
\n\n| Q: | \n\tWhen I link modules with the MS linker and QLINK, sometimes the \n\t executable files are of very different sizes? | \n
| A: | \n\tThis can occur if a .LIB is used to resolve external references. \n\t Because there is no rule as to the order in which external refs are \n\t processed, different ordering of these references mean that there \n\t can be different segment boundary alignments which can change the \n\t final executable file size. | \n
In no particular order of importance (nor of expectation of getting done), \n the following topics are on my list:
\nPlease feel free to add to this list.
\n\nPlease contact the author via Internet e-mail at
\n\n\n (Bob Smith)
\n\nQLINK is © Copyright 1994-2006 Qualitas, Inc. All rights reserved.
\n\n5.08 23 March 2006
\n\n5.07 2 January 2004
\n\n5.06 24 December 2003
\n\n5.05 19 June 2003
\n\n5.04 22 May 2003
\n\n5.03 21 July 2002
\n\n5.02 1 July 2002
\n\n5.01 26 June 2002
\n\n5.00 26 June 2002
\n\n1.30 22 June 2002
\n\n1.29 18 April 2002
\n\n1.28 25 April 2000
\n\n1.27 18 April 2000
\n\n1.26 10 April 2000
\n\n1.25 7 April 2000
\n\n1.24 4 April 2000
\n\n1.23 30 March 2000
\n\n1.22 30 March 2000
\n\n1.21 28 March 2000
\n\n1.20 24 March 2000
\n\n1.19 22 March 2000
\n\n1.18 15 March 2000
\n\n1.17 2 October 1999
\n\n1.16 8 September 1999
\n\n1.15 6 September 1999
\n\n1.14 3 September 1999
\n\n1.13 25 May 1999
\n\n1.12 16 May 1999
\n\n1.11 25 June 1998
\n\n1.10 27 April 1998
\n\n1.09 12 March 1998
\n\n1.08 12 November 1997
\n\n1.07 8 July 1997
\n\n1.06 25 June 1995
\n\n1.05 8 May 1995
\n\n1.04 25 March 1995
\n\n1.03 14 February 1995
\n\n1.02 18 November 1994
\n\n1.01 26 October 1994
\n\n1.00 2 October 1994
\n\nUse this program on an international keyboard to help the author of\n386SWAT support your keyboard.\n\n
First try out the program to see how it works (note Space bar to Exit). \nNext redirect the program's output to a file and type all keys (blindly).\n\n
Type every key on your keyboard except for function, arrow, and keypad\nkeys. Type every key in unshifted state as well as with the Shift-,\nControl-, and Alt-keys. If your keyboard distinguishes between the\nleft and right Shift-, Control-, and/or Alt-keys be sure to test all states\nfor all keys.\n\n
After exiting the program, annotate the output file with any comments\nyou consider appropriate. Finally, e-mail the file to the author\n(bsmith@sudleyplace.com).\n\n
For reference, supported international keyboard layouts include\n
| GR129 | \n\nGermany | \n
| SP172 | \n\nSpain | \n
| BE120 | \n\nBelgium | \n
| CF058 | \n\nCanada (French) | \n
| DK159 | \n\nDenmark | \n
| SU153 | \n\nFinland | \n
| FR120 | \n\nFrance | \n
| FR189 | \n\nFrance | \n
| IS197 | \n\nIceland | \n
| IT142 | \n\nItaly | \n
| LA171 | \n\nLatin America | \n
| NL143 | \n\nNetherlands | \n
| NO155 | \n\nNorway | \n
| PO163 | \n\nPortugal | \n
| SF150 | \n\nSwitzerland (French) | \n
| SG150 | \n\nSwitzerland (German) | \n
| TR179 | \n\nTurkey | \n
| UK166 | \n\nUnited Kingdom | \n
| YU234 | \n\nYugoslavia (Latin) | \n
| \n This protected mode debugger provides debugging services to real mode, \n protected mode, virtual 8086 mode programs, DPMI and VCPI clients, and \n Win 3.1x and Win95/98 programs under any memory manager while occupying \n only a few kilobytes of low DOS memory. \n It supports disassembly of the full 386, 387, 486, Pentium, and Pentium \n Pro CPU instruction sets through the Pentium MMX & SSE instructions. \n This debugger is also a Windows Kernel Debugger providing low-level Windows \n debugging services a la WDEB386, but residing in the same machine, so \n no COM port hookup is needed. To take advantage of this feature, you must \n have a separate video adapter (PCI or ISA monochrome) and matching monitor \n attached to your system. \n This program started out in early 1988 as an internal tool in Qualitas \n to help write and debug 386MAX, but has matured into a significant program \n in itself (the executable is over 400 KB generated from over 3MB of 386 \n assembly language source code). As it stands now, 386SWAT can debug almost \n any \n
Although 386SWAT was written to debug 386MAX, it can also intrude into \n the PL0 context of other memory managers as well so as to function as \n a PL0 debugger there. It also can debug programs remotely (over a modem) \n and can display source code instead of just disassembly instructions, \n along with many other features. \n I'd be interested in getting some feedback from you as to how useful \n 386SWAT is as well as how I can improve it.\n Questions or comments, please e-mail the author at bsmith@sudleyplace.com, \n or perhaps you'd like more detailed documentation, \n or just jump right in and download it.\n | \n \n \n \n | \n
\n \n\n\n" }, { "path": "swat/SWATAFLT.HTM", "content": "\n
\n \n \n \nHave you ever been puzzled by some CPU fault as to why it occurred,\nthat is, why did the CPU think there was a problem? If so, this feature\nis for you. Whenever 386SWAT is called on the difficult to figure\nout CPU faults (TSS Fault, Stack Fault, GP Fault, or Page Fault), the Autofault\nfeature attempts to determine why and to present a short prose description\nof the cause. The description is displayed in the lower lefthand\ncorner of the screen. Pressing a key causes the message to disappear. \nTo display it again (up to the time another fault occurs), press s-F4.\n\n
This feature is implemented for GP, TSS, and Page Faults, although they\nall could use more tweaking. \n\n\n" }, { "path": "swat/SWATBMRK.HTM", "content": "\n
\n \n \n \nAt times you need to browse through some code (sometimes it's even your\nown code) following subroutine calls, conditional jumps, etc. wherever\nthey might go. To make this task easier, use the s-F1\nand s-F2 keys. To disassemble at the target\nof some instruction which transfers control, place the instruction at the\ntop of the disassembly window and press s-F1. For example, say at offset\n1234 in the code segment there is a CALL\n5678. Place the CALL at the top\nof the disassembly window and press s-F1. The disassembly window now displays\nthe code at 5678 with an invisible bookmark\nleft at the calling address 1234. Each time\ns-F1 is used, it leaves a bookmark at the instruction at the top of the\ndisassembly window and disassembles at that instruction's target. To return\nto the previous bookmark, press s-F2. 386SWAT supports up to 128\nnested levels of such disassembly.\n\n
As another example, you should be able to disassemble almost any interrupt\n(say, U .VMI21 which disassembles at VM interrupt\n21h), and using the bookmark feature exclusively, go down to the bottom\nof the chain.\n\n
This feature is clever, but not that clever. It can figure out where\n(say)\n\n
JMP Dword Ptr CS:[1234]\n\n
is going and disassemble at that target, but it can't figure out the\nsame instruction with a DS override. Nor\ncan it handle effective addresses other than ones with an immediate displacement\nonly (i.e., no registers such as [BX+SI]). \n\n\n" }, { "path": "swat/SWATCMD.HTM", "content": "\n\n
\n \n \n \nA number of arithmetic, bitwise, and logical functions are available.\nThe precedence of evaluation is similar to that of the C programming language. \nHere they are, listed in order of precedence:\n
\n
| Functions | \n\nType | \n
|---|---|
| - ~ | \n\nMonadic | \n
| * / | \n\nDyadic | \n
| + - | \n\nDyadic | \n
| symbols, .code, .data,\netc. | \n\nAddress expression | \n
| : | | \n\nDyadic (address construction) | \n
| ] [ { | \n\nMonadic (extraction) | \n
| >> << | \n\nDyadic (bit shift) | \n
| < <= >= > | \n\nDyadic (relational) | \n
| == != | \n\nEquality | \n
| & | \n\nDyadic (bitwise AND) | \n
| ^ | \n\nDyadic (bitwise XOR) | \n
| && | \n\nDyadic (logical AND) | \n
| || | \n\nDyadic (logical OR) | \n
2a + 3 * {[.data+2|2c / 4 & ffff == 5af &&\n3 << bl || 21 ^ 2\n
is evaluated as\n
(((2a + (3 * ({([.data+2)|(2c / 4)))) & (ffff\n== 5af)) && (3 << bl)) || (21 ^ 2)\n
\n
\n
| BD | \nDisplay debug registers (also Alt-F9). | \n
| BD addr | \nSet DR breakpoint on instruction fetches at address addr. | \n
| BD addr LnI | \nSet DR breakpoint on I/O of length n (n=1 (byte), 2 (word), \n 4 (dword)) at I/O port addr. | \n
| BD addr LnR | \nSet DR breakpoint on read/writes of length n (n=1, 2, 4) \n at address addr. | \n
| BD addr LnW | \nSet DR breakpoint on writes of length n (n=1, 2, 4) at address \n addr. | \n
| BDn* | \nClear DRn. | \n
| BDn+ | \nEnable DRn. | \n
| BDn- | \nDisable DRn. | \n
| E addr\n[xx ...] | \n\nEnter data starting at addr using optional hex bytes xx. | \n
| DTE expr | \n\nDisplay the Descriptor Table Entry corresponding to the selector in\nexpr. | \n
| EXIT | \n\nExit to DOS. This command is equivalent to the following command sequence: \n R AH=4C\n | \n
| M addr Llen\naddr | \n\nMove data starting at first addr of length len to second\naddr | \n
| H exp | \n\nDisplay hex arithmetic result | \n
| G | \n\nGo without stopping (same as ESC) | \n
| G addr | \n\nGoto to instruction at address addr | \n
| GM bool_exp | \n\nGo monitor (single-step until bool_exp is TRUE) -- see Monitor\nMode | \n
| GM | \n\nGo monitor using last boolean expression specified with GM | \n
| MACBASE addr | \n\nSet the base address of the MAC chain in case it's different from .DMAC.\nThis is handy when displaying the DOS subsegment chain. | \n
| PTE addr\n PTE val | \n\nDisplay the Page Directory and Page Table entries which correspond\nto the address addr or linear address val. | \n
| SPTE addr/val | \n\nSame as PTE command, but also displays the matching PTE in the PTE\ndisplay screen (F5). | \n
| R reg[=]exp | \n\nSet register reg to exp. Valid registers include all\nGP and EGP as well as FL, EFL,\nCRn,\nDRn, TRn,\nTR,\nand LDTR. There are two ways to crash the\nsystem via this command: setting CR3 to a bad value, or setting EFL with\na bad value for the VM or IOPL flags. The code which sets CR0 forces the\nPage Enable and Protect Enable bits on (as evidenced by typing R\nCR0=0), so experiment without fear. Use the pseudo-register\nnames CSIP or CSEIP\nto set both registers to an address. | \n
| R reg.str[=]exp | \n\nThis command also supports bit mask qualifiers on registers. For example,\nto set the AM bit in CR0, type R CR0.AM=1.\nSee Register Mask Values for a complete list\nof mask values supported. | \n
| RC | \n\nClear saved register state so another RS\nmay execute. | \n
| RR | \n\nRestore saved registers. | \n
| RS | \n\nSave registers to restore later via RR.\nOnly one RS may be executed at a time without\neither restoring the state via RR or clearing\nthe state via RC. | \n
| S addr1 addr2 tgt\n S addr L\nlen tgt | \n\nSearch from addr1 to addr2 or from ea for len\nbytes\nfor target tgt. | \n
The target may take one of several forms:\n
* Use a target of the form xx, xxxx, xxxxxxxx where x represents a hex\ndigit to search for bytes, words, or dwords of a specified value. For example,\nthe form S 0:0 L FFFF 10CD searches for all\noccurrences of the hex bytes CD followed by 10 in the first 64KB of conventional\nmemory. Word and dword searches do not require word or dword alignment\nof the matching data. The number of digits entered determines the width\nof the value. Thus you should use leading zeros to pad out a small\nvalue to a wider width. For example, 0\nand 00 both search for a single byte of zeros,\n000\nand 0000 both search for a word of zeros,\nand 00000,\n000000,\n0000000, and 00000000\nall search for a dword of zeros.\n
* Use a target of the form \"search_string\" to search for a case sensitive\nstring. For example, S 0:0 L FFFF \"386MAX\"\nsearches for all occurrences of the string 386MAX in the first 64KB of\nconventional memory. The ability to search for a case insensitive string\nwill be added in the future.\n
* Use a target of the form !instr\nto search for a specific assembler instruction. For example, S\n0:0 L FFFF !INT 10 searches for all occurrences of video interrupts\nin the first 64KB of conventional memory. This target is found by disassembling\nthe code between the start and stop addresses instruction by instruction,\nthus the alignment of the matching instructions and the starting address\nis critical. If data appears within that range, some matches may be missed.\nThe command S1 (instead of S)\ncan be used to disassemble the code byte by byte. That is, with the S\ncommand, having disassembled an instruction which does not match the specified\npattern, the next instruction is searched; with the S1\ncommand, the next byte is searched. The code search text may include one\nor more question marks as wildcards which match any character in the disassembled\ninstructions. For example, use S 50|0 FFFF !mov e??,cr?\nto find all moves from a control register to a 32-bit register. Try the\nforms S 3BC7:100 FFFF !mov [1234] and S\n3BC7:100 FFFF !mov ?s:[1234] to find all moves into location\n[1234]\nwith or without a segment override. To find jumps to a specific location,\nuse the code targets !j? 1234, !j??\n1234, and !j??? 1234. Note that\nfloating point instructions may be disassembled beginning with either F\nor FN depending upon the presence of a preceding\nWAIT opcode (9Bh). To be safe, search for both.\n
* Use a target of the form #pte\nto search for a PTE in the Page Tables. For example, S\n0 C0000000 # CF4000 searches for the PTE CF4000\nfrom linear 0 through linear C0000000.\nThe linear addresses are both rounded down to a 4KB boundary. A match at\na particular linear address means that the PTE was found and it covers\nthe 4KB block at the linear address displayed. When comparing PTEs, the\nflag bits are ignored, thus a match might be found when the PTE in the\nPage Tables is not present.\n
\n
\n
| CD [d:][path]\n CHDIR [d:][path] | \n\nChange the current directory to path. If no argument, display the current\ndrive/directory. | \n
| FS | \n\nFlush symbol table. | \n
| LF filename | \n\nLoad file into browser. | \n
| LI + | \n\nEnable line number display in disassembly screen. | \n
| LI - | \n\nDisable line number display. | \n
| LI dddd | \n\nGo to line dddd (decimal) in file browser. | \n
| LI dddd+ | \n\nGo to line dddd forward from current line. | \n
| LI dddd- | \n\nGo to line dddd back from current line. | \n
| LS filename | \n\nLoad symbol file. | \n
| LS filename exp | \n\nLoad symbol file and add 16-bit value to all VM segments. | \n
| PATH d:\\dir1[,d:\\dir2[,...]] | \n\nSet source file search path. | \n
| PATH+ d:\\dira[,d:\\dirb[,...]] | \n\nAdd to source file search path. | \n
| PS r | \n\nSet range of symbol proximity searches to r. | \n
| PS r g | \n\nSet range r and granularity g (1=bytes,\n2=words,\n4=dwords) of symbol proximity searches. | \n
| QS addr | \n\nDisplay the symbol which is nearest to (and below) the given address. | \n
| SB+ | \n\nEnable source browser mode. | \n
| SB- | \n\nDisable source browser mode. | \n
| SB*+ | \n\nEnable source browser mode but disregard module names. | \n
| TS | \n\nForce all symbols to be retranslated according to current GDT and LDT. | \n
| TS sel | \n\nRetranslates only for selector/segment sel. | \n
| TS * ID | \n\nRetranslates for all selectors/segments with ID specified. | \n
| TS sel ID | \n\nRetranslates only for selector/segment sel with ID specified. | \n
| TS *|sel *|IDv|p | \n\nChange to specified mode for selector and/or ID specified. | \n
| TS *|sel *|ID\n*|v|p\nnsel | \n\nReplace segment/selector and mode for specified selectors and IDs.\nIf * is specified for mode, the mode is left\nalone. | \n
| TS *|sel *|ID\n*|v|p\nnsel+ | \n\nnsel is added to all specified segments. | \n
| APPKEY | \n\nEdit application keystroke buffer. This is primarily useful for remote\ndebugging. If an application is waiting for a keystroke, this feature allows\nyou to send one to the application, as well as to view any that may already\nbe available. | \n
| CHAT | \n\nEnter CHAT mode (also via Ctl-F8). | \n
| SETCOM port bps | \n\nInitialize specified serial port for communications. See SETCOM=\nprofile option for full syntax. | \n
| SETCOM | \n\nReinitialize the serial port with values last specified by SETCOM\nor SETCOM=.\nThis is useful when an application has reprogrammed the UART. | \n
| SETCOM - | \n\nIgnore all activity on serial port. Use this if you are done with remote\ndebugging and wish an application to have access to the serial port. When\n386SWAT is using the serial port, no serial port interrupts will be visible\nto virtual mode programs. | \n
| SETCOM RTS+ | \n\nPull RTS (Request To Send) line high. | \n
| SETCOM RTS- | \n\nDrop RTS (Request To Send) line low. | \n
| SETCOM DTR+ | \n\nPull DTR (Data Terminal Ready) line high. | \n
| SETCOM DTR- | \n\nDrop DTR (Data Terminal Ready) line low. This is one way to hang up\na modem that won't respond to (wait)+++ (wait)ATH(ENTER). | \n
| REMDBG | \n\nAttempt to establish remote debugging session (also via Ctl-F9).\nSee the section below on remote debugging. | \n
| VMSCOUNT=val | \n\nDon't intrude into the GDT/IDT for VCPI debugging until the value in\nthis counter has decremented to zero. This keyword is useful for occasions\nwhere the VCPI client shuffles its GDT and IDT around for a while before\ndeciding just where it's going to be. | \n
| VMSINT=ON|OFF | \n\nEnable (ON) or disable (OFF)\nVCPI debugging. Use this feature in cases where some VCPI programs misbehave\nwhen VCPI debugging is enabled. In this case, enable VCPI debugging only\nas necessary. | \n
| VMSINT=xx,xx,... | \n\nChange the default interrupts intercepted by 386SWAT when debugging\nVCPI clients. | \n
| BTF | \n\nDisplay Branch Trace Facility state (ON or OFF). | \n
| BTF ON|OFF | \n\nTurn Branch Trace Facility state ON or\nOFF. | \n
| LBR | \n\nDisplay Last Branch/Exception values on the command line. | \n
| LBR ON|OFF | \n\nTurn Last Branch/Exception window display ON\nor OFF. The four-line window displays the\nLast Branch From EIP, Last Branch To EIP, Last Exception From EIP, and\nLast Exception To EIP. Also, the keywords .LBRFR,\n.LBRTO,\n.LEXFR,\n.LEXTO\ncontain the value of the Last Branch/Exception From/To EIP in case these\nneed to be used in command line expressions (e.g., U\n.LBRFR). | \n
| IPF [/d]\n[/s] [/r] expr | \n\nIf Invalid Page Faults are being trapped by 386SWAT's VxD\n(see SWATVXD.DOC for more details), use the IPF\ncommand to control how these events are to be handled. The optional switch\n/d\ntells 386SWAT not to display a message on the mono screen describing this\nevent, /s tells 386SWAT not to stop when\nthis event occurs, /r tells 386SWAT to remove\nthis entry from its local tables, and expr is an expression which\nevaulates to a linear address corresponding to the Invalid Page Fault. | \n
| MDB expr | \n\nDisplay the memory which corresponds to the selector expr as\na Module Database. | \n
| SGH [/b|/s|/h|/o]\n[/c] expr | \n\nSearch through the Windows Global Heap for values. The expression\n(expr) entered is interpreted as a base address if /b\nis specified, size if /s, handle if /h,\nand owner if /h. If /c\nis specified, the search continues from the currently displayed entry;\notherwise, the search starts at the top of the heap. | \n
| TDB expr | \n\nDisplay the memory which corresponds to the selector expr as\na Task Database. | \n
| WKD [ON|OFF] | \n\nTurn ON or OFF\nKernel Debugging. This command cannot be used from within Windows. | \n
| WKD [QUIET|NOISY] | \n\nDisable (QUIET) or Enable\n(NOISY) reports on Parameter Errors. | \n
| WKD LOGERROR [ON|OFF] | \n\nTurn ON or OFF\nthe INT 01h trap of calls to LogError (). | \n
| WKD FAULT [ON|OFF|SKIP] | \n\nTurn ON, OFF,\nor SKIP once traps for Faults. | \n
There are a number of points in memory to which it is common to refer,\ne.g., the address of the instruction at the top of the disassembly window.\nThese references are made easier by using one of the following shortcuts\n(all of which can be used anywhere on the command line where an address\nis expected such as BD .CODE, or BD\n.DATA L4 W):\n
| .EA | \n\nEffective Address of the first (or only) operand to the instruction\nat the top of the disassembly window | \n
| .EA2 | \n\nEffective Address of the second operand to the instruction at the top\nof the disassembly window | \n
| .GDT | \n\nGDT base address (using selector zero) | \n
| .IDT | \n\nIDT base address (using selector zero) | \n
| .LDT | \n\nLDT base address (using selector zero) | \n
| .TSS | \n\nTSS base address (using selector zero) | \n
| .CMAC | \n\nSeg:Off of next C MAC entry -- equivalent to .DATA\n+ 2 + FFFE & [.DATA | \n
| .CODE | \n\ncurrent code display address | \n
| .CSIP | \n\ncurrent cs:[e]ip | \n
| .DATA | \n\ncurrent data display address | \n
| .DMAC | \n\nSeg:0 of first DOS MAC entry | \n
| .NMAC | \n\nSeg:0 of next DOS MAC entry -- equivalent to ((S..DATA)+1+[.DATA+3):0 | \n
| .LBRFR | \n\nEIP of Last Branch From | \n
| .LBRTO | \n\nEIP of Last Branch To | \n
| .LEXFR | \n\nEIP of Exception From | \n
| .LEXTO | \n\nEIP of Exception To | \n
| .MDB | \n\nBase address of the current Module Database (Windows only) | \n
| .PMIxx | \n\nSel|Off of PM Interrupt xxh | \n
| .RMIxx | \n\nSeg:Off of RM interrupt # xx | \n
| .TDB | \n\nBase address of the current Task Database (Windows only) | \n
| .VM | \n\nSel|Off of current Windows VM structure | \n
| .VMIxx | \n\nSeg:Off of VM interrupt # xx | \n
| .VMRET | \n\nReturn CS|EIP saved in .VMSTK at .VMSTK+50\n(DPMI fn 0300) or .VMSTK+150 (emulated INT) | \n
| .VMSTK | \n\nSel|Off of stack saved in .VM | \n
| .XBDA | \n\nSeg:Off of XBDA; same as ([40:0E):0 | \n
| .XBDA2 | \n\nSeg:Off of 2ndary XBDA; same as ((S..XBDA)+[.XBDA+B4):0 | \n
| Keyword | \n\nGrammar Equivalent | \n\nMeaning | \n
| .RETND | \n\n{LaSTK | \n\nNear dword | \n
| .RETNS | \n\n[LaSTK | \n\nNear word | \n
| .RETFD | \n\n:{LaSTK or |{LaSTK | \n\nFar word:dword or word|dword (depending upon the VM bit\nin the current EFL) | \n
| .RETFS | \n\n:[LaSTK or |[LaSTK | \n\nFar word:word or word|word (depending upon the VM bit in\nthe current EFL) | \n
| .RETN | \n\n.RETND or .RETNS | \n\nDepending upon the D-bit in CS | \n
| .RETF | \n\n.RETFD or .RETFS | \n\nDepending upon the D-bit in CS | \n
| .IRET | \n\n.RETF in VM \n .RETFD in PM | \n\nAlso allows mode switch from PM to VM by checking VM bit\nin EFL above return address | \n
No magic is invoked to extract the return address if data has been pushed\nonto the stack below the return address, so be sure that LaSTK points to\nthe actual return address.\n\n
Also note that the keystrokes A-F and\nA-N are defined as shortcuts for the commands\nG .RETF and G .RETN,\nrespectively. \n\n\n" }, { "path": "swat/SWATDEF.HTM", "content": "\n
\n \n \n \n\n
trapdiv ; Direct INT 00h\nto 386SWAT (Divide Overflow Fault)\n
trapnmi ; Direct INT 02h\nto 386SWAT (Non-maskable interrupt)\n
trapbound ; Direct INT 05h to 386SWAT\n(BOUND Fault)\n
trapinv ; Direct INT 06h\nto 386SWAT (Invalid Opcode Fault)\n
trapstack ; Direct INT 0Ch to 386SWAT\n(Stack Fault)\n\n
\n
; debug=caps ; Signal NMI if CapsLock pressed at startup\n
; debug=ibv ; Use Interrupt mask base Vector\nfor Ctrl-Alt-PAD5\n
; debug=int ; Signal INT 03h if CapsLock present\nat startup\n
; debug=pmi ; Signal INT 03h near end of INIT_PROT\n
; debug=trip ; Use triple fault method to reboot\n
; debug=vmi ; Signal INT 03h on entry to INIT_VIRT\n
; debug=wcb1 ; Signal INT 01h on WCB VM->RM\n\n\n\n"
},
{
"path": "swat/SWATDISP.HTM",
"content": "\n\n
The debugger presents its output on various display devices in various\ncontexts. Typically, it uses the primary display, but other options\nare possible. If you have a secondary display, such as a monochrome\nadapter/monitor or if you are running on a PCI system with a second PCI\nVGA adapter, 386SWAT can use those also.\n
If you have a monochrome adapter in your system, place the keyword MONO\nin your 386SWAT profile. The debugger determines whether or not your\nmonochrome adapter is always visible or is hidden by a PCI VGA card, even\nan AGP controller. In either case, 386SWAT ferrets out the adapter\nand displays its output there. Pressing Alt-F7\nswitches between the monochrome and color adapters.\n
If you have a secondary PCI VGA adapter in your system, place the keyword\nDVGA\nin your 386SWAT profile. The debugger displays its output on this\nscreen, even if it's hidden by an AGP controller. Pressing Alt-F7\nswitches between the two PCI VGA adapters.\n
I learned a bit about PCI programming getting the above to work, so\nI've gathered together assembler\ncode to demonstrate the techniques used for you to browse. Thanks\ngo to Dominik Behr, Federico Bianchi, Ralf Brown, and others for their\nhelpful suggestions and/or source code.\n\n\n" }, { "path": "swat/SWATDOC.HTM", "content": "\n\n
\n \n \nThis protected mode debugger when used in conjunction with 386MAX or\nany other memory manager provides debugging services to protected mode,\nvirtual 8086 mode programs, Windows 3.1x and Win95/98 programs, and DPMI\nand VCPI clients while occupying only a few kilobytes of conventional memory.\nIt supports disassembly of the full 386, 387, 486, Pentium, Pentium Pro\nthrough the Pentium 4 MMX & SSE instruction set. Note that all\nof this documentation is included in the download file in HTML format.\n
Installing 386SWAT -- getting it into your\nsystem\n
386SWAT Profile Options -- configuring it\n
Invoking The Debugger -- bringing it up\n
Monochrome and Dual PCI VGA Support -- displaying\nit\n
Debugging Aids in 386MAX -- in case you're\nrunning my favorite memory manager\n
Debugging Screen and Keystrokes -- what it\nlooks like and what you can type\n
Disassembly Bookmarks -- a feature for browsing\nthrough assembly code\n
Autofault -- a feature for understanding\nfaults\n
Windows Debugging -- how it works under Windows\n
Windows Kernel Debugging -- very low-level\ndebugging\n
Monitor mode -- conditional tracing\n
Command Line Actions -- built-in commands\n
Common Memory References -- dot commands\n
Register Mask Values -- bit mask modifiers\nfor registers\n
NDP Register Screen -- Numeric Data Processor\ndisplay\n
Remote debugging -- over a COM line\n
VCPI Program Debugging -- going where no debugger\nhad gone before\n
Wish List -- it'll never be finished\n
Version History -- what's been done\n
\n
Limitations\n
This program is very preliminary. It lacks many of the features of a\nfull-blown debugger. On the other hand, it has a few features they don't\nhave.\n
\n
Technical Support\n
Please send your problems, praises, and comments to bsmith@sudleyplace.com\n\n\n" }, { "path": "swat/SWATGRM.HTM", "content": "\n
\n \n \n \n// Command lines\n
APPKEY\n
BCx opt_addr \nx = {<empty>, *, +,\n-}\n
BD opt_addr\n
BD addr Ln\nR n\n= {<empty>, 1, 2,\n4}\n
BD addr Ln\nW n = {<empty>,\n1, 2, 4}\n
BDnx \nx = {*, +,\n-} n = {<empty>, 0,\n1, 2, 3}\n
BTF\n
BTF {ON|OFF}\n
CHAT\n
Dxy- \nx = {<empty>, b, d,\ng, i, t,\nt2, t3, v,\nw},\n
\ny = {<empty>, /n} where\nn is the data width\n
Dxy opt_addr \nx = {<empty>, b, d,\ng, i, t,\nt2, t3, v,\nw},\n
\ny = {<empty>, /n} where\nn is the data width\n
Dxy addr P \nx = {<empty>, b, d,\ng, i, t,\nt2, t3, v,\nw},\n
\ny = {<empty>, /n} where n is\nthe data width\n
Dxy addr P\nexp x =\n{<empty>, b, d,\ng, i, t,\nt2, t3, v,\nw},\n
\ny = {<empty>, /n} where\nn is the data width\n
DTE exp\n
E addr\n
E addr lvallist\n
EXIT\n
F addr\nL lval lval\n
F addr L\nlval lval P\n
F addr L\nlval lval P\nexp\n
FS\n
G opt_addr\n
GM opt_boolexp\n
H addr\n
Ix lval \nx = {<empty>, b, d,\nw}\n
IMR\n
INSERT gdtr idtr [cr3 [lapde]]\n
INSERT * idtr\n
IPF [/d]\n[/s] [/r] exp\n
IRR\n
ISR\n
LBR\n
LBR {ON|OFF}\n
LF filename\n
LI x \nx = {+, -}\n
LI dcon x \nx = {<empty>, +, -}\n
LS filename\nx x = {<empty>, lval}\n
M addr L\nlval addr\n
MACBASE addr\n
MDB exp\n
Ox lval lval \nx = {<empty>, b, d,\nw}\n
PATHx dirlist \nx = {<empty>, +}\n
PS lval x \nx = {<empty>, lval (<256)}\n
PTE addr\n
PTE exp\n
PTE addr P\nexp\n
PTE exp P\nexp\n
QS addr\n
R reg\n[=] exp\n
R reg.str\n[=] exp\n
REMDBG\n
RC\n
RR\n
RS\n
Sx addr L\nexp atom x = {<empty>,\n1}\n
Sx addr addr \natom x = {<empty>, 1}\n
S addr addr\n! instr\n
S addr L\nexp ! instr\n
S addr addr \n# exp\n
S addr L\nexp # exp\n
SBx \nx = {+, -}\n
SB*x \nx = {+, -}\n
SETCOM x \nx = {<empty>, -}\n
SETCOM port bps \nport = {1, 2,\n3, 4}\n
SETCOM xn \nx = {RTS, DTR} \nn = {+, -}\n
SGH [/b|/s|/h|/o|/n] \n[/c] exp\n
SIGINT lval\n
SPTE addr\n
SPTE exp\n
SPTE addr P\nexp\n
SPTE exp \nP exp\n
TDB exp\n
TOGINT lvallist\n
TS\n
TS opt_sel\nopt_group x opt_seln\nopt_addr\n
\nx = {<empty>, *, P,\nV} n = {<empty>, +,\n-}\n
Ux- \nx = {<empty>, 16, 32}\n
Ux opt_addr \nx = {<empty>, 16, 32}\n
Ux addr\nP \nx = {<empty>, 16, 32}\n
Ux addr\nP exp \nx = {<empty>, 16, 32}\n\n
VMSCOUNT xx\n
VMSINT {ON|OFF}\n
VMSINT=xx,xx,...\n\n
WKD FAULT [ON|OFF|SKIP]\n
WKD LOGERROR [ON|OFF]\n
WKD [ON|OFF]\n
WKD [QUIET|NOISY]\n
\n
\n
| lvallist | \n\nlval | \n
| \n\n | lval lvallist | \n
| opt_addr | \n\n<empty> | \n
| \n\n | addr | \n
| addr | \n\nexp | \n\nusing default segment/selector as per specific command | \n
| \n\n | ea | \n\n\n |
| opt_boolexp | \n\n<empty> | \n
| \n\n | exp | \n
| exp | \n\n( exp ) | \n\n\n |
| \n\n | mfn | \n\nmonadic functions | \n
| \n\n | dfn | \n\ndyadic functions | \n
| mfn | \n\natom | \n\n\n |
| \n\n | [ ea | \n\nextract word at effective address | \n
| \n\n | { ea | \n\nextract dword ... | \n
| \n\n | O.ea | \n\nextract offset from effective address | \n
| \n\n | S.ea | \n\nextract segment/selector ... | \n
| \n\n | L.ea | \n\nextract linear address ... | \n
| \n\n | P.ea | \n\nextract physical address ... | \n
| \n\n | +exp | \n\n\n |
| \n\n | -exp | \n\n\n |
| \n\n | ~exp | \n\n\n |
| lval | \n\natom | \n
| \n\n | ( exp ) | \n
| ea | \n\nseg : exp | \n\n\n |
| \n\n | sel | exp | \n\n\n |
| \n\n | .EA | \n\nEffective Address #1 (or the only one) | \n
| \n\n | .EA2 | \n\n... \n#2 | \n
| \n\n | .GDT | \n\nGDT base address (using selector zero) | \n
| \n\n | .IDT | \n\nIDT ... | \n
| \n\n | .LDT | \n\nLDT ... | \n
| \n\n | .TSS | \n\nTSS ... | \n
| \n\n | .CMAC | \n\naddress of next C MAC entry | \n
| \n\n | .CODE | \n\ncurrent code display address | \n
| \n\n | .CSIP | \n\naddress of current cs:[e]ip | \n
| \n\n | .DATA | \n\ncurrent data display address | \n
| \n\n | .DMAC | \n\nsegment of first DOS MAC entry | \n
| \n\n | .NMAC | \n\nsegment of next DOS MAC entry | \n
| \n\n | .PMIxx | \n\nSel|Off of PM Interrupt xxh | \n
| \n\n | .RMIxx | \n\nSeg:Off of RM interrupt xxh | \n
| \n\n | .VM | \n\nSel|Off of current Windows VM structure | \n
| \n\n | .VMIxx | \n\n... VM ... | \n
| \n\n | .VMRET | \n\nreturn cs|eip from Windows VM (|{.vmstk+50\nor |{.vmstk+150) | \n
| \n\n | .VMSTK | \n\ncurrent ss|esp saved in Windows VM structure\n(same as |{.vm+40) | \n
| \n\n | .IRET | \n\nfar word:dword return address on stack allowing a mode switch from\nPM to VM | \n
| \n\n | .RETN | \n\nnear word or dword return address on stack | \n
| \n\n | .RETND | \n\nnear dword return address on stack | \n
| \n\n | .RETNS | \n\nnear word return address on stack | \n
| \n\n | .RETF | \n\nfar word:word or word:dword return address on stack | \n
| \n\n | .RETFD | \n\nfar word:dword return address on stack | \n
| \n\n | .RETFS | \n\nfar word:word return address on stack | \n
| \n\n | .XBDA | \n\nSeg:Off of XBDA; same as ([40:0E):0 | \n
| \n\n | .XBDA2 | \n\nSeg:Off of 2ndary XBDA; same as ((S..XBDA)+[.XBDA+B4):0 | \n
| \n\n | dotcmd ? exp | \n\ndyadic functions on dot commands (.GDT,\n.IDT, etc.) where ? is a dyadic function | \n
| \n\n | :[ ea | \n\nextract word:word at effective address | \n
| \n\n | :{ ea | \n\nextract word:dword at effective address | \n
| \n\n | |[ ea | \n\n... word|word ... | \n
| \n\n | |{ ea | \n\n... word|dword ... | \n
| \n\n | |G ea | \n\n... ... in GDT-format (using selector zero) | \n
| \n\n | |I ea | \n\n... ... in IDT-format (using IDT selector) | \n
| \n\n | |L ea | \n\n... ... in LDT-format (same as GDT-format) | \n
| \n\n | |T ea | \n\n... ... in TSS-format (using CS|EIP) | \n
| \n\n | symbol | \n\neffective address of this symbol | \n
| dotcmd ? exp \n | \n\nS.dotcmd : O.dotcmd\n? exp | \n\nfor VM addresses | \n
| \n\n | S.dotcmd | O.dotcmd\n? exp | \n\nfor PM addresses \n where ? is a dyadic function | \n
| dfn | \n\natom | \n\n\n |
| \n\n | lval + exp | \n\naddition | \n
| \n\n | lval - exp | \n\nsubtraction | \n
| \n\n | lval * exp | \n\nmultiplication | \n
| \n\n | lval / exp | \n\ndivision (with truncation towards zero) | \n
| \n\n | lval &\nexp | \n\nbitwise AND | \n
| \n\n | lval ^ exp | \n\nbitwise XOR | \n
| \n\n | lval == exp | \n\nis equal (eq) | \n
| \n\n | lval != exp | \n\nis not equal (ne) | \n
| \n\n | lval < \nexp | \n\nis less than (lt) | \n
| \n\n | lval <=\nexp | \n\nlt or eq | \n
| \n\n | lval > \nexp | \n\nis greater than (gt) | \n
| \n\n | lval >= exp | \n\ngt or eq | \n
| \n\n | lval &&\nexp | \n\nlogical AND | \n
| \n\n | lval || exp | \n\nlogical OR | \n
| Operators | \n\nType | \n
| - ~ | \n\nMonadic | \n
| * / | \n\nDyadic | \n
| + - | \n\nDyadic | \n
| symbols, .code, .data,\netc. | \n\nAddress expression | \n
| : | | \n\nDyadic (address construction) | \n
| ] [ { | \n\nMonadic (extraction) | \n
| >> << | \n\nDyadic (bit shift) | \n
| < <= >= > | \n\nDyadic (relational) | \n
| == != | \n\nEquality | \n
| & | \n\nDyadic (bitwise AND) | \n
| ^ | \n\nDyadic (bitwise XOR) | \n
| && | \n\nDyadic (logical AND) | \n
| || | \n\nDyadic (logical OR) | \n
| seg | \n\nlval | \n
| sel | \n\nlval | \n
| opt_sel | \n\n<empty> | \n
| \n\n | * | \n
| \n\n | seg | \n
| \n\n | sel | \n
| opt_group | \n\n<empty> | \n
| \n\n | * | \n
| \n\n | con | \n
| atom | \n\ncon | \n
| \n\n | reg | \n
| \n\n | .LBRFR | \n
| \n\n | .LBRTO | \n
| \n\n | .LEXFR | \n
| \n\n | .LEXTO | \n
| reg | \n\nGP | \n\nAX, AL,\nAH, BX, ... | \n
| \n\n | EGP | \n\nEAX, EBX,\nECX, ... | \n
| \n\n | CRn | \n\nControl registers | \n
| \n\n | DRn | \n\nDebug registers | \n
| \n\n | TRn | \n\nTest registers | \n
| \n\n | Misc | \n\nIP, EIP,\nFL, EFL, TR,\nLDTR | \n
| con | \n\n<32-bit hex values> | \n
| dcon | \n\n<16-bit unsigned decimal values> | \n
| filename | \n\n<DOS pathname> | \n
| dirlist | \n\n<List of directory names separated by commas (,)> | \n
| bps | \n\n55 | \n
| \n\n | 110 | \n
| \n\n | 300 | \n
| \n\n | 600 | \n
| \n\n | 1200 | \n
| \n\n | 2400 | \n
| \n\n | 4800 | \n
| \n\n | 9600 | \n
| \n\n | 19200 | \n
| \n\n | 38400 | \n
| \n\n | 76800 | \n
| \n\n | 115200 | \n
Examples\n\n
* To display the successive entries in the DOS memory allocation chain,\ndisplay one such entry via a DB command. \nThen type\n\n
/D ((S..DATA)+1+[.DATA+3):0\n\n
Continuing to press Enter displays the successive MAC entries.\n\n
* To display the successive entries in the C memory allocation chain,\ndisplay one such entry (at the count word) via a DB\ncommand. Then type\n\n
/D .DATA + 2 + FFFE & [.DATA \n\n\n" }, { "path": "swat/SWATINST.HTM", "content": "\n
\n \n \n \nCreate a directory on your hard disk (say, C:\\386SWAT),\ncopy the ZIP file to that directory, and unzip it there. To unzip 386SWAT,\nuse\n\n
PKUNZIP 386SWAT\n\n
This debugger can be used in conjunction with any memory manager which\nsupports VCPI, or with just HIMEM.SYS.\n\n
To install 386SWAT, place the following line into your CONFIG.SYS file:\n\n
Device=d:\\path\\386SWAT.LOD\noptions\n\n
Place the Device= statement for 386SWAT\nimmediately following the Device= for the\nmemory manager (if any), or HIMEM.SYS if no memory manager is being used.\nd:\\path\\ represents the drive and path location of 386SWAT and options\nrepresents zero or more profile options.\n\n
As there are several options you may wish to use with 386SWAT, we recommend\nthat you put all 386SWAT keywords in a profile one keyword per line, and\npoint to the profile with the PRO=\noption on the 386SWAT.LOD line. For example,\n\n
Device=d:\\path\\386SWAT.LOD\nPRO=d:\\path\\386SWAT.PRO\n
\n\n\n"
},
{
"path": "swat/SWATINV.HTM",
"content": "\n
Generally, the debugger lies in the background waiting for some catastrophic\nevent to occur.\n\n
To bring up the debugger from the keyboard, press Ctl-Alt-Pad5. That\nis, with the Ctl- and Alt-keys held down, pressing the 5 key on the numeric\npad invokes the debugger. This mechanism is useful when your program is\nstuck somewhere. Remember, the keyboard and the keyboard interrupt must\nbe enabled for this to work. On systems for which the Pad5 key is inconvenient\nto use (such as some laptops), the sequence Ctl-Alt-SysReq also brings\nup the debugger.\n\n
It is also handy to install an NMI switch for when the system really\ngets locked up. Be sure to put the keyword TRAPNMI\nin the 386SWAT profile.\n\n
To run a particular program through the debugger, use the SWATRUN\nutility.\n\n
If remote debugging is active (see SETCOM\nprofile option and SETCOM\ncommand) the debugger may also be activated by sending SWT!\nfollowed by a break signal. This is done by pressing Ctl-6 in the CHAT\nscreen.\n\n
The utility SWATCMD\n(loaded via Device= or from the DOS command\nline) may be used to pass commands to 386SWAT. Invoking SWATCMD\nwith no options brings up 386SWAT at an INT 03h (assuming TRAPSKIP\nor TRAPDEBUG\nis active).\n\n\n\n" }, { "path": "swat/SWATMAX.HTM", "content": "\n
\n \n \n \nThe following options are recognized by 386MAX and may be useful in\nconjunction with 386SWAT. These options should be placed in your 386MAX\nprofile.\n\n
To catch even-value stack wraps, use DEBUG=NOWRAP.\nThis situation occurs when an interrupt is encountered with SP = 2 or 4.\nIn this case, the 386 will push the three words onto the stack and wrap\nto the end of the stack segment leaving SP = FFFC or FFFE. Quite likely,\nthis is an error as most stack segments aren't meant to be 64 KB in length.\nTechnically, this event is not an error as far as the 386 is concerned,\nbut logically it almost always is an error. The default behavior of 386MAX\nis to emulate the behavior of the CPU and not signal an error; the DEBUG=NOWRAP\nkeyword tells 386MAX to trap this case.\n\n
To catch writes into unmapped EMS pages, use DEBUG=EMSWRIT.\nThis option traps with a Page Fault attempts to write into unmapped EMS\npages as well as after a Save Page Map call. The latter is presumed to\nhave been done by a memory-resident program prior to mapping in its own\npages. To catch reads and/or writes in unmapped EMS pages, use DEBUG=EMSRDWR.\nTo catch an EMS bug in MS-DOS 4.0x, try this latter option with BUFFERS\nin EMS memory.\n\n
To catch unemulated Invalid Opcodes, use DEBUG=I06.\n\n
To signal an INT 01h on each DPMI error, use DEBUG=DPMIERR.\n\n
To force a new selector on all selector allocates, use DEBUG=DPMINEWSEL.\nThis option is useful if your code has a stale selector, that is, you allocate\na selector and tuck it away for later use, but then, before its last reference,\nyou free it and allocate another selector. Without this option you might\nget the old selector number (the one you just freed). When the stale selector\nis used, it might not generate an error, but surely it won't do what you\nexpected.\n\n\n\n" }, { "path": "swat/SWATMON.HTM", "content": "\n
\n \n \n \nThe GM (go monitor) command takes an expression\nwhich will be evaluated as the CPU single-steps (equivalent to Padplus\nor F11). No display will occur until\n\n
1) the monitor expression evaluates TRUE, or\n
2) 386SWAT is invoked by some other means (GP fault, NMI, Ctrl-Alt-Pad5,\netc.)\n\n
Boolean expressions may be constructed using the dyadic functions &&,\n||, <, <=,\n==, >=, and\n>. Function precedence is the same as the\nC language. See Command Line Actions.\n\n
For example:\n\n
gm ah\n
will execute until AH is non-zero.\n\n
gm [.csip == 21cd && ah!=9\n
will execute until the current instruction is INT 21 and AH\nis any value other than 9 (DOS display string).\n\n
gm cx == 0\n
will execute until CX is 0.\n\n
gm\n
will execute until the last expression specified with gm\nis TRUE.\n\n\n\n"
},
{
"path": "swat/SWATNDP.HTM",
"content": "\n
This feature is preliminary, but it does allow you to move through the\nNumeric Data Processor (NDP) registers and settings and change them at\nwill. Lacking is an exact binary to decimal conversion algorithm\nas well as a decimal to binary conversion algorithm. This screen\ncan be displayed and cleared via Alt-F8.\n\n\n\n" }, { "path": "swat/SWATPRO.HTM", "content": "\n
\n \n \n \nThe following profile options are recognized by 386SWAT. Options\nmay be entered in upper and/or lower case. See the file 386SWAT\nfor a list you can use already in profile format.\n
\n
| [section name] | \n\nFor versions of DOS which support MultiConfig, this option\nlimits profile processing to the matching MultiConfig section in CONFIG.SYS. | \n||||||||||||||||||||||||
| ADDRHBITS=n | \n\nBits to use for address hashing (8-12;\ndefault 12). See SWATSYM.DOC. | \n||||||||||||||||||||||||
| ALTSCR | \n\nDisplay debugging information on the screen other than the\ncurrent one being used. That is, in a two monitor system, if the current\nscreen uses the color adapter, display debugging data on the monochrome\nscreen and vice versa. This option is valid only if we detect that there\nare both a color and monochrome adapter in the system. Otherwise, it is\nignored. Note that the screens can be swapped via Alt-F7.\nAn alias for this option is /A. | \n||||||||||||||||||||||||
| BUCKETS=n | \n\nSpecify the number of name hashing blocks to allocate (about\n1K each). See SWATSYM.DOC. | \n||||||||||||||||||||||||
| CMDHIST=nnn | \n\nSpecify the size of the command history buffer used by command\nlie recall. Default is 1024. | \n||||||||||||||||||||||||
| COLDBOOT | \n\nDon't write 1234h to warm\nboot flag location when rebooting system from within 386SWAT. | \n||||||||||||||||||||||||
| DEBUG=TRIP | \n\nUse triple fault method of rebooting. Sometimes a system\ndoesn't reboot when using the 8042 method (the default), so here's another\nway to skin the cat. | \n||||||||||||||||||||||||
| DVGA | \n\nUse a Dual VGA screen as the secondary monitor. | \n||||||||||||||||||||||||
| GPSKIP=key[,key] | \n\nIf a GP Fault occurs on any of the instructions named in\nthe list, do not signal this to 386SWAT. This option allows you to trap\nGP Faults but filter out ones which may commonly occur but not be of interest.\nThe key values (GP Skip instructions) supported are \n
| \n||||||||||||||||||||||||
| INTRUDE | \n\nAttempt to intrude into another memory manager's PL0 context.\nIf this is successful, 386SWAT appears as a PL0 debugger in the context\nof the memory manager. This option is now the default. To disable this\noption, use VCPISWAT. | \n||||||||||||||||||||||||
| KEYB=cclay | \n\nUse international keyboard whose country code/layout is\ncclay. Possible values are \n
| \n||||||||||||||||||||||||
| LCD | \n\nSpecify that an LCD screen is present (and 386SWAT uses\nthe LCD screen attributes). Does anyone know how to detect this case under\nprogram control? I would prefer not to require the user to tell us what\nthe screen is like. | \n||||||||||||||||||||||||
| LOADLOW | \n\nTell 386MAX it's not OK to load us into extended memory\nafter INIT_REAL and to relocate our INIT_VIRT code. It's highly unlikely\nyou'll need this option. | \n||||||||||||||||||||||||
| LOADSYM=filename\n[optional] | \n\nLoad specified symbol file with optional arguments: \n
| \n||||||||||||||||||||||||
| LOGSIZE=nnnnn | \n\nDefine size of error log in bytes. Default is 4096. | \n||||||||||||||||||||||||
| MONO | \n\nUse monochrome adapter if present. | \n||||||||||||||||||||||||
| NOGD | \n\nBecause some programs may reset the debug registers which\nyou've carefully setup, 386SWAT automatically sets the Global Debug (GD)\nbit in DR7 on startup so that we can stop such programs before they can\ndo any harm. In case you don't want 386SWAT to do this, use this keyword. | \n||||||||||||||||||||||||
| NORMLIDT | \n\nDisable Real Mode LIDT redirection. Device 386SWAT uses\na separate IDT to handle nasty bugs which write into the Real Mode IDT\nat 0:0 such as DOS 6.x does during its transient CONFIG.SYS processing.\nThis is the default state. Use RMLIDT\nto find this kind of bug. | \n||||||||||||||||||||||||
| NOSWAP | \n\nDon't restore the previous underlying screen when single-stepping.\nThis option is useful in conjunction with the ALTSCR\noption. This option specifies the initial state only. It can be toggled\nvia Alt-F6. | \n||||||||||||||||||||||||
| NOWINK | \n\nDisable Windows Kernel Debugging. | \n||||||||||||||||||||||||
| PASSTHROUGH=xx,xx,xx,... | \n\nAllow one or more hardware interrupts to be passed through\nto the previous protected mode handler while 386SWAT is active. Currently,\nthese are limited to 76, 77,\n0B, and 0C.\nTHIS OPTION SHOULD NOT BE USED UNLESS NECESSARY. For example, when the\nIBM PS/2 SCSI adapter (8EFE or 8EFF) is used, staying in 386SWAT for more\nthan 1 or 2 minutes will cause the hard disk to lock on the next disk access.\nPASSTHROUGH=76 will allow one to stay in\n386SWAT indefinitely. | \n||||||||||||||||||||||||
| PATH=d:\\dir1[,d:\\dir2[,...]] | \n\nSpecify source file search path (see SWATSYM.DOC). | \n||||||||||||||||||||||||
| PORTINIT=string | \n\nInitialize serial port. String may contain any character\nexcept semicolon, including the following escape sequences: \n
| \n||||||||||||||||||||||||
| PRO=d:\\path\\filename.ext | \n\nRead subsequent command line options from a profile. Just\nas with 386MAX, as you append more and more options to the 386SWAT command\nline, you may prefer to collect them all in a 386SWAT profile, one per\nline. These options may be followed by a semicolon and a comment. This\nprofile is handled exactly the same way as is the corresponding profile\nfor 386MAX. | \n||||||||||||||||||||||||
| PROXSRCH=r[,g] | \n\nSet range and granularity for proximity searching on symbol\naddresses. See SWATSYM.DOC. | \n||||||||||||||||||||||||
| PS4=xxxx | \n\nPeriscope 4 hardware debugger board is installed at I/O\nport xxxx (for reference, the factory setting is 300h). This feature\nallows 386SWAT to manage the traceback buffer and other features of the\nPeriscope Company's 386 hardware debugger. *NOTE* this feature isn't finished. | \n||||||||||||||||||||||||
| RMLIDT | \n\nEnable Real Mode LIDT redirection. Device 386SWAT uses a\nseparate IDT to handle nasty bugs which write into the Real Mode IDT at\n0:0 such as DOS 6.x does during its transient CONFIG.SYS processing. | \n||||||||||||||||||||||||
| SAVESCREEN=nnn | \n\nSpecify the number of last screens to save. This keyword\nallows you to control how many screens back Alt-F10\ncan display. The default is sixteen. Each screen consumes 4000 bytes of\nstorage in extended memory. | \n||||||||||||||||||||||||
| SETCOM=port,bps[,itype[,portbase]] | \n\nSpecify port to use for remote debugging. \n
| \n||||||||||||||||||||||||
| SYMFILTER=text1\n[text2 [...]] | \n\nSome symbols, especially from Windows programs written in\nC, are prefaced with text such as \"__imp__\",\n\"_\", and the like which adds to the symbol's\nlength but not understanding. This feature allows you to specify in the\n386SWAT profile leading text which is to be stripped from each symbol. \n\n The default settings are \n\n SYMFILTER=__imp__ _ \n\n Up to 128 characters can be specified in this way. | \n||||||||||||||||||||||||
| SYMSIZE=nnnnn | \n\nSpecify the number of bytes to reserve for the symbol table.\nThe default size is 4096. See SWATSYM.DOC. | \n||||||||||||||||||||||||
| TRAPBOUND | \n\nTrap BOUND instruction interrupts, ignoring INT 05h. | \n||||||||||||||||||||||||
| TRAPDEBUG | \n\nIntercept INT 01h/03h at installation time. Normally, 386MAX\ndirects protected mode occurrences of INT 01h/03h to 386SWAT and real mode\noccurrences to the real IDT handler. This options causes all such interrupts\nto be handled by 386SWAT. This feature may be toggled via Alt-F1. | \n||||||||||||||||||||||||
| TRAPDIV | \n\nTrap divide overflow interrupts. | \n||||||||||||||||||||||||
| TRAPGENP | \n\nTrap General Protection Faults (toggle via Alt-F3). | \n||||||||||||||||||||||||
| TRAPINV | \n\nTrap Invalid Opcode interrupts (toggle via Ctl-F3). | \n||||||||||||||||||||||||
| TRAPNMI | \n\nTrap Non-Maskable Interrupts. This option is useful in conjunction\nwith a hardware breakout switch which can be used to invoke the debugger\neven if all interrupts are disabled (toggle via Alt-F2). | \n||||||||||||||||||||||||
| TRAPPAGE | \n\nTrap Page Faults (toggle via Alt-F4). | \n||||||||||||||||||||||||
| TRAPSEGNP | \n\nTrap Segment Not Present Faults. | \n||||||||||||||||||||||||
| TRAPSKIP | \n\nTrap INT 03h instructions (toggle via Ctl-F2). | \n||||||||||||||||||||||||
| TRAPSTACK | \n\nTrap Stack Faults (toggle via Ctl-F4). | \n||||||||||||||||||||||||
| TRAPSTEP | \n\nTrap INT 01h breakpoints (toggle via Ctl-F1). | \n||||||||||||||||||||||||
| TRAPTSS | \n\nTrap TSS Faults. | \n||||||||||||||||||||||||
| VCPISWAT | \n\nDo not attempt to intrude into another memory manager's\nPL0 context. This option disables the default INTRUDE\noption. | \n||||||||||||||||||||||||
| VIDEO=d:\\path\\filename.ext | \n\nRead in/write to video tables. If the specified file exists,\nit is read in and used as video table information. If the file doesn't\nexist, it is created. The information in the video table specifies how\nto switch to particular video modes as well as how to set certain cursor\ntypes. Use this option if you wish to bring up 386SWAT on top of graphic\napplications on single-monitor systems. *NOTE* this option doesn't fully\nwork as yet, so I suggest that you don't use it. | \n||||||||||||||||||||||||
| VMSCOUNT=n | \n\nUsed with VMSINT. \nLimit number of times 386SWAT inserts itself into a VCPI client's GDT/IDT.\nThis may be useful when debugging VCPI applications that call Enter Protected\nMode (AX=DE0C) repeatedly, such as a real-mode\nint 08h handler that enters protected mode on every clock tick. The correct\nvalue may have to be determined by trial and error. | \n||||||||||||||||||||||||
| VMSINT[=xx,xx,...] | \n\nTrap VCPI Enter Protected Mode switches (AX=DE0C)\nand blast in sufficient GDT and IDT entries to debug the client application.\nThis option is useful when debugging a VCPI application which does not\nfollow the preliminary VCPI debugger specification. Use this option with\ncare. The argument (if present) limits the intercepted interrupts to the\nvalues. When VMSINT is in effect, it may\nbe important to limit the interrupts. For example, some DOS16M apps (such\nas Lotus 1-2-3 Version 3.0) intercept interrupts but don't set the access\nrights byte in the IDT (they assume that it's still set for a 286 interrupt\ngate, as DOS16M setup originally). Thus when 386SWAT blasts its task gate\nentries into the IDT, subsequent DOS16M intercepts leave those entries\nmarked as a task gate. This debug option limits us to intercepting those\nfaults necessary to catch catastrophic errors, but not everything. Interrupts\nwhich may be intercepted are 00, 01,\n02, 03, 05,\n06, 0A, 0B,\n0C, 0D, and\n0E. | \n||||||||||||||||||||||||
| WKDLS=nnn | \n\nReserve space for nnn WKD load segment\nentries. | \n
Two machines may be connected for remote debugging. The connection may\nbe made via a null modem cable connecting the serial ports on both machines,\nor via modem.\n\n
The connection is initiated by using the SETCOM\ncommand to initialize the serial port, then pressing Ctl-F9\non each system to attempt to connect. When a connection is established,\nthe \"Press M to become master\" prompt appears. Only one of the two systems\nmay become master; the other one then becomes the slave. Processing on\nthe slave system then proceeds normally; the master system is now running\na special terminal program.\n\n
Keystrokes typed in the master terminal program are sent to the remote\nsystem (with some exceptions - see below), and screen output from the remote\n386SWAT system appears on the master terminal screen.\n
\n\n
Special keys\n\n
Ctl-Alt-Del will NOT be sent to\nthe remote system while in the master terminal screen - it will reboot\nthe master system. Ctl-F9 invokes\na menu of special options for the master system:\n
\n
| T | \n\nTerminate connection with slave immediately. | \n
| G | \n\nTerminate connection, but have slave go instead of returning to the\n386SWAT command prompt. | \n
| R | \n\nTerminate connection, have slave go, but have slave automatically attempt\nto re-establish connection on next invocation of 386SWAT. | \n
| B | \n\nTerminate connection and reboot slave system. | \n
| S | \n\nSuspend session temporarily. This temporarily exits the terminal program.\nYou may exit 386SWAT. Ctl-F9 again resumes\nthe connection. | \n
| U | \n\nUpload program to remote. | \n
| D | \n\nDownload program from remote. | \n
| Esc | \n\nContinue with terminal program | \n
The following pseudo-records describe the bit masks supported by the\nregister command where \"*\" represents reserved\nbits with no corresponding name:\n
\n
| EFL | \n\nrecord | \n\n*:13, AC:1, VM:1, RF:1, *:1, NT:1, IOPL:2, OF:1,\nDF:1, IF:1, TF:1, SF:1, ZF:1, *:1, AF:1, *:1, PF:1, *:1, CF:1 | \n
| CR0 | \n\nrecord | \n\nPG:1, CD:1, NW:1, *:10, AM:1, *:1, WP:1, *:10, NE:1,\nET:1, TS:1, EM:1, MP:1, PE:1 | \n
| PTE | \n\nrecord | \n\nFRM:20, PTE_AVL:3, *:2, PTE_D:1, PTE_A:1, PTE_CE:1,\nPTE_WT:1, PTE_US:1, PTE_RW:1, PTE_P:1 | \n
| SEL | \n\nrecord | \n\nSEL:13, TI:1, PL:2 | \n
| DR6 | \n\nrecord | \n\n*:16, BT:1, BS:1, BD:1, *:9, B3:1, B2:1, B1:1, B0:1 | \n
| DR7 | \n\nrecord | \n\nLEN3:2, RW3:2, LEN2:2, RW2:2, LEN1:2, RW1:2, LEN0:2,\nRW0:2, *:2, GD:1, *:3, GE:1, LE:1, G3:1, L3:1, G2:1, L2:1, G1:1, L1:1,\nG0:1, L0:1 | \n
| TR4 | \n\nrecord | \n\nTR4_TAG:21, TR4_WVAL:1, TR4_LRU:3, TR4_RVAL:4, *:3 | \n
| TR5 | \n\nrecord | \n\n*:21, TR5_SSEL:7, TR5_ESEL:2, TR5_CTL:2 | \n
| TR6 | \n\nrecord | \n\nFRM:20, TR6_V:1, TR6_D:1, TR6_DP:1, TR6_U:1, TR6_UP:1,\nTR6_W:1, TR6_WP:1, *:4, TR6_C:1 | \n
| TR7 | \n\nrecord | \n\nFRM:20,*:7, TR7_HT:1, TR7_REP:2, *:2 | \n
Debugging Screen\n
The top of the initial debugging screen consists of a row of the 32-bit\ngeneral purpose registers, two rows of the segment registers, and one row\nof CR0, CR2, and extended flags.\n
The rest of the initial debugging screen displays the instructions to\nbe executed with the stack appearing on the right in one or two columns.\nIf the current instruction references memory, the segment register, offset,\nand memory value of the reference are displayed on the line separating\nthe registers from the instructions.\n
The line at the bottom of the screen is used to enter various commands. \nThe following table summarizes the possibilities. The usual editing keys\nare available such as Left, Right, Home, End, Insert, Backspace, and Delete. \nNote that a colon (:) is used to separate a segment from an offset (Virtual\n8086 Mode) and that a stile (|) is used to\nseparate a selector from an offset (Protected Mode). The command\nline is parsed according to the grammar found in the file 386SWAT.GRM.\n
\n
Commands entered on the command line are saved in a ring buffer whose\nlength can be changed from the default of 1024 via the profile keyword\nCMDHIST=nnn.\n
Previous commands can be retrieved via the keystrokes Alt-<\n(previous command) and \">Alt-> (next command). Pressing\neither of these keys repeatedly scrolls through the buffer in the chosen\ndirection. The keystroke Alt-? displays a history of\n(up to 24) commands from which a command can be chosen by scrolling up\nor down through the list, or by typing the letter next to the command.\nA command may be deleted from this list via the Del key.\n
\n
Special keystrokes available from the command line include:\n
\n
| ESC | \n\nContinue processing. Equivalent to the Go\ncommand. | \n
| F1 | \n\nDisplay a help screen with submenus. | \n
| F3 | \n\nDisplay LDT entries. | \n
| F4 | \n\nDisplay IDT entries. | \n
| F5 | \n\nDisplay PTE entries. | \n
| F6 | \n\nDisplay search screen. | \n
| F7 | \n\nDisplay memory. While this display is active, Ctl-B\ndisplays in byte format, Ctl-W, in word format, Ctl-D\nin dword format, Ctl-V in vector format, Ctl-G\nin GDT format, Ctl-I in IDT format, and Ctl-T\nin TSS format. | \n
| F8 | \n\nDisplay TSS entries. | \n
| F9 | \n\nDisplay the instruction disassembly screen. | \n
| F10 | \n\nDisplay screen on entry to debugger. | \n
| F11 | \n\nSingle-step the current instruction (see Padplus).\nThis key as well as F12 are useful on systems without\na Padplus/Padminus key,\nor ones for which those keys are difficult to type such as some laptops. | \n
| F12 | \n\nSingle-skip the current instruction (see Padminus). | \n
| s-F1 | \n\nGoto the immediate CALL or JMP address of the instruction\nat the top of the screen and save the address of the current instruction\n(see Disassembly Bookmarks). | \n
| s-F2 | \n\nReturn from the previous s-F1 goto (see\nDisassembly\nBookmarks). | \n
| s-F3 | \n\nGoto the instruction on the top line (see Padstar). | \n
| s-F4 | \n\nDisplay the last AutoFault message. | \n
| s-F5 | \n\nDisplay the Real Mode Interrupt Vector Table. | \n
| s-F10 | \n\nSave the current screen into the last screen buffers. | \n
| a-F1 | \n\nToggle intercept of INTs 01h/03h. The current state appears\nbelow the segment/selector register display as 01 or blank, 03 or blank.\nThe default state is controlled by the presence or absence of the TRAPDEBUGkeyword. | \n
| a-F2 | \n\nToggle intercept of INT 02h. The current state appears below\nthe segment/selector register display as 02 or blank. The default state\nis controlled by the presence or absence of the TRAPNMIkeyword. | \n
| a-F3 | \n\nToggle intercept of INT 0Dh. The current state appears below\nthe segment/selector register display as 0D or blank. The default state\nis controlled by the presence or absence of the TRAPGENPkeyword. | \n
| a-F4 | \n\nToggle intercept of INT 0Eh. The current state appears below\nthe segment/selector register display as 0E or blank. The default state\nis controlled by the presence or absence of the TRAPPAGEkeyword. | \n
| a-F5 | \n\nToggle stack display state between two columns of words\nand one column of dwords. The tick marks appear every 16 bytes. | \n
| a-F6 | \n\nToggle screen save state (eliminates screen flicker when\nsingle-stepping over instructions which don't write to the screen). The\ncurrent state appears below the segment/selector register display as SS=ON\nor SS=OFF. | \n
| a-F7 | \n\nToggle video base (switch debugging screens in a two-monitor\nsystem). | \n
| a-F8 | \n\nDisplay NDP (floating point) register screen. Use the same\nkeystroke to remove the NDP screen. | \n
| a-F9 | \n\nDisplay debug register screen. This screen remains active\nuntil it is replaced by another screen. That is, you may type on the command\nline, etc. while the debug register screen is displayed. | \n
| a-F10 | \n\nDisplay previous debugging screens. This option can be used\nto compare changes over a single-step or single-skip. Up to sixteen previous\nscreens can be displayed in this manner using the Up\nand Down arrows. To change from the default value of\nsixteen, use the keyword SAVESCREEN(see\nabove). | \n
| a-F11 | \n\nDisplay MMX and SSE2 register screen. | \n
| a-F | \n\nGoto the far return address at SS:SP\nor SS|eSP (depending upon the current mode).\nIf the current code segment is USE16, the far return address is assumed\nto be word:word (or word|word); if it's USE32, the format is assumed to\nbe word:dword (or word|dword).\nThis shortcut is equivalent to typing G\n.RETF at the command line. | \n
| a-N | \n\nGoto the near return address at SS:SP\nor SS|eSP (depending upon the current mode).\nIf the current code segment is USE16, the near return address is assumed\nto be word; if it's USE32, the format is assumed to be dword. This shortcut\nis equivalent to typing G\n.RETN at the command line. | \n
| a-< | \n\nRetrieve the previous command from the command\nhistory buffer. | \n
| \">a-> | \n\nRetrieve the next command from the command\nhistory buffer. | \n
| a-? | \n\nDisplay the command history buffer. | \n
| c-F1 | \n\nToggle intercept of INT 01h only. The current state appears\nbelow the segment/selector register display as 01 or blank. The default\nstate is controlled by the presence or absence of the TRAPSTEPkeyword. | \n
| c-F2 | \n\nToggle intercept of INT 03h only. The current state appears\nbelow the segment/selector register display as 03 or blank. The default\nstate is controlled by the presence or absence of the TRAPSKIPkeyword. | \n
| c-F3 | \n\nToggle intercept of INT 06h. The current state appears below\nthe segment/selector register display as 06 or blank. The default state\nis controlled by the presence or absence of the TRAPINVkeyword. | \n
| c-F4 | \n\nToggle intercept of INT 0Ch. The current state appears below\nthe segment/selector register display as 0C or blank. The default state\nis controlled by the presence or absence of the TRAPSTACKkeyword. | \n
| c-F5 | \n\nDisplay PDE entries. | \n
| c-F6 | \n\nDisplay symbols. | \n
| c-F7 | \n\nDisplay file browser. | \n
| c-F8 | \n\nEnter CHAT mode. This allows\ntwo connected machines to test the serial port connection. What you type\nis displayed on the lower screen and sent to the other system; whatever\nis received is displayed on the top screen. If only garbage characters\nappear the two machines may not have the same data transfer rate set. | \n
| c-F9 | \n\nAttempt to connect for remote debugging. See the section\nat the end of this document on remote debugging. | \n
| c-F10 | \n\nDisplay error log. | \n
| c-F11 | \n\nSingle-step INT-like instruction in VM to PM, otherwise\njust single-step (same as c-Padplus). | \n
| c-Up | \n\nDecrement the location pointer to the previous entry. This\nchange has a different effect depending upon the type of information being\ndisplayed. If used in a data display, it moves back one data item (byte,\nword, dword, etc.). If used in a TSS display, the I/O ports in the I/O\nbit permission map scroll up. | \n
| c-Down | \n\nIncrement the location pointer to the next entry. This change\nhas a different effect depending upon the type of information being displayed.\nIf used in a data display, it moves forward one data item (byte, word,\ndword, etc.). If used in a TSS display, the I/O ports in the I/O bit permission\nmap scroll down. | \n
| c-Home | \n\nPlace the current instruction at the top of the screen. | \n
| c-B | \n\nDisplay memory in byte (xx) format. | \n
| c-D | \n\nDisplay memory in dword (xxxxxxxx) format. | \n
| c-G | \n\nDisplay memory in GDT format. | \n
| c-I | \n\nDisplay memory in IDT format. | \n
| c-K | \n\nDisplay Windows Kernel Debugger Structures menu. This menu\nmay be displayed only when running under Windows as a kernel debugger. \nSee WINKDBG.DOC. | \n
| c-M | \n\nDisplay memory allocation chain entries based at the value\nassigned to MACBASE.\nBy default, this value is the initial value of .DMAC. | \n
| c-T | \n\nDisplay memory in TSS format. | \n
| c-V | \n\nDisplay memory in vector (xxxx:xxxx) format. | \n
| c-W | \n\nDisplay memory in word (xxxx) format. | \n
| c-Z | \n\nZap (convert to NOPs) the instruction at the top of the\ninstruction disassembly window. | \n
| c-ESC | \n\nSame as ESC, but if you're on an INT 03h, it skips over\nit first and then continues. If the current instruction is not an INT 03h,\nthis keystroke behaves identically to ESC. | \n
| Padplus | \n\nSingle-step the current instruction (same as F11). | \n
| c-Padplus | \n\nSingle-step INT-like instruction in VM to PM, otherwise\njust single-step (same as c-F11). | \n
| Padminus | \n\nSingle-skip the current instruction (same as F12).\nThat is, execute the current instruction and put a breakpoint on the instruction\nfollowing. This is used to execute but not single-step through a CALL or\nLOOP instruction. | \n
| Padstar | \n\nGoto the instruction on the top line (same as s-F3). | \n
| Up | \n\nScroll the screen up one line. This key has the same effect\nin almost all screen displays. | \n
| Down | \n\nScroll the screen down one line. This key has the same effect\nin almost all screen displays. | \n
| PgUp | \n\nScroll the screen up one page. This key has the same effect\nin almost all screen displays. | \n
| PgDown | \n\nScroll the screen down one page. This key has the same effect\nin almost all screen displays. | \n
| s-PrtSc | \n\nPrint the screen. Note that if either the previous application\nscreen (F10) or one of the previous debugging screens\n(a-F10) is currently displayed, that screen is sent\nto the printer. The I/O port in the BIOS data area which corresponds to\nLPT1 is used. | \n
| Ctl-Alt-Del | \n\nReboot the system. | \n
This document covers the basics of symbolic debugging support for 386SWAT. \n The 386SWAT API specifics are documented in VCPIDBG.DOC; \n here we will describe actual usage of SWAT for symbolic debugging, and the tools \n needed to load symbols. \n
Using symbols\n\n
New Commands Within 386SWAT\n\n
Several profile options are new to 386SWAT:\n\n
Specify number of address bits to use for address hash table. \nValues less than 8 and over 12 are ignored.\n\n
Address hash table storage in bytes is 2 ^ (ADDRHBITS\n+ 2). The minimum is therefore 1K and the maximum, 16K.\n\n
ADDRHBITS defaults to 12. When symbols\nare present, all possible addresses in the disassembly screen are searched\nagainst the address hash table. Possible hits require traversal of\nthe address hash buckets chain, similar to name hash bucket traversal. \nA \"next address bucket\" pointer is part of the symbol record. Thus\nthe set of symbol records forms two interleaved linked lists: the\naddress bucket chain and the name bucket chain.\n\n
The number of bits specified by ADDRHBITS\nare taken from a resolved linear address, shifted left 2 bits, and used\nas an index into the table of dword pointers based at the address contained\nin SYMNHASH. The address pointed to\nis an offset from the address in SYMBASE,\nand points to the beginning symbol record in that address bucket chain. \nIf the value is -1 (FFFFFFFF), there is no such address.\n\n
Smaller address hash tables may significantly impact unassembly.\n
\n\n
Specify number of 1K blocks to be used for symbol name hashing. \nValues less than 1 and over 255 are ignored.\n\n
To speed symbol name searches, all names are hashed using the following\nalgorithm:\n\n
extern unsigned int HASHPRIME;\n\n
int hashpjw(char *s)\n
{\n
char *p;\n
unsigned long h=0, g;\n\n
for (p=s; *p; p++) {\n
h = (h <<\n4) + (unsigned) tolower (*p);\n
if (g = (h &\n0xf0000000)) {\n
\nh = h ^ (g >> 24);\n
\nh = h ^ g;\n
}\n
}\n\n
return ((int) (h % HASHPRIME));\n
}\n\n
HASHPRIME is derived from a table of prime\nnumbers closest to multiples of 256. Here are some examples:\n\n
BUCKETS HASHPRIME\n
1 \n257\n
2 \n509\n
3 \n769\n
254 65027\n
255 65287\n\n
The storage occupied by the name hashing table is HASHPRIMES[BUCKETS-1]\n* 4, or approximately BUCKETS * 1K.\n\n
When a hash value is calculated from a name, that value is shifted left\n2 bits and used as an index into the table of dword bucket pointers based\nat the address contained in SYMNHASH. \nA bucket pointer may contain -1 (FFFFFFFF) or an offset from the address\ncontained in SYMBASE. In this case,\na \"bucket\" actually points to a symbol record. Next name pointers\nin each symbol record form a linked list which may be traversed to find\nan exact name match.\n\n
The smaller the BUCKETS value, the longer\nthese bucket chains will be, thus increasing name search time. This\nis only likely to be a performance hit when loading symbols, since 386SWAT\nchecks for existing symbols by name. Searches for symbols entered\nat the command line would not be visibly impacted by longer searches.\n
\n\n
LOADSYM \nEnable file I/O functions within 386SWAT. This is needed for using\nthe file browser, and for source level debugging.\n\n
LOADSYM=filename.ssf\n\n
Enables file I/O (same as LOADSYM). \nAlso loads symbols from the specified .SSF file (created by MAPSSF)\nat initialization time.\n
\n\n
PATH=d:\\dir1[,d:\\dir2[,...]]\n\n
Specify search path for source browser. If not specified, only\nthe current directory is searched. If a path is specified, the current\ndirectory (.) must be included explicitly. For example, PATH=c:\\qui\\quilib,c:\\qui\\inst\nwill not search the current directory for source files.\n
\n\n
Specify how far 386SWAT continues proximity searches and with what granularity. \nThe default is 1 word. The high order byte of PROXSRCH contains the\ngranularity in bytes, and the low order byte contains the number of units\nto search. The default is 0201h. \n0108h would do byte granular searches from\nx+1 to x+8.\n\n
Proximity searches should not visibly impact disassembly performance. \nA separate check for an empty symbol table ensures that no time is wasted\nin unnecessary calls to the symbol search routine (which has its own check\nfor empty tables). No proximity searches are done for label display\nand data display; this only affects values within the disassembly.\n\n
The command line option PS\nallows these settings to be changed on the fly.\n
\n\n
This option sets the number of bytes to be used for the 386SWAT symbol\ntable. The internal format of 386SWAT's symbol table is 12 bytes\nlarger than the symbol table used for the 386SWAT API calls. Each\npublic or line number occupies 23 bytes plus the length of the symbol name.\n\n
SYMSIZE is used to calculate a default value for BUCKETS (described\nbelow). If BUCKETS is not explicitly defined in the profile, it will\nbe set to min (255, max (1, SYMSIZE / 4096)).\n\n
If SYMSIZE is not specified, it will default to 4096 bytes. The\ndefault BUCKETS value (if also not specified) will then be 1. See\nbelow for BUCKETS storage requirements.\n\n
Use SYMSIZE=0 to minimize symbol storage\nrequirements. This will save 4K over the default.\n
\n
Any symbol may be used as an effective address. For example,\n\n
dd 180|{SYMHASH\n\n
will display the symbol address hash table. Symbol display occurs\nautomatically if the symbols are loaded properly. See sections below\non SWATRUN and MAPSSF.\n\n
Symbols are displayed in the Unassemble (F9) screen. Code addresses\nmay be displayed as public names or line numbers (if line numbers were\nspecified with the linker's /LI option). \nAddresses within the unassembly are handled as intelligently as possible. \nFor example,\n\n
mov ax,[bx+7c39]\n\n
may be displayed as\n\n
mov ax,[bx+FOOBAR]\n\n
if FOOBAR's offset is 7C39 and the default\nsegment/selector (DS in this case) matches the segment/selector specified\nfor the symbol FOOBAR.\n\n
386SWAT can now resolve addresses CLOSE TO symbols; a construction commonly\nseen in C code might be:\n\n
mov [FOOBAR],bx\n
mov [7c3b],es\n\n
386SWAT will disassemble this as\n\n
mov [FOOBAR],bx\n
mov [FOOBAR+02],es\n\n
Another useful feature would be to turn off case sensitivity when searching\nfor symbol matches. This is more of an issue when debugging C code.\nAgain, it could be settable in the profile as well as from the command\nline.\n
\n
The Translate Symbols (TS) command may\nbe used to adjust segment/selector values, as well as to add a constant\nto symbol offsets, after the symbols are loaded. This is needed for\ndebugging the VxD. The VxD symbols would be loaded with MAPSSF,\nusing a .wsg file to assign selector values and group ID's to the different\nlinker groups. Once SWATVXD has located\nthe offsets of the different VxD groups, they may be translated one at\na time.\n\n
For example, the VxD's DGROUP\nis assigned selector 28, group ID 2001,\nand IGROUP is assigned selector 30,\ngroup ID 2002. The .WSG file entries\nare\n\n
2001 P \n28 DGROUP \n; Comments\n
2002 P \n30 IGROUP \n; More comments\n\n
We load the .MAP file before entering Windows:\n\n
MAPSSF -wVXD.WSG VXD.MAP\n\n
We find that the offsets within the Windows flat model segment are\n\n
DGROUP 8001BE24\n
IGROUP 8020397C\n\n
The TS command is used to translate both groups:\n\n
ts 28 2001 P 28 8001BE24\n
ts 30 2002 P 30 8020397C\n\n
The complete syntax of the TS command is\n\n
TS osel ogrp nflag nsel nbase\n
\n
| osel | \n\nOld selector value | \n
| ogrp | \n\nTarget group value (unless specified in .WSG file, 0) | \n
| nflag | \n\nP for PM symbols \n V for VM symbols | \n
| nsel | \n\nNew selector value (in above example, unchanged) | \n
| nbase | \n\nBase value to be added to all symbol offsets | \n
The Query Symbol (QS) command may be used\nto display on the command line the name and distance from a given address. \nFor example,\n\n
QS .code\n\n
might display as\n\n
QS .code = VWIN32_Code0001+00005678\n
\n
This program is called by SWATRUN to load .MAP files on the fly. \nIt may also be used to produce .SSF files for loading at CONFIG.SYS time\n(not currently supported by SWAT). .SSF files may also be loaded\ndirectly by SWATRUN. This is faster than calling MAPSSF every time\nsymbols are loaded.\n\n
Besides reading .MAP files, MAPSSF will also process Windows SYM32 files. \nMAPSSF has been tested with the following .MAP file formats:\n\n
- Microsoft LINK\n
- Microsoft LINK386 flat model\n
- Borland TLINK\n\n
Syntax:\n\n
MapSSF [options] fspec1 [fspec2\n[...]]\n\n
All options are preceded with - or /\n
\n
| -g#,# | \n\nrestrict symbol group types to specified #'s (SYM32 files only). \nOnly symbols with group types matching one of these values will be loaded. \nThe group type in SYM32 files is NOT the same as the group ID defined in\na .WSG file. | \n|||||||||||||||||||||||||||||||||||||||||||||||||||||||
| -l | \n\nignore line number information in .MAP file. This option may\nbe used to suppress loading of line number symbols when space is at a premium. \nTypically, line numbers take about 80% of symbol space. | \n|||||||||||||||||||||||||||||||||||||||||||||||||||||||
| -o | \n\noverwrite existing symbol table (default is append). Normally,\nnew symbols are added to SWAT. Existing \n symbols will be updated. This option forces the symbol table\nto be flushed at the beginning of MAPSSF. | \n|||||||||||||||||||||||||||||||||||||||||||||||||||||||
| -sxxxxm | \n\nset selector to xxxx hex, where m is \n
| \n|||||||||||||||||||||||||||||||||||||||||||||||||||||||
| -tfname | \n\necho 386SWAT tables to file fname. This option may be\nused to create a file in 386SWAT symbol format (.SSF file). | \n|||||||||||||||||||||||||||||||||||||||||||||||||||||||
| -wfname[.wsg] | \n\nread Windows Symbol Group file fname.wsg. This feature may be\nused for .MAP files or for .SYM files. As an example, the QMAX.WSG\nfile contains: \n
Association of public symbols with groups is sometimes not sufficient. \nBoth code and data are in PGROUP, but different\nselectors are used. We therefore specify the individual data segments\nwithin PGROUP that will be assigned selector\n18h (EDATA\nand VALSEG). Since segments are more\ncompletely specified in the MAP file than groups, MAPSSF will check for\nsegment matches before checking for group matches. We also use this\nmechanism to avoid loading the NCODE and\nNDATA segments within PGROUP. \n\n Group matches are made by checking group origin values, which are sorted\nby value in descending order, against addresses. ALL groups which\nCOULD include an address, from highest to lowest, are checked for inclusion\nin the .WSG file. The first match determines what changes are made\nto the matching symbol address. | \n|||||||||||||||||||||||||||||||||||||||||||||||||||||||
| -v | \n\nsort symbols by value (default is by name). This option controls\nwhich section of the .MAP file is read. If included on the command\nline, the \"By Value\" section is read. By default, the \"By Name\" section\nis read. By controlling the order in which symbols are passed to\nSWAT, the display in SWAT's Ctrl-F6 screen may be sorted by name or by\nvalue. | \n|||||||||||||||||||||||||||||||||||||||||||||||||||||||
| -x# | \n\nset debugging level to # (default is 0\n-- no messages). This is useful for debugging only. | \n|||||||||||||||||||||||||||||||||||||||||||||||||||||||
| -y | \n\ndefault to recognizing files as SYM32 format. Normally, MAPSSF\nrecognizes files as .MAP or .SYM by their extension. If neither extension\nis used, this option forces recognition as SYM32. | \n
Syntax: Device=d:\\path\\swatcmd.exe\ncommand\n
or swatcmd command\n\n
SWATCMD can be loaded via Device=\nor from the DOS command line. It may be used to pass commands to\n386SWAT under program control. Invoking SWATCMD\nwith no options brings up 386SWAT at an INT 03h (assuming TRAPSKIP\nor TRAPDEBUG\nis active).\n
\n\n
Syntax: SWATRUN [options] progname\n[arguments]\n\n
SWATRUN is a program loader for debugging V86 mode programs. It\ncreates a breakpoint before the first instruction of the target program,\nand will also attempt to load symbols into 386SWAT via the VCPI debugger\nAPI (VCPIDBG.DOC) with the appropriate segment\nfixup.\n\n
If no file extension is specified, SWATRUN looks first for a .COM file\nthen an .EXE file. The filename specified is converted into a fully\nqualified pathname including drive letter, directory, and extension. \nSWATRUN will load this file using DOS function 4B01 to determine\nthe segment fixup.\n\n
SWATRUN will then look for a matching .SSF file, and if found, will\nload it directly into 386SWAT. If an .SSF file is not found, SWATRUN\nwill look for a matching .MAP file. If a .MAP file is found, SWATRUN\nwill invoke MAPSSF with the proper parameters to fixup and load the parsed\n.MAP file. See the section on MAPSSF for further information on .MAP\nfile formats supported and on creation of .SSF files. .SSF file loading\nis faster, but does not currently report symbol allocation table shortages. \nIf your symbols do not appear to be loaded from an .SSF file, delete the\n.SSF file. SWATRUN will try to load symbols from the .MAP file with\nMAPSSF. MAPSSF will report any changes required to the 386SWAT.PRO\nfile.\n
\n
Valid SWATRUN options are\n
\n
| /b | \n\nGenerate Int 1 at beginning of SWATRUN. This is useful only for\ndebugging the loading process | \n
| /mMAPFILE | \n\nLoad MAPFILE instead of progname.map. If no .SSF file\nis present, SWATRUN constructs a map file name by taking the path and basename\nof the .EXE or .COM file and adding .MAP. This filename is passed\nto MAPSSF if it exists. This option may be used to specify a map\nfile on another drive:directory. | \n
| /n | \n\nDo not load symbols. If SWATRUN has already run once, the target\nprogram did not go resident, and symbols were loaded, run SWATRUN with\nthis option on subsequent invocations. | \n
| /o | \n\nOverwrite existing SWAT symbols. This option is passed to MAPSSF. \nAny existing symbols will be destroyed. | \n
| /sSYMFILE | \n\nLoad SYMFILE instead of progname.ssf. SWATRUN normally constructs\na .ssf file name by taking the path and basename of the .EXE or .COM file\nand adding .SSF. If this file exists and is in the proper format\ncreated by MAPSSF, it will be loaded into 386SWAT. | \n
| /? | \n\nDisplay a help message. | \n
Version 6.03\n
\n
\n
\n
\n
\n
\n
\n
In case you do not need to restore a saved register set, the saved state\ncan be cleared with the RC\ncommand.
1. The Branch Trace Facility (BTF)\ncan be turned on and off via the command line BTF ON/OFF.\n
2. The Last Branch/Exception From/To registers can be displayed\nat all times in the lower right corner of the screen. This feature\ncan be turned on and off via the command line LBR ON/OFF.\n
\n
\n
\n
\n
\n
Version 5.10.038
The SWATVXD.EXE file is the accompanying VxD to 386SWAT. As long\nas it is in the same directory as the debugger file (386SWAT.LOD), it is\nloaded automatically by 386SWAT. If for some reason you don't wish\nthat to happen, using the command WIN NOSWAT\nprevents the VxD from loading.\n
\n\n
Switches\n\n
The VxD provides Windows services for 386SWAT, and is useful for debugging\nVxDs.\n\n
The VxD's operation is controlled by various switches all of which appear\nin the [386SWAT] section of your SYSTEM.INI\nfile.\n\n
SWATDualDisplay\n
Squirt cool info to the mono display -- you must use this option to\nget the most useful output to the mono screen.\n\n
SSF=d:\\path\\name.SSF\n
Specify the WIN.SSF file -- this file is generated when 386SWAT VxD\nis built and contains useful symbol information about Windows VxDs.\n\n
SWATVxDROM\n
In Sys_Critical_Init, mark the Page Table Entries of all VxD code segments\nas read-only (normally, they are read-writable!). This feature was\nimplemented in an attempt to figure out why Windows was crashing (I thought\nthat there might be a bad pointer out there). While I didn't find anything\nin particular, it is handy to rule out this problem. If a VxD code\nsegment is written into, an Invalid Page Fault is generated (see below). \nLikely, you'll find that a single IPF due to this feature is generated\nat the start of Windows. The default action (taken by pressing Esc\nat the command line) is to test for a RO page and set the RW bit. \nThis clears the IPF for this one page only. From that point on, all IPFs\nshould be examined carefully. If this switch is set, the SWATVxDIPF\nswitch is also set automatically.\n\n
SWATVxDIPF\n
In Sys_Critical_Init, hook the Invalid Page Fault handler. This\nfeature, in conjunction with the IPF command\nin 386SWAT can be useful for debugging these beasts. The mono screen\ncontains a formatted message of the incoming data to the IPF hook procedure. \nThis feature is preliminary and provides a way to get control at the point\nof the IPF -- after that, you're on your own. If you can suggest\nmore things 386SWAT can do to help debug IPFs, I'm very open to suggestions.\n
\n
HookIRQ\n
Hook IRQ0-7 locally if 386SWAT hooks them. This switch is necessary\nfor some VxDs (RAM Doubler in particular) as they don't install correctly\nif they find some IRQs not hooked by selector 28h. Go figure.\n
\n\n
Debugging VxDs\n\n
To debug VxDs at their entry points, use the following switches:\n\n
HookVxD=DDB_Name[,#s]\n
Trap at a particular VxD by name. Note that DDB_Name is\ncase sensitive, and # specifies message numbers (optional). \nSee the VxD Filename and Message\n# tables below.\n\n
HookPM=DDB_Name,reg,#\n
Trap at a particular VxD's PM API entry. reg specifies\na 16-bit register used by the VxD for the function code, and # specifies\nthe functions to trap. For example, HookPM=SHELL,DX,3\ntraps at the WINOLDAP hook\n
\n\n
Some VxD filenames, DDB names, Device_ID, and their switches:\n\n
WINA20.386 'LA20HMA\n' xxxxh\n
\nNOLOW64KPAGING\n
\nNOLOW64KPAGINGPORT\n
Debug \n' ' 0002h\n
*VPICD \n'VPICD ' 0003h\n
*VDMAD \n'VDMAD ' 0004h\n
*VTD \n'VTD ' 0005h\n
*V86MMGR \n'V86MMGR ' 0006h\n
*PAGESWAP \n'PageSwap' 0007h\n
*VKD \n'VKD ' 000Dh\n
\nINITPS2MOUSEATEXIT=ON/OFF\n
*DOSMGR \n'DOSMGR ' 0015h\n
*WSHELL \n'SHELL ' 0017h\n
*PAGEFILE \n'PageFile' 0021h\n
386MAX.VXD 'LoadHi \n' 001Ch\n
SWATVXD.EXE 'SWATVXD ' 2400h\n
VDDVGA.386 'VDD \n' 000Ah\n
VNETWARE.386 'DOSNET ' 001Ah\n
PM_BIOS.386 'PMVDD ' 2250h\n
\n\n
0000h Sys_Critical_Init \n001Bh Sys_Dynamic_Device_Init\n
0001h Device_Init \n001Ch Sys_Dynamic_Device_Exit\n
0002h Init_Complete \n001Dh Create_Thread\n
0003h Sys_VM_Init \n001Eh Thread_Init\n
0004h Sys_VM_Terminate \n001Fh Terminate_Thread\n
0005h System_Exit \n0020h Thread_Not_Executeable\n
0006h Sys_Critical_Exit \n0021h Destroy_Thread\n
0007h Create_VM \n0022h PNP_New_Devnode\n
0008h VM_Critical_Init \n0023h W32_DeviceIOControl\n
0009h VM_Init \n0024h Sys_VM_Terminate2\n
000Ah VM_Terminate \n0025h System_Exit2\n
000Bh VM_Not_Executeable \n0026h Sys_Critical_Exit2\n
000Ch Destroy_VM \n0027h Vm_Terminate2\n
000Dh VM_Suspend \n0028h Vm_Not_Executeable2\n
000Eh VM_Resume \n0029h Destroy_VM2\n
000Fh Set_Device_Focus \n002Ah VM_Suspend2\n
0010h Begin_Message_Mode \n002Bh End_Message_Mode2\n
0011h End_Message_Mode \n002Ch End_PM_App2\n
0012h Reboot_Processor \n002Dh Device_Reboot_Notify2\n
0013h Query_Destroy \n002Eh Crit_Reboot_Notify2\n
0014h Debug_Query \n002Fh Close_VM_Notify2\n
0015h Begin_PM_App \n0030h Get_Contention_Handler\n
0016h End_PM_App \n0031h Kernel32_Initialized\n
0017h Device_Reboot_Notify 0032h Kernel32_Shutdown\n
0018h Crit_Reboot_Notify\n
0019h Close_VM_Notify\n
001Ah Power_Event \n
\n\n
Message Number Traps\n\n
To stop inside 386SWAT at various message numbers, use the following\nswitches:\n\n
SWATSysCriticalInit\n
SWATDeviceInit\n
SWATInitComplete\n
SWATSysVMInit\n
SWATSysVMTerminate\n
SWATSystemExit\n
SWATSysCriticalExit\n
SWATCreateVM\n
SWATVMCriticalInit\n
SWATVMInit\n
SWATVMTerminate\n
SWATVMNotExecuteable\n
SWATDestroyVM\n
SWATVMSuspend\n
SWATVMResume\n
SWATSetDeviceFocus\n
SWATBeginMessageMode\n
SWATEndMessageMode\n
SWATRebootProcessor\n
SWATQueryDestroy\n
SWATDebugQuery\n
SWATBeginPMApp\n
SWATEndPMApp\n
SWATDeviceRebootNotify\n
SWATCritRebootNotify\n
SWATCloseVMNotify\n
SWATPowerEvent\n
SWATSysDynamicDeviceInit\n
SWATSysDynamicDeviceExit\n
SWATCreateThread\n
SWATThreadInit\n
SWATTerminateThread\n
SWATThreadNotExecuteable\n
SWATDestroyThread\n
SWATPNPNewDevnode\n
SWATW32DeviceIOControl\n
SWATSysVMTerminate2\n
SWATSystemExit2\n
SWATSysCriticalExit2\n
SWATVMTerminate2\n
SWATVMNotExecuteable2\n
SWATDestroyVM2\n
SWATVMSuspend2\n
SWATEndMessageMode2\n
SWATEndPMApp2\n
SWATDeviceRebootNotify2\n
SWATCritRebootNotify2\n
SWATCloseVMNotify2\n
SWATGetContentionHandler\n
SWATKernel32Initialized\n
SWATKernel32Shutdown\n
\n\n
Internal Use Only\n\n
The following switches are for internal use only.\n\n
SSFPrefix=name\n
Specify device name and DDB prefix.\n
\n
SWATDebugThruExit\n
Call 386SWAT's INIT_PROT during Sys_Critical_Exit. This allows\ndebugging on the way out of 386SWAT. Now that 386SWAT is a Windows\nkernel debugger, this switch is unnecessary.\n\n
RealModeBreak=ON/OFF\n
Hit an INT 1 early in RealModeInit.\n
\n
Rehook123=ON/OFF\n
Blast INTs 1, 2, and 3 into the IDT. To avoid trouble with WDEB386.\nNow that 386SWAT is a Windows kernel debugger, there should be less need\nto run WDEB386. \n\n\n"
},
{
"path": "swat/SWATWDBG.HTM",
"content": "\n
386SWAT runs as a debugger under Windows 3.x and 95/98 when accompanied\nby its VxD. This file (SWATVXD.EXE) should\nbe in the same directory as the debugger file (386SWAT.LOD)\nand is loaded automatically when Windows starts. To take advantage of the\ninformation provided by the VxD, you should have a monochrome monitor attached\nto your system. For more details about the VxD including how to configure\nit, see the file SWATVXD.DOC. \n\n\n" }, { "path": "swat/SWATWISH.HTM", "content": "\n\n
\n \n \n \nHere's my wish list (in no particular order) of things I would like\nthis debugger to do. Feel free to contribute yours in our newsgroup:\n
If you program under Windows 3.1x or Win95/98 (but not WinNT), 386SWAT\npresents itself to Windows as a very low-level debugger. Essentially, 386SWAT\nis provided the same level of access as the remote debugger WDEB386 shipped\nwith Windows. WDEB386 requires that you run it from a separate system with\na COM cable running between the two systems. In contrast, 386SWAT runs\non the same system being debugged, however it does require that you have\na monochrome adapter and monitor installed in the system.\n\n
For more details on this topic, see the file WINKDBG.DOC. \n\n\n" }, { "path": "swat/VCPIDBG.DOC", "content": "\t\t\t Preliminary Proposal\n\t\t\t\t For\n\t\t\t Debugger Extensions\n\t\t\t\t to\n\t\t\t VCPI Specification\n\t\t\t 30 May 89\n\t\t\t Amended 22 Aug 90\n\t\t\t Amended 9 Aug 94\n\n\t\t\t Ŀ\n\t\t\t Rationale \n\t\t\t \n\nThe premise is that there is already a resident debugger in the system\nwhich the client wishes to use. These calls provide an interface\nbetween the client and the debugger to allow that to happen. In order\nfor the debugger to support this interface, it should intercept INT\n67h during its initialization and troll for the following calls,\nignoring most others. The debugger may wish to troll for the \"Set\n8259A Interrupt Vector Mappings\" call in order to properly determine\nwhere the timer and keyboard interrupts start.\n\n\n\t\t Ŀ\n\t\t V86 Mode Program Interface \n\t\t \n\n\t\t\t OVERVIEW\n\nIf your program enters PM via DPMI using a memory manager with an\nintegrated DPMI host, skip all this as 386SWAT hooks into the host's\nGDT and IDT through the INTRUDE option. Note that DPMI hosts which\ninstall as a separate device driver appear to the memory manager (and\nthus to 386SWAT) as a VCPI client, so the above advice to skip this\ndocument does not apply. I haven't tried to debug a DPMI client in\nthis context, so I'm not sure how to do it.\n\nIf your program enters PM via VCPI, use functions DEF0, DE01, DEF4,\nDEF2, and DEF3 in that order so that 386SWAT is properly initialized\nin your program's GDT and IDT.\n\nIf your program enters PM from RM and uses paging, use functions DEF0,\nDEF4, DEF2, DEF3, and DEF9 in that order although function DEF9 can be\nexecuted anytime after function DEF0 executes successfully.\n\nIf your program enters PM from RM and does not use paging, use\nfunctions DEF0, DEF4, DEF2, and DEF3 in that order.\n\nWhen debugging VCPI clients, be sure to enable the VMSINT flag either\nby putting the keyword VMSINT into your 386SWAT profile, or by typing\nVMSINT ON from the 386SWAT command line.\n\n\n\nINT 67h\nAX = 0DEF0h\t Determine Debugger Presence\n\nINPUTS: \t None.\n\nOUTPUTS:\t AH = 00h if successful\n\t\t = 84h if VCPI not supported\n\t\t = 8Fh if debugger support not present\n\t\t BH = Debugger specification major version #\n\t\t BL = ...\t\t minor ...\n\n\nThis call determines whether or not a resident debugger is present in\nthe system. The current specification version number is 5.00; that\nis, BH = 05, BL = 00. These values are in binary such that if the\nspecification version number were 10.12, this call would return BH =\n0Ah, BL = 0Ch.\n\n\nINT 67h\nAX = 0DEF1h\t Get Debugger Information\n\nINPUTS: \t None.\n\nOUTPUTS:\t AH = 00h if successful\n\t\t EDX = Physical address of debugger information\n\n\nThis call returns the physical address of a certain data structure\ninside 386SWAT for use in conjunction with the 386SWAT Virutal Device\nfor Windows 3.\tThe contents of the structure is as follows:\n\nINFO_LEN\tdw\t?\t; Byte count of structure\nINFO_BASE\tdd\t?\t; Physical base address of SWAT code segment\nSWTINF_VER\tdw\t?\t; Version # of structure\nMore fields are defined which are used by SWATVXD.\n\n\nINT 67h\nAX = 0DEF2h\t Initialize Debugger Interface, Task Gate\n\nINPUTS: \t ES:DI ==> GDT entries for debugger support\n\t\t If ES = 0, EDI ==> ...\n\t\t BX = initial selector\n\nOUTPUTS:\t AH = 00h if successful\n\t\t = 84h if VCPI not supported\n\t\t = 8Fh if debugger support not present\n\t\t BX:EDX = Address of protected mode entry point\n\n\nThis call allows the debugger to setup its own GDT entries as it\npleases. The number of entries it may use is limited to thirty (30)\nso the client can statically allocate space in its GDT. Each GDT\nentry used by SWAT is a TSS selector, and the IDT entries used (when\nDEF3 is called) are Task Gates (cf. DEFD). The starting selector\nnumber in BX is needed so that the \"Initialize Debugger IDT Entry\"\ncall knows what selectors to use when initializing an IDT entry.\nConsequently, this call must precede that call in order to know the\nproper selector value.\n\nIf you are writing a PM program which enters PM via VCPI, your call to\nthe VCPI Get PM Interface (DE01) must precede this call as 386SWAT\nneeds to hook into the latter call in order to ensure that its PTEs\nare visible when the VCPI client is active (and thus know what its new\nlinear address is).\n\nThe selector and offset returned identify the address of the protected\nmode entry point in the debugger (see below). This entry point should\nbe called via a USE32 far call as it might be a task gate.\n\n\nINT 67h\nAX = 0DEF3h\t Initialize Debugger IDT Entry\n\nINPUTS: \t BX = interrupt #\n\t\t ES:DI ==> IDT entry for interrupt BX\n\t\t If ES = 0, EDI ==> ...\n\nOUTPUTS:\t AH = 00h if successful\n\t\t = 83h if interrupt # not supported by the debugger\n\t\t = 84h if VCPI not supported\n\t\t = 8Fh if debugger support not present\n\n\nThis call allows the client to selectively activate the debugger's\ninterrupt handlers. Because some debuggers may support more interrupt\nhandlers than others, it is recommended that the client call this\nfunction for all interrupts between 00h and 1Fh. If the debugger\ndoesn't support a particular interrupt number, it will return an error\ncode which the caller can ignore.\n\nSome interrupt numbers may be handled wholly by the debugger (not\npassed on to the previous handler). Some may be chained, with the\ndebugger handling only certain situations (as may be the case if the\n8259A's interrupt numbers overlay CPU fault interrupt numbers). For\nthis reason, the client should initialize the IDT entry with a valid\nhandler in case the debugger passes along the interrupt.\n\nBecause this call may be invoked multiple times on the same interrupt\nnumber, the debugger must check the existing entry to see if it is the\nsame as the value to which it would initialize the entry. If that's\nthe case, the debugger should ignore the call and return a successful\nresult code.\n\nIf you are writing a PM program which enters PM via VCPI, your call to\nthe VCPI Get PM Interface (DE01) must precede this call as 386SWAT\nneeds to hook into the latter call in order to ensure that its PTEs\nare visible when the VCPI client is active (and thus know what its new\nlinear address is).\n\n\nINT 67h\nAX = 0DEF4h\t Set New Debugger CR3 and Linear Address\n\nINPUTS: \t EBX = new CR3 or -1 if unchanged\n\t\t EDX = new linear address or -1 if unchanged.\n\nOUTPUTS:\t AH = 00h if successful\n\n\nThis call is used in conjunction with functions DEF2 and DEF3 if your\nprogram enters PM without using either VCPI or DPMI. In that case,\nthis case must precede the calls to functions DEF2 and DEF3 and you\nmust also call function DEF9. If EDX == -1 on entry, SWAT will return\nthe current linear address in EDX upon return.\n\n\nINT 67h\nAX = 0DEF5h\t (Reserved)\n\n\nINT 67h\nAX = 0DEF6h\t Symbol Table Management Functions\n\nINPUTS: \t BL = 00h Append ECX names from DS:ESI\n\t\t ECX = # names to append\n\t\t DS:ESI ==> table of names to append (see SYMC_STR)\n\nOUTPUTS:\t AH = 00h if successful\n\t\t AH = 88h if not\n\t\t ECX = # symbols appended\n\n\nSYMC_STR struc\n\nSYMC_FVEC df\t ?\t\t; Seg:Off or Sel|Off\nSYMC_FLAG dw\t ?\t\t; Flags: see SYMFL_REC below\nSYMC_GRP dw\t ?\t\t; Group # (arbitray value may be used\n\t\t\t\t; with TS command from the command\n\t\t\t\t; line to group symbols)\nSYMC_NAMLEN db\t ?\t\t; Length byte\n\t db\t ? dup (?)\t; ASCII name (no terminating zero)\n\nSYMC_STR ends\n\nSYMFL_REC record $SYMFL_VM:1,$SYMFL_TYP:5,$SYMFL_RSV:10\n\n@SYMFL_VM equ\t mask $SYMFL_VM ; 1 = symbol is for VM\n\t\t\t\t; 0 = ...\t PM\n\t\t\t\t; The above flag is meaningful for _DAT and _LN\n\t\t\t\t; types only.\n@SYMFL_TYP equ\t mask $SYMFL_TYP ; Data types:\tsee @SYMTYP_xxx below\n@SYMTYP_DAT equ 0\t\t; Code or data\n@SYMTYP_LN equ 1\t\t; Line number record constructed by MAPSSF\n@SYMTYP_ABS equ 2\t\t; ABS record\n@SYMTYP_SWT equ 3\t\t; Symbol is for SWAT internal use\n\n\nINPUTS: \t BL = 01h Search for name DS:ESI\n\t\t DS:ESI ==> name to search for (see SYMC_STR)\n\nOUTPUTS:\t AH = 00h if successful\n\t\t AH = A0h if not found\n\nINPUTS: \t BL = 02h Translate old symbol to new\n\t\t DS:ESI ==> SYMTRAN_STR (see below)\n\nOUTPUTS:\t AH = 00h if successful\n\n\nUse this call to translate a symbol's segment/selector and group to a\nnew segment/selector and base.\n\nSYMTRAN_STR struc\n\nSYMTRAN_OSEL dw ?\t\t; Old segment/selector\nSYMTRAN_OGRP dw ?\t\t; Old group #\nSYMTRAN_NFLAG dw ?\t\t; New flags\nSYMTRAN_NSEL dw ?\t\t; New segment/selector\nSYMTRAN_NBASE dd ?\t\t; New base (to be added to all offsets)\nSYMTRAN_FLAGS dw ?\t\t; Flags for match significance\n\nSYMTRAN_STR ends\n\n; Flags used in SYMTRAN_FLAGS to indicate which elements in SYMTRAN_STR\n; are to be ignored.\n; $SYMFL_ADDVMSEG indicates that the new segment value is to be added\n; to all V86 mode segments.\nSYMTFL_REC record $SYMTFL_IGOSEL:1,$SYMTFL_IGOGRP:1,$SYMTFL_IGNFLAG:1,\\\n\t$SYMTFL_IGNSEL:1,$SYMTFL_ADDVMSEG:1,$SYMTFL_RSVD:11\n\n\nINPUTS: \t BL = 03h Flush the symbol table\n\nOUTPUTS:\t AH = 00h if successful\n\nINPUTS: \t BL = 04h Append without replacing existing symbols\n\t\t\t (allow duplicates of existing symbols)\n\t\t\t (same as BL=00h)\n\nOUTPUTS:\t AH = 00h if successful\n\nINPUTS: \t BL = 05h Execute ASCIIZ command in 386SWAT\n\t\t DS:ESI ==> ASCIIZ string containing a command\n\nOUTPUTS:\t AH = 00h if successful\n\nUse this call to execute a command on the 386SWAT command line. This\nfunction is used by the SWATCMD.EXE device driver.\n\nINPUTS: \t BL = 06h Copy ASCIIZ string to error log\n\t\t DS:ESI ==> ASCIIZ string\n\nOUTPUTS:\t AH = 00h if successful\n\n\nINT 67h\nAX = 0DEF7h\t (Reserved)\n\nINT 67h\nAX = 0DEF8h\t (Reserved)\n\nINT 67h\nAX = 0DEF9h\t Fill in 386SWAT's PTEs\n\nINPUTS: \t ECX = maximum # PTEs ES:DI can hold\n\t\t ES:DI ==> save area for PTEs\n\t\t If ES = 0, EDI ==> ...\n\nOUTPUTS:\t AH = 00h if successful\n\t\t AH = 8Bh if 386SWAT needs more PTEs than specified\n\t\t ECX = # additional PTEs 386SWAT needs\n\n\nUse this call in conjunction with function DEF4 if your program enters\nPM without using VCPI or DPMI so that 386SWAT's PTEs are visible in\nyour program's address space.\n\nTo determine how many PTEs SWAT needs without filling them in, call\nthis function with ECX = 0, and on return (with AH = 8Bh), ECX has the\nnumber of PTEs SWAT needs.\n\n\nINT 67h\nAX = 0DEFAh\t (Reserved)\n\nINT 67h\nAX = 0DEFBh\t (Reserved)\n\nINT 67h\nAX = 0DEFCh\t (Reserved)\n\nINT 67h\nAX = 0DEFDh\t Initialize Debugger Interface, Interrupt Gate\n\nINPUTS: \t ES:DI ==> GDT entries for debugger support\n\t\t If ES = 0, EDI ==> ...\n\t\t BX = initial selector\n\nOUTPUTS:\t AH = 00h if successful\n\t\t = 84h if VCPI not supported\n\t\t = 8Fh if debugger support not present\n\t\t BX:EDX = Address of protected mode entry point\n\n\nThis call allows the debugger to setup its own GDT entries as it\npleases. The number of entries it may use is limited to four (4) so\nthe client can statically allocate space in its GDT. Each GDT entry\nused by SWAT is a Code, Data, or LDT selector, and the IDT entries\nused (when DEF3 is called) are Interrupt Gates (cf. DEF2). The\nstarting selector number in BX is needed so that the \"Initialize\nDebugger IDT Entry\" call knows what selectors to use when initializing\nan IDT entry. Consequently, this call must precede that call in order\nto know the proper selector value.\n\nIf you are writing a PM program which enters PM via VCPI, your call to\nthe VCPI Get PM Interface (DE01) must precede this call as 386SWAT\nneeds to hook into the latter call in order to ensure that its PTEs\nare visible when the VCPI client is active (and thus know what its new\nlinear address is).\n\nThe selector and offset returned identify the address of the protected\nmode entry point in the debugger (see below). This entry point should\nbe called via a USE32 far call as it might be a task gate.\n\n\n\n\t\t Ŀ\n\t\t Protected Mode Program Interface \n\t\t \n\nFor the moment, there are no defined functions. However, when there\nare, we will require that AH = 0DEh and that the subfunction code be\nin AL.\n\n\n\n\n\t\t Ŀ\n\t\t Tips On Debugging DPMI Programs \n\t\t \n\nIf you are using an integrated DPMI host such as 386MAX, no special\naction is needed on your part to debug a DPMI program.\t386SWAT\ninstalls itself as a PL0 extension to the memory manager and thus also\nto the DPMI host. Place breakpoints in your code as needed as well as\nstep right over the far call to the DPMI host which switches from VM\nto PM.\n\nIf you using a non-integrated DPMI host such as QDPMI.SYS which is\ndistributed with QEMM, then essentially you are debugging a VCPI\nclient which provides DPMI services to its clients. See the next\nsection for details on debugging VCPI programs.\n\n\n\n\n\t\t Ŀ\n\t\t Tips On Debugging VCPI Programs \n\t\t \n\nAssuming SWAT has successfully intruded into the MM's (memory\nmanager's) PM context, it is on the same level as MM -- that is, you\nshould think of it as a PL0 extension of the VCPI host. This means\nthat you need to tell SWAT to intrude into the VCPI client's context.\n\nSome VCPI clients are easy to break into, some are quite hostile (not\nmaliciously, it's just that they don't leave any wiggle room).\nThere's no magic to this. Fundamentally, SWAT needs room in the GDT\nfor its selectors. See the above description on how to get your\nprogram to cooperate with SWAT, but if you want to get up and running\nquickly, you might first try these steps:\n\n* Allocate about 30 selectors at the end of the GDT,\n* Initialize the selectors to all zero,\n* Plant an INT 01h/03h in the PM portion of your code or whatever you\n prefer,\n* Type VMSINT ON on the SWAT command line,\n* Start your program.\n\nThe only tricky part is to ensure that any breakpoints you set to\nwhich SWAT would respond occur after the stack in the VCPI client has\nbeen setup (and preferably also DS, ES, FS, and GS). Typically, this\nmeans that you can debug through every single instruction except for\nthe handful which occur during the handoff from the VCPI host's PM\ncontext to the VCPI client's PM context. The reason for this is that\nthe VCPI PM handoff depends upon descriptor caching. In particular,\nthe VCPI spec has the client specifying the state of all EGP\nregisters, but only the CS segment registers. Thus the VCPI client\nstarts off execution with its own environment (GDT, LDT, IDT, TR, and\nCR3) in effect, but on the VCPI host's stack. The value of that stack\nselector quite likely is invalid in the client's GDT/LDT, so the VCPI\nclient must switch to its own stack ASAP. Of course, if an\ninterrupt/exception occurs before then, when the CPU attempts to use\nthe (presumably) invalid stack it would trigger a Double Fault,\nquickly followed by a Triple Fault and system shutdown.\n\nOne other sharp corner I've run into is with VCPI clients which assume\nthat their TSS won't be used by the CPU, so they \"save\" a few bytes by\nre-using that data area. SWAT uses TSS selectors for its IDT entries,\nso when SWAT gains control the CPU saves the preceding context into\nthe caller's TSS. Also, it's a nice touch to save your CR3 into the\nappropriate place in the TSS, but SWAT will do that for you in case\nyou forget. Other debuggers might not be so thoughtful.\n\nAlso, if you switch LDTs from the original one, be sure to save the\ncurrent one in the TSS as that field is read-only. That is, the CPU\ndoesn't save the current LDT there when it performs a task switch, so\nSWAT can't \"see\" your LDT otherwise.\n\nIf your program changes the PIC base(s), use the VCPI call (DE0B) to\ninform SWAT of the change.\n\nAs far as symbols are concerned, use MAPSSF with a .WSG file. See the\nSWATSYM.DOC for more details. After SWAT pops up in PM within your\nprogram, type TS on the SWAT command line to tell SWAT to recalculate\nthe base address of all symbols and symbols should appear. The .WSG\nfile tells SWAT the value of various selectors, but of course it can't\nknow at that time the base address. That's why you need to tell SWAT\nto recalculate.\n\n\n\n\n\t\t Ŀ\n\t\t Tips On Debugging RM Programs \n\t\t \n\nDebugging Real Mode programs is quite similar to debugging VCPI\nprograms, except that you must use the debugging interface to allow\nSWAT to gain a foothold into your PM context. Because there is no\ninterrupt (such as INT 67h for VCPI) when a RM programs enters PM,\nyour program must cooperate with SWAT in order for it to be of use.\n\nAlso note that you cannot trace through the instructions which setup the\nresources the CPU needs to run in PM. In particular, this includes LGDT,\nLIDT, and MOV CR0,r32 (or LMSW), as well as those instructions which\nsetup the segment registers in PM, especially CS and SS (note that CS\nis setup by executing a far jump).\n\n\u001a" }, { "path": "swat/VCPIDBG.HTM", "content": "\n
\n \n \n \nThe premise is that there is already a resident debugger in the system\nwhich the client wishes to use. These calls provide an interface\nbetween the client and the debugger to allow that to happen. In order\nfor the debugger to support this interface, it should intercept INT 67h\nduring its initialization and troll for the following calls, ignoring most\nothers. The debugger may wish to troll for the \"Set 8259A Interrupt\nVector Mappings\" call in order to properly determine where the timer and\nkeyboard interrupts start.\n
\n
If your program enters PM via DPMI using a memory manager with an integrated\nDPMI host, skip all this as 386SWAT hooks into the host's GDT and IDT through\nthe INTRUDE option. Note that DPMI hosts which install as a separate\ndevice driver appear to the memory manager (and thus to 386SWAT) as a VCPI\nclient, so the above advice to skip this document does not apply. \nI haven't tried to debug a DPMI client in this context, so I'm not sure\nhow to do it.\n\n
If your program enters PM via VCPI, use functions DEF0,\nDE01, DEF2,\nand DEF3 in that order so that 386SWAT is\nproperly initialized in your program's GDT and IDT.\n\n
If your program enters PM from RM and uses paging, use functions DEF0,\nDEF4, DEF2,\nDEF3, and DEF9\nin that order although function DEF9 can\nbe executed anytime after function DEF0 executes\nsuccessfully.\n\n
If your program enters PM from RM and does not use paging, use functions\nDEF0, DEF2,\nand DEF3 in that order.\n\n
When debugging VCPI clients, be sure to enable the VMSINT flag either\nby putting the keyword VMSINT\ninto your 386SWAT profile, or by typing VMSINT\nON from the 386SWAT command line.\n
\n
\n
\n
INFO_LEN \ndw ? \n; Byte count of structure\n
INFO_BASE dd \n? ; Physical base address of SWAT code\nsegment\n
SWTINF_VER dw \n? ; Version # of structure\n
More fields are defined which are used by SWATVXD.\n\n
\n
If you are writing a PM program which enters PM via VCPI, your call\nto the VCPI Get PM Interface (DE01) must\nprecede this call as 386SWAT needs to hook into the latter call in order\nto ensure that its PTEs are visible when the VCPI client is active (and\nthus know what its new linear address is).\n\n
The selector and offset returned identify the address of the protected\nmode entry point in the debugger (see below). This entry point should\nbe called via a USE32 far call as it might be a task gate.\n\n
\n
Some interrupt numbers may be handled wholly by the debugger (not passed\non to the previous handler). Some may be chained, with the debugger\nhandling only certain situations (as may be the case if the 8259A's interrupt\nnumbers overlay CPU fault interrupt numbers). For this reason, the\nclient should initialize the IDT entry with a valid handler in case the\ndebugger passes along the interrupt.\n\n
Because this call may be invoked multiple times on the same interrupt\nnumber, the debugger must check the existing entry to see if it is the\nsame as the value to which it would initialize the entry. If that's\nthe case, the debugger should ignore the call and return a successful result\ncode.\n\n
If you are writing a PM program which enters PM via VCPI, your call\nto the VCPI Get PM Interface (DE01) must\nprecede this call as 386SWAT needs to hook into the latter call in order\nto ensure that its PTEs are visible when the VCPI client is active (and\nthus know what its new linear address is).\n\n
\n
\n
SYMC_FVEC df ? \n; Seg:Off or Sel|Off\n
SYMC_FLAG dw ? \n; Flags: see SYMFL_REC below\n
SYMC_GRP dw ? \n; Group # (arbitray value may be used\n
\n; with TS command from the command\n
\n; line to group symbols)\n
SYMC_NAMLEN db ? \n; Length byte\n
\ndb ? dup (?) \n; ASCII name (no terminating zero)\n\n
SYMC_STR ends\n\n
SYMFL_REC record $SYMFL_VM:1,$SYMFL_TYP:5,$SYMFL_RSV:10\n\n
@SYMFL_VM equ mask $SYMFL_VM ; 1\n= symbol is for VM\n
\n; 0 = ... PM\n
\n; The above flag is meaningful for _DAT and _LN\n
\n; types only.\n
@SYMFL_TYP equ mask $SYMFL_TYP ; Data\ntypes: see @SYMTYP_xxx below\n
@SYMTYP_DAT equ 0 \n; Code or data\n
@SYMTYP_LN equ 1 \n; Line number record constructed by MAPSSF\n
@SYMTYP_ABS equ 2 \n; ABS record\n
@SYMTYP_SWT equ 3 \n; Symbol is for SWAT internal use\n\n
\n
SYMTRAN_STR struc\n\n
SYMTRAN_OSEL dw ? \n; Old segment/selector\n
SYMTRAN_OGRP dw ? \n; Old group #\n
SYMTRAN_NFLAG dw ? \n; New flags\n
SYMTRAN_NSEL dw ? \n; New segment/selector\n
SYMTRAN_NBASE dd ? \n; New base (to be added to all offsets)\n
SYMTRAN_FLAGS dw ? \n; Flags for match significance\n\n
SYMTRAN_STR ends\n\n
; Flags used in SYMTRAN_FLAGS to indicate which elements\nin SYMTRAN_STR\n
; are to be ignored.\n
; $SYMFL_ADDVMSEG indicates that the new segment\nvalue is to be added\n
; to all V86 mode segments.\n
SYMTFL_REC record $SYMTFL_IGOSEL:1,$SYMTFL_IGOGRP:1,$SYMTFL_IGNFLAG:1,\\\n
$SYMTFL_IGNSEL:1,$SYMTFL_ADDVMSEG:1,$SYMTFL_RSVD:11\n\n
\n
For the moment, there are no defined functions. However, when\nthere are, we will require that AH = 0DEh\nand that the subfunction code be in AL.\n
\n\n
\n
If you are using an integrated DPMI host such as 386MAX, no special\naction is needed on your part to debug a DPMI program. 386SWAT installs\nitself as a PL0 extension to the memory manager and thus also to the DPMI\nhost. Place breakpoints in your code as needed as well as step right\nover the far call to the DPMI host which switches from VM to PM.\n\n
If you using a non-integrated DPMI host such as QDPMI.SYS which is distributed\nwith QEMM, then essentially you are debugging a VCPI client which provides\nDPMI services to its clients. See the next section for details on\ndebugging VCPI programs.\n
\n\n
\n
Assuming SWAT has successfully intruded into the MM's (memory manager's)\nPM context, it is on the same level as MM -- that is, you should think\nof it as a PL0 extension of the VCPI host. This means that you need\nto tell SWAT to intrude into the VCPI client's context.\n\n
Some VCPI clients are easy to break into, some are quite hostile (not\nmaliciously, it's just that they don't leave any wiggle room). There's\nno magic to this. Fundamentally, SWAT needs room in the GDT for its\nselectors. See the above description on how to get your program to\ncooperate with SWAT, but if you want to get up and running quickly, you\nmight first try these steps:\n
One other sharp corner I've run into is with VCPI clients which assume\nthat their TSS won't be used by the CPU, so they \"save\" a few bytes by\nre-using that data area. SWAT uses TSS selectors for its IDT entries,\nso when SWAT gains control the CPU saves the preceding context into the\ncaller's TSS. Also, it's a nice touch to save your CR3 into the appropriate\nplace in the TSS, but SWAT will do that for you in case you forget. \nOther debuggers might not be so thoughtful.\n\n
Also, if you switch LDTs from the original one, be sure to save the\ncurrent one in the TSS as that field is read-only to the CPU. That\nis, the CPU doesn't save the current LDT there when it performs a task\nswitch, so SWAT can't \"see\" your LDT otherwise.\n\n
As far as symbols are concerned, use MAPSSF\nwith a .WSG file. See the SWATSYM.DOC\nfor more details. After SWAT pops up in PM within your program, type\nTS on the SWAT command line to tell SWAT\nto recalculate the base address of all symbols and symbols should appear. \nThe .WSG file tells SWAT the value\nof various selectors, but of course it can't know at that time the base\naddress. That's why you need to tell SWAT to recalculate.\n
\n
Debugging Real Mode programs is quite similar to debugging VCPI programs,\nexcept that you must use the debugging interface to allow SWAT to gain\na foothold into your PM context. Because there is no interrupt (such\nas INT 67h for VCPI) when a RM programs enters PM, your program must cooperate\nwith SWAT in order for it to be of use.\n\n
Also note that you cannot trace through the instructions which setup\nthe resources the CPU needs to run in PM. In particular, this includes\nLGDT, LIDT, and MOV CR0,r32 (or LMSW),\nas well as those instructions which setup the segment registers in PM,\nespecially CS and SS\n(note that CS is setup by executing a far\njump). \n\n\n"
},
{
"path": "swat/WHATSNEW",
"content": "Version 6.04\n\n* Implement UNREAL as keyword in the 386SWAT.PRO file.\n\n\nVersion 6.03\n\n* Support for display of MMX & SSE instructions\n* Display MMX and SSE registers via Alt-F11.\n* Support for display of FCMOVcc, FCOMI, FUCOMI, FCOMIP, FUCOMIP\n instructions\n* Implement FSONLY keyword to allow SWAT to install in Windows w/o\n DVGA or MDA because you promise to bring up SWAT in a Full Screen\n DOS window only.\n* Implement X15 keyword to tell SWAT to pass through INT 15h memory\n size calls (thus not protecting its own allocated memory). This is \n a debugging keyword only, not for general use.\n* Fix bug where all Family 6 CPUs were thought to support the Last\n Branch/Exception feature, whereas, in fact, only Intel CPUs do. \n This would cause SWAT to reboot during initialization on certain \n Cyrix CPUs.\n* Display + or - sign after jcc instruction if a Branch Hint prefix\n (2Eh or 3Eh) is present.\n\n\nVersion 6.02\n\n* Support MDA hidden by PCI VGA or PCI AGP controller, and secondary\n PCI VGA adapter.\t See SWATIDSP.HTM for more details.\n* Support 4MB pages in PTE display as well as the PTE and SPTE\n commands.\n* Fix bug when using BC on current instruction and G to another\n instruction.\n* Fix bug in display of MOV r32,[EBP*n+disp32].\n* Display appropriate comments on PCI calls (INT 1Ah).\n* Emulate references to the debug registers (DRn) if the GD bit is set\n in DR7.\n* Implement search for not a value, e.g., S addr addr ~val.\n* Implement DLG16 & DLG32 commands to display dialogs when in Windows.\n\n* Extend monitor expressions to BD and BC commands.\n* Implement BP command to break on page references.\n\n\nVersion 6.01\n\n* Implement UNREAL command to allow debugging of Unreal Mode. This\n mode is a variant of Real Mode in which any segment register can\n access all of the 4GB address space.\tThat is, instead of the normal\n 64KB length of a segment, the length is 4GB.\tThis command can\n enable all or just some of the segment registers for Unreal Mode.\n See SWATCMD.HTM for more details.\n\n\nVersion 6.00.002\n\n* Implement s-F10 to save the current screen into the last screen\n buffers.\n* Fix various bugs in 386SWAT's RM Windows support.\n* Implement QS command to display nearest symbol at or before a given\n address.\n* Implement DTE command to display Descriptor Table Entry on the\n command line.\n* Implement MDB command to display a Windows Module Database.\n* Implement TDB command to display a Windows Task Database.\n* Implement .MDB to return Sel|0 of current MDB.\n* Implement .TDB to return Sel|0 of current TDB.\n* Display PDE and PTE bits with PTE command.\n\n\nVersion 6.00.001\n\n* Code reorganization to accommodate logged in versions 5.10.071-9\n* Documentation moved over to HTML format.\n\n\nVersion 6.00.000\n\n* Implement support for Windows kernel debugging. This major upgrade\n is described (to some degree) in WINKDBG.DOC; also see 386SWAT.DOC\n and SWATVXD.DOC.\n\n\nVersion 5.10.079\n\n* Add More Service Routine Text\n\n Add service routine text displays for Win95 VMM routines. This text\n is displayed when decoding INT 20h calls.\n\n\nVersion 5.10.078\n\n* Fix .VMSTK and .VMRET Commands\n\n For some reason, the implementations of the .VMSTK and .VMRET\n commands didn't work, so now they do. Moreover, .VMSTK is now\n called .VMCRS (for Client Register Struc).\n\n\nVersion 5.10.077\n\n* Implement Time Stamp Counter Display\n\n On CPUs which support it (TSC bit set in CR4), display the # clocks\n executed since the last time 386SWAT was entered. There is a\n certain amount of overhead in each entry to 386SWAT, so the numbers\n displayed will never be at the level of single instruction clock\n counts, but it is a good measure of time over a longer set of\n instructions.\n\n\nVersion 5.10.076\n\n* Handle New Windows Keyboard Keys\n\n The Microsoft Natural keyboard contains three new keys:\n\n * Left Windows key\n * Right Windows key\n * Application key\n\n These keys have new scan codes which our keyboard handler now\n recognizes, although we don't do much with them as yet. The left\n and right Windows keys are meant to be modifiers just as Shift,\n Ctl-, and Alt-keys are modifiers. The Application key is meant to\n be an actual keystroke, so I've assigned arbitrary key codes to it\n in its Unshifted, Shift-, Ctl-, and Alt-states.\n\n For the moment, until someone can think of something better, the\n Application key invokes the Help menu.\n\n\nVersion 5.10.075\n\n* Miscellaneous internal changes\n\n\nVersion 5.10.074\n\n* Use Ctrl-Shift-PrtSc To Print Instruction Window Only\n\n When printing multiple instruction screens, repeating the register\n display and other information on the second and subsequent screens\n is unnecessary. To this end, the key combination Ctrl-Shift-PrtSc\n prints the instruction portion of the display only, assuming the\n instruction window is displayed (if not, the entire screen is\n printed as usual).\n\n\nVersion 5.10.073\n\n* Implement Saved Register Clear Command\n\n In case you do not need to restore a saved register set, the saved\n state can be cleared with the RC command.\n\n* In the operand analysis display for an IRETd with NT=1, the back\n link TSS selector is omitted as there's no room for it and all of\n the other information being displayed.\n\n\nVersion 5.10.072\n\n* Implement Command Recall\n\n Commands entered on the command line are saved in a ring buffer\n whose length can be changed from the default of 1024 via the profile\n keyword CMDHIST=nnn.\n\n Previous commands can be retrieved via the keystrokes Alt-<\n (previous command) and Alt-> (next command).\tPressing either of\n these keys repeatedly scrolls through the buffer in the chosen\n direction. The keystroke Alt-? displays a history of (up to 25)\n commands from which a command can be chosen by scrolling up or down\n through the list, or by typing the letter next to the command. A\n command may be deleted from this list via the Del key.\n\n* A bug was fixed when running under Windows where a jump was taken\n with the wrong sense (JZ vs.\tJNZ) if Win386 services are available.\n\n* A new help screen to describe the various searching options is\n defined.\n\n\nVersion 5.10.071\n\n* Fix Bug When Searching For Bytes\n\n In an earlier TWT, when handling Page Faults, the ZF flag was\n cleared without realizing that subsequent code depended upon it\n being set. The effect was that searches for bytes were never found.\n This change fixes that.\n\n\nVersion 5.10.070\n\n* Implement INSERT Command\n\n To debug Windows at the lowest level, we need to be able to insert\n ourselves into Windows startup shortly after it enters PM. To this\n end, the INSERT command is available. It is used from the 386SWAT\n command line at the point just before Windows enters PM.\n\n\nVersion 5.10.069\n\n* Allow Fill Command On Physical Memory\n\n The Fill (F) command used to change data in memory now allows an\n optional trailing P also optionally followed by a CR3, just as the\n Unassemble and other commands allow.\n\n\nVersion 5.10.068\n\n* Fix Bug In Implicit Stack References\n\n When displaying the data (if any) pointed to by the current\n instruction, if the instruction used an implicit stack reference\n (such as the PUSH instruction) we sometimes would use the wrong base\n register (ESP vs. SP). This TWT fixes that bug.\n\n\nVersion 5.10.067\n\n* AutoFault for GP Faults\n\n The Autofault facility has been extended to GP Faults. This means\n that an attempt is made to interpret each GP Fault intercepted by\n 386SWAT in a short sentence.\tType Shift-F4 to see the last\n Autofault error message.\tBecause GP Faults are many and varied,\n some cases will be missed (marked as unknown) or mistaken. Please\n notify the author as you encounter such cases with the exact\n circumstances of the GP Fault so they may be corrected.\n\n\nVersion 5.10.066\n\n* When Running Under Windows, Map In/Out VM's First Megabyte\n\n Previously, when our local keyboard handler was active, we avoided\n checking and setting the keyboard values in the BIOS data area if\n Windows was active because we couldn't be sure that that memory\n region was mapped in. Now that I have discovered Win386 (INT 22h)\n services, we can map in/out that region around references to it.\n\n\nVersion 5.10.065\n\n* Set the GD Bit In DR7\n\n Because some programs get a kick out of resetting the debug\n registers which we've carefully setup, this change has 386SWAT\n automatically set the Global Debug (GD) bit in DR7 on startup so\n that we can stop such programs before they can do any harm. Perhaps\n it doesn't surprise you that Windows is the chief reason for this\n feature.\n\n\nVersion 5.10.064\n\n* Display Real Mode Interrupt Vector Table\n\n As it's a very common data structure to view, the keystroke Shift-F5\n now displays the RM IVT.\n\n\nVersion 5.10.063\n\n* Filter Leading Text From Symbols\n\n Some symbols, especially from Windows programs written in C, are\n prefaced with text such as \"__imp__\", \"_\", and the like which adds\n the symbol's length but not understanding. This feature allows you\n to specify in the 386SWAT profile leading text which is to be\n stripped from each symbol.\n\n\t SYMFILTER = text1 [text2 [...]]\n\n The default settings are\n\n\t SYMFILTER=__imp__ _\n\n Up to 128 characters can be specified in this way.\n\n\nVersion 5.10.062\n\n* Fix Bug When Displaying Long Symbol Names\n\n When we display a symbol names of 50 chars or greater at the top of\n a data screen, we're off by one in our calculations which can cause\n the name to fold to the next line.\n\n\nVersion 5.10.061\n\n* Fix Bug In The Stack Width Change Calculation\n\n Previously, the calculation of when to change stack width (words or\n dwords) occurred only when the code selector changed. In fact, it\n should be checked when the stack selector changes (duh!).\n\n\nVersion 5.10.060\n\n* Fix Bug With Mis-aligned Stack In GP Fault Handler\n\n If the user hooks GP Faults, the handler in LCL_INT0D uses a stack\n structure which is missing one word in the middle. It's amazing it\n has worked at all so far.\n\n\nVersion 5.10.059\n\n* Implement Support For P6 Features\n\n Two P6 features are supported by this TWT.\n\n 1. The Branch Trace Facility (BTF) can be turned on and off via the\n\t command line BTF ON/OFF.\n\n 2. The Last Branch/Exeception From/To registers can be displayed at\n\t all times in the lower right corner of the screen. This feature\n\t can be turned on and off via the command line LBR ON/OFF.\n\n* Skip Over Read/Write From/To Debug Registers If GD Bit Is Set\n\n When the GD bit in DR7 is set, any read from or write to a debug\n register triggers a Debug Fault (and the CPU clears the GD bit from\n DR7 so the Debug Fault handler can use those registers).\n\n Some environments (Microsoft Windows comes to mind) clear the debug\n registers upon entry (and at other times) thus making it difficult\n debug in that context. With this change, setting the GD bit traps\n reads and writes of those registers and handles them transparently.\n A read from a debug register returns the actual value. A write to a\n debug register is ignored. The GD bit can be set from the 386SWAT\n command line via\n\n\tR DR7.GD=1\n\n If you desire this behavior to be the default, use SWATCMD with the\n above argument.\n\n\nVersion 5.10.058\n\n* Add .VM addresses for Windows debugging\n\n Especially when debugging calls from a Windows app down to a VM\n interrupt handler, it is sometimes useful to know where we'll come\n back to in Windows on the other side of the ARPL wall. .VMRET will\n often work if the call was made via DPMI SIMVMI (function 0300h) or\n an INT instruction emulated by the DPMI host (Windows).\n\n* Add Go Monitor command and .CSIP to 386SWAT\n\n The GM (go monitor) command takes an expression which will be\n evaluated as the CPU single-steps (equivalent to Pad-plus or F11).\n No display will occur until 1) the monitor expression evaluates TRUE\n or 2) 386SWAT is invoked by some other means (GP fault, NMI, Ctrl-\n Alt-Pad5, etc.)\n\n Boolean expressions may be constructed using the dyadic operators\n &&, ||, <, <=, ==, >=, and >. Operator precedence is the same as\n the C language.\n\n For example:\n\n GM ah\n\t executes until AH is non-zero.\n\n GM [.csip == 21cd && ah!=9\n\t executes until the current instruction is INT 21 and AH is any\n\t value other than 9 (DOS display string).\n\n GM cx == 0\n\t executes until CX is 0.\n\n GM\n\texecutes until the last expression specified with GM is TRUE.\n\n There are some limitations:\n\n\t1. Currently, GM does not single-step across mode switches via INT\n\t (but will handle any mode switch handled by Pad Plus).\n\t2. It is slow as molasses.\n\t3. With the addition of boolean operators like && and ||\n\t precedence becomes more of something one would reasonably\n\t expect.\n\t4. GM will not work in TSS mode currently (non-critical, failure\n\t mode is the expression doesn't trigger).\n\n\nVersion 5.10.057\n\n* Fix Bug When Testing For Extended Memory\n\n Due to an oversight, when I put in the code to determine the amount\n of extended memory using the INT 15h/0E801h call, I put it in after\n the INT 15h/0DA88h, instead of before. Because of a bug in Phoenix\n 4.04 BIOSes, which crash on the 0DA88h call, the order is important.\n\n Also, when setting up the IDT entry for VCPI debugging using TSSes,\n we used to set the offset to -1 (because the IDT selector is a TSS\n and the offset isn't used). For convenience, I'm now setting the\n low-order byte of the offset to the interrupt #.\tThat way, when\n looking at the IDT in memory (not via F4) it's easy to tell which\n interrupt it covers.\n\n\nVersion 5.10.056\n\n* Workaround Feature In Win95\n\n Because of a quirk in Win95 (what, only one!), when we blast in the\n PTEs for 386SWAT to address the monochrome and color video buffers\n from local addresses, we need to preserve the AVL bits and set the\n accessed bit so this PTE won't be thought of as one available for\n allocation.\n\n\nVersion 5.10.055\n\n* Handle Large Size 386SWAT With VCPI Clients\n\n If the resident portion of 386SWAT becomes too large (perhaps a\n large SYMSIZE or SAVESCREEN), then we might not be able to debug\n VCPI clients because our footprint exceeds the 4MB limit (one page\n directory) for VCPI.\tIf this happens, we should at least warn the\n user in case s/he intends to debug VCPI clients.\n\n* Fix Bug With Unused GDT Entry\n\n When 386SWAT loads via the 386MAX profile, it is passed its linear\n address when it is a VCPI client in the third of the three GDT\n entries allocated for load modules. This is done because 386SWAT's\n PTEs are part of 386MAX's and get relocated by 386MAX when a VCPI\n client loads.\n\n When 386SWAT intrudes into a Memory Manager, we don't use the third\n GDT entry in the same way, and in some cases we might not even\n allocate a third GDT entry if we have found existing GDT entries for\n an all memory selector and one which maps CR3. In this case (I\n encountered it when intruding into QEMM), we can mistakenly\n reference the third GDT entry. This TWT fixes that.\n\n* Check For Additional Autofault Errors For TSS Faults\n\n If a TSS fault occurs, there are some additional reasons for it\n which we now test for and report on, such as invalid selectors in\n the back link TSS when a return from a nested TSS occurs.\n\n At the same time, I included some additional fault error messages\n which occur when we're using TSSs ourselves (typically when we're\n debugging VCPI clients) which we we're checking for before. This\n also involves moving that error message text from the data to the\n code segment to match where the Autofault code expects it.\n\n Also, I changed references to $PTE_0 to $PTE_G as that's its new\n definition, and checked for Page Fault problems related to that bit\n if PTE Global Extensions are enabled in CR4.\n\n\nVersion 5.10.054\n\n* Handle Multiple GDTs When VCPI Debugging\n\n While tracking down a bug in the CDROM game The 11th Hour, I found\n that 386SWAT needed to handle intruding into multiple GDTs as this\n game appear to use up to three different ones, alternating between\n two quite frequently. We now support up to eight alternating GDTs.\n\n At the same time, I fixed a bug where 386SWAT was not correctly\n recognizing whether or not it had already intruded into a GDT. This\n had the effect of filling up the GDT with 386SWAT's TSS selectors\n which crashed the system in quick order.\n\n Finally, while running VCPITEST to see if I had broken anything in\n the process, I decided to remove the check for VMSINT=ON from the\n VCPI call DE01 (Get PM Interface) in order to allow Intrude 386SWAT\n to work with a cooperating VCPI client without having to set that\n variable. This means that Intrude 386SWAT will insert its PTEs into\n every such call, but that should be harmless. The VMSINT=ON setting\n still controls whether or not 386SWAT intrudes into the VCPI call\n DE0C (Switch From VM To PM).\n\n\nVersion 5.10.053\n\n* Enable Debugging Extensions (If Supported) At Virtual Init Time\n\n The Pentium CPU's debugging extensions are supported in 386SWAT via\n the BD command on an I/O port at which time the $DE bit is set in\n CR4.\tThis change enables them at an earlier time so any other\n program (such as 386MAX) can modify its behavior depending upon\n whether or not the $DE bit is set.\n\n\nVersion 5.10.052\n\n* Make Device Driver 386SWAT Sensitive to Another Extended Memory\n Function\n\n The recent change to 386MAX to support the 0E801h Extended Memory\n function call needs to be copied to device-loading 386SWAT not only\n so it can detect how much extended memory is in the system, but also\n so it can lie to any subsequent program requesting the extended\n memory size through that interface.\n\n\nVersion 5.10.051\n\n* Implement Show PTE Command\n\n Strolling through a large set of Page Tables such as under Windows\n can be tiresome, hence there's a new command. The SPTE command\n works exactly likely the PTE command (displaying the Linear\n address/PDE/PTE on the command line) as well as displaying the\n corresponding PTE (as if you had pressed F5 and scrolled down to the\n appropriate entry).\n\n At the same time, I allowed Ctrl-Up and -Down to scroll through the\n PDEs/PTEs one entry at a time (Up and Down scroll through one line\n at a time).\n\n\nVersion 5.10.050\n\n* Fix Bug When Using TSS For Faults\n\n A previous TWT changed a local routine to be more self-sufficient by\n setting DS within the routine instead of relying upon the caller to\n set this register. Alas, that was a mistake as in some cases we\n rely upon the Invisible Descriptor Cache, particularly when we're\n accessing selector values in the caller's LDT. This TWT fixes that\n to use two routines, one which assumes the global DS has been set,\n one which does not.\n\n At the same time, I fixed a problem with device-loading 386SWAT\n where software INTs 01h, 02h, 03h, and 68h are not being enabled if\n VME is.\n\n\nVersion 5.10.049\n\n* Fix Bug With DEBUG=PMI And Device-Loading 386SWAT\n\n If we're loading as Device 386SWAT at startup, INIT_PROT is called\n at the point where 386SWAT is a temporary VCPI client of the MM.\n Thus the active IDT is that of the VCPI client and INIT_PROT is\n setting up the MM's IDT where the VCPI client has calculated the\n IDT's linear address in the VCPI client's linear address space.\n\n All this is background to say that we can't signal an INT 01h if\n DEBUG=PMI is specified because the active IDT (that of the VCPI\n client) does not have its IDT entries setup for debugging unless\n there's a preceding 386SWAT in the picture. This changes enforces\n that condition.\n\n\nVersion 5.10.048\n\n* Call REST_PROT/INIT_PROT On Windows Entry/Exit With Device-Loading\n 386SWAT\n\n When 386SWAT is loaded as a device driver (whether it was intruding\n into an existing memory manager or loading as VCPI SWAT), previously\n it wasn't handling the transitions into and out of Windows.\n\n When Windows starts up, 386SWAT needs to disable itself (by calling\n its REST_PROT entry point) so that it is in the proper state when\n the 386SWAT VxD calls 386SWAT's INIT_PROT entry point after Windows\n loads. Correspondingly, when Windows terminates, the VxD calls\n 386SWAT at its REST_PROT and 386SWAT needs to call its INIT_PROT\n entry point to re-enable it.\n\n When 386SWAT is loaded from within 386MAX, MAX handles calling the\n proper REST_PROT/INIT_PROT entry points.\tWhen 386SWAT is loaded as\n a device driver, these calls were not made.\n\n Now they are.\n\n\nVersion 5.10.047\n\n* Swap Out Local IDT Entries Around TOGINT Call\n\n When 386SWAT is active, it hooks various interrupts for its own use\n such as the timer, keyboard, cascade, and mouse (the latter two in\n case there's a PS/2-style mouse which goes through the keyboard\n controller).\n\n When we toggle an interrupt via command line (TOGINT xx xx ...), or\n keystroke (Alt-F1, etc.), we need to swap out our local entries\n around the toggle so that we save the new entry in the proper\n (global) location. In particular, this affects TOGINT 0A which is\n hooked locally.\n\n\nVersion 5.10.045 & 5.10.046\n\n* Allow Search Command Of PTEs\n\n When tracking down a bug in Win95, I found it useful to extend the\n search command to search through the PTEs for a specific value. The\n new syntax is\n\n\t S\taddr addr\t# PTE\n\t S\taddr L expr # PTE\n\n where PTE can be any expression.\n\n At the same time, I fixed a bug where a Page Fault during the\n display of the searched for data caused a crash.\n\n* Miscellaneous Changes\n\n 1. Display appropriate comment on DPMI interrupt lines.\tThis also\n\t involves defining a new segment to hold the DPMI function values\n\t (as words).\n\n 2. For display of PTEs, note the PDE which contains the top line of\n\t the display as well as the range of linear addresses covered by\n\t the top line.\n\n 3. For display of PDEs, note the range of linear addresses covered\n\t by the top line.\n\n 4. Display display of PTEs and PDEs, handle not present entries by\n\t displaying \"????????\".\n\n 5. Change the initial mask for memory display to allow 32-bit\n\t values.\n\n 6. Change the number of entries displayed in dword format to eight\n\t by squeezing the entries together. Note that the previous width\n\t can be obtained via the dd/4 command.\n\n 7. Save the previous d?/?? value for later use separately for each\n\t width.\n\n 8. If the selector passed to any routine which calls GETARWBASE is\n\t not present, return with CF=1 to indicate an error. This change\n\t is needed by WINSWAT to avoid displaying an incorrect label for\n\t not present selectors. As it turns out, without this change and\n\t with the new KRNL386, USER, GDI symbol display in WINSWAT the\n\t label displayed for not present selectors is that of the Windows\n\t routine BOZOSLIVEHERE.\n\n\nVersion 5.10.044\n\n* Prepare for Winswat\n\n A feature needed by WINSWAT is the ability to set a temporary\n breakpoint from a Windows program. This requires that we fill in\n the rest of the fields where else this feature is used.\n\n A feature needed by WINSWAT is the ability to refresh debug hooks\n when a selector's linear address changes.\n\n\nVersion 5.10.043\n\n* Make Device Driver 386SWAT Sensitive to PCI Extended Memory Function\n\n The recent change to 386MAX to support the PCI Extended Memory\n function call needs to be copied to device-loading 386SWAT not only\n so it can detect how much extended memory is in the system, but also\n so it can lie to any subsequent program requesting the extended\n memory size through that interface.\n\n\nVersion 5.10.042\n\n* Implement Data Width Switch\n\n When displaying data via the Dx command, a new switch allows you to\n specify the number of elements to be displayed per line.\tFor\n example, to display five (instead of the usual eight) words per\n line, use DW/5.\n\n This feature is a stopgap until I implement a more general data\n record display as in the Periscope debugger.\n\n\nVersion 5.10.041\n\n* Use Monochrome Adapter If Present\n\n Rather than switch to the mono adapter every time I startup the\n system, I thought it easier to implement a keyword to do the same.\n With this keyword (MONO) present, if a monochrome adapter is present\n in the system, it becomes the initial display screen for 386SWAT.\n The monochrome adapter has always been supported by 386SWAT -- this\n just makes it the initial display screen as opposed to the color\n monitor.\n\n\nVersion 5.10.040\n\n* Allow TSS Debugging In VM\n\n If a program enters PM from RM and asks 386SWAT to enter its GDT and\n IDT, as usual we setup TSS selectors for the interrupts we manage.\n If this program subsequently enters VM, we need to handle the\n interrupt via a TSS from VM differently as the stack and register\n interpretation (segments vs. selectors) are different. Previously,\n our TSS interrupt code expected to be entered from PM only, so a\n change is needed.\n\n Also, when debugging such a RM program where the user sets a\n breakpoint shortly after entering PM (via setting the PE bit in CR0)\n but before setting TR, I found that 386SWAT failed miserably because\n it was depending upon there being a valid back link in the local\n TSS.\tThus, more changes were needed to handle an invalid back link.\n In conjunction with this change, the register set command (R) is\n enhanced to allow TR and LDTR (a.k.a. LDT) to be read and set, so\n the user can setup a valid back link should the need arise.\n\n Also, when 386SWAT is installed as a RM debugger, avoid setting TR\n to our local TSS as that changes it from an invalid value to a valid\n value. Unfortunately, this doesn't prevent another program from\n doing the same, but at least we're not the culprit. BTW, unlike the\n LDTR, there seems to be no way to clear (and thus invalidate) the\n Task Register once it's set. Setting TR to zero (which is after all\n its initial state), causes a GP Fault even though the current value\n of TR may be already be invalid.\tThus, once TR is set to an invalid\n (and possibly non-zero) value, it stays that way until set to a\n valid value.\n\n* Clear NT bit in EPM.ASM\n\n After switching into PM, the code in EPM.ASM should clear the NT bit\n in case a subsequent IRET/D occurs (as it does) in order to avoid a\n TSS Fault. Thanks to John Fine for pointing this out.\n\n\nVersion 5.10.039\n\n* Support Spain 172 Keyboard Layout\n\n Thanks to Roberto Deza Asensio, 386SWAT now supports this keyboard\n layout.\n\n\nVersion 5.10.038\n\n* Include Function-Specific Text in INT 21h Comments\n\n Because they occur so often in code, the display of INT 21h\n instructions which are the current instruction now includes\n function-specific text (e.g., \"Write File (handle)\").\n\n\nVersion 5.10.037\n\n* Calculate SYMSIZE based upon the size of the loaded symbol table\n\n Previously, I had attempted to calculate SYMSIZE based upon the size\n of the incoming .SSF file and it didn't work. This time it does.\n The effect is that you don't need to use SYMSIZE with a LOADSYM,\n thus reducing wasted space in 386SWAT's symbol table as well as\n perhaps avoiding a mistake when calculating SYMSIZE and finding it\n is too small.\n\n* Fix Bug In MAPSSF\n\n Due to a bug in my linker, certain far calls weren't fixed up\n properly.\n\n\nVersion 5.10.036\n\n* Support International Keyboards\n\n One of 386SWAT's design goals is to be as unassuming about the\n system as possible, intruding into the system at an absolute\n minimum.\tAs part of achieving this goal, 386SWAT has its own\n keyboard handler so it can debug keyboard actions within the BIOS as\n well as not depend upon the system's keyboard routines or data being\n intact and functional.\n\n One consequence of this is that 386SWAT needs to be changed in order\n to support international keyboards which is what this TWT\n accomplishes.\n\n To this end, the keyword KEYB= is recognized in the 386SWAT profile.\n At the start, the only keyboard supported is the German one -- its\n keyboard layout is 129, so the KEYB= value is GR129.\tOthers can be\n supported as the need arises. See file 386SWAT.DOC under the KEYB=\n entry for the list of supported keyboards.\n\n Thanks to Armin Kunaschik, 386SWAT now supports this keyboard\n layout.\n\n\nVersion 5.10.035\n\n* Include INT 03h and INTO in GPSKIP=INT Processing\n\n When I put in GPSKIP=INT, I checked for the INT xxh opcode (0CDh),\n but forgot about INT 03h (0CCh) and INTO (0CEh).\tThese cases are\n now covered.\n\n\nVersion 5.10.034\n\n* Implement Return Address and Goto Return Address\n\n A common address to jump to is the (near or far) return address of a\n subroutine. This is made easier by using shortened forms of the\n commands one might use to extract these addresses. For details, see\n the \"Common Memory References\" section in 386SWAT.DOC.\n\n\nVersion 5.10.033\n\n* Make NORMLIDT The Default\n\n I've encountered enough circumstances debugging RM where RM LIDT\n redirection has gotten in the way, that I've decided that it's best\n to make NORMLIDT the default and use the (new) keyword RMLIDT to\n enable it when necessary.\n\n\nVersion 5.10.032\n\n* Parse I/O Command line Instructions as LVALs\n\n For greater generality, the command line I/O instructions now allow\n an LVAL instead of just an atom.\tAlso, the IMR command line action\n displays the original values not the ones set by 386SWAT.\n\n\nVersion 5.10.031\n\n* Validate Back Link In Operand Analysis Display for IRET/D\n\n On occasion, I've had the system go poof on an IRET/D when the NT\n bit was set (and I didn't notice that) and the back link TSS was\n invalid for some reason (either bad TSS selector, or something was\n wrong with the TSS, such as the CR3 value was invalid). This TWT\n checks for that condition and reports it as part of the operand\n analysis display for the IRET/D instructions.\n\n\nVersion 5.10.030\n\n* Ensure Default Options Set If No Profile\n\n If the user omits a profile on the 386SWAT device line, we skip out\n before setting default options. Now we don't.\n\n\nVersion 5.10.029\n\n* Handle Invalid Symbol Selectors\n\n If we upload symbols with an invalid selector (say, the *.WSG file\n is for another context -- DPMI vs. VCPI vs.\tRM), the call to\n GETBASE returns an error along with EAX=-1. If this value is used\n for the linear address, the symbol is marked as invalid and the\n address hash code gets confused.\tThis change checks for the above\n eventuality and sets the pseudo-linear address to zero to avoid this\n problem.\tBTW, the symptom is that (say) SWATRUN hangs when\n uploading symbols if it has two or more symbols with the same\n (invalid) linear address, e.g. 300|0.\n\n* At the same time, I upgraded the grammar for LS and PS to accept\n lvals instead of just atoms, thus allowing a wider variety of ways\n of specifying the arguments to these commands. Others in this same\n vein to follow.\n\n\nVersion 5.10.028\n\n* Make INTRUDE The Default Option\n\n Now that INTRUDE is reasonably well debugged, I'm making it the\n default option so users don't need to remember to use it (which has\n happened several times).\tThis will reduce the number of tech\n support questions I get from users of 386SWAT on the Internet. In\n case the user needs to use the VCPI client version of 386SWAT, the\n disabling option VCPISWAT is defined.\n\n\nVersion 5.10.027\n\n* Fix Bug When Running in RM\n\n An earlier TWT introduced a bug (for RM SWAT only) which set the\n B-bit in the stack selector.\tThe problem is that I forgot to reset\n that bit when returning to RM. The solution is to define a new\n selector which has the same characteristics as DTE_SS, except with\n the B-bit is clear. Before returning to RM, we switch to this new\n selector so as to return to an environment which is compatible with\n RM.\n\n\nVersion 5.10.026\n\n* Handle SIGINT 1/3\n\n While debugging an incompatibilty with ViruSafe, I needed a minor\n enhancement to SIGINT to overcome their attempts to fool a RM\n debugger. They used many tricks including self-modifying code, as\n well as installing their own INT 01h/03h handlers. At one point\n their code signals INT 01h which 386SWAT intercepts, of course. I\n needed to signal this interrupt to them, but SIGINT 1 invoked it as\n a PM interrupt, which proceeded to crash the system.\tThe solution\n was to signal INT 01h/03h as a VM interrupt, as well as ensure that\n TF is set in the return flags if it's INT 01h from a single-step (as\n opposed to a software interrupt INT 01h).\n\n* At the same time, I needed to save the incoming value of DR6 which\n triggered another change (and bug fix). The bug fixed is an\n incorrect data value width in a struc missed when I changed the code\n segment from USE16 to USE32.\n\n* A related change cleaned up (and documented) the tests which handle\n the case where 386SWAT is entered other than through a debug\n exception, but with the GD bit set.\n\n\nVersion 5.10.025\n\n* Display MAC Entries\n\n After many years of wading through MAC entries, I decided to\n implement a separate display screen for them (actually, Win95 pushed\n me over the edge -- this is a variant of \"The devil made me do it\").\n\n The keyboard combination of Ctl-M brings up this screen.\n\n* There's also a separate command MACBASE which allows you to set the\n base address of the MAC chain in case it's different from .DMAC.\n This is handy when displaying the DOS subsegment chain.\n\n\nVersion 5.10.024\n\n* Fix Bug In PATH= Profile Routine\n\n When converting over to USE32 data, I missed a place where I should\n have cleared the high-order word of a 32-bit register.\n\n Also, in the process of debugging this problem, I put in several\n more Shift debugging messages.\n\n\nVersion 5.10.023\n\n* Fix Bug With VCPI Get Protected Mode Interface Calls\n\n In order for us to provide debugging services to VCPI clients, we\n need to insert our PTEs into the VCPI client's address space. There\n are several contexts in which this might occur:\n\n 1. 386SWAT is loaded via LOAD= with 386MAX:\tour PTEs are\n\t automatically copied to the VCPI client's address space as part\n\t of 386MAX's response to the Get Protected Mode Interface (GPMI\n\t -- DE01h) call.\n\n 2. 386SWAT is loaded as a VCPI client to a memory manager:\n\t previously we didn't handle this case. Now we use the newly\n\t defined RMDEV_GPMITAIL label in low DOS memory which this\n\t TWT defines an return point in order to catch the tail of\n\t the GPMI call. At this point, we switch back to our code in\n\t extended memory, and copy our PTEs to the end of the GPMI\n\t caller's PTE buffer.\n\n 3. 386SWAT intruded into a MM (possibly 386MAX): previously we\n\t placed a PM return address on the stack and passed control\n\t on to the MM. This doesn't work with all MMs as some check\n\t the VM bit in the flags when interpreting the segment\n\t registers saved on the stack. Now we use the newly defined\n\t DEV_GPMITAIL label which this TWT defines as a return point\n\t in order to catch the tail of the GPMI call.\tAt this point,\n\t we switch back to our code in extended memory, and copy our\n\t PTEs to the end of the GPMI caller's PTE buffer.\n\n\nVersion 5.10.022\n\n* Avoid Page Fault on LIN2PPTE Accesses\n\n The LIN2PPTE subroutine translates a linear address to a pointer to\n the corresponding PTE according to a specific CR3. Sometimes we\n need to read more than one PTE from the Page Directory which doesn't\n always work (because the subroutine doesn't know how many PTEs to\n map in the case we're not mapping relative to the current CR3). A\n solution to this is to tell the subroutine how many PTEs are to be\n mapped in.\n\n\nVersion 5.10.021\n\n* Compatibility With PMODE\n\n There is a popular shareware DOS extender available on the Internet\n called PMODE which is used to create PM programs. When it is run as\n a VCPI client, it allocates selectors from the top down in the GDT\n -- the same as 386SWAT does.\tPMODE uses the AVL bit in the DTE to\n mark a selector as in use, so this change has us set that bit in the\n selectors we allocate so PMODE doesn't write on top of our\n selectors.\n\n\nVersion 5.10.020\n\n* Fix Bug When Swapping INTs\n\n When we swap IDT entries (say when displaying the IDT via F4) so we\n see or act upon the global IDT entries, we don't swap INTs 74h and\n 76h.\tNow we do.\n\n\nVersion 5.10.019\n\n* Use Same DPL When Hooking Interrupts\n\n Some memory managers (pssst, it's EMM386) set the DPL of various\n entries in the IDT to zero expecting the CPU to signal a GP Fault if\n the corresponding software interrupt occurs.\tWhen we intrude into\n their PL0 context, previously we were setting the DPL to three\n because we didn't expect to encounter a MM which had a fetish with\n GP Faults. Now we retain the same DPL as the original IDT entry\n except for INTs 01h and 03h.\tThey are handled differently so we can\n issue the corresponding software interrupts and gain control\n immediately instead of having to hook the GP Fault handler and pick\n them off there.\n\n\nVersion 5.10.018\n\n* Fix Disappearing Cursor Bug\n\n For years we've put up with this bug. Now it's fixed.\n\n The problem occurs in any of three contexts:\n\n * when reviewing last screens (Alt-F10),\n * when switching between color and mono adapters (Alt-F7), or\n * when swapping screens (say, when exiting 386SWAT).\n\n The problem occurs because not all programs maintain a consistent\n set of data values in the BIOS data area on which we rely (e.g., the\n dependence between the cursor type and the cursor emulation bit).\n\n The fix is to read the cursor start and end line values upon entry\n and restore those values in the above circumstances.\tA new routine,\n GET6845 is defined for the read starting value part.\tI seem to\n recall that the original definition of the 6845 registers was that\n they were write-only, but apparently they are now readable as well.\n\n At the same time, while testing the different contexts in which\n 386SWAT changes the cursor type, I noticed that the Enter command\n handles the INS key, but not the XINS key, so I changed it.\n\n\nVersion 5.10.017\n\n* Implement Exit Command\n\n A common command line sequence is to set AH to 4C, SIGINT 21, and G.\n This is now done via a command called EXIT.\n\n\nVersion 5.10.016\n\n* Add Debugging Displays To 386SWAT During Initialization\n\n To help me figure out why 386SWAT wasn't installing under Win95, I\n made several changes:\n\n * Add some debugging displays (press and hold either shift key when\n\t386SWAT is loading ala Shift-MAX).\n * If there are no VCPI services (DEBUG=NOVCPI in 386MAX), fail\n\tgracefully.\n * Ensure interrupts are re-enabled upon returning from VCPI/PM.\n * Ensure that the B-bit is set in our stack selector.\n * Avoid calling CHECK_I92 if we're in VM as it can reboot the system\n\t(learned the hard way).\n * Put in a check to avoid calling OLDINT67_VEC if it's zero (who can\n\targue with that?).\n * Avoid a bug in MASM 5.10b which generates a word fixup when it\n\tshould generate a dword fixup.\tAny questions on why I want to\n\twrite my own assembler?\n\n\n"
},
{
"path": "swat/WINKDBG.DOC",
"content": "\t\t Notes on Windows Kernel Debugging\n\t\t ---------------------------------\n\nWindows implements a low-level debugging interface called Kernel\nDebugging (WKD) which obtains control very early in the startup\nsequence of Windows. The program WDEB386 shipped with the Windows SDK\nis an example of one such program; 386SWAT is another.\n\nWhen Windows sees that a kernel debugger is present, it informs the\ndebugger about a number of events as they occur, principally parameter\nerrors made by running Windows programs as they call Windows API\nfunctions.\tFor example, if a program calls EnableWindow with an\ninvalid window handle (say, zero), this error is passed on to the WKD\nfor processing before returning to the calling program. In this way,\na great many errors can be caught before they can cause any harm.\n\nBy default, 386SWAT is a WKD. If, for some reason, you wish to\ndisable this feature, place the keyword NOWINK into your 386SWAT\nprofile.\n\nAt the current time, you must have a monochrome adapter and monitor\nattached to your system in order for WKD services to be allowed by\n386SWAT. 386SWAT tests for a mono card and disables WKD if not found.\n\n\nNew Command Line Actions\n------------------------\n\n* To enable or disable WKD services entirely, use\n\n\tWKD [ON|OFF]\n\n This option is available outside Windows only. If you have\n specified NOWINK in the 386SWAT profile, this option has no effect\n -- you must remove that profile option and reboot the system to\n enable WKD services.\n\n* To change the response to a parameter error, use\n\n\tWKD [NOISY|QUIET]\n\n If NOISY is specified, then each parameter error is followed by the\n prompt \"Break, Ignore, Quiet?\" to which you must respond B, I, or\n Q.\n\n A response of Q, is equivalent to setting WKD QUIET after which\n parameter errors are logged to the screen, but execution does not\n stop for any more parameter errors until you break into 386SWAT and\n type WKD NOISY on 386SWAT's command line. This is the default\n state, so you'll see parameter errors fly past on the mono screen\n without pause. I recommend that when you are debugging your own\n code, use WKD NOISY; otherwise, use WKD QUIET. This is because many\n commercial packages contain so many parameter errors that you'll\n constantly be interrupted with a BIQ prompt.\n\n A response of I, ignores this one error only and continues\n execution.\n\n A response of B, triggers a single step breakpoint at an IRETD\n inside 386SWAT. Tracing over this instruction returns to the\n instruction inside Windows immediately following the call to\n 386SWAT (typically an INT 41h). Tracing from this point on\n eventually gets you back to a call to LogError which was called by\n the Windows API function which encountered the invalid parameter,\n and then back to the application which called the Windows API with\n an invalid parameter. If the application is Win32, then you'll have\n to trace back through a thunking layer before you get to the\n application.\tThis can be quite tricky. At some point, I'll try to\n put in some stack tracing to aid this process.\n\n* Sometimes Windows and/or applications make direct calls to LogError\n as opposed to indirect calls as part of a parameter error. These\n calls are uncommon, so there is a separate switch to control\n 386SWAT's response to such an event. Use\n\n\tWKD LOGERROR [ON|OFF]\n\n to change the response of stopping at an IRETD inside 386SWAT or\n not.\tThe default setting is OFF.\n\n* Sometimes an application is bad enough that it triggers an\n unrecoverable fault (typically a GP or Page Fault) and it must be\n terminated. Windows gives the WKD a crack at it first to which\n 386SWAT responds by stopping in the application at the faulting\n instruction, thus giving you the opportunity to debug the problem.\n If you wish to tell Windows to handle the fault itself (typically\n by terminating the application), use\n\n\tWKD FAULT SKIP\n\n If you do not want to receive any more fault messages from Windows,\n use\n\n\tWKD FAULT OFF\n\n To restart receiving fault messages, use\n\n\tWKD FAULT ON\n\n* The keystroke Ctrl-K brings up a menu from which you can choose to\n display various internal Windows structures.\tAt the moment, the\n only one which has been fleshed out is the display of the Windows\n Global Heap (WGH). The WGH contains one entry for each globally\n allocated region of memory. For example, the various code and data\n segments of KRNL386.EXE are global allocations and have entries in\n this table. To scroll through this table, use the usual up and down\n arrow keys as well as Page Up and Page Down.\n\n To search through the WGH for a specific entry, use the SGH command:\n\n SGH [/b|/s|/h|/o] [/c] expr\n\n The expression (expr) entered is interpreted as a base address if /b\n is specified, size if /s, handle if /h, and owner if /o. If /c is\n specified, the search continues from the currently displayed entry;\n otherwise, the search starts at the top of the heap.\tIf the value\n is found in the WGH, the WGH is displayed with the matching entry at\n the top of the screen. If you wish to repeat the search (perhaps\n becayse there are multiple entries with the same owner), either\n retype the command (and specify /c so the search continues with the\n next entry after the one at the top of the screen), or start the\n command with a slash so it is not erased after successful execution.\n If the value is not found in the WGH, an error message is displayed.\n\n* If Invalid Page Faults are being trapped by SWAT's VxD (see\n SWATVXD.DOC for more details), use the IPF command to control how\n these events are to be handled.\n\n IPF [/d] [/s] [/r] expr\n\n where /d tells SWAT not to display a message on the mono screen\n describing this event, /s tells SWAT not to stop when this event\n occurs, /r tells SWAT to remove this entry from its local tables,\n and expr is an expression which evaulates to a linear address\n corresponding to the Invalid Page Fault.\n\n* To display the memory pointed to by a selector as a Module Database,\n use\n\n MDB expr\n\n* To display the memory pointed to by a selector as a Task Database,\n use\n\n TDB expr\n\n* Certain commands usually preceded with a dot are automatically\n passed to Windows for processing by WIN386, assuming Windows is\n active and WIN386 services are available. These commands include\n\n ?\t\tDisplay a Help screen with the available commands\n .?\t\tDisplay a list of registered dot commands (e.g., .M)\n .R [#]\tDisplay the registers of the current thread (or thread #)\n .VM [#]\tDisplay the complete VM status of the current VM (or #)\n .VC [#]\tDisplay the current VM's (or #) control block\n .VH [#]\tDisplay a VMM linked list, given list handle\n .VR [#]\tDisplay the registers of the current VM (or #)\n .VS [#]\tDisplay the current VM's (or #) virtual stack\n .VL\t\tDisplay list of all valid VM handles\n .DS\t\tDisplay protected mode stack with labels\n .VMM\t\tDisplay menu of VMM state info\n . Windows implements a low-level debugging interface called Kernel Debugging\n(WKD) which obtains control very early in the startup sequence of Windows. \nThe program WDEB386 shipped with the Windows SDK is an example of one such\nprogram; 386SWAT is another.\n\n When Windows sees that a kernel debugger is present, it informs the\ndebugger about a number of events as they occur, principally parameter\nerrors made by running Windows programs as they call Windows API functions. \nFor example, if a program calls EnableWindow with an invalid window handle\n(say, zero), this error is passed on to the WKD for processing before returning\nto the calling program. In this way, a great many errors can be caught\nbefore they can cause any harm.\n\n By default, 386SWAT is a WKD. If, for some reason, you wish to\ndisable this feature, place the keyword NOWINK\ninto your 386SWAT profile.\n\n At the current time, you must have a monochrome adapter and monitor\nattached to your system in order for WKD services to be allowed by 386SWAT. \n386SWAT tests for a mono card and disables WKD if not found.\n New Command Line Actions\n\n The WKD command takes several options:\n If you do not want to receive any more fault messages from Windows,\nuse\n\n WKD FAULT\nOFF\n\n To restart receiving fault messages, use\n\n WKD FAULT ON\n\n * The keystroke Ctrl-K brings up a menu of items to\ndisplay from which you can choose various internal Windows structures. \nAt the moment, the only one which has been fleshed out is the display of\nthe Windows Global Heap (WGH). The WGH contains one entry for each\nglobally allocated region of memory. For example, the various code\nand data segments of KRNL386.EXE are global allocations and have entries\nin this table. To scroll through this table, use the usual up and\ndown arrow keys as well as Page Up and Page Down.\n\n * To search through the WGH for a specific\nentry, use the SGH command:\n\n SGH\n[/b|/s|/h|/o] \n[/c] expr\n\n The expression (expr) entered is interpreted as a base address\nif /b is specified, size if /s,\nhandle if /h, and owner if /o. \nIf /c is specified, the search continues\nfrom the currently displayed entry; otherwise, the search starts at the\ntop of the heap. If the value is found in the WGH, the WGH is displayed\nwith the matching entry at the top of the screen. If you wish to\nrepeat the search (perhaps because there are multiple entries with the\nsame owner), either retype the command (and specify /c\nso the search continues with the next entry after the one at the top of\nthe screen), or start the command with a slash so it is not erased after\nsuccessful execution. If the value is not found in the WGH, an error message\nis displayed.\n\n * If Invalid Page Faults are being trapped\nby SWAT's VxD (see SWATVXD.DOC for more details),\nuse the IPF command to control how these events are to be handled.\n\n IPF\n[/d] [/s] \n[/r] expr\n\n where /d tells SWAT not to display a message\non the mono screen describing this event, /s\ntells SWAT not to stop when this event occurs, /r\ntells SWAT to remove this entry from its local tables, and expr is\nan expression which evaulates to a linear address corresponding to the\nInvalid Page Fault.\n\n * To display the memory pointed to by a selector as a Module Database,\nuse\n\n MDB\nexpr\n\n * To display the memory pointed to by a selector as a Task Database,\nuse\n\n TDB\nexpr\n\n * Certain commands usually preceded with a dot are automatically passed\nto Windows for processing by WIN386, assuming Windows is active and WIN386\nservices are available. These commands include\n Profile Options\n\n Because 386SWAT is a WKD, it is given much more information to process. \nMuch of that data is stored in its internal log file (acessible via Ctl-F10)\nwhich means that you should increase the log file's default size. \nYou might experiment with different values, but I suggest using something\non the order of LOGSIZE=100000.\n\n During Windows startup while still in RM/VM, Windows loads the real\nmode portion of all of the VxDs to be used this Windows session. \nAt this time, Windows tells the WKD about these VxDs and where they will\nbe loaded in memory when in PM, and 386SWAT logs this information in two\nways.\n\n The first way is to write a line to the mono display with the data about\neach segment (code or data) of the form\n\n Loaded VxD VxDname,\nmodule Modname at address\nlen length\n\n The second way is to append a symbol to 386SWAT's symbol table of the\nform VxDname_Codennnn or VxDname_Datannnn,\nwhere nnnn is a decimal sequence number starting at 1\nand is used to distinguigh one code/data segment from another. By\nconvention in Windows, code segments are in selector 0028h\nand data segments are in selector 0030h. \nThese symbols are useful when debugging VxDs.\n\n In order to save this information, you need to tell\n386SWAT how much space to reserve. The profile option WKDLS\n(Load Segments) is used for this purpose. The actual\nvalue depends upon how many VxD code and data segments are loaded on your\nsystem. I use WKDLS=700. If you\nhave no interest in debugging VxDs, omit this profile option as the default\nvalue is zero which reserves no space. You might also want to increase\nthe profile value for SYMSIZE. \nI use SYMSIZE=700000 (you do have 32MB of\nRAM, don't you?).\n Debugging DLLs\n\n The Windows SDK (3.1x or 95) contains separate copies of various system\nDLLs each of which contain more messages and checks on Windows execution. \nI haven't played with these much, so you're on your own, but it may be\nvery worthwhile. They also contain symbol files for which I haven't\nas yet put in code to load.\n SWAT VxD\n\n This version of 386SWAT no longer requires that you load SWATVXD.EXE\nas a resident program (thus saving you a few bytes of DOS memory), but\nthe VxD must be in same directory as 386SWAT.LOD. The VxD is now\nloaded by 386SWAT when Windows starts up. See the file SWATVXD.DOC\nfor more information on how to configure the VxD.\n Loading 386SWAT\n\n If you are running 386MAX as your memory manager, you could load 386SWAT\nfrom the 386MAX profile with the LOAD= keyword. \nHowever, because this mechanism doesn't provide for 386SWAT to have a DOS\nfootprint and such a footprint is needed for WKDing, I do not recommend\nloading SWAT this way anymore. Instead, load 386SWAT as a device\ndriver on the line which immediately follows the line which loads the memory\nmanager. 386SWAT must load in low DOS memory, so don't try to load\nit high. The low DOS memory footprint of 386SWAT is about 2KB. \n\n\n"
},
{
"path": "switcher/main.cpp",
"content": "#include
\n\n\n
\n WKD [ON|OFF]\n
\n\n
\n WKD [NOISY|QUIET]\n
\n\n
\n WKD LOGERROR\n[ON|OFF]\n
\n\n
\n WKD FAULT\nSKIP\n\n\n
\n \n\n\n \n\n? \n\nDisplay a Help screen with the available commands \n\n \n\n.? \n\nDisplay a list of registered dot commands (e.g., .M) \n\n \n\n.R [#] \n\nDisplay the registers of the current thread (or thread #) \n\n \n\n.VM [#] \n\nDisplay the complete VM status of the current VM (or #) \n\n \n\n.VC [#] \n\nDisplay the current VM's (or #) control block \n\n \n\n.VH [#] \n\nDisplay a VMM linked list, given list handle \n\n \n\n.VR [#] \n\nDisplay the registers of the current VM (or #) \n\n \n\n.VS [#] \n\nDisplay the current VM's (or #) virtual stack \n\n \n\n.VL \n\nDisplay list of all valid VM handles \n\n \n\n.DS \n\nDisplay protected mode stack with labels \n\n \n\n.VMM \n\nDisplay menu of VMM state info \n\n \n.dev_name \n\nDisplay device-specific info \n
\n\n
\n\n
\n\n