386SWAT Symbolic Debugging

Several profile options are new to 386SWAT:

Specify number of address bits to use for address hash table. Values less than 8 and over 12 are ignored.

Address hash table storage in bytes is 2 ^ (ADDRHBITS + 2). The minimum is therefore 1K and the maximum, 16K.

ADDRHBITS defaults to 12. When symbols are present, all possible addresses in the disassembly screen are searched against the address hash table. Possible hits require traversal of the address hash buckets chain, similar to name hash bucket traversal. A "next address bucket" pointer is part of the symbol record. Thus the set of symbol records forms two interleaved linked lists: the address bucket chain and the name bucket chain.

The number of bits specified by ADDRHBITS are taken from a resolved linear address, shifted left 2 bits, and used as an index into the table of dword pointers based at the address contained in SYMNHASH. The address pointed to is an offset from the address in SYMBASE, and points to the beginning symbol record in that address bucket chain. If the value is -1 (FFFFFFFF), there is no such address.

Smaller address hash tables may significantly impact unassembly.

Specify number of 1K blocks to be used for symbol name hashing. Values less than 1 and over 255 are ignored.

To speed symbol name searches, all names are hashed using the following algorithm:

extern unsigned int HASHPRIME;

int hashpjw (char *s)
{
  char *p;
  unsigned long h=0, g;

  for (p=s; *p; p++)
  {
     h = (h << 4) + (unsigned) tolower (*p);
     if (g = (h & 0xf0000000))
     {
       h = h ^ (g >> 24);
       h = h ^ g;
     }
  }

  return ((int) (h % HASHPRIME));
}

HASHPRIME is derived from a table of prime numbers closest to multiples of 256. Here are some examples:

BUCKETS    HASHPRIME
    1         257
    2         509
    3         769
  254       65027
  255       65287

The storage occupied by the name hashing table is HASHPRIMES[BUCKETS-1] * 4, or approximately BUCKETS * 1K.

When a hash value is calculated from a name, that value is shifted left 2 bits and used as an index into the table of dword bucket pointers based at the address contained in SYMNHASH. A bucket pointer may contain -1 (FFFFFFFF) or an offset from the address contained in SYMBASE. In this case, a "bucket" actually points to a symbol record. Next name pointers in each symbol record form a linked list which may be traversed to find an exact name match.

The smaller the BUCKETS value, the longer these bucket chains will be, thus increasing name search time. This is only likely to be a performance hit when loading symbols, since 386SWAT checks for existing symbols by name. Searches for symbols entered at the command line would not be visibly impacted by longer searches.

Enable file I/O functions within 386SWAT. This is needed for using the file browser, and for source level debugging.

LOADSYM=filename.ssf

Specify search path for source browser. If not specified, only the current directory is searched. If a path is specified, the current directory (.) must be included explicitly. For example, PATH=c:\qui\quilib,c:\qui\inst will not search the current directory for source files.

Specify how far 386SWAT continues proximity searches and with what granularity. The default is 1 word. The high order byte of PROXSRCH contains the granularity in bytes, and the low order byte contains the number of units to search. The default is 0201h. 0108h would do byte granular searches from x+1 to x+8.

Proximity searches should not visibly impact disassembly performance. A separate check for an empty symbol table ensures that no time is wasted in unnecessary calls to the symbol search routine (which has its own check for empty tables). No proximity searches are done for label display and data display; this only affects values within the disassembly.

This option sets the number of bytes to be used for the 386SWAT symbol table. The internal format of 386SWAT's symbol table is 12 bytes larger than the symbol table used for the 386SWAT API calls. Each public or line number occupies 23 bytes plus the length of the symbol name.

SYMSIZE is used to calculate a default value for BUCKETS (described below). If BUCKETS is not explicitly defined in the profile, it will be set to min (255, max (1, SYMSIZE / 4096)).

If SYMSIZE is not specified, it will default to 4096 bytes. The default BUCKETS value (if also not specified) will then be 1. See below for BUCKETS storage requirements.

Use SYMSIZE=0 to minimize symbol storage requirements. This will save 4K over the default.

Any symbol may be used as an effective address. For example,

dd 180|{SYMHASH

2001  P  28    DGROUP    ; Comments
2002  P  30    IGROUP    ; More comments

We load the .MAP file before entering Windows:

MAPSSF -wVXD.WSG VXD.MAP

We find that the offsets within the Windows flat model segment are

DGROUP  8001BE24
IGROUP  8020397C

The TS command is used to translate both groups:

ts 28 2001 P 28 8001BE24
ts 30 2002 P 30 8020397C

The complete syntax of the TS command is

TS osel ogrp nflag nsel nbase

The Query Symbol (QS) command may be used to display on the command line the name and distance from a given address. For example,

QS .code

might display as

QS .code = VWIN32_Code0001+00005678

This program is called by SWATRUN to load .MAP files on the fly. It may also be used to produce .SSF files for loading at CONFIG.SYS time (not currently supported by 386SWAT). .SSF files may also be loaded directly by SWATRUN. This is faster than calling MAPSSF every time symbols are loaded.

Besides reading .MAP files, MAPSSF will also process Windows SYM32 files. MAPSSF has been tested with the following .MAP file formats:

• Microsoft LINK
• Microsoft LINK386 flat model
• Borland TLINK

Syntax:

MAPSSF [options] fspec1 [fspec2 [...]]

All options are preceded with - or /

group   mode  sel  group[!segment]  ; comment
 3000    P     50  PGROUP           ; 386MAX code
 3001    P     18  PGROUP!EDATA     ; 386MAX data
 3001    P     18  PGROUP!VALSEG    ; 386MAX data
    0    D      0  PGROUP!NCODE     ; 386MAX non-resident code
    0    D      0  PGROUP!NDATA     ; 386MAX non-resident data
 3002    P    118  IGROUP!ICODE     ; 386MAX extra code
 3003    P    120  IGROUP!IDATA     ; 386MAX extra data
    0    D      0  XGROUP           ; 386MAX non-resident code/data
    0    D      0  PSPGRP           ; PSP group (non-resident)
 3004    P     70  PDTGRP           ; OFFPDT group (uninitialized)

Syntax: Device=d:\path\swatcmd.exe command
  or       swatcmd command

Syntax: SWATRUN [options] progname [arguments]