...
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.txtsection 3). Some bugs appear only in Release because, according toMBBS10.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]- |
>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)) < 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->usrclsin 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¦=NOPAGE; 533 ; 534 0316 C4 |
1E |
0077r les bx,dword ptr tptr 535 |
031A 26: 83 |
0F 01 or word ptr es:[bx],1 536 ; 537 ; usrptr- |
>substt=1; 538 ; 539 |
031E B8 |
0000s mov ax,seg _usrptr 540 0321 |
8E C0 mov es,ax 541 0323 26: C4 |
1E |
0000e les bx,dword ptr es:_usrptr 542 |
0328 26: C7 47 |
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