Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

Applies to: v10

Debugging a v10 add-on: to debug in Release mode, start the BBS, then in Visual Studio choose Debug, Attach to Process, and select wgserver.exe (MBBS10.txt section 3). Some bugs appear only in Release because, according to MBBS10.txt, Debug builds zero out pointers (so garbage memory does not always show up), and likewise for string-literal misuse (chapter 29, section 29.4). The Debug-pointer-zeroing statement is the author's observation: unverified.

...

To write code that will only execute when it’s compiled for the debug version, use the DEBUG define:

Code Block
#ifdef DEBUG
    for (i=0 ; i < MAXLST ; i++) {
        if (list[i] == NULL) {
            catastro("NULL list entry!");
        }
    }
#endif
Assertions

An easy to use debugging tool is the assertion. Assertions are failures triggered by the ASSERT() macro. ASSERT() is used to assert that a condition is always true. When DEBUG is not defined, ASSERT() calls are not evaluated. When DEBUG is defined, ASSERT() will fail if the passed condition is not true. In the failure message will be the filename, file version, line number, and specific condition that failed. By default, assertion failures take the form of catastro() crashes. But, assertions can be altered to fail in different ways, as described below.

...

If you would like to use ASSERT() in one of your C files, you’ll first need to define the FILREV symbol at the top of it as the version number of the file. If your version control system doesn’t offer the ability to automatically fill in text with version numbers, you’ll have to maintain this number yourself:

Code Block
#define FILREV "1.0.4.1"

To use ASSERT(), just call it like a function, passing it a condition to test:

Code Block
ASSERT(ptr != NULL);

The ASSERTM() macro is the same as ASSERT(), except it allows you to specify a special message to appear in resulting failure messages in place of the condition string:

Code Block
ASSERTM(ptr != NULL,"Developer passed NULL to rsp2read()!");

It’s critical that you are careful not to write any ASSERT()s or other debug-only code that will alter the manner in which non-debug code will run. For example:

Code Block
ASSERT(i++ != 3);

In this example, the debug version will increment i, the non-debug version won’t. The following code may rely on i being incremented, and work fine as long as you’re running the debug version. Once you build final, non-debug shipping disks, you’ll be surprised to find a new bug. Bugs caused by debugging code are often the most painful.

...

Another helpful method of debugging involves using phase transitions. Phase transitions are used to track the basic flow of code by recording major events. The BEG_PHASE() and END_PHASE() macros are used to record the beginning and end of phases or events. The last x phase transitions are reported in catastro() and GP crashes to help understand what led to the crash. BEG_PHASE() and END_PHASE() both take a string and a long for a brief description of the phase and any relevant data. Generally, they are used to bracket some well-defined set of code:

Code Block
BEG_PHASE("Status handling",0);
(*(module[usrptr-
>state
>state]-
>stsrou
>stsrou))();
END_PHASE("Status handling",0);

In the above case, the phase transitions bracket a module’s handling of a status code. BEG_PHASE() and END_PHASE() calls don’t necessarily have to have a one-to-one correspondence:

Code Block
BEG_PHASE("Global commands",0);
for (i=0 ; i < nglobs ; i++) {
    rc=(*globs[i])();
    END_PHASE("Global command",globs[i]);
    :
    :
}

In the above case, the address of the global command just executed is included as the extra parameter to END_PHASE(). This will report the address of the global command just executed along with the Global command end transition message.

...

If you create any debug-only CNF options, put them in CNF’s level 95. That’s the level where all debugging options go by default. A Sysop can edit those options by running CNF directly from DOS with a special command-line parameter:

Code Block
CNF -L95
The Baseline's Debugging Module

...

For example, consider the following code fragments:

Code Block
                ...
                      blah(margv[0],NULL);
                ...
                blah(stg1,stg2)
                char *stg1,*stg2;
                {
                        if (strcmp(stg1,stg2) == 0) {
                              ...

This will cause a GP when strcmp() is called, because although NULL is not an illegal value for a pointer, to access memory through it is an illegal operation. Right? When you pass NULL as a pointer, you never mean “go to the memory at absolute memory location zero and look at whatever bytes are there.” You mean “this here is the absence of a pointer”. This is not a problem in real mode ordinarily because absolute memory location zero has some garbage in it that is unlikely to match a normal string. Referring to NULL may be similar to referring to the empty string, "", and it is possible when writing real mode programs to form the bad habit of using the two interchangeably. Protected mode is not going to let you get away with this.

...

The most common way this happens in practice is if you use invalid array indices. However, not every invalid array access attempt will cause a GP. It is complicated, because protected mode will only detect an attempt to go outside a whole segment, and one segment may contain several arrays, variables, structures, etc. A classic example of this kind of bug is the innocent looking little binary search routine in none other than Kernighan & Ritchie’s revered tome “The C Programming Language”, first edition, page 129 (we reformatted the code to match our own formatting standards):

Code Block
         1      struct key *binary(word,tab,n)
         2      char *word;
         3      struct key tab[];
         4      int n;
         5      {
         6           int cond;
         7           struct key *low,*mid,*high;
         8
         9           low=&tab[0];
        10           high=&tab[n-1];
        11           while (low <= high) {
        12                mid=low+(high-low)/2;
        13                if ((cond=strcmp(word,mid-
>keyword
>keyword)) < 0) {
        14                     high=mid-1;
        15                }
        16                else if (cond > 0) {
        17                     low=mid+1;
        18                }
        19                else {
        20                     return(mid);
        21                }
        22           }
        23           return(NULL);
        24      }

This code begins to come unglued if the sought keyword fits sequentially before all entries in the sorted tab[] array, and the tab[] array just happens to physically reside at the beginning of a segment or selector (that is, its offset is 0x0000). Then the instruction in line 14 eventually does this: high=&tab[-1]. That pointer computation results in an offset of 0xFFFF or thereabouts. This does not generate a GP yet, because the high pointer is not dereferenced.

...

To fix this code, you could put the following three lines between lines 13 and 14:

Code Block
        13.1            if (mid == low) {
        13.2                 break;
        13.3            }

And, to be truly thorough about it (in protected mode this tends to be a good idea), you can guard against the possibility that the top of the table is flush up against the high bound of a full 64K data segment by inserting the following between lines 16 and 17:

Code Block
         16.            if (mid == high) {
         16.2                break;
         16.3           }

Another example of this is a situation in which you wish to truncate a string to a certain maximum length, without knowing in advance just how much storage has been allocated for the string. Consider the following code fragments:

Code Block
        :
             speak("hi there");
        :
        speak(stg)
        char *stg;
        {
             char temp;
             temp=stg[20];
             stg[20]='\0';
             printf(stg);
             stg[20]=temp;
        }

In real mode, this is not a problem because even if the memory location that is 20 beyond the start of stg is in some other segment, you are putting it back to what it was when you are through. In protected mode, though, this type of thing can generate an immediate GP, depending on how close the "hi there" string is to the end of the segment in which it is allocated.

...

Keep in mind that GP.OUT accumulates reports, so you’ll want to look at the bottom of the file. Here is an example of one report in a GP.OUT file:

Code Block
        WORLDGROUP GP @ 2d4f:031a EC 0000 (recorded 12/16/94 17:11:17)
        GP'ed between 2d4f:0000 _INIT__TELECON and 0000:0000 Unknown
        AX=0000 BX=0000 CX=0000 DX=0787 SI=0005 DI=0054 BP=2a88 ES=0000 DS=2d57 Flags=3246
        Current CS:IP==>26 83 0f 01 b8 f7 04 8e c0 26 c4 1e 87 08 26 c7

        YOUR SYSTEM NAME HERE
        Server Version: 1.00
        User 3  channel 00  User-ID "Sysop"  status 3
        Online level 6, state 5, substate 0
        MSG:galtlc.mcv/-1
        Module "Teleconference"
        Input "T"

        0167=C:\WGSERV\MAJORBBS.EXE
        0717=C:\WGSERV\GALGSBL.DLL
        073f=C:\WGSERV\BBSBTU.DLL
        075f=C:\WGSERV\DOSCALLS
        2a5f=C:\WGSERV\GALMSG.DLL
        2cff=C:\WGSERV\GALRSY.DLL
        2d3f=C:\WGSERV\GALTLC.DLL
        2d6f=C:\WGSERV\GALTXV.DLL
        2d97=C:\WGSERV\GALUIE.DLL
        2dbf=C:\WGSERV\GALXIT.DLL
        2de7=C:\WGSERV\GALTST.DLL
        Stack:
        0707:2a78  04ff  0746  04ff  0054  2f47  04ff  0054  0005               0707:2a88 >2aaa< 0ba3  0197  04ff  0000  098a  0197  04f7               0707:2a98  0000  4f54  0050  2aaa  0029  039f  0074  0065               0707:2aa8  04f7 >2ac0< 529a  018f  0039  28ef  0001  0000               0707:2ab8  04f7  1b32  0003  0000 >2ace< 3579  018f  04f7               0707:2ac8  000e  4f84  018f >2b30< 3099  018f  04f7  022f               0707:2ad8  018f  0707  1b14  0000  0000  0000  0000  0000
        0707:2ae8  0000   0000   0000   011f   96c7  0017   0006  0000          0707:2af8  0707   0000   011f   966b   0017  0e29   0000  0e29          0707:2b08  0000   2b36   0707   0707   0001  1330   26cc  0147          0707:2b18  1b32   0707   1b32   1b14   2b36  4c48   016f  0578          0707:2b28  0707   0587   0707   000f  >0000< 014f   016f  0000          0707:2b38  0000   0000   fdcc   077f  ----  ----  ----  ---             0707:2b48  ----  ----  ----  ----  ----  ----  ----  ---                        0707:2b58  ----  ----  ----  ----  ----  ----  ----  ---                0707:2b68  ----  ----  ----  ----  ----  ----  ----  ---                0707:2b78  ----  ----  ----  ----  ----  ----  ----  ---                0707:2b88  ----  ----  ----  ----  ----  ----  ----  ---                        Routines:
        0197:07c5 _GOPAGE         <     0197:0ba3       <   0197:0e3d _DSPMNU
        018f:4e23 _NXTLOF         <     018f:529a       <   018f:53be _CURUSR           018f:3487 _HDLINP         <     018f:3579       <   018f:35e4 _CLRXRF           018f:2502 _KILETC         <     018f:3099       <   018f:3145 _CONDEX           0000:0000 Unknown         <     016f:014f       <   016f:0155 __CLEANUP
GP Location

The first line of GP.OUT has the CPU instruction pointer CS:IP (or CS:EIP depending on the CPU) contents, which reflect the location (address) of the fault. Usually this points to an instruction that the CPU refused to execute for some reason. This line also tells you when the GP occurred. If you see GPCNT here, then the Sysop has GPHDLR set to YES and the GP reported is not the first (and perhaps not the most informative — have them set GPHDLR to NO and get you another GP.OUT).

...

Applies to: WG3.x

Header check: usrptr->usrcls in WG3.2 (MAJORBBS.H:105; chapter 3).

state 5 usrptr->state (see page 45)

...

In the example above, the GP occurred at address 2d4f:031a. That’s somewhere in GALTLC because GALTLC.DLL starts at 2d3f and the next one, GALTXV, starts at 2d6F. There’s a little more you can find out here. Selectors are created in increments of 8 hexadecimal.

Code Block
        2d3f    GALTLC starting selector
        2d47    \run286\bc4\lib\c0phdll.obj
        2d4F    \WGSERV\phobj\mjrtlc.obj
        2d57
        2d5f    }(other selectors used by GALTLC)
        2d67
        2d6f    GALTXV starting selector
        2d77    :
        2d7f    :

After the starting selector, selectors are created for each of the .OBJ files in the order they are listed in the .LNK file. In GALTLC.LNK there are two .OBJ files. The GP occurred in the code from MJRTLC.OBJ, which of course comes from MJRTLC.C. The offset starts at 0000 in the code from that file, so the error occurred 031a bytes into the object code produced from MJRTLC.C.

...

To get the assembly language listing of MJRTLC.C, we have to generate assembly source code and then assemble it and make a listing:

Code Block
        CD \WGSERV\SRC
        CTDLL -S MJRTLC
        CD \WGSERV\PHOBJ
        TASM MJRTLC,NUL,MJRTLC;

Use CTPH -S for getting the assembly listing of files that are part of the kernel — that go to make up MAJORBBS.EXE. The -S parameter (capital S, not small s) asks for an .ASM assembly source file to be output instead of an .OBJ. Then TASM assembles \WGSERV\PHOBJ\MJRTLC.ASM and makes a listing file in \WGSERV\PHOBJ\MJRTLC.LST. (The nul means don’t generate an .OBJ file from the .ASM file.) That .LST file is pretty big. It’s where the offsets and object code can be found. To find what we’re looking for, there are two clues: The GP location is 2d4f:031a, so we can look in the vicinity of the offset 031a. And the code somewhere near there should be 26 83 0f 01 .... (from the fifth line of GP.OUT). Turns out it’s somewhere exactly at 031a:

Code Block
Turbo Assembler         Version 3.1        07/13/92 11:19:52       Page 10
mjrtlc.ASM
530                     ;
531                     ;         case 0:
532                     ;              tptr-
>flags¦
>flags¦=NOPAGE;
533                     ;
534 0316  C4 
1E
1E 
0077r
0077r        les     bx,dword ptr tptr
535 
031A
031A  26: 83 
0F
0F 01       or      word ptr es:[bx],1
536                     ;
537                     ;              usrptr-
>substt
>substt=1;
538                     ;
539 
031E
031E  B8 
0000s
0000s             mov     ax,seg _usrptr
540 0321  
8E
8E C0                mov     es,ax
541 0323  26: C4 
1E
1E 
0000e
0000e      les     bx,dword ptr es:_usrptr
542 
0328
0328  26: C7 47 
08
08 0001    mov     word ptr es:[bx+8],1

Notice that the sixteen bytes of code don’t match exactly where 0000s goes with f7 04? Those 0000s and 0000e symbols means that the exact object code is not known at compile (or assembly) time. It will take linking and loading to find out those exact values. So, the object code confirms that we’re looking at the right instruction (the or instruction).

...

A scrutiny of the C source logic reveals that tptr is not expected to be initialized here: it’s just a low-level looping pointer. We cheated of course; this is exactly the line we inserted to make this GP happen.

...

Previous: Major BBS v10: 11 More Routines And Variables  |  Contents  |  Next: Major BBS v10: 13 Introduction