Using SoftICE

Using Soft I CE
So f t I CE Ver sio n 4 . 3 . 0
f or D r i ve r St ud io 3 . 0 an d
Sof t I CE D r i ve r Sui t e 3 . 0

Tech n ical support is available from our Tech n ical Support Hot lin e or via
our Fron t Lin e Support Web sit e.
Tech n ical Support Hot lin e:
1-800-538-7822
Fron t Lin e Support Web Sit e:
h t t p:/ / fron t lin e.compuware.com
Th is documen t an d t h e product referen ced in it are subject t o t h e
followin g legen ds:
Access is limit ed t o aut h orized users. Use of t h is product is subject t o t h e
t erms an d con dit ion s of t h e users Licen se Agreemen t wit h Compuware
Corporat ion .
2003 Compuware Corporat ion . All righ t s reserved. Un publish ed - righ t s
reserved un der t h e Copyrigh t Laws of t h e Un it ed St at es.
U.S. GOVERNMENT RIGHTS
Use, duplicat ion , or disclosure by t h e U.S. Govern men t is subject t o
rest rict ion s as set fort h in Compuware Corporat ion licen se agreemen t an d
as provided in DFARS 227.7202-1(a) an d 227.7202-3(a) (1995), DFARS
252.227-7013(c)(1)(ii)(OCT 1988), FAR 12.212(a) (1995), FAR 52.227-19,
or FAR 52.227-14 (ALT III), as applicable. Compuware Corporat ion .
Th is product con t ain s con fiden t ial in format ion an d t rade secret s of
Compuware Corporat ion . Use, disclosure, or reproduct ion is proh ibit ed
wit h out t h e prior express writ t en permission of Compuware Corporat ion .
DriverSt udio, Soft ICE Driver Suit e, DriverNet works, DriverWorks,
TrueCoverage, an d DriverWorkben ch are t rademarks of Compuware
Corporat ion . Boun dsCh ecker, Soft ICE, an d TrueTime are regist ered
t rademarks of Compuware Corporat ion .
Acrobat
Reader copyrigh t 1987-2003 Adobe Syst ems In corporat ed. All

righ t s reserved. Adobe, Acrobat , an d Acrobat Reader are t rademarks of
Adobe Syst ems In corporat ed.
All ot h er compan y or product n ames are t rademarks of t h eir respect ive
own ers.
US Pat en t Nos.: Not Applicable.
Doc. 11577
May 16, 2003

i i i

Table of Cont ent s
Pr e f ace
Purpose of Th is Man ual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi
Wh at Th is Man ual Covers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xii
Con ven t ion s Used In Th is Man ual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiii
How t o Use Th is Man ual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiv
Ot h er Useful Documen t at ion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiv
Cust omer Assist an ce . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv
For Non -Tech n ical Issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv
For Tech n ical Issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv
Chapt er 1
Ch o o sin g Yo ur So f t I CE V e r sio n
Soft ICE or Visual Soft ICE? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
Sin gle Mach in e Debuggin g: Soft ICE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
Dual Mach in e Debuggin g: Visual Soft ICE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
But Wh ich On e Sh ould I Use? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
Chapt er 2
W e lco m e t o So f t I CE
Product Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Ben efit s of Soft ICE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
How Soft ICE is Implemen t ed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
Soft ICE User In t erface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
About t h e Symbol Loader . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

i v Usi n g Sof t I CE
Chapt er 3
So f t I CE T ut o r ial
In t roduct ion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Loadin g Soft ICE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Buildin g t h e GDIDEMO Sample Applicat ion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Loadin g t h e GDIDEMO Sample Applicat ion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Con t rollin g t h e Soft ICE Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Tracin g an d St eppin g t h rough t h e Source Code . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Viewin g Local Dat a . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Set t in g Poin t -an d-Sh oot Breakpoin t s . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Set t in g a On e-Sh ot Breakpoin t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Set t in g a St icky Breakpoin t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Usin g Soft ICE In format ion al Comman ds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Usin g Symbols an d Symbol Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Set t in g a Con dit ion al Breakpoin t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Set t in g a BPX Breakpoin t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Edit in g a Breakpoin t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Set t in g a Read-Writ e Memory Breakpoin t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Chapt er 4
Lo ad in g Co d e in t o So f t I CE
Debuggin g Con cept s . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Preparin g t o Debug Applicat ion s . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Preparin g t o Debug Device Drivers an d VxDs . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Loadin g Soft ICE Man ually . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Loadin g Soft ICE for Win dows 9x . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Loadin g Soft ICE for Win dows NT/ 2000/ XP . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Buildin g Applicat ion s wit h Debug In format ion . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Usin g Symbol Loader t o Tran slat e an d Load Files . . . . . . . . . . . . . . . . . . . . . . . . . . 35
Modifyin g Module Set t in gs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Modifyin g Gen eral Set t in gs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
Modifyin g Tran slat ion Set t in gs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Modifyin g Debuggin g Set t in gs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Specifyin g Program Source Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Delet in g Symbol Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Usin g Symbol Loader From a DOS Prompt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
Usin g t h e Symbol Loader Comman d-Lin e Ut ilit y . . . . . . . . . . . . . . . . . . . . . . . . . . 45
NMSYM Comman d Syn t ax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
Usin g NMSYM t o Tran slat e Symbol In format ion . . . . . . . . . . . . . . . . . . . . . . . 46
Ta b l e of Con t en t s v

Usin g NMSYM t o Load a Module an d Symbol In format ion . . . . . . . . . . . . . . . 50
Usin g NMSYM t o Load Symbol Tables or Export s . . . . . . . . . . . . . . . . . . . . . . 53
Usin g NMSYM t o Un load Symbol In format ion . . . . . . . . . . . . . . . . . . . . . . . . 54
Usin g NMSYM t o Save Hist ory Logs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
Get t in g In format ion about NMSYM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
Chapt er 5
N avig at in g T h r o ug h So f t I CE
In t roduct ion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
Un iversal Video Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
Set t in g t h e Video Memory Size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
Poppin g Up t h e Soft ICE Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
Disablin g Soft ICE at St art up . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
Usin g t h e Soft ICE Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
Resizin g t h e Soft ICE Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
Con t rollin g Soft ICE Win dows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
User-Defin able Pop-up Men us . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
In lin e Edit in g . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
Copyin g an d Past in g Dat a . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
En t erin g Comman ds From t h e Mouse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
Obt ain in g Help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
Usin g t h e Comman d Win dow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
Scrollin g t h e Comman d Win dow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
En t erin g Comman ds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
Recallin g Comman ds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
Usin g Run -t ime Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
Savin g t h e Comman d Win dow Hist ory Buffer t o a File . . . . . . . . . . . . . . . . . . 75
Associat ed Comman ds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
Usin g t h e Code Win dow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
Con t rollin g t h e Code Win dow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
Viewin g In format ion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
En t erin g Comman ds From t h e Code Win dow . . . . . . . . . . . . . . . . . . . . . . . . . 80
Usin g t h e Locals Win dow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
Con t rollin g t h e Locals Win dow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
Expan din g an d Collapsin g St acks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
Usin g t h e Wat ch Win dow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
Con t rollin g t h e Wat ch Win dow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
Set t in g an Expression t o Wat ch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
Expan din g an d Collapsin g Typed Expression s . . . . . . . . . . . . . . . . . . . . . . . . . 84

v i Usi n g Sof t I CE
Usin g t h e Regist er Win dow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
Con t rollin g t h e Regist er Win dow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
Edit in g Regist ers an d Flags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
Usin g t h e Dat a Win dow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
Con t rollin g t h e Dat a Win dow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
Ch an gin g t h e Memory Address an d Format . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
Edit in g Memory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
Assign in g Expression s . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
Usin g t h e St ack Win dow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
Usin g t h e Th read Win dow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
Con t rollin g t h e Th read Win dow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
Usin g t h e Pen t ium III/ IV Regist er Win dow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
Usin g t h e FPU St ack Win dow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
Chapt er 6
U sin g So f t I CE
Debuggin g Mult iple Programs at On ce . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
Trappin g Fault s . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
Rin g 3 (32-bit ) Prot ect ed Mode (Win 32 Programs) . . . . . . . . . . . . . . . . . . . . . . 96
Rin g 0 Driver Code (Kern el Mode Device Drivers) . . . . . . . . . . . . . . . . . . . . . . 96
Rin g 3 (16-bit ) Prot ect ed Mode (16-bit Win dows Programs) . . . . . . . . . . . . . . 97
About Address Con t ext s . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
Usin g INT 0x41 .DOT Comman ds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
Un derst an din g Tran sit ion s From Rin g 3 t o Rin g 0 . . . . . . . . . . . . . . . . . . . . . . . . 100
Chapt er 7
U sin g Br e akp o in t s
In t roduct ion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
Types of Breakpoin t s Support ed by Soft ICE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
Breakpoin t Opt ion s . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
Execut ion Breakpoin t s . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
Memory Breakpoin t s . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
In t errupt Breakpoin t s . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
I/ O Breakpoin t s . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
Win dow Message Breakpoin t s . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
Un derst an din g Breakpoin t Con t ext s . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
Ta b l e of Con t en t s vi i

Virt ual Breakpoin t s . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
Set t in g a Breakpoin t Act ion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
Con dit ion al Breakpoin t s . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
Con dit ion al Breakpoin t Coun t Fun ct ion s . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
Usin g Local Variables in Con dit ion al Expression s . . . . . . . . . . . . . . . . . . . . . 117
Referen cin g t h e St ack in Con dit ion al Breakpoin t s . . . . . . . . . . . . . . . . . . . . . 118
Performan ce . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
Duplicat e Breakpoin t s . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
Elapsed Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
Breakpoin t St at ist ics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
Referrin g t o Breakpoin t s in Expression s . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
Man ipulat in g Breakpoin t s . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
Usin g Embedded Breakpoin t s . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
Chapt er 8
U sin g Exp r e ssi o n s
Expression Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
Support ed Operat ors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
Operat or Preceden ce . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
Formin g Expression s . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
Numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
Ch aract er Con st an t s . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
Regist ers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
Symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
Built -in Fun ct ion s . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
Expression Evaluat or Type Syst em . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
Symbol Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
Address Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
In direct ion Operat ors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
Operan d Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
C++ Type Cast in g . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
Evaluat in g Symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
Usin g In direct ion Wit h Symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
Poin t er Arit h met ic wit h Symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
Array Symbols In Expression s . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
Chapt er 9
Lo ad in g Sym b o l s f o r Syst e m Co m p o n e n t s
Loadin g Export Symbols for DLLs an d EXEs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
Usin g Un n amed En t ry Poin t s . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142

v i i i Usi n g Sof t I CE
Usin g Export Names in Expression s . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142
Loadin g Export s Dyn amically . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
Usin g Win dows NT/ 2000/ XP Symbol Files wit h Soft ICE . . . . . . . . . . . . . . . . . . . 143
Usin g Win dows 9x Symbol (.SYM) Files wit h Soft ICE . . . . . . . . . . . . . . . . . . . . . . 144
Chapt er 10
Re m o t e D eb ug g in g w it h So f t I CE
In t roduct ion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
Types of Remot e Con n ect ion s . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
DSR Namespace Ext en sion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
Remot e Debuggin g Det ails . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
Specialized Net work Drivers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
Un iversal Net work Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
Serial Con n ect ion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
Modem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
SIREMOTE Ut ilit y (Host Comput er) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
NET Comman d (Target Comput er) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159
Chapt er 11
Cust o m i z in g So f t I CE
Modifyin g Soft ICE In it ializat ion Set t in gs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
Modifyin g Gen eral Set t in gs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
In it ializat ion St rin g . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
Hist ory Buffer Size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
Trace BufferSize (Win dows 9x On ly) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164
Tot al RAM (Win dows 9x On ly) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164
Display Diagn ost ic Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164
Trap NMI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164
Lowercase Disassembly . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
Pre-loadin g Symbols an d Source Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
Addin g Symbol Files t o t h e Symbols List . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
Removin g Symbols an d Source Code Pre-Loadin g . . . . . . . . . . . . . . . . . . . . . 166
Reservin g Symbol Memory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
Pre-loadin g Export s . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
Con figurin g Remot e Debuggin g . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
Requiremen t s for Remot e Soft ICE Support . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
Set t in g Up Soft ICE for Remot e Debuggin g . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
En ablin g Remot e Debuggin g from t h e Target Side . . . . . . . . . . . . . . . . . . . . . 168
St art in g t h e Remot e Debuggin g Session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170
Con figurin g Remot e Debuggin g wit h a Modem . . . . . . . . . . . . . . . . . . . . . . . 170
Ta b l e of Con t en t s i x

Modifyin g Keyboard Mappin gs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
Comman d Syn t ax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
Modifyin g Fun ct ion Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
Creat in g Fun ct ion Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
Delet in g Fun ct ion Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
Rest orin g Fun ct ion Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
Workin g wit h Persist en t Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
Creat in g Persist en t Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174
St art in g an d St oppin g Persist en t Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175
Set t in g Troublesh oot in g Opt ion s . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
Disable Mouse Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
Disable Num Lock an d Caps Lock Programmin g . . . . . . . . . . . . . . . . . . . . . . 176
Do Not Pat ch Keyboard Driver (Win dows NT/ 2000/ XP On ly) . . . . . . . . . . . . 177
Disable Mappin g of Non -Presen t Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
Disable Pen t ium Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
Disable Th read-Specific St eppin g . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
Chapt er 12
Exp lo r in g W in d o w s N T
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
Resources for Advan ced Debuggin g . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
In side t h e Win dows NT Kern el . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
Man agin g t h e In t el Arch it ect ure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184
Win dows NT Syst em Memory Map . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188
Win 32 Subsyst em . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195
In side CSRSS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195
USER an d GDI Object s . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
Process Address Space . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202
Heap API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204
Appendix A
Er r o r M e ssag e s . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217
Appendix B
Sup p o r t e d D isp lay Ad ap t e r s . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221
Appendix C
Tr o ub le sh o o t i n g So f t I CE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225
Appendix D
Ker n e l D eb ug g e r Ext e n sio n s . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227

x Usi n g Sof t I CE
Glo ssar y . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229
I n d ex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231
x i

Preface
Pur p o se of Th is M an ual
W h at Th is M an ual Co ver s
Con ven t io n s U sed I n Th is M an ual
H ow t o U se Th is M an ual
O t h er U sef ul D o cum en t at ion
Cust o m er Assist an ce
Purpose of This Manual
N o t e : Un l ess st at ed o t h er w i se, t h i s d o cu m en t w i l l u se Wi n d o w s
9 x t o
r ef er t o t h e Wi n d o w s 9 5 , Wi n d o w s 9 8 , an d Wi n d o w s M i l l en n i u m
( Wi n d o w s M E) o p er at i n g syst em s ( t r eat ed as a g r o u p ) ; Wi n d o w s
N T
f am i l y or Wi n d o w s N T/ 2 0 0 0 / XP w i l l r ef er t o t h e Wi n d o w s
N T, Wi n d o w s 2 0 0 0 , an d Wi n d o w s XP o p er at i n g sy st em s. ( Al so ,
u n l ess st at ed o t h er w i se, ch ar act er i st i cs o f Wi n d o w s N T d escr i b ed i n
t h i s m an u al al so ap p l y t o Wi n d o w s 2 0 0 0 an d Wi n d o w s XP. )
Soft ICE
is an advan ced, all-purpose debugger t h at can debug virt ually

an y t ype of code in cludin g applicat ion s, device drivers, EXEs, DLLs,
OCXs, an d dyn amic an d st at ic VxDs. Sin ce man y programmers prefer t o
learn t h rough h an ds on experien ce, t h is man ual in cludes a t ut orial t h at
leads you t h rough t h e basics of debuggin g code.
Th is man ual is in t en ded for programmers wh o wan t t o use Soft ICE t o
debug code for Win dows 9x an d Win dows NT family plat forms.
Users of previous version s of Soft ICE sh ould read t h e Release Not es/
Readme documen t at ion t o see h ow t h is version of Soft ICE differs from
previous version s.
Th is man ual assumes t h at you are familiar wit h t h e Microsoft
Win dows
in t erface an d wit h soft ware debuggin g con cept s.

x i i Usi n g Sof t I CE
What This Manual Covers
Th is man ual con t ain s t h e followin g ch apt ers an d appen dixes:
Th e Using SoftICE man ual is organ ized as follows:
Ch apt er 1, Ch oosin g Your Soft ICE Version
Explain s t h e differen ces bet ween Soft ICE an d it s compan ion
debugger, Visual Soft ICE.
Ch apt er 2, Welcome t o Soft ICE
Briefly describes Soft ICE compon en t s an d feat ures. Ch apt er 2 also
explain s h ow t o con t act t h e Compuware Tech n ical Support Cen t er.
Ch apt er 3, Soft ICE Tut orial
Provides a h an ds-on t ut orial t h at demon st rat es t h e basics for
debuggin g code. Topics in clude t racin g code, viewin g t h e con t en t s of
locals an d st ruct ures, set t in g a variet y of breakpoin t s, an d viewin g
t h e con t en t s of symbol t ables.
Ch apt er 4, Loadin g Code in t o Soft ICE
Explain s h ow t o use Soft ICE Symbol Loader t o load various t ypes of
code in t o Soft ICE.
Ch apt er 5, Navigat in g Th rough Soft ICE
Describes h ow t o use t h e in t erface t h at Soft ICE provides for code
debuggin g.
Ch apt er 6, Usin g Soft ICE
Provides in format ion about t rappin g fault s, address con t ext s, usin g
INT 0x41.DOT comman ds, an d t ran sit ion s from Rin g-3 t o Rin g-0.
Ch apt er 7, Usin g Breakpoin t s
Explain s h ow t o set breakpoin t s on program execut ion , on memory
locat ion reads an d writ es, on in t errupt s, an d on reads an d writ es t o
t h e I/ O port s.
Ch apt er 8, Usin g Expression s
Explain s h ow t o form expression s t o evaluat e breakpoin t s.
Ch apt er 9, Loadin g Symbols for Syst em Compon en t s
Explain s h ow t o load export symbols for DLLs an d EXEs an d h ow t o
use symbol files wit h Soft ICE.
Ch apt er 10, Remot e Debuggin g wit h Soft ICE
Explain s h ow t o est ablish a remot e con n ect ion t o operat e Soft ICE
from a remot e PC.
Pr ef a ce x i i i

Ch apt er 11, Cust omizin g Soft ICE
Explain s h ow t o use t h e Soft ICE con figurat ion set t in gs t o cust omize
your Soft ICE en viron men t , pre-load symbols an d export s, con figure
remot e debuggin g, modify keyboard mappin gs, creat e macro-
defin it ion s, an d set t roublesh oot in g opt ion s.
Ch apt er 12, Explorin g Win dows NT
Provides a quick overview of t h e Win dows NT operat in g syst em.
Appen dix A, Error Messages
Explain s t h e Soft ICE error messages.
Appen dix B, Support ed Display Adapt ers
List s t h e display adapt ers t h at Soft ICE support s.
Appen dix C, Troublesh oot in g Soft ICE
Explain s h ow t o solve problems you migh t en coun t er.
Appen dix D, Kern el Debugger Ext en sion s
Explain s h ow t o prepare a Kern el Debugger Ext en sion for use wit h
Soft ICE.
Glossary
In dex
Convent ions Used In This Manual
Th is book uses t h e followin g con ven t ion s t o presen t in format ion :
Co n v en t i o n D escr i p t i o n
En t er In d i cat es t h at y o u sh o u l d t y p e t ex t , t h en p r ess RETURN o r
cl i ck O K.
It al i cs In d i cat es v ar i ab l e i n f o r m at i o n . Fo r ex am p l e: l i b r a r y- n a m e.
M o n o sp aced t ex t Used w i t h i n i n st r u ct i o n s an d co d e ex am p l es t o i n d i cat e
ch ar act er s y o u t y p e o n y o u r key b o ar d .
Sm al l cap s In d i cat es a u ser - i n t er f ace el em en t , su ch as a b u t t o n o r
m en u .
UPPERCASE In d i cat es d i r ect o r y n am es, f i l e n am es, key w o r d s, an d
ac r o n y m s.
Bo l d t y p ef ace Scr een co m m an d s an d m en u n am es ap p ear i n b o ld
t yp ef ace. Fo r ex am p l e:
Ch o o se I t em Br o w ser f r o m t h e To ols m en u .

x i v Usi n g Sof t I CE
How t o Use This Manual
Th e followin g t able suggest s t h e best st art in g poin t for usin g t h is man ual
based on your level of experien ce debuggin g applicat ion s.
Ot her Useful Document at ion
In addit ion t o t h is man ual, Compuware provides t h e followin g
documen t at ion for Soft ICE:
Soft ICE Comman d Referen ce
Describes all t h e Soft ICE comman ds in alph abet ical order. Each
descript ion provides t h e appropriat e syn t ax an d out put for t h e
comman d as well as examples t h at h igh ligh t h ow t o use it .
Soft ICE on -lin e Help
Soft ICE provides con t ext -sen sit ive h elp for Symbol Loader an d a h elp
lin e for Soft ICE comman ds in t h e debugger.
Co m m an d s an d f i l e
n am es
Co m p u t er co m m an d s an d f i l e n am es ap p ear i n moroacc
l,cacc. Fo r ex am p l e:
Th e Usi n g Sof t I CE m an u al ( Using SoftICE.pdf)
d escr i b es. . .
Var i ab l es Var i ab l es w i t h i n co m p u t er co m m an d s an d f i l e n am es ( f o r
w h i ch y o u m u st su p p l y val u es ap p r o p r i at e f o r y o u r
i n st al l at i o n ) ap p ear i n italic monospace type. Fo r
ex am p l e:
En t er http://servername/cgi-win/itemview.dll i n
t h e D est i n at i o n f i el d .
Co n v en t i o n D escr i p t i o n
Ex p er i en ce Su g g est ed St ar t i n g Po i n t
N o ex p er i en ce u si n g d eb u g g er s Per f o r m t h e t u t o r i al i n Ch ap t er 3 .
Ex p er i en ce w i t h o t h er d eb u g g er s Read Ch ap t er 4 , Lo ad i n g Co d e i n t o So f t ICE.
Th en r ead Ch ap t er 5 , N av i g at i n g Th r o u g h
So f t ICE.
Ex p er i en ce u si n g a p r evi o u s
r el ease o f So f t ICE
Read Ch ap t er 1 , Pr o d u c t O v er v i ew , t o
l ear n ab o u t t h i s v er si o n o f So f t ICE.
Pr ef a ce x v

On -lin e documen t at ion
Bot h t h e Using SoftICE man ual an d t h e SoftICE Command Reference are
available on lin e. To access t h e on -lin e version of t h ese books, st art
Acrobat Reader an d open t h e Using SoftICE or t h e SoftICE Command
Reference PDF files.
Cust omer Assist ance
For N on- Techni ca l I ssues
Cust omer Service is available t o an swer an y quest ion s you migh t h ave
regardin g upgrades, serial n umbers an d ot h er order fulfillmen t n eeds.
Cust omer Service is available from 8:30am t o 5:30pm EST, Mon day
t h rough Friday. Call:
In t h e U.S. an d Can ada: 1-888-283-9896
In t ern at ion al: +1 603 578-8103
For Techni ca l I ssues
Tech n ical Support can assist you wit h all your t ech n ical problems, from
in st allat ion t o t roublesh oot in g. Before con t act in g Tech n ical Support ,
please read t h e relevan t sect ion s of t h e product documen t at ion as well as
t h e Readme files for t h is product . You can con t act Tech n ical Support by:
E-Mail: In clude your serial n umber an d sen d as man y det ails as
possible t o:
mailto:nashua.support@compuware.com
World Wide Web: Submit issues an d access addit ion al support
services at :
http://frontline.compuware.com/nashua/
Fax: In clude your serial n umber an d sen d as man y det ails as possible
t o:
1-603-578-8401
Telephone: Teleph on e support is available as a paid* Priorit y
Support Service from 8:30am t o 5:30pm EST, Mon day t h rough Friday.
Have product version an d serial n umber ready.
In t h e U.S. an d Can ada, call: 1-888-686-3427
In t ern at ion al cust omers, call: +1-603-578-8100
*Tech n ical Support h an dles in st allat ion an d set up issues free of ch arge.

x v i Usi n g Sof t I CE
Wh en con t act in g Tech n ical Support , please h ave t h e followin g
in format ion available:
Product / service pack n ame an d version .
Product serial n umber.
Your syst em con figurat ion : operat in g syst em, n et work con figurat ion ,
amoun t of RAM, en viron men t variables, an d pat h s.
Th e det ails of t h e problem: set t in gs, error messages, st ack dumps, an d
t h e con t en t s of an y diagn ost ic win dows.
Th e det ails of h ow t o reproduce t h e problem (if t h e problem is
repeat able).
Th e n ame an d version of your compiler an d lin ker an d t h e opt ion s
you used in compilin g an d lin kin g.
1
BETA REVI EW
Ch ap t er 1
Choosing Your Soft ICE Version
Sof t I CE o r Visual So f t I CE?
Sin g le M ach in e D eb ug g in g : So f t I CE
D ual M ach in e D e b ug g in g : Visual Sof t I CE
But W h ich O n e Sh ould I U se?
Soft ICE or Visual Soft ICE?
DriverSt udio
TM
3.0 an d Soft ICE Driver Suit e
TM
3.0 in clude t wo un ique
debuggers: Soft ICE, t h e powerh ouse sin gle-mach in e debugger, an d Visual
Soft ICE, a n ew GUI-based dual-mach in e debugger. Depen din g on t h e
debuggin g t ask you are facin g, it may or may n ot be obvious wh ich
debugger you sh ould use. Th is sect ion will h elp you decide wh ich t ool
best fit s your n eeds.
In some sit uat ion s, your ch oice will be simple: some processor arch it ec-
t ures an d operat in g syst ems are on ly support ed by on e of t h e t wo debug-
gers. Table 1-1 sh ows t h e plat forms support ed by Soft ICE an d Visual
Soft ICE.
Tab l e 1 - 1 : Su p p o r t ed Pl at f o r m s
Pr o cesso r O p er at i n g Sy st em So f t ICE Vi su al So f t ICE
In t el x86 an d
compat ibles
MS-DOS, Win dows 3.0/
3.1/ 3.11, Win dows 9x
Yes No
In t el x86 an d
compat ibles
Win dows NT 3.x,
Win dows NT 4.0
Yes
In t el x86 an d
compat ibles
Win dows 2000,
Win dows XP, Advan ced
Server, .Net Server
Yes Yes
In t el It an ium1
an d It an ium2
(IA64)
Win dows XP 64bit Ed.,
.Net Server 64bit Ed.
Yes
BETA REVI EW
2 Usi n g Sof t I CE
If youre debuggin g on DOS or t h e Win dows 9x family, Soft ICE is your
on ly ch oice. If youre workin g on a 64-bit arch it ect ure, on ly Visual
Soft ICE will do. If your t arget is Win dows NT/ 2K/ XP an d t h e x86 or
compat ible arch it ect ure, eit h er debugger will work. In t h at case, read on
for an overview of t h e differen ces bet ween t h ese t wo t ools.
Single Machine Debugging: Soft ICE
Soft ICE is a sin gle-mach in e debugger, mean in g simply t h at all of it s code
run s on t h e same mach in e as t h e code bein g debugged. Wh en run n in g,
Soft ICE h as t wo basic st at es: popped up, wh ere t h e Soft ICE win dow is
displayed, an d popped down , wh ere Soft ICE is in visible an d t h e mach in e
run s as n ormal. Wh en Soft ICE is popped up, all processes on t h e
mach in e are st opped, t h e operat in g syst em does n ot run , an d Soft ICEs
comman ds are available t o t h e user. Soft ICE can pop up in respon se t o
user in put (t h e CTRL-D h ot key), breakpoin t s, except ion s, or syst em
crash es. Soft ICE is popped down by issuin g on e of t h e go or exit
comman ds, at wh ich poin t t h e Soft ICE screen is erased an d all processes
in t h e syst em resume operat ion .
Th e fact t h at Soft ICE h alt s t h e operat in g syst em wh en it is popped up
mean s t h at it must operat e wit h out makin g use of an y of t h e OS services.
Th is h as a n umber of con sequen ces. For on e, t h e Soft ICE user in t erface
does n ot resemble t h at of a n ormal Win dows applicat ion . Alt h ough
Soft ICE support s keyboard an d mouse in put , it does n ot use Win dows
fon t s, n or does it s in t erface con t ain t h e en h an cemen t s common t o
Win dows applicat ion s. In addit ion , Soft ICE can n ot assume t h at it is safe
t o perform disk access wh en ever it is popped up, so loadin g or savin g
symbol in format ion an d Soft ICE dat a is don e t h rough compan ion
applicat ion s, such as Symbol Loader (Loader32.exe).
An ot h er con sequen ce of Soft ICEs sin gle mach in e arch it ect ure is t h at t h e
in t erface is ext remely fast . All t h e dat a in t h e mach in e is direct ly
accessible t o t h e debugger, so even t asks in volvin g large amoun t s of
memory access are complet ed wit h n o n ot iceable delay.
AMD Opt eron ,
Hammer (x86-64
/ K8)
Win dows XP 64bit Ed.,
.Net Server 64bit Ed.
Yes
Tab l e 1 - 1 : Su p p o r t ed Pl at f o r m s
Pr o cesso r O p er at i n g Sy st em So f t ICE Vi su al So f t ICE
Ch ap t er 1 Ch o o si n g Yo u r So f t ICE Ver si o n 3
BETA REVI EW
Because symbols an d source code must be loaded ah ead of t ime, Soft ICE
uses a packaged format for symbols called NMS files. Symbols, t ran slat ed
from t h e DBG or PDB files out put by t h e lin ker, can be combin ed wit h all
or some of t h e source files used t o build t h e module, an d loaded in t o
Soft ICE all at on ce usin g Symbol Loader or it s comman d-lin e equivalen t ,
NMSYM. In addit ion , t h e n ew Microsoft Symbol Servers can be accessed
usin g Symbol Ret riever ut ilit y, wh ich is also capable of t ran slat in g
symbols in t o NMS files an d loadin g t h em in t o Soft ICE. Th ese t ools make
t h e n ecessary man agemen t of symbols for Soft ICE as simple as possible.
Soft ICE support s a subset of t h e available KD Ext en sion s defin ed by
Microsoft . Because t h e operat in g syst em is st opped wh en t h e debugger is
popped up, Soft ICE does n ot support all t h e available KD Ext en sion s,
sin ce it is n ot able t o make syst em calls.
Th ere are cert ain sit uat ion s wh ere debuggin g on a sin gle mach in e is
impract ical. For in st an ce, if your project is a display driver t h at is n ot yet
workin g properly, Soft ICE may n ot be able t o display it s out put . Soft ICE
does in clude support for remot e debuggin g, wh ich can be used in man y
of t h ese sit uat ion s t o redirect Soft ICEs in put an d out put over a serial or
IP n et workin g lin k. Th e remot e applicat ion in t h is case is SIRemot e,
wh ich simply act s as a dumb t ermin al for Soft ICE. Th e operat ion of t h e
debugger is n ot ot h erwise ch an ged by run n in g remot ely.
Dual Machine Debugging: Visual Soft ICE
Visual Soft ICE, on t h e ot h er h an d, is a dual-mach in e debugger. Th e user
in t erface an d n early all of t h e in t erpret ive code run s on t h e mast er
mach in e; t h e code t o be debugged run s alon gside a small core of
debuggin g fun ct ion s on t h e t arget mach in e. Mast er an d t arget
mach in es are con n ect ed via a t ran sport , wh ich can be a serial cable, IP
n et work in t erface device, or IEEE 1394 con n ect ion .
Because t h e mast er mach in e is n ever st opped by t h e debugger, Visual
Soft ICEs user in t erface is free t o t ake advan t age of all of t h e usual
Win dows UI devices. Visual Soft ICEs user in t erface will be in st an t ly
familiar t o an yon e wh o h as used soph ist icat ed Win dows programs
before; in addit ion , t h e comman d set h as been duplicat ed (wit h a few
except ion s) from t h e origin al Soft ICE, so Soft ICE users sh ould fin d much
t h at is familiar about Visual Soft ICE as well.
Visual Soft ICE is also able t o load symbol in format ion on -t h e-fly at an y
t ime in cludin g ret rievin g symbols from a Symbol Server sit e so t h is
t ask is gen erally h an dled aut omat ically by t h e debugger. Th is frees t h e
BETA REVI EW
user from t h e n ecessit y of man ually specifyin g symbol files t o be loaded
by t h e debugger, alt h ough t h at opt ion is st ill available in Visual Soft ICE.
Visual Soft ICE support s loadin g an d examin in g crash dump an d
min idump files direct ly, a feat ure n ot foun d in Soft ICE. (DriverSt udios
DriverWorkben ch Applicat ion also support s t h is).
Visual Soft ICE also provides complet e support for Microsoft s KD
Ext en sion s, in cludin g t h ose t h at will n ot run on Soft ICE for arch it ect ural
reason s.
But Which One Should I Use?
If your project falls in t o t h e wide overlap bet ween Soft ICE an d Visual
Soft ICE, an d youve n ever used Soft ICE before, youre probably st ill
won derin g wh ich debugger is best for you. Obviously, t h eres n ot always
a sin gle righ t an swer t o t h is quest ion , but in t h e remain der of t h is sect ion
well t ry t o cover some of t h e scen arios wh ere on e debugger migh t be
favored over t h e ot h er. Were down t o guidelin es h ere, t h ough ; devot ees
of eit h er debugger will be quick t o poin t out t h at t h eir favorit e st ill h as
advan t ages, even in cases wh ere t h e ot h er migh t appear t o be t h e bet t er
ch oice. We en courage you t o t ry t h em bot h , an d con sider t h em t wo
similar but dist in ct t ools in your debuggin g t oolbox.
If you prefer a full-feat ured Win dows GUI, youll probably wan t t o
use Visual Soft ICE. Soft ICEs in t erface is fast an d powerful, but it
doesn t h ave a Win dows GUI, an d it t akes some get t in g used t o.
If youre debuggin g a n et work driver, an d youre con cern ed t h at
Visual Soft ICEs IP t ran sport layer migh t affect t h e result s, use
Soft ICE. Con versely, if youre debuggin g a video drivers mode
in it ializat ion , or a Direct 3D or st reamin g app or driver, t ry Visual
Soft ICE or run Soft ICE remot ely.
If you wan t direct access t o Boun dsCh ecker
even t s from wit h in t h e

debugger, use Soft ICE. Soft ICE can st op t h e mach in e wh en an even t
occurs an d allow you t o diagn ose problems as t h ey occur, even aft er a
syst em crash .
If youre debuggin g a crash dump file, t ry Visual Soft ICE. Youll be
able t o use man y of t h e debuggin g comman ds youre already familiar
wit h , an d Visual Soft ICE operat es in side t h e DriverWorkben ch
Tech n ology En viron men t .
If you don t h ave access t o a secon d mach in e, or youre t ravelin g an d
debuggin g code on a lapt op, use Soft ICE.
Ch ap t er 1 Ch o o si n g Yo u r So f t ICE Ver si o n 5
BETA REVI EW
If you n eed complet e KD Ext en sion s support , use Visual Soft ICE.
Soft ICE provides a limit ed subset of KD Ext en sion s, but n ot t h e
wh ole set .
If you n eed t h e abilit y t o package source code t oget h er wit h symbolic
debuggin g in format ion in NMS files, use Soft ICE. Bot h debuggers are
capable of loadin g source code separat ely from symbol files, of
course.
If youre st ill con fused about wh ich debugger t o use, skim t h rough t h e
documen t at ion for bot h of t h em. Ch an ces are t h at somet h in g you see
t h ere will poin t you in t h e righ t direct ion .
BETA REVI EW
7
BETA REVI EW
Ch ap t er 2
Welcome t o Soft ICE
Pr o d uct O ver view
H ow So f t I CE is I m p lem en t e d
Ab out t h e Sym b o l Load er
Product Overview
Soft ICE is available for Win dows 9x an d Win dows NT/ 2000/ XP. Soft ICE
con sist s of t h e Soft ICE kern el-mode debugger an d t h e Symbol Loader
ut ilit y. Th e Soft ICE debugger (Soft ICE) is an advan ced, all-purpose debug-
ger t h at can debug virt ually an y t ype of code in cludin g in t errupt
rout in es, processor level ch an ges, an d I/ O drivers. Th e Symbol Loader
ut ilit y loads t h e debug in format ion for your module in t o Soft ICE,
main t ain s t h e Soft ICE in it ializat ion set t in gs, an d let s you save t h e
con t en t s of t h e Soft ICE h ist ory buffer t o a file. Th e followin g sect ion s
briefly describe Soft ICE an d t h e Symbol Loader.
Benef i t s of Sof t I CE
Soft ICE combin es t h e power of a h ardware debugger wit h t h e ease of use
of a symbolic debugger. It provides h ardware-like breakpoin t s an d st icky
breakpoin t s t h at follow t h e memory as t h e operat in g syst em discards,
reloads, an d swaps pages. Soft ICE displays your source code as you debug,
an d let s you access your local an d global dat a t h rough t h eir symbolic
n ames.
Some of t h e major ben efit s Soft ICE provides in clude t h e followin g:
Source level debuggin g of 32-bit (Win 32) applicat ion s, Win dows NT/
2000/ XP device drivers (bot h kern el an d user mode), Win dows 9x
drivers, VxDs, 16-bit win dows programs, an d DOS programs.
BETA REVI EW
Debuggin g virt ually an y code, in cludin g in t errupt rout in es an d t h e
Win dows 9x an d Win dows NT/ 2000/ XP kern els.
Set t in g real-t ime breakpoin t s on memory reads/ writ es, port reads/
writ es, an d in t errupt s.
Set t in g breakpoin t s on Win dows messages.
Set t in g con dit ion al breakpoin t s an d breakpoin t act ion s.
Displayin g elapsed t ime t o t h e breakpoin t t rigger usin g t h e Pen t ium
clock coun t er.
Kern el-level debuggin g on on e mach in e.
Displayin g in t ern al Win dows 9x an d Win dows NT/ 2000/ XP in forma-
t ion , such as:
Complet e t h read an d process in format ion
Virt ual memory map of a process
Kern el-mode en t ry poin t s
Win dows NT object direct ory
Complet e driver object an d device object in format ion
Win 32 h eaps
St ruct ured Except ion Han dlin g (SEH) frames
DLL export s
Usin g t h e WHAT comman d t o iden t ify a n ame or an expression , if it
evaluat es t o a kn own t ype.
Poppin g up t h e Soft ICE screen aut omat ically wh en an un h an dled
except ion occurs.
Usin g Soft ICE t o con n ect by modem, n et work, serial, or In t ern et t o a
remot e user. Th is en ables you t o diagn ose a remot e users problem,
such as a syst em crash .
Support in g t h e MMX, SSE, an d SSE2 in st ruct ion set ext en sion s.
Creat in g user-defin ed macros.
How Sof t I CE i s I mpl ement ed
Soft ICE for Win dows 9x an d Win dows NT/ 2000/ XP are implemen t ed in
sligh t ly differen t ways. Soft ICE for Win dows 9x comprises t wo VxDs,
wh ile Soft ICE for Win dows NT/ 2000/ XP comprises t wo NT kern el device
drivers. Th is is sh own in Table 1-1 on 9.
Ch ap t er 2 W el co m e t o So f t ICE 9
BETA REVI EW
Tab l e 2 - 1 . So f t ICE In p l em en t at i o n M et h o d s
N o t e : So f t I CE f o r Wi n d o w s N T/ 2 0 0 0 / XP m u st b e l o ad ed b y t h e o p er at i n g
sy st em b ecau se i t i s i m p l em en t ed as a d evi ce d r i ver. If y o u n eed t o
d eb u g a b o o t m o d e d r i v er y o u w i l l n eed t o t ake an ad d i t i o n al st ep o f
set t i n g u p Si w sy m an d m an u al l y ch an g i n g t h e l o ad o r d er o f So f t ICE.
Yo u w i l l n o t b e ab l e t o d eb u g t h e N TO SKRN L i n i t i al i zat i o n co d e, an d
an y Wi n d o w s N T/ 2 0 0 0 / XP l o ad er o r N TD ETECT co d e. Fo r ad d i t i o n al
i n f o r m at i o n o n si w sy m , p l ease r ead t h e i n cl u d ed si w sy m . t x t f i l e
Soft ICE User Int erface
Soft ICE provides a con sist en t in t erface for debuggin g applicat ion s across
all plat forms. Th e Soft ICE user in t erface is design ed t o be fun ct ion al
wit h out compromisin g syst em robust n ess. For Soft ICE t o pop up at an y
t ime wit h out dist urbin g t h e syst em st at e, it must access t h e h ardware
direct ly t o perform it s I/ O.
Soft ICE uses a full-screen ch aract er-orien t ed display win dow, as sh own in
Figure 2-1 on page 10.
W in d ow s
9 x ( VxD )
W in d ow s M E
W in d o w s N T/ 2 0 0 0 / X P
( N T/ 2 0 0 0 / X P Ker n el
D evice D r iver )
D escr ip t io n
WINICE.EXE WINICE.EXE NTICE.SYS Provides the debugger.
SIWVID.386 SIWVID.386 SIWVID.SYS Provides video support
for your PC.
WINICE.VXD
DEBUGGER.EXE
BETA REVI EW
1 0 Usi n g Sof t I CE
Fi g u r e 2 - 1 . So f t ICE D i sp l ay Wi n d o w
Ch ap t er 2 W el co m e t o So f t ICE 1 1
BETA REVI EW
Refer t o Chapter 4: Navigating Through SoftICE on page 47 for more in forma-
t ion about usin g t h e Soft ICE screen .
About t he Symbol Loader
Symbol Loader is a graph ical ut ilit y t h at ext ract s debug symbol in forma-
t ion from your device drivers, EXEs, DLLs, OCXs, an d dyn amic an d st at ic
VxDs an d loads it in t o Soft ICE. Th is ut ilit y let s you do t h e followin g:
Cust omize t h e t ype an d amoun t of in format ion it loads t o suit your
debuggin g requiremen t s.
Provides a Workspace an d Session en viron men t .
Load an d un load en t ire groups of symbol files, t ran slat ion s, an d
lin ks.
Aut omat ically st art your applicat ion an d set a breakpoin t at it s en t ry
poin t .
Save your debuggin g session t o a file.
Th e followin g figure illust rat es Symbol Loader.
Fi g u r e 2 - 2 . Sy m b o l Lo ad er Wi n d o w
Symbol Loader also support s a comman d lin e in t erface t h at let s you use
man y of it s feat ures from a DOS prompt . Th us, you can aut omat e man y
of t h e most common t asks it performs. Addit ion ally, Soft ICE provides a
separat e comman d-lin e ut ilit y (NMSYM) t h at let s you aut omat e t h e
creat ion of symbol in format ion from a bat ch file.
BETA REVI EW
1 3
BETA REVI EW
Ch ap t er 3
Soft ICE Tut orial
I n t r o d uct ion
Load in g Sof t I CE
Build in g t h e GD I D EM O Sam p le Ap p licat io n
Load in g t h e GD I D EM O Sam p le Ap p licat io n
Con t r o llin g t h e Sof t I CE Scr een
Tr acin g an d St ep p in g t h r o ug h t h e So urce Co d e
View in g Lo cal D at a
Se t t in g Poin t - an d - Sh oo t Br eakp oin t s
U sin g Sof t I CE I n f or m at io n al Com m an d s
U sin g Sym b o ls an d Sym b ol Tab le s
Se t t in g a Co n d it io n al Br eakp oin t
Se t t in g a Read - W r it e M em or y Br eakp oin t
Int roduct ion
Th is t ut orial gives you h an ds-on experien ce debuggin g a Win dows appli-
cat ion , t each in g you t h e fun damen t al st eps for debuggin g applicat ion s
an d drivers. Durin g t h is debuggin g session , you will learn h ow t o do t h e
followin g:
Load Soft ICE
Build an applicat ion
Load t h e applicat ion s source an d symbol files
Trace an d st ep t h rough source code an d assembly lan guage
View local dat a an d st ruct ures
Set poin t -an d-sh oot breakpoin t s
Use Soft ICE in format ion al comman ds t o explore t h e st at e of t h e
applicat ion
Work wit h symbols an d symbol tables
BETA REVI EW
Modify a breakpoin t t o use a con dit ion al expression
Each sect ion in t h e t ut orial builds upon t h e previous sect ion s, so you
sh ould perform t h em in order.
Th is t ut orial uses t h e GDIDEMO applicat ion as it s basis. GDIDEMO
provides a demon st rat ion of GDI fun ct ion alit y. GDIDEMO is locat ed in
t h e \ EXAMPLES\ GDIDEMO direct ory on your CD-ROM. If you use t h e
GDIDEMO on t h e CDROM, copy it t o your h ard drive.
You can subst it ut e a differen t sample applicat ion or an applicat ion of
your own design . Th e debuggin g prin ciples an d feat ures of Soft ICE used
in t h is t ut orial apply t o most applicat ion s.
N o t e : Th e ex am p l es i s t h i s t u t o r i al ar e b ased o n Wi n d o w s N T. If y o u ar e
u si n g Wi n d o w s 9 x , Wi n d o w s 2 0 0 0 , o r Wi n d o w s XP, y o u r o u t p u t m ay
v ar y.
If u si n g t h e Un i v er sal Vi d eo D r i v er w i t h So f t ICE w h i l e d eb u g g i n g
GD ID EM O , w e su g g est y o u f i r st i ssu e t h e SET FLASH ON co m m an d
i n t h e So f t I CE Co m m an d w i n d o w . Yo u can al so u se CTRL- L t o cl ear
an o m al i es f r o m t h e scr een .
Loading Soft ICE
If you are run n in g Soft ICE wit h Win dows 9x in Boot mode, or un der
Win dows NT/ 2000/ XP in Boot , Syst em, or Aut omat ic mode, Soft ICE
aut omat ically loads wh en you st art or reboot your PC. If you are run n in g
Soft ICE in Man ual or Disabled mode wit h Win dows NT/ 2000/ XP, Soft ICE
does n ot load aut omat ically. To ch an ge t h e mode in wh ich you h ave
Soft ICE con figured t o load, access t h e St art up screen in t h e Con figura-
t ion win dow, an d select t h e desired mode usin g t h e radio but t on s.
Th e followin g figures display t h e St art up Con figurat ion screen s for
Win dows 9x an d Win dows NT/ 2000/ XP respect ively.
Ch ap t er 3 So f t ICE Tu t o r i al 1 5
BETA REVI EW
Fi g u r e 3 - 1 . Wi n 9 x St ar t u p Co n f i g u r at i o n Scr een
Fi g u r e 3 - 2 . Wi n d o w s N T/ 2 0 0 0 / XP St ar t u p Co n f i g u r at i o n Scr een
BETA REVI EW
If you h ave select ed Disabled mode, you can n ot load an d st art Soft ICE. If
you h ave select ed Man ual mode, you must load an d st art Soft ICE by
issuin g man ual comman ds. To man ually load Soft ICE for Win dows NT/
2000/ XP, do on e of t h e followin g:
Select START SOFTICE from t h e Soft ICE Program Group, or
En t er t h e comman d NET START NTICE from a comman d prompt .
N o t e : O n ce y o u l o ad So f t ICE, y o u can n o t d eact i v at e i t u n t i l y o u r eb o o t
y o u r PC.
To verify t h at Soft ICE is loaded, press t h e Soft ICE h ot key sequen ce Ct rl-
D. Th e Soft ICE screen sh ould appear. To ret urn t o t h e Win dows operat in g
syst em, use t h e X (exit ) or G
(go t o) comman d (F5).
Building t he GDIDEMO Sample Applicat ion
Th e first st ep in preparin g t o debug a Win dows applicat ion is t o build it
wit h debug in format ion . Th e makefile for t h e sample applicat ion
GDIDEMO is already set up for t h is purpose.
To build t h e sample program, perform t h e followin g st eps:
1 Open a DOS sh ell.
N o t e : M ake c er t ai n t h at y o u h av e a D O S sh el l t h at i s p r o p er l y co n f i g u r ed t o
b u i l d a d eb u g v er si o n o f y o u r so u r ce co d e. Th i s t y p i cal l y i n v o l v es
r u n n i n g VCVARS3 2 . BAT o r o p en i n g a D D K-c h ec ked b u i l d en v i r o n -
m en t .
2 Ch an ge t o t h e direct ory t h at con t ain s t h e sample code.
3 Execut e t h e NMAKE comman d:
C:\PROGRAM FILES\NUMEGA\DRIVER-
STUDIO\SOFTICE\EXAMPLES\GDIDEMO>NMAKE
If GDIDEMO is locat ed in an ot h er direct ory, ch an ge t h e pat h as
appropriat e.
Loading t he GDIDEMO Sample Applicat ion
Loadin g an applicat ion en t ails creat in g a symbol file from t h e applica-
t ion s debug in format ion an d loadin g t h e symbol an d source files in t o
Soft ICE. To Load t h e GDIDEMO applicat ion , perform t h e followin g st eps:
BETA REVI EW
1 St art Symbol Loader.
Th e Symbol Loader win dow appears.
Fi g u r e 3 - 3 . Sy n b o l Lo ad er Wi n d o w
2 Eit h er ch oose OPEN MODULE from t h e File men u or click t h e OPEN but -
t on .
Th e Open win dow appears.
3 Locat e GDIDEMO.EXE an d click Open .
4 Eit h er ch oose LOAD from t h e Module men u or click t h e LOAD but t on
t o load GDIDEMO.
Symbol Loader t ran slat es t h e debug in format ion in t o a .NMS symbol
file, loads t h e symbol an d source files, st art s GDIDEMO, pops up t h e
Soft ICE screen , an d displays t h e source code for t h e file GDIDEMO.C.
Cont rolling t he Soft ICE Screen
Th e Soft ICE screen is your cen t ral locat ion for viewin g an d debuggin g
code. It provides up t o seven win dows an d on e h elp lin e t o let you view
an d con t rol various aspect s of your debuggin g session . By default , it
displays t h e followin g:
Code win dow Displays source code or un assembled in st ruct ion s
Comman d win dow En t ers user comman ds an d display in forma-
t ion
BETA REVI EW
Help lin e Provides in format ion about Soft ICE comman ds an d
sh ows t h e act ive address con t ext . (Th e Help lin e is displayed at t h e
screen s bot t om.)
Breakpoin t Creat es a breakpoin t an d st ops at t h e first main mod-
ule it en coun t ers wh en loadin g your applicat ion .
Fi g u r e 3 - 4 . So f t ICE Scr een
To see all t h e source files t h at Soft ICE loaded, en t er t h e FILE comman d
wit h t h e wild card ch aract er:
:FILE *
Register window
Data window (1,2,3)
Code window
Command window
Locals window
Watch window
Thread window
Stack window
BETA REVI EW
Soft ICE displays t h e source files for GDIDEMO: draw.c, maze.c, xform.c,
poly.c, win in fo.c, dialog.c, in it .c, boun ce.c, an d gdidemo.c. Th e
Comman d win dow varies in size depen din g upon t h e n umber of lin es
used by open win dows, so you migh t n ot see all t h ese file n ames. To
display t h e remain in g file n ames, press an y key. (Refer t o Chapter 5: on
page 57 for in format ion about resizin g win dows.)
Man y Soft ICE win dows can be scrolled. If you h ave a mouse, you can
click on t h e scroll arrows. If n ot , Soft ICE provides key sequen ces t h at let
you scroll specific win dows. Try t h ese met h ods for scrollin g t h e Code
win dow:
To disassemble t h e in st ruct ion s for t h e curren t in st ruct ion poin t er, en t er
t h e U comman d, followed by EIP comman d.
:U EIP
You can also use t h e . (dot ) comman d t o accomplish t h e same t h in g:
:.
Tracing and St epping t hrough t he Source Code
Th e followin g st eps sh ow you h ow t o use Soft ICE t o t race t h rough source
code:
1 En t er t h e T (t race) comman d or press t h e F8 key t o t race on e in st ruc-
t ion .
:T
Th e F8 key i s t h e d ef au l t key f o r t h e T ( t r ace) co m m an d .
Tab l e 3 - 1 : Scr o l l i n g M et h o d s
Sc r o l l Co d e Wi n d o w Key Seq u en ce M o u se Act i o n
Scroll t o t h e previous page. PageUp Click t h e in n ermost up scroll
arrow
Scroll t o t h e n ext page. PageDown Click t h e in n ermost down scroll
arrow
Scroll t o t h e previous lin e. UpArrow Click t h e out ermost up scroll
arrow
Scroll t o t h e n ext lin e. Down Arrow Click t h e out ermost down scroll
arrow
Scroll left on e ch aract er. Ct rl-Left Arrow Click t h e left scroll arrow
Scroll righ t on e ch aract er. Ct rl-Righ t Arrow Click t h e righ t scroll arrow
BETA REVI EW
Execut ion proceeds t o t h e n ext source lin e an d h igh ligh t s it . At t h is
poin t , t h e followin g source lin e sh ould be h igh ligh t ed:
if(!hPrevInst)
2 Th e Code win dow is curren t ly displayin g source code. However, it
can also display disassembled code or mixed (bot h source an d disas-
sembled) code. To view mixed code, use t h e SRC comman d (F3).
:SRC
Ti p Th e T com m a n d
d oes n ot t r a ce i n t o a
f u n ct i on ca l l i f t h e
so u r ce cod e i s n ot
a va i l a b l e. A g ood
exa m p l e of t h i s i s
Wi n 3 2 API ca l l s. To
t r a ce i n t o a f u n ct i on
ca l l w h en sou rce cod e
i s n ot a va i l a b l e, u se t h e
SRC com m a n d ( F3 ) t o
sw i t ch i n t o m i xed or
a ssem b l y m od e.
Not e t h at each source lin e is followed by it s assembler in st ruct ion s.
3 Press F3 on ce t o see disassembled code, t h en again t o ret urn t o source
code.
4 En t er t h e T comman d (F8) t o t race on e in st ruct ion .
Execut ion proceeds un t il it reach es t h e lin e t h at execut es t h e Regis-
t erAppClass fun ct ion .
As demon st rat ed in t h ese st eps, t h e T comman d execut es on e source
st at emen t or assembly lan guage in st ruct ion . You can also use t h e P
comman d (F10) t o execut e on e program st ep. St eppin g differs from
t racin g in on e crucial way. If you are st eppin g an d t h e st at emen t or
in st ruct ion is a fun ct ion call, con t rol is n ot ret urn ed un t il t h e fun ct ion
call is complet e.
Viewing Local Dat a
Th e Locals win dow displays t h e curren t st ack frame. In t h is case, it
con t ain s t h e local dat a for t h e Win Main fun ct ion .
Th e followin g st eps illust rat e h ow t o use t h e Locals win dow:
1 En t er t h e T comman d t o en t er t h e Regist erAppClass fun ct ion . Th e
Locals win dow is n ow empt y because local dat a is n ot yet allocat ed
for t h e fun ct ion .
Th e Regist erAppClass fun ct ion is implemen t ed in t h e source file
INIT.C. Soft ICE displays t h e curren t source file in t h e upper left
corn er of t h e Code win dow.
2 En t er t h e T comman d again .
Th e Locals win dow con t ain s t h e paramet er passed t o t h e Regist erAp-
pClass (h In st an ce) an d a local st ruct ure wn dClass. Th e st ruct ure t ag
wn dClass is marked wit h a plus sign (+). Th is plus sign in dicat es t h at
you can expan d t h e st ruct ure t o view it s con t en t s.
N o t e : Yo u can al so ex p an d ch ar act er st r i n g s an d ar r ay s.
BETA REVI EW
3 If you h ave a Pen t ium-class processor an d a mouse, double-click t h e
st ruct ure WNDCLASSA t o expan d it . To collapse t h e st ruct ure wn d-
Class, double-click it s con t en t s.
4 To use t h e keyboard t o expan d t h e st ruct ure: press Alt -L t o move t h e
cursor t o t h e Locals win dow, use t h e UpArrow or Down Arrow t o
move t h e h igh ligh t bar t o t h e st ruct ure, an d press En t er. Double-click
t h e min us sign (-) t o collapse it .
Set t ing Point -and-Shoot Breakpoint s
Th is sect ion sh ows you h ow t o set t wo h an dy t ypes of poin t -an d-sh oot
breakpoin t s: on e-sh ot an d st icky breakpoin t s.
Set t i ng a One- Shot Br ea kpoi nt
Th e followin g st eps demon st rat e h ow t o set a on e-sh ot breakpoin t . A
on e-sh ot breakpoin t clears aft er t h e breakpoin t is t riggered.
1 To sh ift focus t o t h e Code win dow, eit h er use your mouse t o click in
t h e win dow or press Alt -C.
If you wan t ed t o sh ift focus back t o t h e Comman d win dow you could
press Alt -C again .
2 Eit h er use t h e Down arrow key, t h e down scroll arrow, or t h e U com-
man d t o place t h e cursor on lin e 61, t h e first call t o t h e Win 32 API
fun ct ion Regist erClass. If you use t h e U comman d, specify t h e source
lin e 61 as follows:
:U .61
Soft ICE places source lin e 61 at t h e t op of t h e Code win dow.
3 Use t h e HERE comman d (F7) t o execut e t o lin e 61.
Th e HERE comman d execut es from t h e curren t in st ruct ion t o t h e
in st ruct ion t h at con t ain s t h e cursor. Th e HERE comman d set s a on e-
sh ot breakpoin t on t h e specified address or source lin e an d con t in ues
execut ion un t il t h at breakpoin t t riggers. Wh en t h e breakpoin t is
t riggered, Soft ICE aut omat ically clears t h e breakpoin t so t h at it does
n ot t rigger again .
Th e followin g curren t source lin e sh ould be h igh ligh t ed:
if(!RegisterClass(&wndClass))
N o t e : Yo u can d o t h e sam e t h i n g b y u si n g t h e G ( g o ) co m m an d an d sp ec i -
f y i n g t h e l i n e n u m b er o r ad d r ess t o w h i ch t o ex ecu t e:
G .61
BETA REVI EW
Set t i ng a St i cky Br ea kpoi nt
Th e followin g st eps demon st rat e an ot h er t ype of poin t -an d-sh oot break-
poin t : t h e st icky breakpoin t , wh ich does n ot clear un t il you explicit ly
clear it .
Ti p Th e F9 key i s t h e
d ef a u l t key f or t h e BPX
co m m a n d .
1 Fin d t h e n ext call t o Regist erClass t h at appears on source lin e 74.
Wit h t h e cursor on lin e 74, en t er t h e BPX comman d (F9) t o set an
execut ion breakpoin t . Not e t h at t h e lin e is h igh ligh t ed wh en you set
a breakpoin t .
2 Press t h e F9 key t o clear t h e breakpoin t .
If you are usin g a Pen t ium-class processor an d you h ave a mouse, you
can double-click on a lin e in t h e Code win dow t o set or clear a break-
poin t .
3 Set a breakpoin t on lin e 74, t h en use t h e G or X comman d (F5) t o
execut e t h e in st ruct ion s un t il t h e breakpoin t t riggers:
:G
Wh en t h e in st ruct ion is execut ed, Soft ICE pops up.
Un like t h e HERE comman d, wh ich set s a on e-sh ot breakpoin t , t h e
BPX comman d set s a st icky breakpoin t . A st icky breakpoin t remain s
un t il you clear it .
4 To view in format ion about breakpoin t s t h at are curren t ly set , use t h e
BL comman d:
:BL
00) BPX #0137:00402442
N o t e : Th e ad d r ess y o u see m i g h t b e d i f f er en t .
From t h e out put of t h e BL comman d, on e breakpoin t is set on code
address 0x402442. Th is address equat es t o source lin e 74 in t h e
curren t file INIT.C.
5 You can use t h e Soft ICE expression evaluat or t o t ran slat e a lin e n um-
ber in t o an address. To fin d t h e address for lin e 74, use t h e ? com-
man d:
:? .74
void * = 0x00402442
6 Th e Regist erAppClass fun ct ion h as a relat ively st raigh t forward imple-
men t at ion , so it is un n ecessary t o t race every sin gle source lin e. Use
t h e P comman d wit h t h e RET paramet er (F12) t o ret urn t o t h e poin t
wh ere t h is fun ct ion was called:
:P RET
BETA REVI EW
Th e RET paramet er t o t h e P comman d causes Soft ICE t o execut e
in st ruct ion s un t il t h e fun ct ion call ret urn s. Because Regist erAppClass
was called from wit h in Win Main , Soft ICE pops up in Win Main on
t h e st at emen t aft er t h e Regist erAppClass fun ct ion call. Th e followin g
source lin e in Win Main sh ould be h igh ligh t ed:
msg.wParam = 1;
7 En t er t h e BC comman d wit h t h e wild card paramet er t o clear all t h e
breakpoin t s:
BC *
Using Soft ICE Informat ional Commands
Soft ICE provides a wide variet y of in format ion al comman ds t h at det ail
t h e st at e of an applicat ion or t h e syst em. Th is sect ion t each es you about
t wo of t h em: H (h elp) an d CLASS.
Th e H an d Class comman ds work best wh en you h ave more room t o
display in format ion , so use t h e WL comman d t o close t h e Locals
win dow. Closin g t h is win dow aut omat ically in creases t h e size of t h e
Comman d win dow.
Th e H comman d provides gen eral h elp on all t h e Soft ICE comman ds
or det ailed h elp on a specific comman d. To view det ailed h elp about
t h e CLASS comman d, en t er CLASS as t h e paramet er t o t h e H com-
man d.
:H CLASS
Display window class information
CLASS [-x] [process | thread | module | class-name]
ex: CLASS USER
Th e first lin e of h elp provides a descript ion of t h e comman d. Th e
secon d lin e is t h e det ailed use, in cludin g an y opt ion s an d/ or parame-
t ers t h e comman d accept s. Th e t h ird lin e is an example of t h e
comman d.
Th e purpose of t h e Regist erAppClass fun ct ion is t o regist er win dow
class t emplat es t h at are used by t h e GDIDEMO applicat ion t o creat e
win dows. Use t h e CLASS comman d t o examin e t h e classes regist ered
by GDIDEMO.
:CLASS GDIDEMO
BETA REVI EW

N o t e : Th i s ex am p l e sh o w s o n l y t h o se cl asses sp eci f i cal l y r eg i st er ed b y t h e
GD ID EM O ap p l i cat i o n . Cl asses r eg i st er ed b y o t h er Wi n d o w s
m o d u l es, su ch as USER3 2 , ar e o m i t t ed .
Th e out put of t h e CLASS comman d provides summary in format ion for
each win dow class regist ered on beh alf of t h e GDIDEMO process. Th is
in cludes t h e class n ame, t h e address of t h e in t ern al WINCLASS dat a
st ruct ure, t h e module wh ich regist ered t h e class, t h e address of t h e
default win dow procedure for t h e class, an d t h e value of t h e class st yle
flags.
N o t e : Fo r m o r e sp eci f i c i n f o r m at i o n o n w i n d o w c l ass d ef i n i t i o n s, u se t h e
CLASS co m m an d w i t h t h e -X o p t i o n , as f o l l o w s:
:CLASS -X
Using Symbols and Symbol Tables
Now t h at you are familiar wit h usin g Soft ICE t o st ep, t race, an d creat e
poin t -an d-sh oot st yle breakpoin t s, it is t ime t o explore symbols an d
t ables. Wh en you load symbols for an applicat ion , Soft ICE creat es a
symbol t able t h at con t ain s all t h e symbols defin ed for t h at module.
Use t h e TABLE comman d t o see all t h e symbol t ables t h at are loaded:
:TABLE
GDIDEMO [NM32]
964657 Bytes Of Symbol Memory Available
Tab l e 3 - 2 : Cl asses Used b y GDIDEMO Ap p l i cat i o n
Cl ass N am e H an d l e O w n er W n d w Pr o c St y l es
------------------Application Private------------------
BOUNCEDEMO A018A3B0 GDIDEMO 004015A4 00000003
DRAWDEMO A018A318 GDIDEMO 00403CE4 00000003
MAZEDEMO A018A280 GDIDEMO 00403A94 00000003
XFORMDEMO A018A1E8 GDIDEMO 00403764 00000003
POLYDEMO A018A150 GDIDEMO 00402F34 00000003
GDIDEMO A018A0C0 GDIDEMO 004010B5 00000003
BETA REVI EW
Th e curren t ly act ive symbol t able is list ed in bold. Th is is t h e symbol
t able used t o resolve symbol n ames. If t h e curren t t able is n ot t h e
t able from wh ich you wan t t o referen ce symbols, use t h e TABLE
comman d an d specify t h e n ame of t h e t able t o make act ive:
:TABLE GDIDEMO
Use t h e SYM comman d t o display t h e symbols from t h e curren t
symbol t able. Wit h t h e curren t t able set t o GDIDEMO, t h e SYM
comman d produces out put similar t o t h e followin g abbreviat ed
out put :
:SYM
.text(001B)
001B:00401000 WinMain
001B:004010B5 WndProc
001B:004011DB CreateProc
001B:00401270 CommandProc
001B:00401496 PaintProc
001B:004014D2 DestroyProc
001B:004014EA lRandom
001B:00401530 CreateBounceWindow
001B:004015A4 BounceProc
001B:004016A6 BounceCreateProc
001B:00401787 BounceCommandProc
001B:0040179C BouncePaintProc
Th is list of symbol n ames is from t h e .t ext sect ion of t h e execut able. Th e
.t ext sect ion is t ypically used for procedures an d fun ct ion s. Th e symbols
displayed in t h is example are all fun ct ion s of GDIDEMO.
Set t ing a Condit ional Breakpoint
On e of t h e symbols defin ed for t h e GDIDEMO applicat ion is t h e
LockWin dowIn fo fun ct ion . Th e purpose of t h is rout in e is t o ret rieve a
poin t er value t h at is specific t o a part icular in st an ce of a win dow.
To learn about con dit ion al an d memory breakpoin t s, you will perform
t h e followin g st eps:
Set a BPX breakpoin t on t h e LockWin dowIn fo fun ct ion .
Edit t h e breakpoin t t o use a con dit ion al expression , t h us set t in g a
con dit ion al breakpoin t .
Set a memory breakpoin t t o mon it or access t o a key piece of in forma-
t ion , as described in Setting a Read-Write Memory Breakpoint on page 28.
BETA REVI EW
Set t i ng a BPX Br ea kpoi nt
Before set t in g t h e con dit ion al breakpoin t , you n eed t o set a BPX-st yle
breakpoin t on LockWin dowIn fo.
1 Set a BPX-st yle breakpoin t on t h e LockWin dowIn fo fun ct ion :
:BPX LockWindowInfo
Wh en on e of t h e GDIDEMO win dows n eeds t o draw in format ion in
it s clien t area, it calls t h e LockWin dowIn fo fun ct ion . Every t ime t h e
LockWin dowIn fo fun ct ion is called, Soft ICE pops up t o let you debug
t h e fun ct ion . Th e GDIDEMO win dows con t in ually updat es, so t h is
breakpoin t goes off quit e frequen t ly.
2 Use t h e BL comman d t o verify t h at t h e breakpoin t is set .
3 Use eit h er t h e X or G comman d t o exit Soft ICE.
4 Soft ICE sh ould pop up almost immediat ely on t h e LockWin dowIn fo
fun ct ion .
Edi t i ng a Br ea kpoi nt
From t h e LockWin dowIn fo fun ct ion prot ot ype on source lin e 47, you
can see t h at t h e fun ct ion accept s on e paramet er of t ype HWND an d
ret urn s a void poin t er t ype. Th e HWND paramet er is t h e h an dle t o t h e
win dow t h at is at t empt in g t o draw in format ion wit h in it s clien t area. At
t h is poin t , you wan t t o modify t h e exist in g breakpoin t , addin g a con di-
t ion al breakpoin t t o isolat e a specific HWND value.
1 Before you can set t h e con dit ion al expression , you n eed t o obt ain t h e
HWND value for t h e POLYDEMO win dow. Th e HWND comman d
provides in format ion about applicat ion win dows. Use t h e HWND
comman d an d specify t h e GDIDEMO process:
:HWND GDIDEMO
Table 2-3 illust rat es wh at you sh ould see if you are usin g Win dows
NT/ 2000/ XP. If you are usin g a Win dows 9x plat form, your out put
will vary.
BETA REVI EW
Th e POLYDEMO win dow h an dle is bold an d un derlin ed. Th is is t h e
win dow h an dle you wan t t o use t o form a con dit ion al expression . If
t h e POLYDEMO win dow does n ot appear in t h e HWND out put , exit
Soft ICE usin g t h e G or X comman ds (F5) an d repeat St ep 1 un t il t h e
win dow is creat ed.
Th e value used in t h is example is probably n ot t h e same value t h at
appears in your out put . For t h e exercise t o work correct ly, you must
use t h e HWND comman d t o obt ain t h e act ual HWND value on your
syst em.
Usin g t h e POLYDEMO win dow h an dle, you can set a con dit ion al
expression t o mon it or calls t o LockWin dowIn fo lookin g for a mat ch -
in g h an dle value. Wh en t h e LockWin dowIn fo fun ct ion is called wit h
t h e POLYDEMO win dow h an dle, Soft ICE pops up.
2 Because you already h ave a breakpoin t set on LockWin dowIn fo, use
t h e BPE comman d (Breakpoin t Edit ) t o modify t h e exist in g break-
poin t :
:BPE 0
Wh en you use t h e BPE comman d t o modify an exist in g breakpoin t ,
Soft ICE places t h e defin it ion of t h at breakpoin t on t o t h e comman d
lin e so t h at it can be easily edit ed. Th e out put of t h e BPE comman d
appears:
:BPX LockWindowInfo
Th e cursor appears at t h e en d of t h e comman d lin e an d is ready for
you t o t ype in t h e con dit ion al expression .
3 Remember t o subst it ut e t h e POLYDEMO win dow h an dle value t h at
you foun d usin g t h e HWND comman d, in st ead of t h e value (100172)
used in t h is example. Your con dit ion al expression sh ould appear sim-
Tab l e 3 - 3 : GDIDEMO Process O u t p u t ( Win dows NT/ 2000/ XP)
Handle Class WinProc TID Module
07019C GDIDEMO 004010B5 2D GDIDEMO
100160 MDIClient 77E7F2F5 2D GDIDEMO
09017E BOUNCEDEMO 004015A4 2D GDIDEMO
100172 POLYDEMO 00402F34 2D GDIDEMO
11015C DRAWDEMO 00403CE4 2D GDIDEMO
BETA REVI EW
ilar t o t h e followin g example. Th e con dit ion al expression appears in
bold t ype.
:BPX LockWindowInfo IF ESP->4 == 100172
N o t e : Wi n 3 2 ap p l i cat i o n s p ass p ar am et er s o n t h e st ack an d at t h e en t r y
p o i n t o f a f u n ct i o n ; t h e f i r st p ar am et er h as a p o si t i v e o f f set o f 4 f r o m
t h e ESP r eg i st er. Usi n g t h e So f t I CE ex p r essi o n ev al u at o r, t h i s i s
ex p r essed i n t h e f o l l o w i n g f o r m : ESP-> 4 . ESP i s t h e CPU st ack p o i n t er
r eg i st er an d t h e - > o p er at o r cau ses t h e l ef t h an d si d e o f t h e ex p r es-
si o n ( ESP) t o b e i n d i r ect ed at t h e o f f set sp eci f i ed o n t h e r i g h t h an d
si d e o f t h e ex p r essi o n ( 4 ) . Fo r m o r e i n f o r m at i o n o n t h e So f t ICE
ex p r essi o n eval u at o r r ef er t o Chapter 8: o n p ag e 1 2 3 an d f o r r ef er -
en ci n g t h e st ack i n co n d i t i o n al ex p r essi o n s r ef er t o Conditional Break-
points o n p ag e 1 1 2 .
4 Verify t h at t h e breakpoin t an d con dit ion al expression are correct ly
set by usin g t h e BL comman d.
5 Exit Soft ICE usin g t h e G or X comman d (F5).
Wh en Soft ICE pops up, t h e con dit ion al expression will be TRUE.
Set t ing a Read-Writ e Memory Breakpoint
We set t h e origin al breakpoin t an d subsequen t ly t h e con dit ion al expres-
sion so t h at we could obt ain t h e address of a dat a st ruct ure specific t o
t h is in st an ce of t h e POLYDEMO win dow. Th is value is st ored in t h e
win dows ext ra dat a an d is a global h an dle. Th e LockWin dowIn fo
fun ct ion ret rieves t h is global h an dle an d uses t h e Win 32 API LocalLock
t o t ran slat e it in t o a poin t er t h at can be used t o access t h e win dows
in st an ce dat a.
1 Obt ain t h e poin t er value for t h e win dows in st an ce dat a by execut in g
up t o t h e ret urn st at emen t on source lin e 57:
:G .57
2 Win 32 API fun ct ion s ret urn 32-bit values in t h e EAX regist er, so you
can use t h e BPMD comman d an d specify t h e EAX regist er t o set a
memory breakpoin t on t h e in st an ce dat a poin t er.
:BPMD EAX
Th e BPMD comman d uses t h e h ardware debug regist ers provided by
In t el CPUs t o mon it or reads an d writ es t o t h e Dword value at a lin ear
address. In t h is case, you are usin g BPMD t o t rap read an d writ e
accesses t o t h e first Dword of t h e win dow in st an ce dat a.
3 Use t h e BL comman d t o verify t h at t h e memory breakpoin t is set .
Your out put sh ould look similar t o t h e followin g:
BETA REVI EW
:BL
00) BPX LockWindowInfo IF ((ESP->4)==0x100172)
01) BPMD #0023:001421F8 RW DR3
Breakpoin t in dex 0 is t h e execut ion breakpoin t on LockWin dowIn fo
an d breakpoin t in dex 1 is t h e BPMD on t h e win dow in st an ce dat a.
4 Use t h e BD comman d t o disable t h e breakpoin t on t h e LockWin dow-
In fo.
:BD 0
Soft ICE provides t h e BC (breakpoin t clear) an d BD (breakpoin t
disable) comman ds t o clear or disable a breakpoin t . Disablin g a
breakpoin t is useful if you wan t t o re-en able t h e breakpoin t lat er in
your debuggin g session . If you are n ot in t erest ed in usin g t h e break-
poin t again , t h en it makes more sen se t o clear it .
5 Use t h e BL comman d t o verify t h at t h e breakpoin t on LockWin dow-
In fo is disabled. Soft ICE in dicat es t h at a breakpoin t is disabled by
placin g an ast erisk (*) aft er t h e breakpoin t in dex. Your out put sh ould
appear similar t o t h e followin g:
:BL
00) * BPX _LockWindowInfo IF ((ESP->4)==0x100172)
01) BPMD #0023:001421F8 RW DR3
N o t e : Yo u can u se t h e BE co m m an d t o r e- en ab l e a b r eakp o i n t :
:BE breakpoint-index-number
Wh en t h e POLYDEMO win dow accesses t h e first Dword of it s
win dow in st an ce dat a, t h e breakpoin t t riggers an d Soft ICE pops up.
Wh en Soft ICE pops up due t o t h e memory breakpoin t , you are in t h e
PolyRedraw or PolyDrawBez fun ct ion . Bot h fun ct ion s access t h e
n BezTot al field at offset 0 of t h e POLYDRAW win dow in st an ce dat a.
N o t e : Th e In t el CPU ar ch i t ec t u r e d ef i n es m em o r y b r eakp o i n t s as t r ap s,
w h i c h m ean s t h at t h e b r eakp o i n t t r i g g er s af t er t h e m em o r y h as b een
accessed . In So f t ICE, t h e i n st r u ct i o n o r so u rce l i n e t h at i s h i g h l i g h t ed
i s t h e o n e af t er t h e i n st r u ct i o n o r so u rce l i n e t h at accessed t h e
m em o r y.
6 Clear t h e breakpoin t s you set in t h is sect ion by usin g t h e BC com-
man d:
:BC *
N o t e : Yo u can u se t h e w i l d car d ch ar act er ( * ) w i t h t h e BC, BD , an d BE
co m m an d s t o cl ear, d i sab l e, an d en ab l e al l b r eakp o i n t s.
7 Exit Soft ICE usin g t h e G or X comman d.
Th e operat in g syst em t ermin at es t h e demo.
BETA REVI EW
Con grat ulat ion s on complet in g your first Soft ICE debuggin g session .
Your world will n ever be t h e same again . In t h is session , you t raced
t h rough source code, viewed locals an d st ruct ures, an d set poin t -an d-
sh oot , con dit ion al, an d read-writ e memory breakpoin t s. Soft ICE provides
man y more advan ced feat ures. Th e Soft ICE comman ds ADDR, HEAP,
LOCALS, QUERY, THREAD, TYPES, WATCH, an d WHAT are just a few of
t h e man y Soft ICE comman ds t h at h elp you debug smart er an d fast er.
Refer t o t h e SoftICE Command Reference for a complete list an d explan a-
t ion of all of t h e Soft ICE comman ds.
3 1
BETA REVI EW
Ch ap t er 4
Loading Code int o Soft ICE
D e b ug g in g Con cep t s
Load in g Sof t I CE M an ually
U sin g Sym b o l Lo ad e r t o Tr an slat e an d Lo ad File s
M od if yin g M o d ule Set t in g s
Sp ecif yin g Pr o g r am Source Files
D elet in g Sym b o l Tab les
U sin g Sym b o l Lo ad e r Fr o m a D O S Pr om p t
U sin g t h e Sym b o l Lo ad er Co m m an d - Lin e U t ilit y
Debugging Concept s
Soft ICE allows you t o debug Win dows applicat ion s an d device drivers at
t h e source level. To accomplish t h is, Soft ICE uses t h e Symbol Loader
ut ilit y t o t ran slat e t h e debug in format ion from your compiled module
in t o an .NMS symbol file. Wh en t h is is don e, Symbol Loader can load t h e
.NMS file an d, opt ion ally, t h e source code in t o Soft ICE, wh ere you can
debug it .
Th e poin t in t ime at wh ich you n eed t o load t h e .NMS file depen ds on
wh et h er you are debuggin g a module t h at run s aft er t h e operat in g syst em
boot s or a device driver or st at ic VxD t h at loads before t h e operat in g
syst em in it ializes. If you are loadin g a device driver or VxD, Soft ICE pre-
loads t h e modules symbols an d source wh en it in it ializes. If you are
debuggin g a module or compon en t t h at run s aft er t h e operat in g syst em
boot s, you can use Symbol Loader t o load symbols wh en you n eed t h em.
Th is ch apter explain s h ow t o use Symbol Loader t o load your module in t o
Soft ICE. It also describes h ow t o use Symbol Loader from a DOS prompt
t o aut omat e man y of t h e most common t asks it performs an d h ow t o use
t h e Symbol Loader comman d-lin e ut ilit y (NMSYM) t o creat e a bat ch
process t o t ran slat e an d load symbol in format ion .
BETA REVI EW
N o t e : Sy m b o l Lo ad er o n l y su p p o r t s Wi n d o w s ap p l i cat i o n s. To d eb u g M S-
D O S ap p l i cat i o n s u se t h e t o o l s i n t h e UTIL1 6 d i r ect o r y.
Pr epa r i ng t o Debug Appl i ca t i ons
Th e followin g gen eral st eps explain h ow t o prepare t o debug modules
an d compon en t s t h at run aft er t h e operat in g syst em boot s. Th ese
modules in clude EXEs, DLLs, dyn amic VxDs, an d OCXs. Th e sect ion s
t h at follow explain h ow t o perform t h ese st eps in det ail.
1 Build t h e module wit h debug in format ion .
2 If Soft ICE is n ot already loaded, load Soft ICE.
4 Select OPEN MODULE from t h e File Men u an d open t h e module you
wan t t o debug.
5 Use Symbol Loader t o t ran slat e t h e debug in format ion in t o a .NMS
symbol file an d load t h e source an d symbol files in t o Soft ICE for you.
Pr epa r i ng t o Debug Devi ce Dr i ver s a nd Vx Ds
Th e followin g gen eral st eps explain h ow t o prepare t o debug device
drivers or st at ic VxDs t h at load before t h e operat in g syst em fully in it ial-
izes. Th e sect ion s t h at follow explain h ow t o perform t h ese st eps in
det ail.
1 Build t h e applicat ion wit h debug in format ion .
2 If Soft ICE is n ot already loaded, load Soft ICE.
4 Click t h e OPEN but t on t o open t h e module you wan t t o debug.
5 Select t h e PACKAGE SOURCE WITH SYMBOL TABLE set t in g wit h in t h e Sym-
bol Loader t ran slat ion set t in gs. Refer t o Modifying Module Settings on
page 37.
6 Click t h e TRANSLATE but t on t o creat e a n ew .NMS symbol file.
7 Modify t h e Soft ICE in it ializat ion set t in gs t o pre-load t h e debug in for-
mat ion for t h e VxD or device driver on st art up. Refer t o Pre-loading
Symbols and Source Code on page 165.
8 Reboot your PC.
Ch ap t er 4 Lo ad i n g Co d e i n t o So f t ICE 3 3
BETA REVI EW
Loading Soft ICE Manually
Soft ICE does n ot load aut omat ically un der t h e followin g con figurat ion s:
If you did n ot run WINICE.EXE from t h e AUTOEXEC.BAT before
st art in g Win dows 9x.
Wh en you set Soft ICE for Win dows NT/ 2000/ XP t o Man ual St art up
mode.
If you are usin g t h ese con figurat ion s, you n eed t o load Soft ICE man ually.
Th e followin g sect ion s describe h ow t o load Soft ICE man ually.
Loa di ng Sof t I CE f or W i ndow s 9 x
Load Soft ICE for Win dows 9x from t h e DOS comman d lin e. Soft ICE will
aut omat ically run Win dows 9x aft er Soft ICE in it ializes. Use t h e followin g
comman d syn t ax.
WINICE[/HST n] [/TRA n] [/SYM n] [/M]
[/LOAD[x] name]
[/EXP name][drive:\path\WIN.COM
[Windows-command-line]]
Ti p You ca n sp eci f y t h ese
sw i t ch es i n t h e
I n i t i a l i z a t i on st r i n g . Ref er
t o M od i f yi n g Sof t I CE
I n i t i a l i z a t i on Set t i n g s on
p a g e 1 6 1 .
Wh ere t h e followin g are opt ion al swit ch es.
Tab l e 4 - 1 . O p t i o n al Co m m an d Li n e Sw i t ch es
O p t i on al
Sw it ch
D ef in it i on
/ EXP n am e Ad d s ex p o r t s f r o m t h e D LL o r Wi n d o w s ap p l i cat i o n sp ec i f i ed b y
n am e t o t h e So f t ICE ex p o r t l i st . Th i s l et s y o u sy m b o l i c al l y access
t h ese ex p o r t ed sy m b o l s.
/ HST n In cr eases t h e si ze o f t h e co m m an d r ecal l b u f f er, w h er e n i s a
d eci m al n u m b er t h at r ep r esen t s t h e n u m b er o f ki l o b y t es. Th e
d ef au l t i s 8 KB.
/ LO AD
n am e[ x ]
Lo ad s sy m b o l an d so u r ce, w h er e n am e i s t h e co m p l et e p at h
an d f i l e n am e f o r a Vx D , D O S T& SR, D O S l o ad ab l e d ev i ce
d r i ver, D O S p r o g r am , Wi n d o w s d r i ver, Wi n d o w s D LL, o r
Wi n d o w s p r o g r am t h at w as b u i l t w i t h sy m b o l s. If x i s p r esen t ,
so u r ce i s n o t l o ad ed .
/ M D i r ect s So f t ICE o u t p u t t o t h e seco n d ar y m o n o ch r o m e m o n i t o r,
b y p assi n g an y i n i t i al VGA p r o g r am m i n g .
Yo u can al so u se t h i s o p t i o n al sw i t ch f o r ser i al d eb u g g i n g b y
sp eci f y i n g / M o n t h e c o m m an d l i n e an d i n cl u d i n g a ser i al
co m m an d i n t h e In i t i al i zat i o n st r i n g .
BETA REVI EW
Loa di ng Sof t I CE f or W i ndow s N T/ 2 0 0 0 / XP
To load Soft ICE for Win dows NT/ 2000/ XP, do on e of t h e followin g:
Select START SOFTICE from t h e Compuware/ SICE group.
En t er t h e comman d: NET START NTICE
N o t e : O n ce y o u l o ad So f t ICE, y o u can n o t d eact i v at e i t u n t i l y o u r eb o o t
y o u r PC.
Building Applicat ions wit h Debug Informat ion
Th e followin g compiler-specific in format ion is provided as a guidelin e. If
you are buildin g an applicat ion wit h debug in format ion , con sult your
compiler or assembler documen t at ion for more in format ion .
/ SYM n Al l o cat es a sy m b o l t ab l e, w h er e n i s a d eci m al n u m b er t h at
r ep r esen t s t h e n u m b er o f ki l o b y t es. Th e d ef au l t i s 0 KB.
/ TRA n In cr eases t h e si ze o f t h e b ack t r ace h i st o r y b u f f er, w h er e n i s a
d eci m al n u m b er t h at r ep r esen t s t h e n u m b er o f ki l o b y t es. Th e
d ef au l t i s 8 KB.
Tab l e 4 - 1 . O p t i o n al Co m m an d Li n e Sw i t ch es
O p t i on al
Sw it ch
D ef in it i on
Tab l e 4 - 2 . Co m p i l er - sp eci f i c D eb u g g i n g In f o r m at i o n
Co m p i l er Gen er at i n g D eb u g g i n g In f o r m at i o n
Bo r l an d C+ + 4 . 5
an d 5 . 0
To g en er at e Bo r l an d s st an d ar d d eb u g i n f o r m at i o n :
Co m p i l e w i t h / v
Li n k w i t h / v
D el p h i 2 . 0 To g en er at e D el p h i s st an d ar d d eb u g i n f o r m at i o n :
Co m p i l e w i t h t h e f o l l o w i n g :
- V t o i n cl u d e d eb u g i n f o r m at i o n i n t h e ex ecu t ab l e
- $ W+ t o cr eat e st ack f r am es
- $ D + t o cr eat e d eb u g i n f o r m at i o n
- $ L+ t o cr eat e l o cal d eb u g sy m b o l s
- $ O - t o d i sab l e o p t i m i zat i o n
BETA REVI EW
N o t e : So f t I CE su p p o r t s o t h er co m p i l er s t h at m ay n o t ap p ear i n t h e ab o v e
t ab l e. In g en er al , So f t ICE p r o v i d es sy m b o l i c d eb u g g i n g f o r an y
co m p i l er t h at p r o d u ces Co d ev i ew co m p at i b l e d eb u g i n f o r m at i o n .
Using Symbol Loader t o Translat e and Load Files
Before Soft ICE can debug your applicat ion , DLL, or driver, you n eed t o
creat e a symbol file for each of t h e modules you wan t t o debug, an d load
t h ese files in t o Soft ICE. Symbol Loader makes t h is procedure quick an d
easy. Symbol Loader let s you iden t ify t h e module you wan t t o load, t h en
aut omat ically creat es a correspon din g symbol file. Fin ally, Symbol Loader
loads t h e symbol, source, an d execut able files in t o Soft ICE. By default ,
Symbol Loader loads all t h e files referen ced in t h e debug in format ion . To
limit t h e source files Symbol Loader loads, refer t o Specifying Program
Source Files on page 42.
To use Symbol Loader t o load a module, do t h e followin g:
M ASM 6 . 1 1 To g en er at e Co d ev i ew d eb u g i n f o r m at i o n :
Assem b l e w i t h / Z i / CO FF
Use M i cr o so f t s 3 2 - b i t LIN K. EXE t o l i n k w i t h
/ D EBUG / D EBUGTYPE: CV / PD B: N O N E
M i cr o so f t Vi su al
C+ + 2 . x , 4 . 0 , 4 . 1 ,
4 . 2 , 5 . 0 , an d 6 . 0
To g en er at e Pr o g r am D at ab ase ( PD B) d eb u g i n f o r m at i o n :
Co m p i l e w i t h Pr o g r am D at ab ase d eb u g i n f o r m at i o n , u si n g
t h e c o m m an d - l i n e o p t i o n / Z i
Use M i cr o so f t s l i n ker t o l i n k w i t h
/ D EBUG / D EBUGTYPE: CV
Note: Vx D s r eq u i r e y o u t o g en er at e PD B d eb u g i n f o r m a-
t i o n .
To g en er at e Co d ev i ew d eb u g i n f o r m at i o n :
Co m p i l e w i t h C7 - co m p at i b l e d eb u g i n f o r m at i o n , u si n g t h e
co m m an d - l i n e o p t i o n / Z 7
Use M i cr o so f t s l i n ker t o l i n k w i t h
/ D EBUG / D EBUGTYPE: CV / PD B: N O N E
Note: I f y o u ar e u si n g t h e st an d ar d Wi n d o w s N T D D K
m ak e p r o ced u r e, u se t h e f o l l o w i n g en v i r o n m en t
v ar i ab l es: N TD EBUG= n t sd an d N TD EBUG-
TYPE= w i n d b g .
Tab l e 4 - 2 . Co m p i l er - sp eci f i c D eb u g g i n g In f o r m at i o n
BETA REVI EW
Fi g u r e 4 - 1 . Sy m b o l Lo ad er Wi n d o w
2 Ch oose Open Module from t h e File men u.
3 Select your t ran slat ion opt ion s.
4 If you open a .SYM file, Symbol Loader displays a dialog box t h at asks
you wh et h er or n ot t h e file is a 32-bit file. If it is a 32-bit file, click
YES; ot h erwise, click NO.
Due t o a file format rest rict ion in .SYM files, Soft ICE can n ot det er-
min e wh et h er .SYM files are 16-bit or 32-bit .
5 Ch oose LOAD from t h e Module men u, or click t h e LOAD but t on t o
load t h e open file.
Symbol Loader t ran slat es your applicat ions debug in format ion t o an
.NMS symbol file. Th en Symbol Loader loads t h e symbol an d source
files in t o Soft ICE. If you are loadin g an .EXE file, Soft ICE st art s t h e
program an d set s a breakpoin t at t h e first main module (Win Main ,
Main , or DllMain ) it en coun t ers.
Th e in format ion Symbol Loader loads depen ds on t h e Tran slat ion
an d Debuggin g set t in gs. Refer t o Modifying Module Settings on page 37
for more in format ion about modifyin g Tran slat ion an d Debuggin g
set t in gs.
BETA REVI EW
Modifying Module Set t ings
Th e Symbol Loader uses a series of set t in gs t o con t rol h ow it t ran slat es
an d loads files. Th ese set t in gs are cat egorized as follows:
Gen eral Specifies comman d-lin e argumen t s an d source file search
pat h s.
Debuggin g Specifies t h e t ypes of files (symbols an d execut ables)
Symbol Loader loads in t o Soft ICE, as well as an y default act ion s Soft -
ICE performs at load t ime.
Tran slat ion Specifies wh ich combin at ion of symbols (publics, t ype
in format ion , symbols, or symbols an d source) Symbol Loader t ran s-
lat es.
Th ese set t in gs are available on a per module basis. Th us, ch an gin g a
part icular set t in g applies t o t h e curren t module on ly. Wh en you open a
differen t module, Symbol Loader uses t h e pre-est ablish ed default s.
Ti p Th e n a m e of t h e
cu r r en t o p en f i l e i s
l i st ed i n t h e Sym b ol
Loa d er t i t l e b a r.
To ch an ge t h e default file set t in gs for a module, do t h e followin g:
1 Open t h e file if it is n ot already open .
2 From t h e Module men u, select SETTINGS.
3 Click t h e t ab t h at represen t s t h e set t in gs you wan t t o modify.
4 See t h e sect ion s t h at follow for more in format ion about specific set -
t in gs for each t ab.
5 Wh en you are don e modifyin g t h e set t in gs, click OK.
6 Load t h e file t o apply your ch an ges.
BETA REVI EW
M odi f yi ng Gener a l Set t i ngs
Th e Gen eral Project Set t in gs t ab allows you t o set comman d-lin e
argumen t s an d specify source file search pat h s.
Fi g u r e 4 - 2 . Gen er al Pr o j ect Set t i n g s Tab
Th e followin g paragraph s describe t h e Gen eral set t in gs select ion s.
Co m m an d Lin e Ar g um en t s
Use Command Line Arguments t o specify comman d-lin e argumen t s t o
pass t o your program.
Source File Sear ch Pat h
Use Source File Search Path t o det ermin e t h e search pat h Soft ICE uses t o
locat e files associat ed wit h t h is applicat ion . If Symbol Loader can n ot
locat e t h e files wit h in t h is search pat h , it uses t h e con t en t s of t h e Default
Source File Search Path t o expan d it s search .
D ef ault Source File Se arch Pat h
Use Default Source File Search Path t o det ermin e t h e search pat h Soft ICE
uses t o locat e files in gen eral. Th is set t in g is a global set t in g.
N o t e : If y o u u se t h e Source File Search Path set t i n g t o sp eci f y t h e sear ch
p at h f o r a sp eci f i c p r o g r am , Sy m b o l Lo ad er u ses t h e search p at h y o u
sp eci f i ed f o r t h e ap p l i cat i o n b ef o r e l o o ki n g at t h e g l o b al search p at h .
BETA REVI EW
Pr o m p t f o r M issin g Sour ce File s
Use Prompt for Missing Source Files t o det ermin e if Symbol Loader
prompt s you wh en it can n ot fin d a source file. Th is set t in g is global an d
is t urn ed on by default .
M odi f yi ng Tr a nsl a t i on Set t i ngs
Tran slat ion set t in gs det ermin e t h e t ype of in format ion Symbol Loader
t ran slat es wh en it creat es .NMS symbol files an d specifies if your source
code is st ored in t h e symbol file. Th ese set t in gs det ermin e h ow much
memory is n eeded t o debug your program an d t h ey are list ed in order
from least t o most amoun t of symbol memory required.
Fi g u r e 4 - 3 . Tr an sl at i o n Set t i n g s Tab
Th e followin g paragraph s describe t h e Tran slat ion set t in gs select ion s.
Pub lics O n ly
Publics Only provides public (global) symbol n ames. Neit h er t ype in for-
mat ion n or source code are in cluded.
Typ e in f or m at io n o n ly
Th is set t in g provides t ype in format ion on ly. Use t h is set t in g t o provide
t ype in format ion for dat a st ruct ures t h at are reverse en gin eered.
BETA REVI EW
Sym b o ls on ly
Symbols only provides global, st at ic, an d local symbol n ames in addit ion
t o t ype in format ion . Source code is n ot in cluded.
Sym b o ls an d source cod e
Symbols and source code provides all available debuggin g in format ion ,
in cludin g source code an d lin e n umber in format ion . Th is set t in g is
en abled by default .
Packag e so urce w it h sym b o l t ab le
Th is set t in g saves your source code wit h t h e symbol in format ion in t h e
.NMS file. You migh t wan t t o in clude your source file in t h e symbol file
un der t h e followin g circumst an ces:
Loadin g source code at boot t ime
Soft Ice does n ot look for code files at boot t ime. If you n eed t o load
source code for a VxD or Win dows NT device driver, select PACKAGE
SOURCE WITH SYMBOLS TABLE. Th en , modify t h e Soft ICE in it ializat ion
set t in gs t o load t h e debug in format ion for t h e VxD or device driver
on st art up. Refer t o Pre-loading Symbols and Source Code on page 165.
Debuggin g on a syst em t h at does n ot h ave access t o your source files
If you wan t t o debug your applicat ion on a syst em t h at does n ot h ave
access t o your source files, select PACKAGE SOURCE WITH SYMBOLS an d
copy t h e .NMS file t o t h e ot h er syst em.
Caut ion : I f you se le ct Package source with symbol table, yo ur so ur ce co d e
is availab le t o an yo n e w h o accesse s t h e sym b o l t ab le. I f you d o n ot w an t
ot h e r s t o h ave acce ss t o yo ur sour ce cod e an d yo u p r ovi d e t h e . N M S f ile
w it h yo ur ap p l icat io n , t ur n o f f t h i s op t io n .
BETA REVI EW
M odi f yi ng Debuggi ng Set t i ngs
Th e Debuggin g set t in gs det ermin e wh at t ype of in format ion t o load an d
wh et h er or n ot t o st op at t h e module en t ry poin t .
Fi g u r e 4 - 4 . D eb u g g i n g Set t i n g s Tab
Th e followin g paragraph s describe t h e Debuggin g set t in gs select ion s.
Load sym b o l in f o r m at ion on ly
Load symbol information only loads t h e .NMS symbol file, but does n ot
load t h e execut able image. It also loads t h e associat ed source files if you
select ed Symbols and Source Code in t h e Tran slat ion opt ion s. By default ,
Symbol Loader select s t h is set t in g for .DLL, .SYS, an d VxD file t ypes.
Load execut ab le
Load executable loads your execut able an d .NMS file. It also loads t h e
associat ed source files if you select ed Symbols and Source Code in t h e
Tran slat ion opt ion s. By default , Symbol Loader select s t h is set t in g for
.EXE files.
St o p at W in M ain , M ain , D llM ain , et c.
Th is set t in g creat es a breakpoin t at t h e first main module Soft ICE
en coun t ers as it loads your applicat ion .
BETA REVI EW
Specifying Program Source Files
By default , all program source files t h at are referen ced in t h e debug in for-
mat ion are loaded. Depen din g on your n eeds, loadin g all program source
files may n ot be n ecessary. Also, if t h e n umber of source files is large,
loadin g all source files may n ot be pract ical.
To avoid loadin g un n ecessary source files, Soft ICE let s you use a .SRC file
t o specify wh ich source files t o load for an execut able module. A .SRC file
is a t ext file t h at you creat e in t h e direct ory wh ere your execut able
resides. Th e filen ame of t h e .SRC file is t h e same as t h e filen ame of t h e
execut able, but wit h a .SRC ext en sion . Th e .SRC file con t ain s a list of t h e
source files t h at are t o be loaded, on e per lin e.
If you h ave an execut able n amed PROGRAM.EXE, you would creat e a
.SRC file, PROGRAM.SRC. Th e con t en t s of t h e PROGRAM.SRC file migh t
look like t h e followin g:
!!!!1.
!!!!.
!!!!4.
Assumin g t h at FILE2.C was a valid program source file, it would n ot be
loaded because it does n ot appear in t h e .SRC file. FILE1.C, FILE3.CPP,
an d FILE4.C would be loaded.
Delet ing Symbol Tables
Every t ime you t ran slat e your source code, Symbol Loader creat es a .NMS
symbol file in t h e form of a symbol t able. Wh en you load your module,
Symbol Loader st ores t h e t able in memory un t il you eit h er delet e t h e
t able or reboot your PC.
To delet e a symbol t able, do t h e followin g:
BETA REVI EW
1 Ch oose Symbol Tables from t h e Edit men u.
Fi g u r e 4 - 5 . So f t ICE Pr o j ect Wi n d o w
2 Righ t -click on t h e .NMS file in t h e Loaded Symbols list an d select
Remove from t h e pop-up men u.
N o t e : Yo u can al so r i g h t - cl i ck o n a sessi o n i n t h e Wo r ksp ace v i ew an d sel ect
Rem o v e f o r an i n d i v i d u al f i l e o r a sessi o n .
Using Symbol Loader From a DOS Prompt
Symbol Loader (LOADER32.EXE) support s a comman d-lin e in t erface t h at
let s you use man y of it s feat ures from a DOS prompt wit h out viewin g
Symbol Loaders graph ical in t erface. Th us, you can aut omat e man y of t h e
most common t asks it performs.
Before you use LOADER32.EXE from a DOS prompt , use Symbol Loaders
graph ical in t erface t o set t h e default search pat h s an d t o specify t ran sla-
t ion an d debuggin g set t in gs for each module you plan t o load. Symbol
Loader save t h ese set t in gs for each file an d uses t h em wh en you use
LOADER32 t o load or t ran slat e t h e files from a DOS prompt . Refer t o
Modifying Module Settings on page 37.
To run LOADER32.EXE, eit h er set your direct ory t o t h e direct ory t h at
con t ain s LOADER32.EXE or specify t h e Soft ICE direct ory in your search
pat h .
BETA REVI EW
Co m m an d Syn t ax
Use t h e followin g syn t ax for LOADER32.EXE:
LOADER32 [[option(s)] file-name]
Wh ere +!cramc is t h e n ame of t h e file you wan t t o t ran slat e or load
an d ol+or are as sh own in Table 3-3.
Follow t h ese guidelin es wh en specifyin g t h e comman d syn t ax:
Opt ion s are n ot required. If you specify a file n ame wit h out an
opt ion , LOADER32.EXE st art s t h e Symbol Loader graph ical in t erface
an d open s t h e file.
Specify bot h t h e / TRANSLATE an d / LOAD opt ion s t o force
LOADER32.EXE t o t ran slat e t h e module before loadin g it .
Do n ot use t h e / EXPORTS or t h e / LOGFILE opt ion s wit h an y ot h er
opt ion .
N o t e : If y o u sp eci f y an o p t i o n , LO AD ER3 2 . EXE d o es n o t d i sp l ay t h e Sy m b o l
Lo ad er g r ap h i cal i n t er f ace u n l ess i t en c o u n t er s an er r o r. If
LO AD ER3 2 . EXE en co u n t er s an er r o r, i t d i sp l ay s t h e er r o r i n t h e
Sy m b o l Lo ad er w i n d o w .
Tab l e 4 - 3 . Sy m b o l Lo ad er Co m m an d - Li n e O p t i o n s
O p t i o n D ef i n i t i o n
/ EXPO RTS Lo ad s ex p o r t s f o r a f i l e.
/ LO AD Tr an sl at es t h e m o d u l e i n t o a . N M S f i l e, i f o n e d o es n o t al r ead y
ex i st , an d l o ad s i t i n t o So f t ICE. If y o u p r ev i o u sl y set Tr an sl at i o n
an d D eb u g g i n g set t i n g s f o r t h i s f i l e, LO AD ER3 2 . EXE u ses t h ese
set t i n g s. If y o u d i d n o t sp eci f y t h ese set t i n g s, LO AD ER3 2 . EXE
u ses t h e d ef au l t s f o r t h e m o d u l e t y p e.
/ LO GFILE Saves t h e So f t ICE h i st o r y b u f f er t o a l o g f i l e.
/ N O PRO M PT In st r u ct s LO AD ER3 2 . EXE n o t t o p r o m p t y o u i f i t can n o t f i n d a
so u r ce f i l e.
/ PACKAGE Saves y o u r so u r ce co d e w i t h t h e sy m b o l i n f o r m at i o n i n t h e
. N M S f i l e.
/ TRAN SLATE Tr an sl at es t h e m o d u l e i n t o a . N M S f i l e u si n g t h e Tr an sl at i o n set -
t i n g s y o u set t h e l ast t i m e y o u t r an sl at ed t h e f i l e o r, i f n o n e ex i st ,
t h e d ef au l t t r an sl at i o n f o r t h e m o d u l e t y p e.
BETA REVI EW
Using t he Symbol Loader Command-Line Ut ilit y
NMSYM is a ut ilit y program t h at let s you creat e a bat ch process t o t ran s-
lat e an d load symbol in format ion for use wit h Soft ICE or ot h er programs
t h at use t h e NM32 symbol t able file format . NMSYM provides a series
of comman d opt ion s an alogous t o feat ures wit h in Soft ICE Symbol
Loader (Loader32.exe) t h at perform t h e followin g fun ct ion s:
N M SYM Comma nd Synt a x
Use t h e followin g syn t ax for NMSYM.EXE:
NMSYM [option(s)] <module-name>
Wh ere:
Opt ion s are specified by usin g a slash (/ ) followed by t h e opt ion
n ame.
PRGXOHQDPH! is t h e n ame of t h e module you wan t t o t ran slat e or
load.
Th e followin g example sh ows a valid comman d lin e:
NMSYM /TRANSLATE C:\MYPROJ\MYPROJECT.EXE
U sin g O p t io n an d File - list Sp ecif ier s
Man y opt ion s in clude addit ion al opt ion an d file-list specifiers. Opt ion
specifiers modify an aspect of t h e opt ion an d file-list specifiers specify
operat ion s on a group of files.
Tab l e 4 - 4 . N M SYM Co m m an d - Li n e O p t i o n s
Fu n ct i o n N M SYM O p t i o n s
Tr an sl at e an d l o ad sy m b o l i n f o r m at i o n f o r an i n d i v i d u al
m o d u l e
/ TRAN SLATE o r / TRAN S
/ LO AD
/ SO URCE
/ ARGS
/ O UTPUT o r / O UT
/ PRO M PT
Lo ad an d u n l o ad g r o u p s o f sy m b o l t ab l es an d m o d u l e
ex p o r t s
/ SYM LO AD o r / SYM
/ EXPO RTS o r / EXP
/ UN LO AD
Sav e t h e So f t ICE h i st o r y b u f f er t o a f i l e / LO GFILE o r / LO G
O b t ai n p r o d u ct v er si o n i n f o r m at i o n an d h el p / VERSIO N o r / VER
/ HELP o r / H
BETA REVI EW
Th e syn t ax for opt ion specifiers is as follows:
/option:<option-specifier>[,<option-specifier>]
Th e opt ion is followed by a colon (:), wh ich , in t urn , is followed by a
comma delimit ed list of specifiers. Th e followin g example uses t h e /
TRANSLATE opt ion wit h t h e SOURCE an d PACKAGE specifiers t o in st ruct
NMSYM t o t ran slat e source an d symbols, t h en package t h e source files
wit h t h e NMS symbol t able:
/TRANSLATE:SOURCE,PACKAGE
Th e syn t ax for file-list specifiers is as follows:
/option:<filename|pathname>[;<filename|pathname>]
Th e followin g example uses t h e / SOURCE opt ion wit h t h ree pat h -list
specifiers. NMSYM search es t h e pat h s in t h e pat h -list specifiers t o locat e
source code files durin g t ran slat ion an d loadin g:
/SOURCE:c:\myproj\i386;c:\myproj\include;c:\msdev\include;
Th e opt ion an d file list specifiers are list ed h ere an d described on t h e
pages t h at follow.
/ TRANSLATE
/ LOAD
/ OUTPUT
/ SOURCE
/ ARGS
/ PROPMT
/ SYM(LOAD)
/ EXP(ORTS)
/ UNLOAD
/ LOG(FILE)
/ VER(SION)
Usi ng N M SYM t o Tr a nsl a t e Symbol I nf or ma t i on
Th e primary purpose of NMSYM is t o t ake compiler gen erat ed debug
in format ion for a module an d t ran slat e it in t o t h e NM32 symbol format ,
t h en place t h at in format ion in t o a .NMS symbol file. To accomplish t h is,
use t h e followin g opt ion s an d paramet ers on t h e NMSYM comman d lin e:
Use t h e / TRANSLATE opt ion t o specify t h e t ype of symbol in forma-
t ion you wan t t o gen erat e.
Use t h e / SOURCE opt ion t o specify t h e source pat h s t h at NMSYM
search es t o locat e source code files.
If you wan t t o specify an alt ern at e filen ame for t h e .NMS file, use t h e
/ OUTPUT opt ion .
Specify t h e n ame of t h e module t h at you wan t t o t ran slat e.
BETA REVI EW
NMSYM /TRANSLATE C:\MYPROJ\MYPROJECT.EXE
Th e followin g paragraph s describe t h e t ran slat ion opt ion s. Use t h ese
opt ion s t o t ran slat e symbol in format ion for an in dividual module.
/ TRAN SLATE O p t io n
Th e / TRANSLATE :<translation-specifier-list> opt ion let s you specify
t h e t ype of symbol in format ion you wish t o produce, as well as wh et h er
source code is packaged wit h t h e symbol file. Ot h er opt ion s in clude t h e
abilit y t o force t h e t ran slat ion t o occur, even if t h e symbol file is already
up t o dat e.
Th e / TRANSLATE opt ion t akes a variet y of opt ion specifiers, in cludin g
symbol-in format ion , source code packagin g, an d a miscellan eous speci-
fier, ALWAYS. Th e followin g sect ion s describe t h ese specifiers.
Sym b o l- in f or m at io n Sp e cif ie r s
Th e followin g t able list s opt ion al symbol-in format ion specifiers t h at
det ermin e wh at symbol in format ion is t ran slat ed. Use on e symbol-in for-
mat ion specifier on ly. If you do n ot use a specifier, NMSYM default s t o
SOURCE.
Tab l e 4 - 5 . O p t i o n al Sy m b o l - i n f o r m at i o n Sp eci f i er s
Sy m b o l -
i n f o r m at i o n
Sp eci f i er
D escr i p t i o n
PUBLICS O n l y p u b l i c ( g l o b al ) sy m b o l s ar e i n cl u d ed . St at i c f u n ct i o n s
an d v ar i ab l es ar e ex cl u d ed . Th i s o p t i o n i s si m i l ar t o t h e
sy m b o l i n f o r m at i o n t h at can b e f o u n d i n a M AP f i l e. It p r o -
d u ces t h e sm al l est sy m b o l t ab l es.
TYPEIN FO O n l y t h e t y p e i n f o r m at i o n i s i n cl u d ed . Sy m b o l i n f o r m at i o n
i s ex cl u d ed . Use t h i s o p t i o n w h en y o u p r o d u ce ad v an ced
t y p e i n f o r m at i o n w i t h o u t t h e o r i g i n al so u r ce co d e o r
d eb u g i n f o r m at i o n .
SYM BO LS In cl u d es al l sy m b o l an d t y p e i n f o r m at i o n . So u r ce co d e an d
l i n e- n u m b er i n f o r m at i o n i s ex cl u d ed . Th i s sp eci f i er p r o -
d u ces sm al l er sy m b o l t ab l es.
SO URCE Th i s i s t h e d ef au l t t r an sl at i o n t y p e. Al l sy m b o l , t y p e, an d
so u r ce co d e i n f o r m at i o n i s i n cl u d ed .
BETA REVI EW
N o t e : So u rce co d e i n f o r m at i o n d o es n o t i n cl u d e t h e so u rce f i l es
t h em sel ves. It i s i n f o r m at i o n ab o u t t h e so u r ce c o d e f i l es, su ch as t h ei r
n am es an d l i n e- n u m b er i n f o r m at i o n .
Source Cod e Packag in g Sp ecif ier s
Opt ion al source code packagin g specifiers det ermin e wh et h er or n ot
NMSYM at t ach es source code t o t h e .NMS symbol file. By default ,
NMSYM does t h e followin g:
Packages t h e source code wit h t h e .NMS symbol files for device driver
modules, because t h ey load before t h e operat in g syst em fully in it ial-
izes.
Does n ot package t h e source code for applicat ion s t h at run aft er t h e
operat in g syst em boot s.
Use t h e followin g source code packagin g specifiers t o override t h ese
default s:
N o t e : If y o u p ac kag e t h e so u rce co d e w i t h t h e . N M S sy m b o l f i l e, y o u r co d e
i s av ai l ab l e t o an y o n e w h o ac cesses t h e sy m b o l t ab l e.
ALW AYS Sp e cif ie r
By default , NMSYM does n ot t ran slat e t h e symbol in format ion if it is
curren t . Use t h e ALWAYS specifier t o force NMSYM t o t ran slat e t h e
symbol in format ion regardless of it s st at us.
Exam p les: U sin g t h e / TRAN SLATE O p t io n
Th e followin g example specifies a module n ame wit h out t h e / TRANSLA-
TON opt ion . Th us, t h e t ran slat ion is performed usin g t h e default opt ion s
for t h e module t ype.
NMSYM myproj.exe
N o t e : Fo r Wi n 3 2 ap p l i cat i o n s o r D LLs, t h e d ef au l t i s
/ TRAN SLATE: SO URCE, N O PACKAGE.
Tab l e 4 - 6 . O p t i o n al So u rc e Co d e Packag i n g Sp eci f i er s
So u rce Co d e
Packag i n g
Sp eci f i er
D escr i p t i o n
PACKAGE In cl u d e so u r ce f i l es w i t h t h e . N M S sy m b o l f i l e.
N O PACKAGE D o n o t i n cl u d e so u rce f i l es w i t h t h e . N M S sy m b o l f i l e.
BETA REVI EW
Fo r d r i v er m o d u l es, t h e d ef au l t i s
/ TRAN SLATE: SO URCE: PACKAGE.
Th e followin g example t ran slat es symbol in format ion for a VxD. It uses
t h e SYMBOLS specifier t o exclude in format ion relat ed t o t h e source code
an d t h e / NOPACKAGE specifier t o preven t NMSYM from packagin g
source code.
NMSYM /TRANSLATE:SYMBOLS,NOPACKAGE c:\myvxd.vxd
Th e followin g example uses t h e default opt ion s for t h e module t ype an d
uses t h e / ALWAYS specifier t o force NMSYM t o t ran slat e t h e symbol
in format ion in t o a .NMS symbol file.
NMSYM /TRANSLATE:ALWAYS myproj.exe
/ SO U RCE O p t ion
Use t h e / SOURCE :<path-list> opt ion t o specify t h e source pat h s t h at
NMSYM sh ould search t o locat e source code files. At t ran slat ion t ime
(PACKAGE on ly) or module load t ime (/ LOAD or / SYMLOAD), NMSYM
will at t empt t o locat e all t h e source files specified wit h in t h e NMS symbol
t able. It will do a default search alon g t h is pat h t o locat e t h em.
Th e pat h -list specifier is on e or more pat h s con cat en at ed t oget h er. Each
pat h is separat ed from t h e previous pat h by a semi-colon ;. Th e /
SOURCE opt ion may be specified on e or more t imes on a sin gle
comman d-lin e. Th e order of t h e / SOURCE st at emen t s, an d t h e order of
t h e pat h s wit h in t h e pat h -list det ermin es t h e search order.
Exam p les: U sin g t h e / SO U RCE O p t ion
Th e followin g example specifies t wo pat h s for locat in g source files.
NMSYM /TRANSLATE:PACKAGE /
SOURCE:c:\myproj\i386;c:\myproj\include; myproj.exe
Th e followin g example specifies t wo set s of source pat h s.
NMSYM /TRANS:PACKAGE /SOURCE:c:\myproj\i386;c:\myproj\include;
/SOURCE:c:\msdev\include; myproj.exe
Th e followin g example specifies t h e base project source pat h an d uses t h e
DOS replacemen t operat or % t o t ake t h e pat h for in clude files from t h e
st an dard en viron men t variable INCLUDE=. Th e pat h -list expan ds t o
in clude c:\ myproj\ i386 an d every pat h list ed in t h e INCLUDE= en viron -
men t variable.
NMSYM /TRANS:PACKAGE /SOURCE:c:\myproj\i386;%INCLUDE%
myproj.exe
BETA REVI EW
N o t e : In t h e even t t h at a so u rce co d e f i l e can n o t b e f o u n d , t h e / PRO M PT
sw i t ch d et er m i n es w h et h er t h e f i l e w i l l b e ski p p ed , o r i f y o u w i l l b e
asked t o h el p l o cat e t h e f i l e.
/ O U TPU T O p t io n
NMSYM derives t h e out put file n ame for t h e NMS symbol t able by t akin g
t h e root module n ame an d appen din g t h e st an dard file ext en sion for
NM32 symbol t ables, NMS. Secon dly, t h e pat h for t h e NMS file is also t h e
same as pat h t o t h e module bein g t ran slat ed. If you n eed t o ch an ge t h e
default n ame or locat ion of t h e NM32 symbol t able file, t h en use t h e
/ OUTPUT:<filename> opt ion t o specify t h e locat ion an d n ame. If you
specify a n ame, but do n ot specify a pat h , t h e pat h t o t h e module will be
used.
Exam p les: U sin g t h e / O U TPU T O p t ion
In t h e followin g example, t h e pat h of t h e NMS file is ch an ged t o a
common direct ory for NM32 symbol t ables.
NMSYM /OUTPUT:c:\NTICE\SYMBOLS\myproj.nms
c:\myproj\myproject.exee
/ PRO M PT O p t io n
NMSYM is a comman d-lin e ut ilit y design ed t o allow t asks of symbol
t ran slat ion an d loadin g t o be aut omat ed. As such , you probably do n ot
desire t o be prompt ed for missin g source files, but t h ere are cases wh ere it
migh t be useful. Use t h e / PROMPT opt ion t o specify t h at NMSYM sh ould
ask for your h elp in locat in g source code files wh en you use t h e / TRANS-
LATE:PACKAGE, / LOAD, or / SYMLOAD opt ion s.
Usi ng N M SYM t o Loa d a M odul e a nd Symbol I nf or ma t i on
Like t ran slat ion , t h e / LOAD fun ct ion alit y of NMSYM is design ed t o work
on a specific module t h at is specified usin g t h e module-n ame paramet er.
Th is module is on e wh ich will be t ran slat ed an d loaded. If you do n ot
n eed t o t ran slat e or load an d execut e a module, t h en t h e / SYMLOAD
opt ion may be a bet t er ch oice.
Th e followin g example sh ows h ow t o use NMSYM t o t ran slat e, load, an d
execut e a module:
NMSYM /TRANS:PACKAGE /LOAD:EXECUTE myproj.exe
Th e n ext example sh ows t h e alt ern at e fun ct ion alit y of loadin g a group of
pre-t ran slat ed symbol files usin g t h e / SYMLOAD opt ion :
BETA REVI EW
NMSYM /SYMLOAD:NTDLL.DLL;NTOSKRNL.NMS;MYPROJ.EXE
In t h e precedin g example, t h ree symbol t ables will be loaded, but t ran sla-
t ion will n ot be performed, even if t h e modules correspon din g NMS is
out of dat e. Also, MYPROJ.EXE will n ot be execut ed so t h at it can be
debugged.
/ LO AD O p t io n
Th e / LOAD: <load-specifier-list> opt ion allows you t o load a modules
NM32 symbol t able in t o Soft ICE, an d opt ion ally, execut e t h e module so
it can be debugged.
You can use t h e followin g specifiers wit h t h e / LOAD opt ion .
Load - Typ e Sp ecif ier s
On e of t h e followin g opt ion s may be select ed t o det ermin e h ow t h e
module an d it s symbol in format ion will be loaded. Th e default specifier
is depen den t on t h e t ype of t h e module, an d for execut ables is EXECUTE.
For n on -execut able module t ypes, t h e default is SYMBOLS.
Br eak- O n - Lo ad Sp ecif ier s
To en able or disable h avin g a breakpoin t set at t h e modules en t ry-poin t ,
use on e of t h e followin g specifiers.
Tab l e 4 - 7 . Lo ad - Ty p e Sp eci f i er s
Lo ad Ty p e
Sp eci f i er s
D ef i n i t i o n
SYM BO LS O n l y sy m b o l i n f o r m at i o n f o r t h e m o d u l e w i l l b e l o ad ed .
Yo u m ay set b r eakp o i n t s u si n g t h i s sy m b o l i n f o r m at i o n ,
an d w h en t h e m o d u l e i s l o ad ed t h e b r eakp o i n t s w i l l t r i g -
g er as ap p r o p r i at e.
EXECUTE Sy m b o l i n f o r m at i o n i s l o ad ed an d t h e ex ecu t ab l e i s l o ad ed
as a p r o cess so t h at i t m ay b e d eb u g g ed .
Tab l e 4 - 8 . Br eak- O n - Lo ad Sp eci f i er s
Br eak o n Lo ad
Sp eci f i er s
D ef i n i t i o n
BREAK Set a b r eakp o i n t o n t h e m o d u l e s en t r y - p o i n t ( Wi n M ai n ,
D l l M ai n , o r D r i v er En t r y ) .
N O BREAK D o n o t set a b r eakp o i n t o n t h e m o d u l es en t r y - p o i n t .
BETA REVI EW
Th e abilit y t o explicit ly t urn module en t ry breakpoin t s on or off is
provided because t h e default set t in g of t h is opt ion is depen den t upon t h e
t ype of t h e module. For applicat ion s t h e BREAK opt ion is t h e default . For
ot h er module t ypes NOBREAK is t h e default .
N O SO U RCE Sp ecif ier
NOSOURCE proh ibit s t h e load of source code files, even if t h e symbol
t able in cludes a source package or lin e-n umber in format ion .
Exam p les: U sin g t h e / LO AD O p t io n
In t h e followin g example NMSYM will load (an d by default ) execut e t h e
module MYPROJ.EXE. If t h e symbol t able is n ot curren t , t h en a default
t ran slat ion for t h e module t ype will be performed:
lN5+N /!AL N+J.!!
Th e n ext example specifies t h at t h e program is t o be execut ed, but a
breakpoin t sh ould n ot be set on t h e program en t ry-poin t . On ce again , if
a t ran slat ion n eeds t o be performed, it will be t h e default t ran slat ion for
t h e module t ype.
NMSYM /LOAD:NOBREAK MYPROJ.EXE
Th e n ext example specifies t h at on ly symbol in format ion sh ould be
loaded, an d explicit ly specifies t h e PUBLICS t ran slat ion t ype:
NMSYM /TRANS:PUBLIC /LOAD:SYMBOLS MYPROJ.DLL
/ ARGS O p t ion
Th e / ARGS:<program-argumens> opt ion is used t o specify t h e program
argumen t s t h at will be passed t o an execut able module. Th is opt ion is
on ly useful wh en used wit h t h e / LOAD:EXECUTE opt ion .
Th e st rin g program-arguments defin es t h e program argumen t s. If it
con t ain s wh it e-space, t h en you sh ould surroun d t h e en t ire opt ion in
double quot es (").
Exam p les: U sin g t h e / ARGS O p t ion
In t h e followin g example, t h e MYPROJ.EXE module is goin g t o be loaded
for debuggin g, an d t h e argumen t s passed t o t h e applicat ion are
TEST.RTF.
NMSYM /LOAD:EXECUTE /ARGS:test.rtf myproj.exe
In t h e n ext example, t h e comman d-lin e is a bit more complicat ed, so we
are goin g t o wrap t h e en t ire opt ion in double-quot es ("):
BETA REVI EW
NMSYM /LOAD:EXECUTE "/ARGS:/PRINT /NOLOGO test.rtf" myproj.exe
Usin g t h e double quot es aroun d t h e opt ion preven t s NMSYM from
becomin g con fused by t h e wh it e-space t h at appears wit h in t h e program
argumen t s: / PRINT^/ NOLOGO^t est .rt f.
Usi ng N M SYM t o Loa d Symbol Ta bl es or Expor t s
In addit ion t o t h e t ran slat ion an d loadin g fun ct ion s, NMSYM also
supplies opt ion s t h at allow for bat ch loadin g an d un loadin g of bot h
symbol t ables an d export s. Th is is ext remely useful for loadin g an
"en viron men t " or relat ed set of symbol t able files. For example, if you
st art Soft ICE man ually you can use NMSYM t o give you t h e equivalen t
fun ct ion alit y of t h e Soft ICE In it ializat ion Set t in gs for Symbols an d
Export s.
For example, you could use a bat ch file similar t o t h e followin g t o con t rol
wh ich symbol t ables are loaded. Th e bat ch file t akes on e opt ion al param-
et er t h at det ermin es wh et h er t h e files t o be loaded are for driver or appli-
cat ion debuggin g (applicat ion is t h e default ). In bot h cases we are
loadin g export s for t h e st an dard Win dows modules.
net start ntice
echo off
if "%1" == "D" goto dodriver
if "%1" == "d" goto dodriver
REM *** These are for debugging applications *** set
SYMBOLS=ntdll.dll;shell32.dll;ole32.dll;win32k.sys goto doload
:dodriver REM *** These are for debugging drivers *** set
SYMBOLS=hal.dll;ntoskrnl.exe;
:doload
NMSYM /SYMLOAD:%SYMBOLS% /
EXPORTS:kernel32.exe;user32.exe;gdi32.exe
An ot h er ben efit of usin g NMSYM is t h at it does n ot require explicit pat h
in format ion t o fin d NMS files or modules. If you do n ot specify a pat h ,
an d t h e specified module or NMS file can n ot be foun d wit h in t h e curren t
direct ory or t h e symbol t able cach e, t h en a search will be execut ed alon g
t h e curren t pat h .
/ SYM LO AD O p t io n
Th e / SYMLOAD: <module-list> opt ion is used t o load on e or more
symbol t ables in t o Soft ICE. Th e symbol t ables must h ave been previously
t ran slat ed sin ce t h is fun ct ion does n ot perform t ran slat ion .
BETA REVI EW
Th e module-list specifier may specify NMS files or t h eir associat ed
modules, wit h or wit h out explicit pat h s t o t h e files. If you do n ot specify
an explicit pat h for t h e module, t h en NMSYM will at t empt t o fin d t h e
file in t h e curren t direct ory, in t h e symbol t able cach e, or on t h e syst em
pat h . If you specify an absolut e or relat ive pat h for t h e module t h en n o
search will be performed.
Exam p les: U sin g t h e / SYM LO AD O p t ion
Th e followin g example uses t h e / SYMLOAD opt ion t o load t h e symbol
t ables t ypically used for debuggin g OLE programs. It does n ot specify an y
pat h s, so a search will be performed (as n ecessary).
NMSYM /SYMLOAD:ole32.dll;oleaut32.dll;olecli32.dll
/ EX PO RTS O p t io n
Th e / EXPORTS: <module-list> opt ion is used t o load export s for on e or
more modules in t o Soft ICE. Export s are ligh t weigh t symbol in format ion
for APIs export ed from a module (usually a DLL, but EXEs can also
con t ain export s).
Th e module-list specifier may specify modules wit h or wit h out explicit
pat h s. If you do n ot specify an explicit pat h for t h e module, t h en
NMSYM will at t empt t o fin d t h e file in t h e curren t direct ory, in t h e
syst em direct ory, or on t h e syst em pat h . If you specify a absolut e or
relat ive pat h for t h e module t h en n o search will be performed.
Exam p les: U sin g t h e / EX PO RTS O p t io n
Th e followin g example uses t h e / EXPORTS opt ion t o load t h e export s for
modules t ypically used wh en debuggin g OLE programs. It does n ot
specify an y pat h s, so a search will be performed, as n ecessary.
NMSYM /EXPORTS:ole32.dll;oleaut32.dll;olecli32.dll
Usi ng N M SYM t o Unl oa d Symbol I nf or ma t i on
NMSYM provides t h e / UNLOAD opt ion so t h at you can programmat i-
cally remove symbol in format ion for a relat ed set of symbol t ables an d/ or
export s. Th is can be used t o save memory used by un n eeded symbol
t ables.
/ U N LO AD O p t ion
Th e / UNLOAD: <module-list> opt ion may specify eit h er symbol t ables
or export t able n ames. Th e n ame of a symbol t able or export t able is
BETA REVI EW
derived from t h e root module-n ame, wit h out pat h or ext en sion in forma-
t ion . For flexibilit y an d t o support fut ure t able n amin g con ven t ion s you
sh ould specify an y pat h or ext en sion in format ion t h at is relevan t t o
un iquely dist in guish t h e t able.
Exam p les: U sin g t h e / U N LO AD O p t ion
Th e followin g example is t h e reverse of t h e examples provided in t h e /
SYMLOAD an d / EXPORTS sect ion s:
NMSYM /UNLOAD:ole32.dll;oleaut32.dll;olecli32.dll
Soft ICE will fin d t h e t able t h at correspon ds t o t h e specified module n ame
an d remove t h e t able (if possible) an d free an y memory in use by t h at
symbol t able.
N o t e : So f t I CE at t em p t s t o u n l o ad a sy m b o l t ab l e b y d ef au l t . If t h e sp eci f i ed
sy m b o l t ab l e d o es n o t ex i st t h en So f t ICE at t em p t s t o u n l o ad an
ex p o r t t ab l e w i t h t h at n am e.
Usi ng N M SYM t o Sa ve Hi st or y Logs
NMSYM provides t h e abilit y t o save t h e Soft ICE h ist ory buffer t o a file
usin g t h e / LOGFILE opt ion . Th is operat ion is equivalen t t o t h e Symbol
Loader Save Soft ICE Hist ory As..." opt ion . NMSYM support s t h e abilit y t o
appen d t o an exist in g file usin g t h e APPEND specifier.
/ LO GFI LE O p t io n
Th e / LO G FI LE: < f il en am e >[ , log f ile - sp e cif i er - l ist ] o p t i o n is t h e pat h an d
filen ame of t h e file t h e h ist ory buffer will be writ t en t o. If n o pat h is
specified t h e curren t direct ory will be assumed.
Log File Sp ecif ier s
APPEND let s you appen d t h e curren t con t en t s of t h e Hist ory buffer t o an
exist in g file. Th e default is t o overwrit e t h e file.
Exam p les: U sin g t h e / LO GFI LE O p t io n
Th e followin g example will creat e/ overwrit e t h e MYPROJ.LOG file wit h
t h e curren t con t en t s of t h e Soft ICE h ist ory buffer:
NMSYM /LOGFILE:myproj.log
Th e n ext example will creat e/ appen d t h e curren t con t en t s of t h e Soft ICE
h ist ory buffer t o t h e file MYPROJ.LOG:
NMSYM /LOGFILE:myproj.log,APPEND
BETA REVI EW
Caut ion : N M SYM w i ll n ot ask you i f yo u w an t t o o ve r w r it e an e xi st in g
f i le . I t w i ll aut om at icall y d o so.
Get t i ng I nf or ma t i on a b out N M SYM
To get in format ion about NMSYM, use t h e / VERSION an d / HELP opt ion s.
/ VERSI O N O p t io n
Use t h e / VERSION opt ion t o obt ain version in format ion for NMSYM,
Soft ICE, as well as t h e t ran slat or an d symbol en gin e version n umbers. For
Soft ICE, Loader32 an d NMSYM t o work t oget h er correct ly, t h ese version s
must be compat ible. Each product n egot iat es an d verifies version
n umbers wit h t h e ot h er product s t o in sure t h at each can work t oget h er.
/ H ELP O p t io n
Use t h e / HELP opt ion t o obt ain comman d-lin e syn t ax, opt ion s, specifi-
ers an d opt ion / specifier syn t ax.
5 7
BETA REVI EW
Ch ap t er 5
Navigat ing Through Soft ICE
I n t r o d uct ion
U n iver sal Vid eo D r iver
Po p p in g U p t h e Sof t I CE Scr een
D isab lin g Sof t I CE at St ar t up
U sin g t h e Sof t I CE Scr e e n
U sin g t h e Co m m an d W in d o w
U sin g t h e Co d e W in d ow
U sin g t h e Lo cals W in d o w
U sin g t h e W at ch W in d ow
U sin g t h e Re g ist er W in d o w
U sin g t h e D at a W in d ow
U sin g t h e St ack W in d o w
U sin g t h e Th r e ad W in d ow
U sin g t h e Pen t ium I I I / I V Re g ist er W in d o w
U sin g t h e FPU St ack W in d o w
Int roduct ion
Th is ch apt er describes h ow t o use t h e Soft ICE screen an d it s win dows.
Th e Soft ICE win dows are described in order of import an ce.
If you are n ew t o Soft ICE, read t h is ch apt er t h orough ly, t h en use it as a
referen ce.
BETA REVI EW
Universal Video Driver
Soft ICE uses a Un iversal Video Driver (UVD) t o display on t h e users
deskt op. Th e UVD allows Soft ICE t o draw direct ly in lin ear frame
memory. To use t h e UVD, Soft ICE requires t h at t h e video h ardware an d
video driver support Direct Draw. You can use t h e followin g comman ds
an d key sequen ces t o move, size, an d cust omize t h e Soft ICE display
win dow:
Tab l e 5 - 1 . So f t ICE Co m m an d s an d Key st r o kes
Co m m an d /
Key st r o kes
Resu l t
LIN ES n Wh er e n i s 2 5 -1 2 8 , sel ect s t h e n u m b er o f l i n es i n t h e So f t ICE
w i n d o w.
WID TH n Wh er e n i s 8 0 -1 6 0 , sel ect s t h e n u m b er o f co l u m n s i n t h e So f t -
ICE w i n d o w .
SET FO N T n Wh er e n i s 1 , 2 , o r 3 , sel ect s a f o n t .
SET O RIGIN x
y
Wh er e x an d y ar e p i x el co o r d i n at es, l o cat es t h e w i n d o w
SET FO RCE-
PALETTE
[ O N |O FF]
Wh en O n , So f t ICE w i l l p r even t t h e sy st em co l o r s ( p al et t e i n d i -
ces 0 - 7 an d 2 4 8 - 2 5 5 ) f r o m b ei n g ch an g ed i n 8 - b p p m o d e. Th i s
en su r es t h at t h e So f t ICE d i sp l ay can al w ay s b e seen . Th i s i s O FF
b y d ef au l t .
SET M AXI-
M IZ E [ O N |
O FF]
Wh en O n , So f t ICE r esi zes i t s w i n d o w t o t h e m ax i m u m p o ssi b l e
si ze, b ased o n f o n t , n u m b er o f l i n es, an d v i d eo m em o r y si ze.
Wh en O f f , ch an g i n g a d i sp l ay f o r m at p ar am et er ( f o n t , n u m b er
o f l i n es, et c. ) w i l l n o t cau se So f t ICE t o r esi ze i t s w i n d o w.
SET M O N I-
TO R n
Wh er e n i s 0 t o t h e n u m b er o f UVD - en ab l ed v i d eo car d s
i n st al l ed . Used w i t h o u t su p p l y i n g an n - v al u e, t h i s co m m an d
r et u r n s t h e l i st o f vi d eo d r i ver s t h at So f t ICE i s aw ar e o f , an d t el l s
y o u w h i ch o n e i s act i v e. Passi n g i n an n - v al u e t el l s So f t ICE t o
sw i t ch t h e o u t p u t t o t h e sp eci f i ed m o n i t o r. Th i s co m m an d can
o n l y b e u sed f o r UVD d i sp l ay s, n o t VGA o r M o n o .
Co n t r o l - Al t -
cu r so r key
M o v es t h e So f t ICE w i n d o w b y a ch ar act er i n cr em en t .
Co n t r o l - Al t -
Ho m e
Reset s t h e So f t ICE w i n d o w p o si t i o n t o ( 0 , 0 )
Co n t r o l - L Ref r esh es t h e So f t ICE d i sp l ay. Usef u l i n t h e r ar e case w h er e t h e
p ar t o f t h e d i sp l ay u sed b y So f t ICE i s o ver l ap p ed b y a b i t b l t
o p er at i o n t h at w as r u n n i n g w h en So f t ICE p o p p ed u p .
Co n t r o l - C Cen t er s t h e So f t ICE d i sp l ay w i n d o w.
Ch ap t er 5 N av i g at i n g Th r o u g h So f t ICE 5 9
BETA REVI EW
Set t i ng t he Vi deo M emor y Si ze
Wh en usin g t h e UVD, Soft ICE must save t h e exist in g con t en t s of t h e
frame buffer so it can be rest ored lat er. Th e amoun t of memory required
depen ds on t h e video mode, t h e n umber of lin es used by Soft ICE. In an y
case, t h e amoun t of memory required can n ot exceed t h e amoun t of
memory on your video card. By default , Soft ICE reserves 2MB, but you
can modify t h is usin g t h e Symbol Loader (go t o Edit -> Soft ICE In it ializa-
t ion Set t in gs an d ch an ge t h e Video memory size set t in g).
Popping Up t he Soft ICE Screen
On ce loaded, t h e Soft ICE screen will aut omat ically pop up in t h e follow-
in g sit uat ion s:
Wh en Soft ICE loads. By default , t h e Soft ICE in it ializat ion st rin g con -
t ain s t h e X (Exit ) comman d, so it immediat ely closes aft er open in g.
Refer t o Modifying SoftICE Initialization Settings on page 161.
Wh en you press Ct rl-D. Th is h ot -key sequen ce t oggles t h e Soft ICE
screen on an d off.
Ti p Use t h e ALTKEY
co m m a n d t o ch a n g e
t h e So f t I CE d ef a u l t
p op - u p key ( Ct r l - D ) .
Wh en breakpoin t con dit ion s are met .
Wh en Soft ICE t raps a syst em fault .
Wh en a syst em crash in Win dows NT/ 2000/ XP result s in Blue
Screen Mode.
Wh en t h e Soft ICE screen pops up, all backgroun d act ivit y on your
comput er comes t o a h alt , all in t errupt s are disabled, an d Soft ICE
performs all video an d keyboard I/ O by accessin g t h e h ardware direct ly.
Disabling Soft ICE at St art up
If Soft ICE was in st alled as a boot or syst em driver wit h Win dows NT/
2000/ XP, you can disable it at st art up. Press t h e Escape key wh en t h e
followin g message appears at t h e bot t om of t h e Blue Text display:
Press Esc to cancel loading SoftICE
If you in st alled Soft ICE as an aut omat ic driver wit h Win dows NT/ 2000/
XP, you can n ot disable it un less you ch an ge your st art up mode an d
reboot your PC. In t h e un likely even t t h at Soft ICE causes difficult ies
durin g boot in g, select t h e followin g opt ion from t h e Win dows NT/ 2000/
XP boot men u:
BETA REVI EW
Last known good configuration
Using t he Soft ICE Screen
Th e Soft ICE screen serves as t h e cen t ral locat ion for debuggin g your
code. It provides several win dows an d a Help lin e t o view an d con t rol
various aspect s of your debuggin g session . Th ese win dows are list ed
below:
Tab l e 5 - 2 . So f t ICE Wi n d o w s
So f t I CE W in d o w s U se
Co m m an d w i n d o w En t er u ser co m m an d s an d d i sp l ay i n f o r m at i o n .
Co d e w i n d o w D i sp l ay u n assem b l ed i n st r u ct i o n s an d / o r so u r ce co d e.
Lo cal s w i n d o w D i sp l ay t h e cu r r en t st ack f r am e.
Wat ch w i n d o w D i sp l ay t h e v al u e o f t h e v ar i ab l es w at ch ed w i t h t h e
WATCH co m m an d .
Reg i st er w i n d o w D i sp l ay an d ed i t t h e cu r r en t st at e o f t h e r eg i st er s an d
f l ag s.
D at a w i n d o w D i sp l ay an d ed i t m em o r y.
St ack Wi n d o w D i sp l ay cal l st ack f o r D O S p r o g r am s, Wi n d o w s t asks, an d
3 2 - b i t co d e
Th r ead Wi n d o w D i sp l ay i n f o r m at i o n o n t h r ead s f o r a g i ven p r o cess
PIII Reg i st er Wi n d o w D i sp l ay Pen t i u m III r eg i st er s
FPU St ack w i n d o w D i sp l ay t h e cu r r en t st at e o f t h e FPU ( Fl o at i n g Po i n t Un i t )
st ack / M M X r eg i st er s.
Hel p l i n e Pr o vi d e i n f o r m at i o n ab o u t So f t ICE co m m an d s.
BETA REVI EW
By default , Soft ICE displays t h e Help lin e an d t h e Comman d, Code, an d
Locals win dows. You can open an d close t h e remain in g win dows as
n ecessary. Th e followin g figure illust rat es a t ypical Soft ICE win dow:
Fi g u r e 5 - 1 . Ty p i cal So f t ICE Wi n d o w
Resi zi ng t he Sof t I CE Scr een
By default , t h e Soft ICE screen uses a t ot al of 25 lin es t o display in forma-
t ion in t h e various win dows. If you are usin g VGA or Text Mode, you can
use t h e LINES comman d t o swit ch t h e t ot al lin es for t h e Soft ICE screen t o
43, 50, or 60 lin es in st ead of t h e st an dard 25 lin es. If you are usin g UVD
you can set t h e t ot al lin es t o an y value from 25 t o 100. Mon och rome
screen s limit you t o 25 lin es. Th e WIDTH comman d allows you t o set t h e
n umber of display column s bet ween 80 an d 160.
LINES 60
WIDTH 80
Th e Soft ICE display can also be moved on t h e Win dows deskt op. Use t h e
Ct rl-Alt an d cursor keys t o move t h e Soft ICE display. Use t h e Ct rl-Alt -
Home keys t o ret urn t h e display t o t h e 0,0 posit ion , or t h e Ct rl-Alt -C keys
t o cen t er t h e display.
Cont r ol l i ng Sof t I CE W i ndow s
You can do t h e followin g t o t h e Soft ICE win dows:
Register window
Data windows
Code window
Command window
Locals window
Watch window
Thread window
Stack window
BETA REVI EW
Open an d close all t h e win dows except t h e Comman d win dow.
Resize t h e Code, Dat a, Locals, St ack, Th read, an d Wat ch win dows.
Scroll t h e Code, Comman d, Dat a, Locals, St ack, Th read, an d Wat ch
win dows.
Soft ICE provides t wo met h ods for con t rollin g t h ese win dows: mouse an d
keyboard in put .
O p e n in g an d Closin g W in d ow s
To open a Soft ICE win dow, use t h e appropriat e comman d list ed in t h e
followin g t able. To close a win dow, eit h er repeat t h e comman d or use
your mouse, if you h ave on e available.To use your mouse t o close a
win dow, select t h e lin e below t h e win dow you wan t t o close an d drag it
up past t h e t op lin e of t h e win dow.
Re siz in g W in d o w s
To resize a win dow, drag t h e lin e at t h e bot t om of t h e win dow you wan t
t o resize eit h er up or down . You can also use t h e same comman ds t h at
you use for open in g an d closin g win dows t o resize t h e win dows. Simply
t ype t h e comman d followed by a decimal n umber t h at represen t s t h e
n umber of lin es you wan t t o display in t h e win dow.
Tab l e 5 - 3 . So f t ICE Wi n d o w Co m m an d s
Co m m an d Wi n d o w
W C Co d e
W D . # D at a
W h er e # i s a n u m b er 0 t h r o u g h 3 t o o p en t h at sp eci f i ed d at a
w i n d o w. Use w i t h o u t 0 - 3 ex t en si o n t o sw i t ch t o o r o p en t h e
n ex t seq u en t i al D at a w i n d o w.
W F FPU St ack
W L Lo cal s
W R Reg i st er
W W Wat ch
W S St ack
W T Th r ead
W X Pen t i u m III Reg i st er
BETA REVI EW
WD 7
Not e t h at t h e n umber of lin es in t h e Comman d win dow aut omat ically
in creases or decreases wh en you resize a win dow. Alt h ough you can n ot
explicit ly resize t h e Comman d widow, ch an gin g t h e size of ot h er
win dows in your display aut omat ically resizes t h e Comman d win dow.
M o vin g t h e Cur so r Am o n g W in d o w s
Th e cursor is locat ed in t h e Comman d win dow by default . To move t h e
cursor t o an ot h er win dow, click t h e mouse in t h e win dow wh ere you
wan t t o place t h e cursor. If t h e cursor is in t h e Comman d or Code
win dows, you can use on e of t h e Alt key combin at ion s in t h e followin g
t able t o move t h e cursor. Repeat t h e same Alt key combin at ion t o ret urn
t h e cursor t o t h e Comman d or Code win dow.
Scr o llin g W in d o w s
You can scroll t h e Code, Comman d, Dat a, Locals, St ack, Th read, an d
Wat ch win dows. Th e FPU St ack an d Regist er win dows are n ot scrollable,
because t h ey are limit ed t o four an d t h ree lin es respect ively.
Soft ICE provides t wo met h ods for scrollin g win dows: key sequen ces an d
mouse scroll arrows. Th e followin g t able describes h ow t o use scroll
arrows an d key sequen ces t o scroll win dows.
N o t e : Th e key seq u en ces f o r so m e w i n d o w s var y. Fo r ex am p l e, so m e
w i n d o w s d o n o t l et y o u j u m p t o t h e f i r st o r l ast l i n es o f t h e f i l e. See
Tab l e 5 - 4 . So f t ICE Wi n d o w Al t Key Co m b i n at i o n s
Wi n d o w Al t Key Co m b i n at i o n
Co d e Al t -C
D at a Al t -D
FPU St ack Can n o t m o v e t h e cu r so r t o t h e FPU St ack w i n d o w.
Lo cal s Al t -L
Reg i st er Al t -R
St ack Al t -S
Th r ead Al t -T
Wat ch Al t -W
BETA REVI EW
t h e sect i o n s t h at d escr i b e t h e i n d i vi d u al w i n d o w s f o r sp eci f i c i n f o r -
m at i o n ab o u t scr o l l i n g p ar t i cu l ar w i n d o w s.
User - Def i na b l e Pop- up M enus
Soft ICE allows you t o cust omize t h e con t en t of t h e pop-up men us t h at
appear wh en you righ t -click wit h t h e mouse. Th e men u en t ries are
defin ed in w+r+cc.Jal. To access t h e edit or an d cust omize t h e pop-up
men us, select Advanced from t h e Soft ICE In it ializat ion men u on t h e
Con figurat ion screen .
Figure 5-2 on page 65 displays t h e pop-up men u edit or.
Tab l e 5 - 5 . So f t ICE Wi n d o w Scr o l l i n g M et h o d s
Scr o l l D i r ect i o n an d
D i st an ce
Key
Seq u en ce
M o u se Act i o n
Scr o l l t h e w i n d o w t o t h e p r evi -
o u s p ag e.
Pag eUp Cl i ck t h e i n n er m o st u p scr o l l
ar r o w
Scr o l l t h e w i n d o w t o t h e n ex t
p ag e.
Pag eD o w n Cl i ck t h e i n n er m o st d o w n scr o l l
ar r o w
Scr o l l t h e w i n d o w t o t h e p r evi -
o u s l i n e.
Up Ar r o w Cl i ck t h e o u t er m o st u p scr o l l
ar r o w
Scr o l l t h e w i n d o w t o t h e n ex t
l i n e.
D o w n Ar r o w Cl i ck t h e o u t er m o st d o w n
scr o l l ar r o w
Ju m p t o t h e f i r st l i n e o f t h e
so u r ce f i l e.
Ho m e N o t su p p o r t ed .
Ju m p t o t h e l ast l i n e o f t h e
so u r ce f i l e.
En d N o t su p p o r t ed .
Scr o l l t h e w i n d o w l ef t o n e
ch ar act er.
Lef t Ar r o w Cl i ck t h e l ef t scr o l l ar r o w.
Scr o l l t h e w i n d o w r i g h t o n e
ch ar act er.
Ri g h t Ar r o w Cl i ck t h e r i g h t scr o l l ar r o w.
BETA REVI EW
Fi g u r e 5 - 2 . Po p - u p M en u Ed i t o r
Th e format of en t ries in w+r+cc.Jal is as follows:
MENU=Description, Command Field, [Modifier]
Description is t h e t ext t h at will appear on t h e men u. It can con t ain
an y valid ch aract er, can h ave spaces, an d must h ave a maximum
len gt h of 13 ch aract ers. All t railin g spaces are removed.
Command Field is t h e Soft ICE comman d, macro, expression evaluat or
comman d, or predefin ed comman d t o be execut ed upon select ion of
t h at men u it em. You must use full comman d n ames an d may n ot use
sh ort cut s. In addit ion you can add a special Modifier flag, %cp%,
wh ich will copy t h e dat a or t ext t h at is un dern eat h t h e cursor an d
past e it in t o t h e st rin g at t h at posit ion .
If you h ave a lin e of t h e screen t h at reads 80001000 ntoskrnl!kitrap0E
an d you h ave defin ed a men u it em as what %cp%, you can place t h e
mouse on o1 an d select t h at men u it em t o submit t h e comman d
wral o1 t o Soft ICE.
In addit ion , several predefin ed comman ds h ave been provided for
backwards compat ibilit y wit h t h e men us in earlier version s of Soft ICE.
BETA REVI EW
Th e predefin ed comman ds are as follows:
NMPD_COPY
NMPD_PASTE
NMPD_COPYANDPASTE
NMPD_DISPLAY
NMPD_UNASSEMBLE
NMPD_WHAT
NMPD_PREV
I nl i ne Edi t i ng
Soft ICE 3.0 is able t o do in lin e edit in g of variables displayed in eit h er t h e
Locals Win dow (WL) or t h e Wat ch Win dow (WW).
U sag e
Navigat e t o t h e variable you wish t o edit in eit h er t h e Locals Win dow
or t h e Wat ch Win dow.
Use t h e h ot key sequen ce, Alt-E, t o laun ch In lin e Edit in g.
Edit your dat a.
Press eit h er t h e Enter key t o st ore your dat a, or t h e Escape key t o
abort your ch an ges.
N avig at ion Ke ys
Th e followin g keys are available for t h e In lin e Edit in g feat ure:.
Tab l e 5 - 6 . In l i n e Ed i t i n g Co m m an d s
Co m m an d Act i o n
En t er St o r es y o u r m o d i f i cat i o n s.
Esc Ab o r t s an y ch an g es.
Lef t / Ri g h t
Ar r o w
Ch an g es y o u r p o si t i o n w i t h i n t h e ed i t f i el d ; ad d i t i o n al l y, p r essi n g
ei t h er o f t h ese key s p u t s y o u i n t o O ver t y p e M o d e.
Ho m e M o v es t o st ar t o f f i el d ; ad d i t i o n al l y p u t s y o u i n t o O v er t y p e M o d e.
BETA REVI EW
Cur r en t Lim it at io n s
Edit in g of st rin gs, float s, an d bit fields is n ot possible in t h is release.
You n eed t o be in t h e Locals/ Wat ch Win dow before t ypin g Alt-E.
Th e In lin e Edit in g h ot key is not remappable.
N o t e s
All in put is don e in h ex.
Wh en you en t er In lin e Edit in g, t h e in format ion t o t h e righ t of t h e
field bein g edit ed will be overwrit t en un t il you complet e your edit .
Th is is t h e in t en ded fun ct ion alit y.
If you st art t ypin g in t h e edit field, t h e en t ire en t ry will be erased.
You will en t er Overt ype Mode if you press t h e left / righ t arrow, Home,
or En d keys .
Copyi ng a nd Pa st i ng Da t a
If you h ave a mouse, you can copy an d past e dat a amon g win dows. Th is
is useful for copyin g addresses an d dat a in t o expression s. To copy an d
past e dat a, do t h e followin g:
1 Select t h e dat a you wan t t o copy.
2 Press t h e righ t mouse but t on t o display t h e followin g list of available
comman ds.
3 Click t h e left mouse but t on t o select t h e comman d (Copy, Copy an d
Past e, or Past e) you wan t t o use. Th e followin g t able describes t h ese
comman ds:.
Tab l e 5 - 7 . Co p y an d Past e Co m m an d s
Co m m an d D escr i p t i o n
Copy Copies t h e selected it em to t h e Copy-an d-Past e buffer.
Copy an d
Past e
Copies t h e selected it em an d pastes it t o th e locat ion of t h e
cursor.
Past e Past es t h e con t en t s of t h e Copy-an d-Paste buffer t o th e
locat ion of t h e cursor.
BETA REVI EW
Ent er i ng Comma nds Fr om t he M ouse
Th e mouse provides sh ort cut s for en t erin g t h e D, U, an d WHAT
comman ds. (Refer t o t h e SoftICE Command Reference for more in forma-
t ion about t h ese comman ds.)
To use your mouse t o en t er on e of t h ese comman ds, do t h e followin g:
1 Select t h e dat a you wan t t h e comman d t o act upon .
For example, select an expression t o iden t ify.
2 Click t h e righ t mouse but t on t o display t h e list of available com-
man ds.
3 Click t h e left mouse but t on t o select t h e comman d you wan t t o use.
Th e followin g t able describes t h ese comman ds.
Obt a i ni ng Hel p
Soft ICE provides you wit h t wo met h ods for obt ain in g h elp wh ile debug-
gin g your module: t h e Help lin e an d H comman d.
U sin g t h e H elp Lin e
Th e bot t om lin e of t h e screen always con t ain s t h e Help lin e. Th is lin e
updat es as you t ype ch aract ers on t h e comman d lin e. Th e Help lin e
provides several differen t t ypes of in format ion , as follows:
Wh en t h e ch aract ers you t ype do n ot specify a complet e comman d,
t h e Help lin e displays all t h e valid comman ds t h at st art wit h t h e
ch aract ers you t yped.
Tab l e 5 - 8 . So f t ICE M o u se Co m m an d s
M o u se
Co m m an d
So f t I CE
Co m m an d
Eq u i val en t
D escr i p t i o n
Display D Displays t h e memory con t en t s at t h e specified
address.
Un -
Assemble
U Displays eit h er source code or un assembled
code at t h e specified address.
Wh at WHAT Det ermin es if a n ame or expression is a kn own
t ype.
Previous N/ A Un does th e previous mouse comman d.
BETA REVI EW
Wh en t h e ch aract ers you t ype mat ch a comman d, t h e Help lin e dis-
plays a descript ion of t h e comman d.
If you en t er a space aft er a comman d, t h e Help lin e displays t h e syn -
t ax for t h at comman d.
If you are edit in g in t h e Regist er or Dat a win dows, t h e Help lin e con -
t ain s t h e valid edit in g keys for t h at win dow.
U sin g t h e H Co m m an d
Use t h e H comman d t o provide gen eral h elp on all t h e Soft ICE
comman ds or det ailed h elp on a specific comman d. To display a brief
descript ion of all t h e Soft ICE comman ds by fun ct ion , en t er t h e H
comman d wit h n o paramet ers.
To display det ailed h elp on a specific comman d, t ype t h e H comman d
an d specify t h e comman d on wh ich you wan t t o receive h elp as t h e
paramet er. Soft ICE displays a descript ion of t h e comman d, t h e comman d
syn t ax, an d an example.
Th e followin g example displays h elp for t h e BPINT comman d:
:H BPINT
Breakpoint on interrupt
BPINT interrupt-number {IF expression] [DO bp-action]
ex: BPINT 50
Using t he Command Window
Th e Comman d win dow let s you en t er comman ds an d displays in forma-
t ion about your debuggin g session . Th e con t en t s of t h e Comman d
win dow are saved in t h e Soft ICE h ist ory buffer.
Th e Comman d win dow is always open an d is at least t wo lin es lon g.
Alt h ough you can n ot explicit ly resize t h e Comman d widow, ch an gin g
t h e size of ot h er win dows in your display aut omat ically resizes t h e
Comman d win dow.
BETA REVI EW
Scr ol l i ng t he Comma nd W i nd ow
To scroll t h e Comman d win dow, eit h er use t h e scroll arrows or t h e keys
list ed in t h e followin g t able.
Ent er i ng Comma nds
You can en t er comman ds wh en ever t h e cursor is in t h e Comman d
win dow or t h e Code win dow.
To en t er a comman d, t ype t h e comman d an d press t h e En t er key t o
execut e it .
Ti p As you t yp e
ch a r a ct er s, t h e Hel p
l i n e d i sp l a ys t h e l i st of
va l i d co m m a n d s t h a t
st a r t w i t h t h ose
ch a r a ct er s. Wh en on l y
on e com m a n d d i sp l a ys,
you ca n p r ess t h e sp a ce
b a r t o com p l et e t h e
co m m a n d
a u t o m a t i ca l l y. Sof t I CE
f i l l s i n t h e r em a i n i n g
ch a r a ct er s o f t h e
co m m a n d f o l l ow ed b y
a t r a i l i n g sp a ce.
Wh en you t ype most Soft ICE comman ds in t h e Comman d win dow,
relat ed in format ion about t h e comman d aut omat ically displays on t h e
lin e ben eat h t h e comman d. If in format ion displays on t h e last lin e of t h e
win dow, t h e win dow scrolls. If all t h e in format ion can n ot fit in t h e
win dow, t h e followin g prompt appears on t h e h elp lin e:
Any Key To Continue, ESC To Cancel
To disable t h is prompt , use t h e followin g comman d:
5!| AU5! !!
Co m m an d Syn t ax
Soft ICE comman ds sh are t h e followin g syn t ax an d rules:
All comman ds are t ext st rin gs of on e t o six ch aract ers in len gt h an d
are n ot case sen sit ive.
All paramet ers are eit h er ASCII st rin gs or expression s.
An address in Soft ICE can be a select or:offset , a segmen t :offset , or just
an offset .
Expression s in Soft ICE are comprised of t h e followin g:
Groupin g symbols
Numbers in h exadecimal or decimal format
Addresses
Tab l e 5 - 9 . Co m m an d Wi n d o w Scr o l l i n g Key s
Fu n ct i o n Key
Scr o l l t h e h i st o r y b u f f er t o t h e p r evi o u s p ag e. Pag eUp
Scr o l l t h e h i st o r y b u f f er t o t h e n ex t p ag e. Pag eD o w n
Scr o l l t h e h i st o r y b u f f er t o t h e p r evi o u s l i n e. Up Ar r o w
Scr o l l t h e h i st o r y b u f f er t o t h e n ex t l i n e. D o w n Ar r o w
BETA REVI EW
Lin e n umbers
St rin g lit erals
Symbols
Operat ors
Built -in fun ct ion s
Regist ers.
([DPSOH '1Z is an expression.
An y comman d t h at accept s a n umber or an address can accept an
arbit rarily complex expression . Use t h e . comman d t o display t h e
value of an expression . In addit ion , breakpoin t s can be con dit ion ally
based on t h e result of an expression ; t h at is, t h e breakpoin t on ly
t riggers wh en t h e expression evaluat es t o n on -zero (TRUE).
U sin g Fun ct ion Ke ys
Soft ICE provides several fun ct ion key assign men t s t o save you t ime wh en
en t erin g common ly-used Soft ICE comman ds. Th ese assign men t s are
sh own in t h e followin g t able.
Tab l e 5 - 1 0 . So f t ICE Fu n ct i o n Key Assi g n m en t s
Fu n ct i o n Key Co m m an d Fu n ct i o n
F1 H D i sp l ay H el p
F2 W R D i sp l ay o r h i d e t h e r eg i st er w i n d o w
F3 SRC Sw i t ch am o n g so u r ce co d e, m i x ed co d e, an d
d i sassem b l ed co d e
F4 RS Sh o w p r o g r am scr een
F5 X Go
F6 EC M o ve t h e cu r so r t o o r f r o m t h e Co d e w i n d o w
F7 H ERE Ex ecu t e t o t h e cu r so r
F8 T Si n g l e st ep
F9 BPX Set an ex ecu t i o n b r eakp o i n t o n t h e cu r r en t l i n e
F1 0 P St ep o ver
F1 1 G @SS: EIP Go t o
F1 2 P RET Ret u r n f r o m t h e p r o c ed u r e cal l
Sh i f t - F3 FO RM AT Ch an g e t h e f o r m at f o r t h e act i ve D at a w i n d o w
BETA REVI EW
You can modify t h e comman ds assign ed t o t h ese keys or assign
comman ds t o addit ion al fun ct ion keys. Refer t o Modifying Keyboard
Mappings on page 171.
Ed it in g Co m m an d s
Use t h e followin g keys t o edit t h e comman d lin e.
Al t - F1 W R O p en o r cl o se t h e Reg i st er w i n d o w
Al t - F2 W D O p en o r cl o se t h e D at a w i n d o w
Al t - F3 W C O p en o r cl o se t h e Co d e w i n d o w
Al t - F4 W W O p en o r cl o se t h e Wat ch w i n d o w
Al t - F5 CLS Cl ear t h e Co m m an d w i n d o w
Al t - F1 1 d d d at aad d r - > 0 In d i r ect f i r st d w o r d i n t h e D at a w i n d o w .
Al t - F1 2 d d d at aad d r - > 4 In d i r ect sec o n d d w o r d i n t h e D at a w i n d o w .
Tab l e 5 - 1 1 . So f t ICE Co m m an d Li n e Ed i t Co m m an d s
Ed i t i n g Fu n ct i o n Key
M o v e t h e cu r so r t o co l u m n 0 o f t h e co m m an d l i n e. Ho m e
M o v e t h e cu r so r p ast t h e l ast ch ar act er o f t h e co m m an d l i n e. En d
To g g l e i n ser t m o d e. W h en i n i n ser t m o d e, t h e cu r so r d i sp l ay s as a
b l o ck cu r so r an d t h e c h ar act er s en t er ed ar e i n ser t ed at t h e cu r r en t
cu r so r p o si t i o n , sh i f t i n g t h e t ex t t o t h e r i g h t b y o n e sp ace. W h en n o t
i n i n ser t m o d e, a ch ar act er en t er ed o v er w r i t es t h e ch ar act er at t h e
cu r so r p o si t i o n .
In ser t
D el et e t h e ch ar act er at t h e cu r r en t c u r so r p o si t i o n an d sh i f t t ex t t o
t h e l ef t b y o n e sp ace.
D el et e
D el et e t h e p r ev i o u s ch ar act er. Bksp
Can cel co m m an d l i n e. Esc
M o v e t h e cu r so r h o r i zo n t al l y w i t h i n t h e co m m an d l i n e. Ar r o w
Key s
Tab l e 5 - 1 0 . So f t ICE Fu n ct i o n Key Assi g n m en t s
Fu n ct i o n Key Co m m an d Fu n ct i o n
BETA REVI EW
Reca l l i ng Comma nds
Soft ICE remembers t h e last t h irt y-t wo comman ds you t yped in t h e
Comman d win dow. You can recall t h ese comman ds for edit in g an d
execut ion from wit h in eit h er t h e Comman d or Code win dows.
Use t h e followin g keys t o recall a comman d from wit h in t h e Comman d
win dow.
N o t e : Pr ef i x es ar e su p p o r t ed . Fo r ex am p l e, i f y o u t y p e t h e l et t er A, t h e
Up Ar r o w o n l y cy cl es t h r o u g h co m m an d s t h at st ar t w i t h t h e l et t er A.
Use t h e followin g keys t o recall a comman d from wit h in t h e Code
win dow.
Usi ng Run- t i me M a cr os
Macros are user-defin ed comman ds t h at you use in t h e same way as
built -in comman ds. Th e defin it ion , or body, of a macro con sist s of a
sequen ce of comman d in vocat ion s. Th e allowable set of comman ds
in cludes ot h er user-defin ed macros an d comman d-lin e argumen t s.
Th ere are t wo ways t o creat e macros. You can creat e run -t ime macros t h at
exist un t il you rest art Soft ICE or persist en t macros t h at are saved an d
aut omat ically loaded wit h Soft ICE. Th is sect ion describes h ow t o use run -
Tab l e 5 - 1 2 . So f t ICE Co m m an d Wi n d o w Recal l Co m m an d s
Fu n ct i o n Key
Get t h e p r evi o u s co m m an d f r o m t h e co m m an d h i st o r y b u f f er. Up Ar r o w
Get t h e n ex t co m m an d f r o m t h e co m m an d h i st o r y b u f f er. D o w n Ar r o w
Tab l e 5 - 1 3 . So f t ICE Co d e Wi n d o w Recal l Co m m an d s
Fu n ct i o n Key
Get t h e p r evi o u s co m m an d f r o m t h e co m m an d h i st o r y b u f f er. Sh i f t - Up Ar r o w
Get t h e n ex t co m m an d f r o m t h e co m m an d h i st o r y b u f f er. Sh i f t -
D o w n Ar r o w
BETA REVI EW
t ime macros. Refer t o Working with Persistent Macros on page 173 for more
in format ion about creat in g an d usin g persist en t macros.
Ti p You ca n u se t h e
M ACRO co m m a n d w i t h
p er si st en t m a cr os t o
t em p or a r i l y m od i f y
t h em d u r i n g r u n t i m e.
Wh en you r el oa d
Sof t I CE, you r p er si st en t
m a cr os r ever t t o t h ei r
or i g i n a l st a t e.
Th e followin g t able sh ows h ow t o creat e, delet e, edit , an d list run -t ime
macros.
Th e body of a macro is a sequen ce of Soft ICE comman ds or ot h er macros
separat ed by semicolon s. You are n ot required t o t ermin at e t h e fin al
comman d wit h a semicolon . Comman d-lin e argumen t s t o t h e macro can
be referen ced an ywh ere in t h e macro body wit h t h e syn t ax <parame-
ter#>, wh ere parameter# is a n umber bet ween on e an d eigh t .
Th e comman d MACRO asm = a %1 Jefin es an alias for t h e A (ASSEM-
BLE) comman d. Th e %1 is replaced wit h t h e first argumen t followin g am
or simply removed if n o argumen t is supplied.
If you n eed t o embed a lit eral quot e ch aract er () or a percen t sign (%)
wit h in t h e macro body, precede t h e ch aract er wit h a backslash ch aract er
(\ ). To specify a lit eral backslash ch aract er, use t wo con secut ive
backslash es (\ \ ).
N o t e : Al t h o u g h i t i s p o ssi b l e f o r a m acr o t o cal l i t sel f r ecu r si v el y, i t i s n o t
p ar t i cu l ar l y u sef u l , b ecau se t h er e i s n o p r o g r am m at i c w ay t o t er m i -
n at e t h e m acr o . If t h e m acr o cal l s i t sel f as t h e l ast co m m an d o f t h e
m acr o ( t ai l r ecu r si o n ) , t h e m acr o ex ecu t es u n t i l y o u u se t h e ESC key
t o t er m i n at e i t . If t h e r ecu r si v e c al l i s n o t t h e l ast co m m an d i n t h e
m acr o , t h e m acr o ex ecu t es 3 2 t i m es ( t h e n est i n g l i m i t ) .
Th e followin g t able sh ows some examples of run -t ime macros.
Tab l e 5 - 1 4 . So f t ICE Ru n - t i m e M acr o s
Act i o n Co m m an d
Cr eat e o r m o d i f y a m acr o M ACRO m a cr o- n a m e = com m a n d 1 ; com m a n d 2 ;
D el et e a m acr o M ACRO m a cr o- n a m e *
D el et e al l m acr o s M ACRO *
Ed i t a m acr o M ACRO m a cr o- n a m e
Li st al l m acr o s M ACRO
Tab l e 5 - 1 5 . Ru n - t i m e M acr o Ex am p l es
Ru n -t i m e M acr o Co m m an d s Ex am p l es
M ACRO Q ex p = ad d r ex p l o r er ; Q u er y % 1 Q ex p
Q ex p 1 4 0 0 0 0
BETA REVI EW
Sa vi ng t he Comma nd W i ndow Hi st or y Buf f er t o a Fi l e
Th e Soft ICE h ist ory buffer con t ain s all t h e in format ion displayed in t h e
Comman d win dow. Savin g t h e Soft ICE h ist ory buffer t o a file is useful for
doin g t h e followin g:
Dumpin g large amoun t s of dat a or regist er values
Disassemblin g code
List in g breakpoin t s logged by t h e BPLOG expression
Sh owin g Win dows messages logged by t h e BMSG comman d
Savin g debuggin g messages sen t from user programs t h at call Out put -
DebugSt rin g an d kern el-mode programs t h at call KdPrin t
Refer t o History Buffer Size on page 163 for more in format ion about ch an g-
in g t h e size of t h e Soft ICE h ist ory buffer.
To save t h e con t en t s of t h e Soft ICE h ist ory buffer t o a file, do t h e follow-
in g:
1 Make sure t h e in format ion you wan t t o save is displayin g t o t h e
Comman d win dow, so t h at it is saved in t h e Hist ory Buffer.
For example, before dumpin g dat a, remove t h e Dat a win dow t o force
t h e dat a t o display in t h e Comman d win dow.Run -t ime
2 Open Symbol Loader.
3 Eit h er ch oose SAVE SOFTICE HISTORY AS... from t h e File men u or click
t h e SAVE SOFTICE HISTORY but t on .
M ACRO 1 sh o t = b p x % 1 d o \ b c b p i n d ex \ 1 sh o t ei p
1 sh o t @esp
M ACRO d d t = d d t h r ead d d t
M ACRO d d p = d d p r o cess d d p
M ACRO t h r = t h r ead % 1 t i d t h r
t h r - x
M ACRO d m y f i l e =
m acr o m y f i l e = \ TABLE % 1 ; f i l e \ % 1 \
d m y f i l e m y t ab l e
m y f i l e m y f i l e. c
Tab l e 5 - 1 5 . Ru n - t i m e M acr o Ex am p l es
Ru n -t i m e M acr o Co m m an d s Ex am p l es
BETA REVI EW
4 Use t h e Save Soft ICE Hist ory dialog box t o det ermin e t h e file n ame
an d locat ion wh ere you wan t t o save t h e file.
Associ a t ed Comma nds
Th e followin g comman d is associat ed wit h t h e Comman d win dow. Refer
t o t h e SoftICE Command Reference for more in format ion about usin g t h is
comman d.
Using t he Code Window
Th e Code win dow displays source code, disassembled code, or bot h
source an d disassembled code (mixed). It also let s you set breakpoin t s.
(Refer t o Chapter 7: on page 103 for an explan at ion of h ow t o set break-
poin t s.)
Cont r ol l i ng t he Code W i ndow
Use t h e followin g comman ds t o con t rol t h e Code win dow.
Scr o llin g t h e Co d e W in d ow
To scroll t h e Code win dow, eit h er use t h e scroll arrows or t h e followin g
keys wh en t h e cursor is in t h e Code win dow.
Tab l e 5 - 1 6 . Co m m an d Wi n d o w SET Co m m an d
Co m m an d Fu n ct i o n
SET [ set v ar i ab l e] [ O N |
O FF] [ v al u e]
D i sp l ay s o r set s u ser p r ef er en ces.
Tab l e 5 - 1 7 . So f t ICE Co d e Wi n d o w Co n t r o l Co m m an d s
WC O p en s an d cl o ses t h e Co d e w i n d o w.
WC [ n u m l i n es] Resi zes t h e Co d e w i n d o w.
Al t -C M o ves t h e cu r so r i n t o o r o u t o f t h e Co d e w i n d o w.
Tab l e 5 - 1 8 . Cu r so r - i n - Co d e Wi n d o w Fu n ct i o n s
Fu n ct i o n ( f r o m w i t h i n t h e Co d e w i n d o w ) Key Seq u en ce
Scr o l l Co d e w i n d o w t o t h e p r evi o u s p ag e. Pag eUp
BETA REVI EW
You can also scroll t h e Code win dow wh en t h e cursor is in t h e Comman d
win dow, as follows.
Vi ew i ng I nf or ma t i on
Th e Code win dow provides t h ree modes t o display source code, disas-
sembled code, or bot h . Th e followin g t able defin es t h ese modes.
Scr o l l Co d e w i n d o w t o t h e n ex t p ag e. Pag eD o w n
Scr o l l Co d e w i n d o w t o t h e p r evi o u s l i n e. Up Ar r o w
Scr o l l Co d e w i n d o w t o t h e n ex t l i n e. D o w n Ar r o w
Ju m p t o t h e f i r st l i n e o f t h e so u rce f i l e. Ct r l - Ho m e
Ju m p t o t h e l ast l i n e o f t h e so u r ce f i l e. Ct r l - En d
Scr o l l Co d e w i n d o w l ef t o n e ch ar act er ( so u r ce m o d e o n l y ) . Ct r l - Lef t Ar r o w
Scr o l l Co d e w i n d o w r i g h t o n e ch ar act er ( so u r ce m o d e o n l y ) . Ct r l - Ri g h t Ar r o w
Tab l e 5 - 1 9 . Cu r so r - i n - Co m m an d Wi n d o w Fu n ct i o n s
Fu n ct i o n ( f r o m w i t h i n t h e Co m m an d w i n d o w ) Key
Scr o l l t h e Co d e w i n d o w t o t h e p r ev i o u s p ag e. Ct r l - Pag eUp
Scr o l l t h e Co d e w i n d o w t o t h e n ex t p ag e. Ct r l - Pag eD n
Scr o l l t h e Co d e w i n d o w t o t h e p r ev i o u s l i n e. Ct r l - Up Ar r o w
Scr o l l t h e Co d e w i n d o w t o t h e n ex t l i n e. Ct r l - D o w n Ar r o w
Ju m p t o t h e f i r st l i n e o f t h e so u rce f i l e. Ct r l - Ho m e
Ju m p t o t h e l ast l i n e o f t h e so u r ce f i l e. Ct r l - En d
Scr o l l t h e Co d e w i n d o w l ef t o n e ch ar act er ( i n so u rce m o d e
o n l y ) .
Ct r l - Lef t Ar r o w
Scr o l l t h e Co d e w i n d o w r i g h t o n e ch ar act er ( i n so u r ce m o d e
o n l y ) .
Ct r l - Ri g h t Ar r o w
Tab l e 5 - 1 8 . Cu r so r - i n - Co d e Wi n d o w Fu n ct i o n s
Fu n ct i o n ( f r o m w i t h i n t h e Co d e w i n d o w ) Key Seq u en ce
Tab l e 5 - 2 0 . Co d e Wi n d o w M o d es
Co d e M o d e D escr i p t i o n
So u rce If so u r ce co d e i s av ai l ab l e, t h e so u r ce f i l e d i sp l ay s i n t h e Co d e
w i n d o w.
BETA REVI EW
To swit ch amon g t h e Code win dow modes, use t h e SRC comman d (F3).
U sin g Cod e an d M ixe d M o d e s
Each disassembled in st ruct ion in code or mixed mode con t ain s t h e
followin g fields.
Th e followin g out put sh ows a disassembled in st ruct ion :
00FD:00001DA1 56 PUSH ESI
Addit ion ally, t h e Soft ICE disassembler aut omat ically provides t h ese
commen t s:
INT 2E calls are commen t ed wit h t h e kern el rout in e t h at will be
called an d t h e n umber of paramet ers it t akes. If you h ave loaded t h e
symbols for NTOSKRNL an d t h at is t h e curren t symbol t able, you will
see t h e n ame of t h e OS rout in e rat h er t h an an address.
M i x ed In m i x ed m o d e, b o t h so u rce l i n es an d d i sassem b l ed i n st r u ct i o n s
d i sp l ay i n t h e Co d e w i n d o w. Eac h so u rce l i n e i s f o l l o w ed b y i t s
assem b l er i n st r u ct i o n s.
Co d e In co d e m o d e, o n l y d i sassem b l ed i n st r u ct i o n s d i sp l ay i n t h e
Co d e w i n d o w.
Tab l e 5 - 2 1 . Co d e an d M i x ed M o d e Fi el d s
Fi el d D escr i p t i o n
Lo cat i o n H ex ad ec i m al ad d r ess o f t h e i n st r u c t i o n . I f t h er e i s a p u b l i c
c o d e sy m b o l f o r t h e l o c at i o n , i t d i sp l ay s o n t h e l i n e ab o v e t h e
i n st r u c t i o n .
Co d e b y t es Act u al h ex ad eci m al b y t es o f t h e i n st r u c t i o n . Th e d ef au l t i s t o
su p p r ess t h e c o d e b y t es b ec au se t h ey ar e u su al l y n o t n eed ed .
Use t h e SET CO D E O N c o m m an d t o d i sp l ay t h e c o d e b y t es.
In st r u c t i o n D i sassem b l ed m n em o n i cs o f t h e i n st r u c t i o n . Th i s i s t h e c u r r en t
assem b l y l an g u ag e i n st r u c t i o n . If an y o f t h e m em o r y ad d r ess
r ef er en c es o f t h e i n st r u c t i o n m at c h a sy m b o l , t h e sy m b o l d i s-
p l ay s i n st ead o f t h e h ex ad ec i m al ad d r ess. Use SET SYM BO LS
O FF t o d i sp l ay h ex ad ec i m al ad d r esses i n st ead .
Co m m en t Hel p f u l co m m en t f r o m t h e d i sassem b l er.
Tab l e 5 - 2 0 . Co d e Wi n d o w M o d es
Co d e M o d e D escr i p t i o n
BETA REVI EW
If an in st ruct ion uses an immediat e operan d t h at mat ch es a Win dows
NT/ 2000/ XP st at us code, t h e n ame of t h e st at us code displays as a
commen t .
INT 21 calls are commen t ed wit h t h eir DOS fun ct ion n ames.
INT 31 calls are commen t ed wit h t h eir DPMI fun ct ion n ames.
VxD service n ames are sh own as code labels wh ere appropriat e.
View in g Ad d it ion al I n f or m at io n
In addit ion t o source an d disassembled code, t h e Code win dow displays
t h e followin g in format ion :
Wh en Soft ICE pops up, t h e in st ruct ion locat ed at t h e curren t EIP is
h igh ligh t ed in bold. If t h e in st ruct ion is a relat ive jump, t h e disas-
semblers commen t field con t ain s eit h er t h e st rin g JUMP or NO
JUMP, in dicat in g wh et h er or n ot t h e jump will be t aken . For t h e
JUMP st rin g, an up or down arrow in dicat es wh ere t h e jump is goin g:
backwards (JUMP ) or forwards (JUMP ). Use t h e arrow t o det er-
min e wh ich way t o scroll t h e Code win dow t o view t h e t arget of t h e
JUMP.
Th e t arget of t h e JUMP in st ruct ion is always marked wit h a h igh -
ligh t ed arrow in dicat or () overlayin g t h e select or port ion of t h e
address.
If t h e in st ruct ion referen ces a memory locat ion , t h e effect ive address
an d t h e value at t h e effect ive address display on t h e en d of t h e code
lin e. If t h e Regist er win dow is visible, h owever, t h e effect ive address
an d t h e value at t h e effect ive address display in t h at win dow ben eat h
t h e flags field.
If a breakpoin t exist s at an y in st ruct ion in t h e Code win dow, t h e cor-
respon din g lin e displays in bold t ext .
Th e lin es above an d below t h e Code win dow sh ow more in format ion
about t h e code.
In format ion above t h e Code win dow in cludes on e of t h e
followin g:
Symboln ame + Offset
Source file n ame, if viewin g source
On e of t h e followin g segmen t t ypes:
V86 Code from a real-mode segmen t :offset address.
PROT16 Code from a 16-bit prot ect ed mode select or:offset
address
BETA REVI EW
PROT32 Code from a 32-bit prot ect ed mode select or:offset
address
In format ion below t h e Code win dow in cludes on e of t h e
followin g:
Win dows module n ame, sect ion n ame, an d OFFSET if it is a
32-bit Win dows module. For example,
KERNEL32!.Text + 002f
Win dows module n ame an d segmen t n umber in paren t h eses
if it is a 16-bit Win dows module. For example, Display (01)
Own er n ame of t h e code segmen t if it is in V86 mode. For
example, DOS.
Ent er i ng Comma nds Fr om t he Code W i ndow
You can st ill en t er comman ds wh en t h e cursor is in t h e Code win dow.
Aft er you t ype t h e first let t er of a comman d, t h e cursor moves down t o
t h e Comman d win dow. Aft er you press En t er an d t h e comman d
complet es, t h e cursor moves back t o t h e Code win dow. You can also use
fun ct ion key comman ds wh ile t h e cursor is in t h e Code win dow. Refer t o
Using the Command Window on page 69 for more in format ion about en t er-
in g comman ds.
Th e followin g comman ds are part icularly useful.
Tab l e 5 - 2 2 . Co d e Wi n d o w s Co m m an d s
. ( D o t ) Vi ew t h e i n st r u c t i o n at t h e c u r r en t EI P.
A a d d r ess Assem b l e i n st r u ct i o n s d i r ec t l y i n t o m em o r y.
BPX ( F9 ) Set p o i n t - an d - sh o o t b r eak p o i n t s.
FILE f i l e- n a m e Sel ec t t h e so u r c e f i l e t o v i ew .
Th e f i l en am e c an b e a p ar t i al n am e. I f y o u d o n o t k n o w t h e
n am e o f t h e f i l en am e, en t er FILE * t o d i sp l ay al l t h e f i l es l o ad ed
f o r t h e sy m b o l t ab l e.
HERE ( F7 ) Set b r eakp o i n t s t h at ex ec u t e o n e t i m e.
SET D i sp l ay o r set u ser p r ef er en c es.
SRC Sw i t c h am o n g t h e Co d e w i n d o w m o d es: so u r c e, m i x ed , an d
c o d e.
BETA REVI EW
Refer t o t h e SoftICE Command Reference for more in format ion about t h ese
comman ds.
Using t he Locals Window
Th e Locals win dow displays t h e curren t st ack. You can view t h e con t en t s
of st ruct ures, arrays, an d ch aract er st rin gs wit h in t h e st ack by expan din g
t h em.
Cont r ol l i ng t he Loca l s W i ndow
Use t h e followin g comman ds t o con t rol t h e Locals win dow.
Scr o llin g t h e Lo cals W in d ow
To scroll t h e Locals win dow, eit h er use t h e scroll arrows or use Alt -L t o
move t h e cursor in t o t h e Locals win dow, t h en use t h e followin g keys.
SS st r i n g M o v e t h e so u r c e d i sp l ay t o t h e n ex t o c cu r r en c e o f t h e sp eci -
f i ed st r i n g .
TABS t a b - set -
t i n g
N o t e : TABS i s n o w p ar t o f t h e SET c o m m an d . See t h e SET
c o m m an d en t r y i n t h e Sof t I CE Com m a n d Ref er en ce f o r d et ai l s.
U a d d r ess Un assem b l e an y c o d e ad d r ess.
I f y o u sp ec i f y a f u n c t i o n n am e f o r t h e ad d r ess p ar am et er, So f t -
I CE scr o l l s t h e Co d e w i n d o w t o t h e f u n c t i o n y o u sp ec i f y.
Tab l e 5 - 2 2 . Co d e Wi n d o w s Co m m an d s
Tab l e 5 - 2 3 . Lo cal s Wi n d o w s Co m m an d s
WL O p en s an d cl o ses t h e Lo cal s w i n d o w.
WL [ n u m l i n es] Resi zes t h e Lo cal s w i n d o w.
Al t -L M o v es t h e cu r so r i n t o o r o u t o f t h e Lo cal s w i n d o w.
Al t -E In vo ke i n l i n e ed i t i n g .
Tab l e 5 - 2 4 . Lo cal s Wi n d o w Scr o l l i n g Fu n ct i o n s
Fu n ct i o n Key Seq u en ce
Scr o l l t h e Lo cal s w i n d o w t o t h e p r evi o u s p ag e. Pag eUp
BETA REVI EW
Expa ndi ng a nd Col l a psi ng St a cks
You can expan d st ruct ures, arrays, an d ch aract er st rin gs t o display t h eir
con t en t s. Th ese it ems are delin eat ed wit h a plus sign (+) t o in dicat e t h at
you can expan d t h em. To expan d or collapse an it em, do t h e followin g:
Pen t ium PCs on lyDouble-click t h e it em.
All PCsUse Alt -L t o en t er t h e Locals win dow, scroll t o t h e it em, an d
press En t er.
Th e followin g comman ds are associat ed wit h t h e Locals win dow. Refer t o
t h e SoftICE Command Reference for more in format ion about usin g t h ese
comman ds.
Using t he Wat ch Window
Th e Wat ch win dow let s you mon it or t h e values of expression s t h at you
set wit h t h e WATCH comman d. Refer t o t h e SoftICE Command Reference
for more in format ion about t h e WATCH comman d.
Scr o l l t h e Lo cal s w i n d o w t o t h e n ex t p ag e. Pag eD n
Scr o l l t h e Lo cal s w i n d o w t o t h e p r evi o u s l i n e. Up Ar r o w
Scr o l l t h e Lo cal s w i n d o w t o t h e n ex t l i n e. D o w n Ar r o w
Ju m p t o f i r st i t em . Ho m e
Ju m p t o l ast i t em . En d
Scr o l l t h e Lo cal s w i n d o w l ef t o n e ch ar act er. Lef t Ar r o w
Scr o l l t h e Lo cal s w i n d o w r i g h t o n e ch ar act er. Ri g h t Ar r o w
Tab l e 5 - 2 4 . Lo cal s Wi n d o w Scr o l l i n g Fu n ct i o n s
Tab l e 5 - 2 5 . Lo cal s Wi n d o w Co m m an d s
LOCALS
Li st s l o c al v ar i ab l es f r o m t h e c u r r en t st ac k f r am e.
TYPES [ t yp e- n a m e] Li st s al l t y p es i n t h e cu r r en t co n t ex t o r l i st s al l t y p e i n f o r -
m at i o n f o r t h e t y p e- n am e sp eci f i ed .
BETA REVI EW
Cont r ol l i ng t he W a t ch W i ndow
Use t h e followin g comman ds t o con t rol t h e Wat ch win dow.
Scr o llin g t h e W at ch W in d ow
To scroll t h e Wat ch win dow, eit h er use t h e scroll arrows or use Alt -W t o
move t h e cursor in t o t h e Wat ch win dow an d use t h e followin g keys.
Set t i ng a n Expr essi on t o W a t ch
Use t h e WATCH comman d t o set an expression t o wat ch . Th e expression
can use global an d local symbols, regist ers, an d addresses.
N o t e : To set a w at ch o n a l o cal var i ab l e, t h e var i ab l e m u st b e i n sco p e.
Th e followin g examples illust rat e h ow t o use t h e WATCH comman d.
Mon it ors t h e value of ds:esi:
WATCH ds:esi
Mon it ors t h e value ds:esi points to:
Tab l e 5 - 2 6 . Wat ch Wi n d o w Co m m an d s
WW O p en s an d cl o ses t h e Wat c h w i n d o w.
WW [ n u m l i n es] Resi zes t h e Wat ch w i n d o w.
Al t -W M o v es t h e cu r so r i n t o o r o u t o f t h e Wat ch w i n d o w.
Al t -E In vo ke i n l i n e ed i t i n g .
Tab l e 5 - 2 7 . Wat ch Wi n d o w Scr o l l i n g Fu n ct i o n s
Scr o l l t h e Wat ch w i n d o w t o t h e p r evi o u s p ag e. Pag eUp
Scr o l l t h e Wat ch w i n d o w t o t h e n ex t p ag e. Pag eD o w n
Scr o l l t h e Wat ch w i n d o w t o t h e p r evi o u s l i n e. Ar r o w
Scr o l l t h e Wat ch w i n d o w t o t h e n ex t l i n e. D o w n Ar r o w
Ju m p t o f i r st i t em . Ho m e
Ju m p t o l ast i t em . En d
Scr o l l t h e Wat ch w i n d o w l ef t o n e ch ar act er. Lef t Ar r o w
Scr o l l t h e Wat ch w i n d o w r i g h t o n e ch ar act er. Ri g h t Ar r o w
BETA REVI EW
WATCH *ds:esi
D elet in g a W at ch
You can use eit h er t h e mouse or keyboard t o delet e a wat ch . To use your
mouse t o delet e a wat ch , click on t h e wat ch an d press Delet e. To use your
keyboard t o delet e a wat ch , use Alt -W t o en t er t h e Wat ch win dow, use
t h e arrow keys t o select t h e wat ch , an d press Delet e.
Th e Wat ch win dow con t ain s t h e followin g fields in t h e order sh own .
Expa ndi ng a nd Col l a psi ng Typed Expr essi ons
You can expan d t yped expression s t o display t h eir con t en t s. Typed
expression s are delin eat ed wit h a plus sign (+) t o in dicat e t h at you can
expan d t h em. To expan d or collapse a t yped expression , do t h e follow-
in g:
Pen t ium PCs on ly Double-click t h e it em.
All PCs Use Alt -W t o en t er t h e Wat ch win dow, scroll t o t h e it em,
t h en press En t er.
Th e followin g comman d is associat ed wit h t h e Wat ch win dow. Refer t o
t h e Soft ICE Comman d Referen ce for more in format ion about usin g t h is
comman d.
Tab l e 5 - 2 8 . Wat ch Wi n d o w Fi el d s
Wat ch Li n e Fi el d D escr i p t i o n
Ex p r essi o n Act u al ex p r essi o n t h at w as t y p ed o n t h e WATCH co m m an d .
Th i s ex p r essi o n i s r e- eval u at ed ever y t i m e t h e Wat ch w i n -
d o w d i sp l ay s.
Ty p e d ef i n i t i o n Ty p e d ef i n i t i o n o f t h e ex p r essi o n .
Val u e Cu r r en t v al u e o f t h e ex p r essi o n b ei n g w at ch ed .
Tab l e 5 - 2 9 . Wat ch Wi n d o w Co m m an d
WATCH ex p r essi o n Ad d s a w at ch ex p r essi o n .
BETA REVI EW
Using t he Regist er Window
Th e Regist er win dow displays t h e curren t value of t h e syst em regist ers,
flags, an d t h e effect ive address if applicable. Use t h is win dow t o det er-
min e wh ich regist ers are alt ered by a procedure call or t o edit t h e regist ers
an d flags.
Cont r ol l i ng t he Regi st er W i nd ow
Use t h e followin g comman ds t o con t rol t h e Regist er win dow.
If you are n ot usin g t h e Regist er win dow, close it t o free up screen space
for ot h er win dows.
Th e first t h ree lin es in t h e Regist er win dow sh ow t h e followin g regist ers,
flags, an d address if available:
EAX, EBX, ECX, EDX, ESI
EDI, EBP, ESP, EIP, o d i s z a p c
CS, DS, SS, ES, FS, GSeffective address=value
Wh en you use t h e T (t race), P (st ep over), an d G (go t o) comman ds,
Soft ICE h igh ligh t s t h e regist ers t h at ch an ge. Th is feat ure is useful for
seein g wh ich regist ers were alt ered by a procedure call.
In t h e secon d lin e of t h e Regist er win dow, t h e CPU flags are defin ed as
follows.
Tab l e 5 - 3 0 . Reg i st er Wi n d o w Co m m an d s
WR O p en s an d cl o ses t h e Reg i st er w i n d o w.
Al t -R M o v es t h e cu r so r i n t o o r o u t o f t h e Reg i st er w i n d o w.
Tab l e 5 - 3 1 . Reg i st er Wi n d o w CPU Fl ag D ef i n i t i o n s
Fl ag D escr i p t i o n Fl ag D escr i p t i o n
o O ver f l o w f l ag z Z er o f l ag
d D i r ect i o n f l ag a Au x i l i ar y car r y f l ag
i In t er r u p t f l ag p Par i t y f l ag
s Si g n f l ag c Car r y f l ag
BETA REVI EW
N o t e : A l o w ercase l et t er t h at i s n o t h i g h l i g h t ed i n d i cat es a f l ag v al u e o f 0 . A
h i g h l i g h t ed u p p er case l et t er i n d i cat es a f l ag v al u e o f 1 , f o r ex am p l e,
o d I s Z a p c.
If t h e curren t in st ruct ion referen ces a memory locat ion , t h e effect ive
address an d t h e value at t h e effect ive address display in t h e t h ird lin e of
t h e Regist er win dow. You can use t h e effect ive address an d value in
expression s wit h t h e Eaddr an d Evalue fun ct ion s; refer t o Built-in Functions
on page 129.
Edi t i ng Regi st er s a nd Fl a gs
You can use t h e Regist er win dow t o edit t h e regist ers an d flags. Move t h e
cursor in t o t h e Regist er win dow, t h en edit t h e regist ers an d flags in place.
To move t h e mouse in t o t h e Regist er win dow, eit h er click t h e mouse in
t h e Regist er win dow or press Alt -R. Th e followin g keys are available for
edit in g wit h in t h e Regist er win dow.
Tab l e 5 - 3 2 . Reg i st er Wi n d o w Ed i t i n g Fu n ct i o n s
Ed i t i n g Fu n ct i o n Act i v e Key s
Po si t i o n cu r so r at t h e b eg i n n i n g o f t h e n ex t r eg i st er f i el d . Tab o r
Sh i f t - Ri g h t Ar r o w
Po si t i o n cu r so r at t h e b eg i n n i n g o f t h e p r ev i o u s r eg i st er f i el d . Sh i f t - Tab o r
Sh i f t - Lef t Ar r o w
Accep t ch an g es an d ex i t ed i t r eg i st er m o d e. En t er
Ex i t ed i t r eg i st er m o d e. Th e r eg i st er t h at t h e cu r so r i s cu r r en t l y
o n w i l l n o t ch an g e, b u t o t h er p r evi o u sl y - m o d i f i ed r eg i st er s
ch an g e.
Esc
To g g l e t h e val u e o f a f l ag w h en t h e cu r so r i s p o si t i o n ed i n t h e
f l ag s f i el d .
In ser t
M o v e t h e cu r so r l ef t , r i g h t , u p , an d d o w n i n t h e Reg i st er w i n -
d o w.
Ar r o w key s
BETA REVI EW
Th e followin g comman ds are associat ed wit h t h e Regist er win dow. Refer
t o t h e SoftICE Command Reference for more in format ion about usin g t h ese
comman ds.
Using t he Dat a Window
Th e Dat a win dow let s you view an d edit t h e con t en t s of memory. You
can use up t o four differen t Dat a win dows at an y given t ime. Each Dat a
win dow can view differen t memory locat ion s an d display in format ion in
it s own un ique format , as well as display an address t h at is in depen den t
of t h e ot h er Dat a win dows.
Cont r ol l i ng t he Da t a W i ndow
Use t h e followin g comman ds t o con t rol t h e Dat a win dow.
Tab l e 5 - 3 3 . Asso c i at ed Reg i st er Wi n d o w Co m m an d s
CPU D i sp l ay s CPU r eg i st er i n f o r m at i o n .
G [ = st a r t - a d d r ess] [ b r ea k-
a d d r ess]
Go es t o an ad d r ess.
P Ex ecu t es o n e p r o g r am st ep .
T [ = st a r t - a d d r ess] [ cou n t ] Tr aces o n e i n st r u ct i o n .
Tab l e 5 - 3 4 . D at a Wi n d o w Co m m an d s
WD . n O p en s an d cl o ses t h e D at a w i n d o w, w h er e n i s a n u m b er f r o m 0
t h r o u g h 3 sp eci f y i n g t h e D at a w i n d o w. If y o u d o n o t sp eci f y a
v al u e f o r n , 0 i s assu m ed .
WD . n [ # - l i n es] Resi zes t h e D at a w i n d o w, o r o p en t h e sp eci f i ed D at a w i n d o w t o
t h e sp eci f i ed si ze.
Al t -D M o v es t h e cu r so r i n t o o r o u t o f t h e cu r r en t D at a w i n d o w.
D ATA n O p en s t h e n ex t seq u en t i al D at a w i n d o w, o r sw i t ch es t o t h e n ex t
seq u en t i al D at a w i n d o w o n ce al l f o u r ar e o p en . Sp eci f y i n g a
v al u e f o r n w i l l set t h e sp eci f i ed w i n d o w as t h e act i v e D at a w i n -
d o w.
D [ a d d r ess] Sel ect an ad d r ess t o vi ew i n t h e cu r r en t D at a w i n d o w.
BETA REVI EW
Th ere can on ly be on e act ive Dat a win dow at a t ime. Soft ICE sign ifies t h e
act ive win dow by displayin g t h e Dat a win dow n umber, on t h e righ t edge
of t h e t it le bar, in bold t ype. To make a specific Dat a win dow t h e act ive
win dow, eit h er select it wit h t h e mouse, or use t h e LA|A r comman d.
Scr o llin g t h e D at a W in d ow
To scroll t h e Dat a win dow, eit h er click t h e scroll arrows or press Alt -D t o
move t h e cursor in t o t h e Dat a win dow an d use t h e followin g keys.
FO RM AT
( Sh i f t - F3 )
Sel ect s a f o r m at t o d i sp l ay i n t h e cu r r en t D at a w i n d o w.
Tab l e 5 - 3 5 . D at a Wi n d o w Scr o l l Fu n ct i o n s
Scr o l l t h e w i n d o w t o t h e p r evi o u s p ag e. Pag eUp
Scr o l l t h e w i n d o w t o t h e n ex t p ag e. Pag eD o w n
Scr o l l t h e w i n d o w t o t h e p r evi o u s l i n e. Up Ar r o w
Scr o l l t h e w i n d o w t o t h e n ex t l i n e. D o w n Ar r o w
Tab l e 5 - 3 4 . D at a Wi n d o w Co m m an d s
BETA REVI EW
Th e lin e above t h e Dat a win dow displays t h e followin g four fields in t h e
order sh own .
Each lin e in a Dat a win dow sh ows 16 byt es of dat a in t h e curren t format
of eit h er byt e, word, dword, sh ort real, lon g real, or 10-byt e real. If t h e
curren t format is 10-byt e real, each lin e sh ows 20 byt es of dat a. Th e dat a
byt es also display in ASCII on t h e righ t side of t h e win dow if t h e curren t
format is h exadecimal (byt e, word, or dword).
Tab l e 5 - 3 6 . D at a Wi n d o w D escr i p t i o n Fi el d s
Fi el d D escr i p t i o n
A St r i n g If t h e w i n d o w w as assi g n ed an ex p r essi o n w i t h t h e D EX co m -
m an d , t h e ASCII ex p r essi o n d i sp l ay s o n t h i s l i n e. O t h er w i se,
t h e n ear est sy m b o l p r eced i n g t h e d at a l o cat i o n d i sp l ay s. Th i s
can b e o n e o f t h e f o l l o w i n g st r i n g s:
Sy m b o l n am e f o l l o w ed b y t h e h ex ad eci m al o f f set f r o m t h e
sy m b o l n am e, f o r ex am p l e, M y SYM BO L+ 0 0 0 1 0
Wi n d o w s m o d u l e n am e f o l l o w ed b y a t y p e, i f t h e d at a
seg m en t i s p ar t o f t h e Wi n d o w s h eap , f o r ex am p l e,
m o u se. m o d u l eD B
O w n er n am e o f t h e d at a seg m en t i f i t i s p ar t o f a v i r t u al
D O S m ach i n e.
Wi n d o w s m o d u l e n am e, sect i o n n am e, an d h ex ad eci m al
o f f set f r o m t h e n am e, f o r ex am p l e, KERN EL3 2 ! . t ex t + 0 0 1 F
If t h e l o cat i o n d o es n o t h av e an asso ci at ed sy m b o l , t h i s f i el d
i s b l an k.
D at a f o r m at t y p e D i sp l ay s ei t h er b y t e, w o r d , d w o r d , sh o r t r eal , l o n g r eal , o r
1 0 - b y t e r eal .
Seg m en t t y p e Ei t h er V8 6 o r PRO T d i sp l ay s. V8 6 i n d i cat es d at a f r o m a r eal -
m o d e seg m en t : o f f set ad d r ess an d PRO T i n d i cat es d at a f r o m a
p r o t ect ed - m o d e sel ect o r : o f f set ad d r ess.
Wi n d o w n u m b er D at a w i n d o w n u m b er f r o m 0 t o 3 .
BETA REVI EW
Cha ngi ng t he M emor y Addr ess a nd For ma t
Ti p You ca n a l so u se
t h e D com m a n d t o
sp eci f y t h e f or m a t f or
t h e a d d r ess you
d i sp l a y. Ref er t o t h e
Sof t I CE Com m a n d
Ref er en ce f or m or e
i n f or m a t i on a b o u t t h e
D co m m a n d .
Eit h er click on t h e format n ame list ed in t h e t op lin e of t h e Dat a win dow
or use t h e FORMAT comman d (Sh ift -F3) t o ch an ge t h e format of t h e
curren t Dat a win dow. Th e format cycles amon g t h e followin g: byt e,
word, dword, sh ort real, lon g real, an d 10-byt e real.
To ch an ge t h e memory address displayed in t h e curren t Dat a win dow,
en t er t h e D comman d an d specify an address. Th e followin g example
displays t h e memory st art in g at address ES:1000h :
: D es:1000
Edi t i ng M emor y
To edit memory, move t h e cursor in t o t h e Dat a win dow an d use eit h er
h exadecimal or ASCII ch aract ers.
Ti p You ca n a l so u se
t h e E com m a n d t o ed i t
d a t a .
Use t h e followin g keys for edit in g wit h in t h e Dat a win dow.
Assi gni ng Expr essi ons
Use t h e DEX comman d t o assign an expression t o an y of t h e Dat a
win dows. Wh en Soft ICE pops up, t h e expression s are evaluat ed an d t h e
result in g locat ion s display in t h eir assign ed Dat a win dows. Th is is useful
for set t in g up a win dow t h at always displays t h e con t en t s of t h e st ack.
For example, t h e followin g comman d displays t h e curren t con t en t s of
t h e st ack in Dat a win dow 0, each t ime Soft ICE pops up:
L! 55:!5
Tab l e 5 - 3 7 . D at a Wi n d o w Ed i t i n g Fu n ct i o n s
Ed i t i n g Fu n ct i o n Act i ve Key s
To g g l e b et w een n u m er i c an d ASCII ar eas. Tab
Po si t i o n cu r so r at t h e b eg i n n i n g o f t h e p r evi o u s d at a f i el d ( p r evi -
o u s b y t e, w o r d , o r d w o r d i n h ex ad eci m al m o d e, o r p r ev i o u s
ch ar act er i n ASCII m o d e) .
Sh i f t - Tab
Accep t ch an g es an d ex i t ed i t d at a m o d e. En t er
Ex i t ed i t d at a m o d e. Th e d at a f i el d t h e cu r so r i s cu r r en t l y o n w i l l
n o t ch an g e, b u t o t h er p r ev i o u sl y - m o d i f i ed d at a f i el d s ch an g e.
Esc
BETA REVI EW
Th e followin g comman ds are associat ed wit h t h e Dat a win dow. Refer t o
t h e SoftICE Command Reference for more in format ion about usin g t h ese
comman ds.
Using t he St ack Window
Th e St ack Win dow displays t h e call st acks for 32-bit code. Th e St ack
win dow h as t h ree column s: Frame poin t er, ret urn address, an d in st ruc-
t ion poin t er (EIP):
0012FFC077F1B304WINMAIN
0012FFF000000000KERNEL32!GetProcessPriorityBoost+0117
Use t h e WS comman d t o open an d close t h e St ack win dow.
You can also click t h e mouse in t h e St ack win dow t o set focus, sin gle
click an it em t o select it , an d double click an it em t o updat e t h e Locals,
Code, an d Th read win dows.
Tab l e 5 - 3 8 . Asso c i at ed D at a Wi n d o w Co m m an d s
D [ si ze] [ ad d r ess] D i sp l ay s m em o r y.
D EX [ d a t a - w i n d ow - n u m b er
[ exp r essi on ] ]
D i sp l ay s o r assi g n s an ex p r essi o n t o t h e
D at a w i n d o w.
E [ si z e] [ a d d r ess [ d a t a - l i st ] ] Ed i t s m em o r y.
S [ - cu ] [ a d d r ess L l en g t h d a t a l i st ] Sear ch es m em o r y f o r d at a.
Tab l e 5 - 3 9 . St ack Wi n d o w Co m m an d s
Co m m an d / Key s Fu n ct i o n
ALT- S Gi v es St ack w i n d o w f o cu s
Ar r o w Key s Sel ect a p ar t i cu l ar cal l st ack el em en t
En t er Up d at es Lo cal s an d Co d e w i n d o w s w h en a cal l st ack i t em i s
sel ect ed
BETA REVI EW
Using t he Thread Window
Th e Th read Win dow displays in format ion for t h reads wit h in a given
process. Th e dat a displayed in t h e Th read win dow depen ds on wh et h er
you are run n in g Win dows 9x or Win dows NT/ 2000/ XP. Refer t o t h e
Soft ICE on lin e h elp for det ails (t h e in format ion can be foun d un der t h e
WT comman d).
Cont r ol l i ng t he Thr ea d W i ndow
Use t h e followin g comman ds t o con t rol t h e Th read win dow:
To scroll t h e Th read win dow, eit h er click t h e scroll arrows or press Alt -T
t o move t h e cursor in t o t h e Th read win dow an d use t h e followin g keys
Using t he Pent ium III/ IV Regist er Window
Th e In t el Pen t ium III/ IV in st ruct ion set is support ed, in cludin g disassem-
bly an d assembly of n ew opcodes. Pen t ium III/ IV regist ers can be viewed
usin g t h e WX comman d.
Tab l e 5 - 4 0 . Th r ead Wi n d o w Co m m an d s
WT O p en s an d cl o ses t h e Th r ead Wi n d o w
WT [ n u m l i n es] Resi zes t h e Th r ead Wi n d o w
Al t -T M o ves t h e cu r so r i n t o o r o u t o f t h e t h r ead w i n d o w
Tab l e 5 - 4 1 . Th r ead Wi n d o w Scr o l l i n g Key Seq u en ces
Scr o l l t h e w i n d o w t o t h e p r evi o u s p ag e. Pag eUp
Scr o l l t h e w i n d o w t o t h e n ex t p ag e. Pag eD o w n
Scr o l l t h e w i n d o w t o t h e p r evi o u s l i n e. Up Ar r o w
Scr o l l t h e w i n d o w t o t h e n ex t l i n e. D o w n Ar r o w
BETA REVI EW
Using t he FPU St ack Window
Th e FPU St ack win dow displays t h e curren t st at e of t h e float in g poin t
un it (FPU) st ack an d MMX regist ers.
Use t h e WF comman d t o open or close t h e FPU St ack win dow.
If t h e values of t h e FPU regist ers display as a quest ion mark (?), t h e FPU is
disabled or n ot presen t . Win dows NT/ 2000/ XP en ables t h e FPU for a
t h read aft er it execut es on e FPU-relat ed in st ruct ion .
Th e In t el arch it ect ure aliases t h e 64-bit MMX regist ers upon t h e FPU
st ack.
N o t e : M M X r ef er s t o t h e m u l t i m ed i a ex t en si o n s t o t h e In t el Pen t i u m an d
Pen t i u m - Pr o p r o cesso r s.
Tab l e 5 - 4 2 . Pen t i u m III/ IV Reg i st er Co m m an d s
CPU Co m m an d Fu n ct i o n
P- III f D i sp l ay as sh o r t r eal val u es
P- III d D i sp l ay as d w o r d v al u es
P- III * To g g l e b et w een d w o r d an d r eal
P- IV+ - d q D o u b l e q u ad - w o r d
P- IV+ - sf Si n g l e f l o at
P- IV+ - d f D o u b l e f l o at
P- IV+ - q Q u ad w o r d
BETA REVI EW
To display regist ers in t h e FPU St ack win dow, select on e of t h e followin g
dat a format s.
Ti p Use t h e W F - D
co m m a n d t o d i sp l a y
t h e con t en t s of t h e
r eg i st er s, t h e st a t u s,
a n d t h e co n t r o l w or d s
i n t h e Com m a n d
w i n d ow.
Wh en t h ey are viewed as float in g poin t s, t h e regist ers are labeled ST0
t h rough ST7. Wh en t h ey are viewed packed, as byt e/ word/ dword, t h e
regist ers are labelled MM0 t h rough MM7. (See t h e SoftICE Command
Reference for more in format ion about t h e WF comman d.)
Tab l e 5 - 4 3 . FPU St ack Wi n d o w Reg i st er D at a Fo r m at s
D at a Fo r m at D escr i p t i o n Use
W F F Fl o at i n g p o i n t Fl o at i n g p o i n t o n l y
W F B By t e p acked
M M X o n l y
W F W Wo r d p acked
W F D D w o r d p acked
9 5
BETA REVI EW
Ch ap t er 6
Using Soft ICE
D e b ug g in g M ult ip le Pr o g r am s at O n ce
Tr ap p in g Fault s
Ab out Ad d r ess Con t ext s
U sin g I N T 0 x4 1 . D O T Com m an d s
U n d er st an d in g Tr an sit ion s Fr o m Rin g 3 t o Rin g 0
Debugging Mult iple Programs at Once
Symbol Loader let s you load several symbol t ables at t h e same t ime.
Th us, you can debug complex set s of syst em soft ware t h at may con t ain
several differen t compon en t s, in cludin g applicat ion s, DLLS, an d drivers.
Use t h e TABLE comman d t o view a list of all t h e symbol t ables curren t ly
loaded an d t o select a differen t symbol t able. Wh en you reach a break-
poin t in a program t h at h as a correspon din g symbol t able, en t er t h e
TABLE comman d followed by t h e first few ch aract ers of t h e symbol t able
n ame t o ch an ge t h e curren t symbol t able t o t h e on e t h at mat ch es your
program.
If you are n ot sure wh ich t able is t h e curren t t able, en t er t h e TABLE
comman d wit h n o paramet ers t o list all t h e loaded t ables. Th e curren t
t able is h igh ligh t ed.
You can also swit ch t ables t o a symbol t able t h at does n ot mat ch t h e code
you are curren t ly execut in g. Th is is useful for set t in g a breakpoin t in a
program ot h er t h an t h e on e you are curren t ly execut in g.
Trapping Fault s
Soft ICE provides fault t rappin g support for t h e followin g t ypes of code:
Rin g 3 (32-bit ) prot ect ed mode (Win 32 programs)
Rin g 0 driver code (kern el mode device drivers)
BETA REVI EW
Rin g 3 (16-bit ) prot ect ed mode (16-bit Win dows programs)
Soft ICE does n ot provide fault t rappin g for DOS boxes. Th is in cludes
bot h st raigh t V86 programs an d DOS ext en der applicat ion s.
Th e followin g sect ion s describe fault t rappin g support .
Ri ng 3 (3 2 - bi t ) Pr ot ect ed M ode (W i n3 2 Pr ogr a ms)
Soft ICE t raps all un h an dled except ion s t h at n ormally cause an error
dialog box. Soft ICE aut omat ically rest art s t h e in st ruct ion t h at caused t h e
fault , pops up t h e Soft ICE win dow, an d displays t h e in st ruct ion an d a
message similar t o t h e followin g:
Break due to Unhandled Exception
NTSTATUS=STATUS_ACCESS_VIOLATION
Th e NTSTATUS field con t ain s t h e appropriat e error message correspon d-
in g t o t h e st at us code. (Refer t o t h e in clude file NTSTATUS.H in t h e
Win dows NT/ 2000/ XP DDK for a complet e list of st at us codes.)
If execut ion con t in ues aft er Soft ICE t raps t h e fault , Soft ICE ign ores t h e
fault an d let s t h e syst em do it s n ormal except ion processin g. For
example, it could presen t an applicat ion failure dialog box.
Ri ng 0 Dr i ver Cod e (Ker nel M ode Devi ce Dr i ver s)
Soft ICE h an dles all rin g 0 except ion s t h at result in a call t o
KeBugCh eckEX. KeBugCh eckEX is t h e rout in e t h at displays t h e blue
screen in Win dows NT/ 2000/ XP.
If t h e KeBugCh eckEX bug code is t h e result of a page fault , GP fault , st ack
fault , or in valid opcode, Soft ICE at t empt s t o rest art t h e fault in g in st ruc-
t ion . Con t rol st ops on t h e act ual fault in g in st ruct ion wit h all t h e regis-
t ers in t h eir origin al st at e. If t h e code con t in ues t o fault on t h e same
in st ruct ion , eit h er reboot or at t empt t o skip t h e fault by alt erin g t h e EIP
or fixin g t h e fault con dit ion .
If t h e KeBugCh eckEx bug code is n ot t h e result of a page fault , GP fault ,
st ack fault , or in valid opcode, t h e in st ruct ion can n ot be rest art ed.
Soft ICE pops up an d displays t h e first in st ruct ion in KeBugCh eckEX an d
a message similar t o t h e followin g:
Break Due to KeBugCheckEx (Unhandled kernel mode exception)
Error=1E (KMODE_EXCEPTION_NOT_HANDLED) P1=8000003 P2=804042B1
P3=0 P4=FFFFFFFF
Th e error field is t h e h exadecimal bug code followed by a descript ion of
t h e error. Bug code defin it ion s are con t ain ed in t h e Win dows NT/ 2000/
XP DDK in t h e in clude file bugcodes.h .
Ch ap t er 6 Usi n g So f t ICE 9 7
BETA REVI EW
Th e P1 t h rough P4 fields are t h e paramet ers passed t o t h e KeBugCh eckEX
rout in e. Th ese fields do n ot h ave a st an dard defin ed mean in g.
If you at t empt t o con t in ue from t h is poin t , Win dows NT/ 2000/ XP
displays a blue screen an d t h en h an gs. If you wan t t o gain con t rol aft er
t h e blue screen , t urn on I3HERE (SET I3HERE ON); Win dows NT/ 2000/
XP execut es an INT 3 in st ruct ion aft er it displays t h e blue screen .
Ri ng 3 (1 6 - bi t ) Pr ot ect ed M ode (1 6 - bi t W i ndow s Pr ogr a ms)
Soft ICE h an dles 16-bit fault t rappin g somewh at differen t ly t h an 32-bit
fault t rappin g. Wh en a 16-bit fault occurs, Win dows NT/ 2000/ XP even t u-
ally displays a dialog box t h at describes t h e fault an d gives you t h e ch oice
of CANCEL or CLOSE.
If you click CANCEL, t h e fault in g in st ruct ion is rest art ed an d Win dows
NT/ 2000/ XP issues a debugger n ot ificat ion for t rappin g t h e fault in g
in st ruct ion . Soft ICE uses t h is debugger h ook t o pop up an d display t h e
fault in g in st ruct ion . In ot h er words, Soft ICE pops up aft er you receive t h e
crash dialog box an d select CANCEL, n ot before.
If you click CLOSE, Win dows NT/ 2000/ XP does n ot rest art t h e in st ruc-
t ion an d Soft ICE does n ot pop up. Th us, if you wan t t o debug t h e fault ,
make sure you click CANCEL.
Some fault s in Win dows NT/ 2000/ XP display more t h an on e dialog box.
If t h is h appen s, t h e first dialog box provides a ch oice of CLOSE or
IGNORE. Ch oose IGNORE t o in st ruct Win dows NT/ 2000/ XP t o skip t h e
fault in g in st ruct ion an d t o con t in ue t o execut e t h e program. Ch oose
CLOSE t o in st ruct Win dows NT/ 2000/ XP t o display t h e secon d dialog
box, as previously described.
About Address Cont ext s
Win dows 9x an d Win dows NT/ 2000/ XP give each process it own address
space from 0 GB t o 2GB. Addit ion ally, Win dows 95, Win dows 98, an d
Win dows ME reserve t h e first 4 MB for each virt ual mach in e (wh ere DOS
an d it s drivers reside). Memory from 2GB t o 4GB is sh ared bet ween all
processes.
Th e process-specific virt ual address space is kn own as t h e _address
con t ext _ (or _process_). Soft ICE displays t h e n ame of t h e curren t process
on t h e far righ t side of t h e st at us bar at t h e bot t om of t h e screen . Be
aware t h at t h e curren t con t ext is n ot always your applicat ion s con t ext ,
part icularly if you h ot key in t o Soft ICE. If you are n ot in t h e con t ext of
BETA REVI EW
your applicat ion , use t h e ADDR comman d t o swit ch t o your applicat ion
before examin in g or modifyin g your applicat ion s dat a or set t in g break-
poin t s in your applicat ion s code.
Soft ICE aut omat ically swit ch es address con t ext s for your con ven ien ce
un der t h e followin g circumst an ces:
If you use t h e TABLE comman d t o swit ch t o a 32-bit t able, Soft ICE
aut omat ically set s t h e curren t address con t ext t o t h e address con t ext
for t h at module.
If you use t h e FILE comman d t o display a source file from a 32-bit
t able, Soft ICE set s t h e curren t address con t ext t o t h e address con t ext
for t h at module.
If you use a symbol n ame in an expression , Soft ICE ch an ges t h e
address con t ext t o t h e appropriat e con t ext . Th is in cludes export
symbols loaded t h rough Symbol Loader.
Wh en you ch an ge address con t ext s, con fusion migh t arise if you are
viewin g code or dat a locat ed in t h e applicat ions privat e address space (a
lin ear address bet ween 0x400000 t o 0x7FFFFFFF for Win dows 9x, an d 0
t o 0x7FFFFFFF for Win dows NT/ 2000/ XP). Th is occurs because t h e dat a
or code t h at is displayed ch an ges even t h ough t h e select or:offset address
do n ot . Th is is n ormal. Th e lin ear addresses remain t h e same, but t h e
un derlyin g syst em page t ables n ow reflect t h e ph ysical memory for t h e
specified address con t ext .
Soft ICE does n ot allow you t o specify an address con t ext as part of an
expression . If you are usin g bare addresses in an expression , be sure t h at
t h e curren t address con t ext is set appropriat ely. For example, D
137:401000 displays memory at 401000 in t h e curren t address con t ext .
Caut ion : Bef o r e you use b ar e ad d r e sses t o se t b r e akp o in t s, b e sur e yo u
ar e in t h e cor r ect ad d r ess con t e xt . Sof t I CE use s t h e cur r e n t co n t e xt t o
t r an slat e ad d r esse s.
Using INT 0x41 .DOT Commands
Un der Win dows 9x, Microsoft provides a set of ext en sion s t h at allow a
VxD or 32-bit DLL t o commun icat e wit h a kern el-level debugger. (See t h e
DEBUGSYS.INC file dist ribut ed wit h t h e Win dows 9x DDK.) Th e .DOT
API allows a VxD t o provide VxD-specific debug in format ion or
comman d ext en sion s in t eract ively t h rough t h e st an dard user in t erface of
t h e kern el-level debugger. Alt h ough t h e API was origin ally design ed for
Ch ap t er 6 Usi n g So f t ICE 9 9
BETA REVI EW
Microsoft s WDEB386, Soft ICE support s a rich subset of t h e .DOT API.
Th us, you can use Soft ICE t o access VMM an d VxD .DOT comman ds, as
well as an y .DOT comman ds you migh t implemen t for your own VxD.
Caut ion : Th e d eb ug f un ct i on alit y f o r all . D O T e xt e n sio n s is b ui lt in t o
V M M or an ot h er VxD . I t i s n o t p ar t of Sof t I CE. Th us, Sof t I CE can n ot
g uar an t e e t h at t h e se e xt en si on s w o r k co r r e ct l y. Also, . D O T ext e n sion s
m i g h t n ot p er f o r m e r r or ch eckin g , w h ich can l ead t o a syst e m cr ash if
in vali d in p ut is en t e r e d . Fin ally, Sof t I CE can n ot d e t e r m in e w h e t h er or
n o t a . D O T e xt en si on r eq uir e s t h e syst e m t o b e in a sp e ci f i c st at e . Th us,
usin g t h e . D O T e xt en si on at an in ap p r op r iat e t im e m i g h t r esul t in a sys-
t e m cr ash .
Soft ICE support s t h e followin g .DOT comman ds in Win dows 9x:
Regist ered .DOT ext en sion s
To get a list of regist ered dot comman ds, use t h e followin g comman d:
.?
Debug_Query .DOT ext en sion s
To in voke t h ese .DOT h an dlers, t ype t h e VxD n ame aft er t h e dot .
Most of t h ese comman ds, if implemen t ed, display men us. For
example, t h e followin g VxDs h ave .DOT h an dlers in bot h t h e ret ail
an d debug version s of Win dows 9x:
.VMM
.VPICD
.VXDLDR
To det ermin e if a VxD h as a .DOT h an dler, t ry it . Th e .DOT h an dlers
in t h e debug version of t h e DDK somet imes provide more fun ct ion al-
it y t h an t h e .DOT h an dlers in t h e ret ail version .
VMM-embedded .DOT ext en sion s
VMM provides a variet y of .DOT ext en sion s t h at are available in bot h
t h e debug an d ret ail version s. To get a list of .DOT ext en sion s
support ed by VMM, use t h e followin g comman d:
..?
In t h e Win dows 9x ret ail build, t h e ..? comman d yields t h e .DOT
ext en sion s sh own in t h e followin g t able.
BETA REVI EW
1 0 0 Usi n g Sof t I CE
Underst anding Transit ions From Ring 3 t o Ring 0
Man y t imes wh en t racin g in t o code usin g Win dows 9x, you arrive at
eit h er an INT 0x30 or an ARPL. Bot h are met h ods for makin g a t ran sit ion
from Rin g-3 t o Rin g-0. Wh en you wish t o follow t h e rin g t ran sit ion , you
can save yourself t h e t ime an d effort of st eppin g t h rough a large amoun t
of VMM code by usin g t h e G(o) comman d t o execut e up t o t h e address
sh own in t h e disassembly.
Win dows 9x uses t h e followin g met h ods t o t ran sit ion Rin g-3 code t o
Rin g-0 code:
For V86 code, Win dows 9x uses t h e ARPL in st ruct ion , wh ich causes
an in valid opcode fault . Th e in valid opcode h an dler t h en passes con -
t rol t o t h e appropriat e VxD. Th e ARPL in st ruct ion is usually in ROM.
Win dows 9x uses on ly on e ARPL an d it varies t h e V86 segmen t :offset
t o in dicat e differen t VxD addresses. For example, if t h e ARPL is at
FFFF:0, Win dows 9x uses t h e addresses FFFF:0, FFFE:10, FFFD:20,
FFFC:30 an d so on .
Tab l e 6 - 1 . Wi n 9 x . D O T Ex t en si o n s
. D O T Ex t en si o n D escr i p t i o n
. R[ # ] D i sp l ay s t h e r eg i st er s o f t h e cu r r en t t h r ead .
. VM [ # ] D i sp l ay s t h e co m p l et e VM st at u s.
. VC[ # ] D i sp l ay s t h e cu r r en t VM s co n t r o l b l o ck.
. VH[ # ] D i sp l ay s a VM M l i n ked l i st , g i v en l i st h an d l e.
. VR[ # ] D i sp l ay s t h e r eg i st er s o f t h e cu r r en t VM .
. VS[ # ] D i sp l ay s t h e cu r r en t VM s v i r t u al m o d e st ack.
. VL D i sp l ay s a l i st o f al l VM h an d l es.
. D S D u m p s p r o t ect ed m o d e st ack w i t h l ab el s.
. VM M M en u VM M st at e i n f o r m at i o n .
. < d ev- n am e> D i sp l ay d evi ce- sp eci f i c i n f o r m at i o n .
Ch ap t er 6 Usi n g So f t ICE 1 0 1
BETA REVI EW
Th e followin g example sh ows sample out put for disassemblin g an
ARPL:
For PM code, Win dows 9x uses in t errupt 0x30h . Segmen t 0x3B con -
t ain s n ot h in g but in t errupt 0x30 in st ruct ion s, each of wh ich t ran sfers
con t rol t o a VxD.
Th e followin g example sh ows sample out put for disassemblin g
segmen t :offset 3B:31A:
FD D 2 : 2 2 0 D ARPL D I, BP ; # 0 0 2 8 : C0 0 7 8 CC9 IFSM g r ( 0 1 ) + 0 5 1 1
003B:031A INT30 ; #0028:C008D4F4 VPICD(01)+0A98
003B:031C INT30 ; #0028:C007F120 IOS(01)+0648
003B:031E INT30 ; #0028:C02C37FC VMOUSE(03))00F0
003B:0320 INT30 ; #0028:C02C37FC VMOUSE(03))00F0
003B:0322 INT30 ; #0028:C023B022 BIOSXLAT(05)=0022
003B:0324 INT30 ; #0028:C230F98 BIOSXLAT(04)=0008
003B:0326 INT30 ; #0028:C023127C BIOSXLAT(04)=02EC
BETA REVI EW
1 0 3
BETA REVI EW
Ch ap t er 7
Using Breakpoint s
I n t r o d uct ion
Typ e s o f Br e akp o in t s Sup p or t e d b y So f t I CE
Vir t ual Br eakp o in t s
Se t t in g a Br eakp oin t Act ion
Con d it io n al Br eakp o in t s
Elap sed Tim e
Br eakp o in t St at ist ics
Re f er r in g t o Br e akp oin t s in Exp r e ssio n s
M an ip ulat in g Br eakp oin t s
U sin g Em b ed d ed Br eakp oin t s
Int roduct ion
You can use Soft ICE t o set breakpoin t s on program execut ion , memory
locat ion reads an d writ es, in t errupt s, an d reads an d writ es t o I/ O port s.
Soft ICE assign s a breakpoin t in dex, from 0 t o FF, t o each breakpoin t . You
can use t h is breakpoin t in dex t o iden t ify breakpoin t s wh en you set ,
delet e, disable, en able, or edit t h em.
All Soft ICE breakpoin t s are st icky, wh ich mean s t h at Soft ICE t racks an d
main t ain s a breakpoin t un t il you in t en t ion ally clear or disable it usin g
t h e BC or t h e BD comman d. Aft er you clear breakpoin t s, you can recall
t h em wit h t h e BH comman d, wh ich displays a breakpoin t h ist ory.
You can set up t o 32 breakpoin t s at on e t ime in Soft ICE. However, t h e
n umber of breakpoin t s you can set on memory locat ion (BPMs) an d I/ O
port s (BPIOs) is a t ot al of four, due t o rest rict ion s of t h e x86 processors.
Wh ere symbol in format ion is available, you can set breakpoin t s usin g
fun ct ion n ames. Wh en in source or mixed mode, you can set poin t -an d-
BETA REVI EW
sh oot st yle breakpoin t s on an y source code lin e. A valuable feat ure is t h at
you can set poin t -an d-sh oot breakpoin t s in a module before it is loaded.
Types of Breakpoint s Support ed by Soft ICE
Soft ICE provides a powerful array of breakpoin t capabilit ies t h at t ake full
advan t age of t h e x86 arch it ect ure, as follows:
Execution Breakpoints: Soft ICE replaces an exist in g in st ruct ion
wit h INT 3. You can use t h e BPX comman d t o set execut ion break-
poin t s.
Memory Breakpoints: Soft ICE uses t h e x86 debug regist ers t o break
wh en a cert ain
byt e/ word/ dword of memory is read, writ t en , or execut ed. You can
use t h e BPM comman d t o set memory breakpoin t s.
Interrupt Breakpoints: Soft ICE in t ercept s in t errupt s by modifyin g
t h e IDT (In t errupt Descript or Table) vect ors. You can use t h e BPINT
comman d t o set in t errupt breakpoin t s.
I/ O Breakpoints: Soft ICE uses a debug regist er ext en sion available on
Pen t ium an d Pen t ium-Pro CPUs t o wat ch for an IN or OUT in st ruc-
t ion goin g t o a part icular port address. You can use t h e BPIO com-
man d t o set I/ O breakpoin t s.
Window Message Breakpoints: Soft ICE t raps wh en a part icular mes-
sage or ran ge of messages arrives at a win dow. Th is is n ot a fun da-
men t al breakpoin t t ype; it is just a con ven ien t feat ure built on t op of
t h e ot h er breakpoin t primit ives. You can use t h e BMSG comman d t o
set win dow message breakpoin t s.
Br ea k poi nt Op t i ons
Soft ICE can accept comman d modifiers t o limit t h e scope of a breakpoin t
for all breakpoin t comman ds, in cludin g bpx, bpm, bpio, an d bpin t .
Depen din g on t h e OS, t h e modifiers differ.
Win dows 9x allows modifiers of .t, .p, .a, an d .v
Win dows NT/ 2000/ XP allow modifiers of .t an d .p
If t h e curren t ly execut in g process ID (PID) is 0x200 an d you issue a bpint.p
2e wit h in Soft ICE, fut ure int 2e breakpoin t s will get h it on ly if t h e execut -
in g process is 0x200. By con t rast , issuin g a comman d of bpint 2e will cause
every sin gle int 2e t o pop-up Soft ICE.
Ch ap t er 7 Usi n g Br eakp o i n t s 1 0 5
BETA REVI EW
You can qualify each t ype of breakpoin t wit h t h e followin g t wo opt ion s:
A con dit ion al expression [IF expression]: Th e expression must eval-
uat e t o n on -zero (TRUE) for t h e breakpoin t t o t rigger. Refer t o Condi-
tional Breakpoints on page 112.
A breakpoin t act ion [DO command1;command2;]: A series of Soft ICE
comman ds can aut omat ically execut e wh en t h e breakpoin t t riggers.
You can use t h is feat ure in con cert wit h user-defin ed macros t o aut o-
mat e t asks t h at would ot h erwise be t edious. Refer t o Setting a Break-
point Action on page 112.
N o t e : Fo r co m p l et e i n f o r m at i o n o n each b r eakp o i n t co m m an d , r ef er t o t h e
SoftICE Command Reference.
Execut i on Br ea kpoi nt s
An execut ion breakpoin t t raps execut in g code such as a fun ct ion call or
lan guage st at emen t . Th is is t h e most frequen t ly used t ype of breakpoin t .
By replacin g an exist in g in st ruct ion wit h an INT 3 in st ruct ion , Soft ICE
t akes con t rol wh en execut ion reach es t h e INT 3 breakpoin t .
Soft ICE provides t wo ways for set t in g execut ion breakpoin t s: usin g a
mouse an d usin g t h e BPX comman d. Th e followin g sect ion s describe
h ow t o use t h ese met h ods for set t in g breakpoin t s.
U sin g a M ouse t o Se t Br e akp oin t s
If you are usin g a Pen t ium processor an d a mouse, you can use t h e mouse
t o set or clear poin t -an d-sh oot (st icky) an d on e-sh ot breakpoin t s. To set a
st icky breakpoin t , double-click t h e lin e on wh ich you wan t t o set t h e
Tab l e 7 - 1 . So f t ICE Co m m an d M o d i f i er s
Co m m an d M o d i f i er D escr i p t i o n
. t Co n d i t i o n al l y set t h e b r eakp o i n t t o t r i g g er i n t h e
act i ve t h r ead .
. p Co n d i t i o n al l y set t h e b r eakp o i n t t o t r i g g er i n t h e act i v e
Pr o cess ID .
. a Co n d i t i o n al l y set t h e b r eakp o i n t t o t r i g g er i n t h e act i v e
ad d r ess co n t ex t .
. v Co n d i t i o n al l y set t h e b r eakp o i n t t o t r i g g er i n t h e act i v e
VM M ID .
BETA REVI EW
breakpoin t . Soft ICE h igh ligh t s t h e lin e t o in dicat e t h at you set a break-
poin t . Double-click t h e lin e again t o clear t h e breakpoin t . To set a on e-
sh ot breakpoin t , click t h e lin e on wh ich you wan t t o set t h e breakpoin t
an d use t h e HERE comman d (F7) t o execut e t o t h at lin e.
U sin g t h e BPX Co m m an d t o Se t Br e akp oin t s
Use t h e BPX comman d wit h an y of t h e followin g paramet ers t o set an
execut ion breakpoin t :
BPX [address] [IF expression] [DO command1;command2;]
To set a breakpoin t on your applicat ion s Win Main fun ct ion , use t h is
comman d:
BPX WinMain
Use t h e BPX comman d wit h out specifyin g an y paramet er t o set a poin t -
an d-sh oot execut ion breakpoin t in t h e source code. Use Alt -C t o move
t h e cursor in t o t h e Code win dow. Th en use t h e arrow keys t o posit ion
t h e cursor on t h e lin e on wh ich you wan t t o set t h e breakpoin t . Fin ally,
use t h e BPX comman d (F9). If you prefer t o use your mouse t o set t h e
breakpoin t , click t h e scroll arrows t o scroll t h e Code win dow, t h en
double-click t h e lin e on wh ich you wan t t o set t h e breakpoin t .
M emor y Br ea kpoi nt s
A memory breakpoin t uses t h e debug regist ers foun d on t h e 386 CPUs
an d lat er models t o mon it or access t o a cert ain memory locat ion . Th is
t ype of breakpoin t is ext remely useful for fin din g out wh en an d wh ere a
program variable is modified, an d for set t in g an execut ion breakpoin t in
read-on ly memory. You can on ly set four memory breakpoin t s at on e
t ime, because t h e CPU con t ain s on ly four debug regist ers.
Use t h e BPM comman d t o set memory breakpoin t s:
BPM[B|W|D] address [R|W|RW|X] [debug register] [IF expression]
[DO command1;command2;]
I F exp r essi o n Ref er t o Conditional Breakpoints on page 112.
D O co m m a n d 1 ; co m m a n d 2 ; Ref er t o Setting a Breakpoint Action on page 112.
BPM a n d BPM B Set a b y t e- si ze b r eakp o i n t .
BPM W Set s a w o r d ( 2 - b y t e) si ze b r eakp o i n t .
BPM D Set s a d w o r d ( 4 - b y t e) si ze b r eakp o i n t .
R, W, a n d RW Br eak o n r ead s, w r i t es, o r b o t h .
BETA REVI EW
Th e followin g example set s a memory breakpoin t t o t rigger wh en a value
of 5 is writ t en t o t h e Dword (4-byt e) variable MyGlobalVariable.
BPMD MyGlobalVariable W IF MyGlobalVariable==5
If t h e t arget locat ion of a BPM breakpoin t is frequen t ly accessed, perfor-
man ce can be degraded regardless of wh et h er t h e con dit ion al expression
evaluat es t o FALSE.
I nt er r upt Br ea kp oi nt s
Use an in t errupt breakpoin t t o t rap an in t errupt t h rough t h e IDT. Th e
breakpoin t on ly t riggers wh en a specified in t errupt is dispat ch ed t h rough
t h e IDT.
Use t h e BPINT comman d t o set in t errupt breakpoin t s:
BPINT interrupt-number [IF expression] [DO
command1;command2;]
If an in t errupt is caused by a soft ware INT in st ruct ion , t h e in st ruct ion
displayed will be t h e INT in st ruct ion . (Soft ICE pops up wh en execut ion
reach es t h e INT in st ruct ion respon sible for t h e breakpoin t , but before t h e
in st ruct ion act ually execut es.) Ot h erwise, t h e curren t in st ruct ion will be
t h e first in st ruct ion of an in t errupt h an dler. You can list all in t errupt s an d
t h eir h an dlers by usin g t h e IDT comman d.
Use t h e followin g comman d t o set a breakpoin t t o t rigger wh en a call t o
t h e kern el-mode rout in e Nt Creat eProcess is made from user mode:
BPINT 2E IF EAX==1E
X Br eaks o n ex ecu t i o n ; t h i s i s m o r e p o w er f u l t h an a
BPX- st y l e b r eakp o i n t b ecau se m em o r y d o es n o t
n eed t o b e m o d i f i ed , en ab l i n g su ch o p t i o n s as
set t i n g b r eakp o i n t s i n RO M o r set t i n g b r eakp o i n t s o n
ad d r esses t h at ar e n o t p r esen t .
d eb u g r eg i st er Sp eci f i es w h i ch d eb u g r eg i st er t o u se. So f t ICE
n o r m al l y m an ag es t h e d eb u g r eg i st er f o r y o u , u n l ess
y o u n eed t o sp eci f y i t i n an u n u su al si t u at i o n .
I F exp r essi on Ref er t o Conditional Breakpoints on page 112.
D O
com m a n d 1 ; co m m a n d 2 ;
Ref er t o Setting a Breakpoint Action on page 112.
i n t er r u p t - n u m b er N u m b er r an g i n g f r o m 0 t o 2 5 5 ( 0 t o FF h ex ) .
D O co m m a n d 1 ; com m a n d 2 ; Ref er t o Setting a Breakpoint Action on page 112.
BETA REVI EW
N o t e : Th e N t Cr eat ePr o cess i s n o r m al l y cal l ed f r o m Z w Cr eat ePr o cess i n t h e
N TD LL. D LL, w h i ch i s i n t u r n cal l ed f r o m Cr eat ePr o cessW i n t h e
KERN EL3 2 . D LL. In t h e co n d i t i o n al ex p r essi o n , 1 E i s t h e ser vi ce
n u m b er f o r N t Cr eat ePr o cess. Use t h e N TCALL co m m an d t o f i n d t h i s
v al u e.
You can use t h e BPINT comman d t o t rap soft ware in t errupt s, for example
INT 21, made by 16-bit Win dows programs. Not e t h at soft ware in t errupt s
issued from V86 mode do n ot pass t h rough t h e IDT vect or t h at t h ey
specify. INT in st ruct ion s execut ed in V86 gen erat e processor gen eral
prot ect ion fault s (GPF), wh ich are h an dled by vect or 0xD in t h e IDT. Th e
Win dows GPF h an dler realizes t h e cause of t h e fault an d passes con t rol t o
a h an dler dedicat ed t o specific V86 in t errupt t ypes. Th e t ypes may en d
up reflect in g t h e in t errupt down t o V86 mode by callin g t h e in t errupt
h an dler en t ered in t h e V86 mode In t errupt Vect or Table (IVT). In some
cases, a real-mode in t errupt is reflect ed (simulat ed) by callin g t h e real-
mode in t errupt vect or.
In t h e case wh ere t h e in t errupt is reflect ed, you can t rap it by placin g a
BPX breakpoin t at t h e begin n in g of t h e real-mode in t errupt h an dler.
To set a breakpoin t on t h e real-mode INT 21 h an dler, use t h e followin g
comman d:
BPX *($0:(21*4))
I / O Br ea kpoi nt s
An I/ O breakpoin t mon it ors reads an d writ es t o a port address. Th e break-
poin t t raps wh en an IN or OUT in st ruct ion accesses t h e port . Soft ICE
implemen t s I/ O breakpoin t s by usin g t h e debug regist er ext en sion s in t ro-
duced wit h t h e Pen t ium. As a result , I/ O breakpoin t s require a Pen t ium or
Pen t ium-Pro CPU. A maximum of four I/ O breakpoin t s can be set at on e
t ime. Th e I/ O breakpoin t is effect ive in kern el-level (rin g 0) code as well
as user (rin g 3) code.
N o t e s:
Wi t h Wi n d o w s 9 x , So f t ICE r el i es o n t h e I/ O p er m i ssi o n b i t m ap , w h i ch
r est r i ct s I/ O t r ap p i n g t o r i n g 3 co d e.
Yo u can n o t u se I/ O b r eakp o i n t s t o t r ap IN / O UT i n st r u ct i o n s ex ecu t ed
b y M S- D O S p r o g r am s. Th e IN / O UT i n st r u ct i o n s ar e t r ap p ed an d
em u l at ed b y t h e o p er at i n g sy st em , an d t h er ef o r e d o n o t g en er at e
r eal p o r t I/ O , at l east n o t i n a 1 : 1 m ap p i n g .
BETA REVI EW
Use t h e BPIO comman d t o set I/ O breakpoin t s:
BPIO port-number [R|W|RW] [IF expression]
[DO command1;command2;]
Wh en an I/ O breakpoin t t riggers an d Soft ICE pops up, t h e curren t
in st ruct ion is t h e in st ruct ion followin g t h e IN or OUT t h at caused t h e
breakpoin t t o t rigger. Un like BPM breakpoin t s, t h ere is n o size specifica-
t ion ; an y access t o t h e port -n umber, wh et h er byt e, word, or dword,
t riggers t h e breakpoin t . An y I/ O t h at span s t h e I/ O breakpoin t will also
t rigger t h e breakpoin t . For example, if you set an I/ O breakpoin t on port
2FF, a word I/ O t o port 2FE would t rigger t h e breakpoin t .
Use t h e followin g comman d t o set a breakpoin t t o t rigger wh en a value is
read from port 3FEH wit h t h e upper 2 bit s set :
BPIO 3FE R IF (AL & C0)==C0
Th e con dit ion is evaluat ed aft er t h e in st ruct ion complet es. Th e value will
be in AL, AX, or EAX because all port I/ O, except for t h e st rin g I/ O
in st ruct ion s (wh ich are rarely used), use t h e EAX regist er.
W i ndow M essa ge Br ea kpoi nt s
Use a win dow message breakpoin t t o t rap a cert ain message or ran ge of
messages delivered t o a win dow procedure. Alt h ough you could imple-
men t an equivalen t breakpoin t yourself usin g BPX wit h a con dit ion al
expression , t h e followin g BMSG comman d is easier t o use:
R, W, a n d RW Br eak o n r ead s ( IN i n st r u ct i o n s) , w r i t es ( O UT
i n st r u ct i o n s) , o r b o t h , r esp ect i v el y.
BETA REVI EW
BMSG window-handle [L] [begin-message [end-message]]
[IF expression] [DO command1;command2;]
Wh en specifyin g a message or a message ran ge, you can use t h e symbolic
n ame, for example, WM_NCPAINT. Use t h e WMSG comman d t o get a list
of t h e win dow messages t h at Soft ICE un derst an ds. If n o message or
message ran ge is specified, an y message will t rigger t h e breakpoin t .
To set a win dow message breakpoin t for t h e win dow h an dle 1001E, use
t h e followin g comman d:
BMSG 1001E WM_NCPAINT
Soft ICE is smart en ough t o t ake in t o accoun t t h e address con t ext of t h e
process t h at own s t h e win dow, so it does n ot mat t er wh at address
con t ext you are in wh en you use BMSG.
You can con st ruct an equivalen t BPX-st yle breakpoin t usin g a con di-
t ion al expression . Use t h e HWND comman d t o get t h e address of t h e
win dow procedure, t h en use t h e followin g BPX comman d (Win 32 on ly):
BPX 5FEBDD12 IF (esp->8)==WM_NCPAINT
Caut ion : W h e n set t i n g a b r eakp oin t usi n g a r aw ad d r e ss ( n o t a sym b o l) ,
it is vit al t o b e in t h e cor r ect ad d r ess con t e xt .
w i n d o w - h a n d l e Val u e r et u r n ed w h en t h e w i n d o w w as cr eat ed ;
y o u can u se t h e HWN D co m m an d t o g et a l i st o f
w i n d o w s w i t h t h ei r h an d l es.
L Si g n i f i es t h at t h e w i n d o w m essag e sh o u l d b e
p r i n t ed t o t h e Co m m an d w i n d o w w i t h o u t
p o p p i n g i n t o So f t ICE.
b eg i n - m essa g e Si n g l e Wi n d o w s m essag e o r t h e l o w er m essag e
n u m b er i n a r an g e o f Wi n d o w s m essag es. I f y o u
d o n o t sp ec i f y a r an g e w i t h an en d - m essag e,
t h en o n l y t h e b eg i n - m essag e w i l l cau se a b r eak.
Fo r b o t h b eg i n - m essag e an d en d - m essag e, t h e
m essag e n u m b er s c an b e sp ec i f i ed ei t h er i n
h ex ad ec i m al o r b y u si n g t h e act u al ASCI I n am es
o f t h e m essag es, f o r ex am p l e, W M _Q UI T.
en d - m essa g e Hi g h er m essag e n u m b er i n a r an g e o f Wi n d o w s
m essag es.
BETA REVI EW
Underst anding Breakpoint Cont ext s
A breakpoin t con t ext con sist s of t h e address con t ext in wh ich t h e break-
poin t was set an d in wh at code module t h e breakpoin t is in , if an y. Break-
poin t con t ext s apply t o t h e BPX an d BPM comman ds, an d breakpoin t
t ypes based on t h ose comman ds such as BMSG.
For Win 32 applicat ion s, breakpoin t s set in t h e upper 2GB of address
space are global; t h ey break in an y con t ext . Breakpoin t s set in t h e lower
2GB are context-sensitive; t h ey t rigger accordin g t o t h e followin g crit eria
an d Soft ICE pops up:
Soft ICE on ly pops up if th e address con t ext match es th e con t ext in
wh ich t h e breakpoin t was set .
If t h e breakpoin t t riggers in t h e same code module in wh ich t h e
breakpoin t was set , t h en Soft ICE disregards t h e address con t ext an d
pops up. Th is mean s t h at a breakpoin t set in a sh ared module like
KERNEL32.DLL breaks in every address con t ext t h at h as t h e module
loaded, regardless of wh at address con t ext was select ed wh en t h e
breakpoin t was set .
Th e except ion is if an ot h er process mapped t h e module at a differen t
base address t h an t h e on e in wh ich t h e breakpoin t is set . In t h is case,
t h e breakpoin t does n ot t rigger. Avoid t h is sit uat ion by basin g your
DLLs at n on -con flict in g addresses.
Breakpoin t s set on MS-DOS an d 16-bit Win dows programs are con t ext -
sen sit ive in t h e sen se t h at t h e breakpoin t on ly affect s t h e NTVDM
process in wh ich t h e breakpoin t was set . Th e breakpoin t n ever crosses
NTVDMs, even if t h e same program is run mult iple t imes.
Breakpoin t con t ext s are more import an t for BPM-t ype breakpoin t s t h an
for BPX. BPM set s an x86 h ardware breakpoin t t h at t riggers on a cert ain
virt ual address. Because t h e CPU breakpoin t h ardware kn ows n ot h in g of
address spaces, it could pot en t ially t rigger on an un relat ed piece of code
or dat a. Breakpoin t con t ext s give Soft ICE t h e abilit y t o discrimin at e
bet ween false t raps an d real on es.
Virt ual Breakpoint s
In Soft ICE, you can set breakpoin t s in Win dows modules before t h ey
load, an d it is n ot n ecessary for a page t o be presen t in ph ysical memory
for a BPX (INT 3) breakpoin t t o be set . In such cases, t h e breakpoin t is
virtual; it will be aut omat ically armed wh en t h e module loads or t h e page
BETA REVI EW
becomes presen t . Virt ual breakpoin t s can on ly be set on eit h er symbols
or source lin es.
Set t ing a Breakpoint Act ion
You can set a breakpoin t t o execut e a series of Soft ICE comman ds, in clud-
in g user-defin ed macros, aft er t h e breakpoin t is t riggered. You defin e
t h ese breakpoin t act ion s wit h t h e DO opt ion , wh ich is available wit h
every breakpoin t t ype:
DO command1;command2;
Th e body of a breakpoin t act ion defin it ion is a sequen ce of Soft ICE
comman ds, or ot h er macros, separat ed by semicolon s. You n eed n ot
t ermin at e t h e fin al comman d wit h a semicolon .
Breakpoin t act ion s are closely relat ed t o macros. Refer t o Working with
Persistent Macros on page 173 for more in format ion about macros. Break-
poin t act ion s are essen t ially un n amed macros t h at do n ot accept
comman d-lin e argumen t s. Breakpoin t act ion s, like macros, can call upon
macros. In fact , a prime use of macros is t o simplify t h e creat ion of
complex breakpoin t act ion s.
If you n eed t o embed a lit eral quot e ch aract er (") or a percen t sign (%)
wit h in t h e macro (breakpoin t ) body, precede t h e ch aract er wit h a
backslash ch aract er (\ ). To specify a lit eral backslash ch aract er, use t wo
con secut ive backslash es (\ \ ).
If a breakpoin t is bein g logged (refer t o t h e built -in fun ct ion BPLOG on
page 116), t h e act ion will n ot be execut ed.
Th e followin g examples illust rat e t h e basic use of breakpoin t act ion s:
BPX EIP DO dd eax
BPX EIP DO data 1;dd eax
BPMB dataaddr if (byte(*dataaddr)==1) do ? IRQL
Condit ional Breakpoint s
Con dit ion al breakpoin t s provide a fast an d easy way t o isolat e a specific
con dit ion or st at e wit h in t h e syst em or applicat ion you are debuggin g.
By set t in g a breakpoin t on an in st ruct ion or memory address an d supply-
in g a con dit ion al expression , Soft ICE will on ly t rigger if t h e breakpoin t
evaluat es t o n on -zero (TRUE). Because t h e Soft ICE expression evaluat or
BETA REVI EW
h an dles complex expression s easily, con dit ion al expression s t ake you
righ t t o t h e problem or sit uat ion you wan t t o debug wit h ease.
All Soft ICE breakpoin t comman ds (BPX, BPM, BPIO, BMSG, an d BPINT)
accept con dit ion al expression s usin g t h e followin g syn t ax:
breakpoint-command [breakpoint options] [IF conditional
expression]
[DO commands]
Th e IF keyword, wh en presen t , is followed by an y expression t h at you
wan t t o be evaluat ed wh en t h e breakpoin t is t riggered. Th e breakpoin t
will be ign ored if t h e con dit ion al expression is FALSE (zero). Wh en t h e
con dit ion al expression is TRUE (n on -zero), Soft ICE pop ups an d displays
t h e reason for t h e break, wh ich in cludes t h e con dit ion al expression .
Th e followin g examples sh ow con dit ion al expression s used durin g t h e
developmen t of Soft ICE.
N o t e : M o st o f t h ese ex am p l es co n t ai n sy st em - sp eci f i c v al u es t h at var y
d ep en d i n g o n t h e ex act v er si o n o f Wi n d o w s N T/ 2 0 0 0 / XP y o u ar e
r u n n i n g .
Wat ch a t h read bein g act ivat ed:
bpx ntoskrnl!SwapContext IF (edi==0xFF8B4020)
Wat ch a t h read bein g deact ivat ed:
bpx ntoskrnl!SwapContext IF (esi==0xFF8B4020)
Wat ch CSRSS HWND object s (t ype 1) bein g creat ed:
bpx winsrv!HMAllocObject IF (esp->c == 1)
Wat ch CSRSS t h read in fo object s (t ype 6) bein g dest royed:
bpx winsrv!HMFreeObject+0x25 IF (byte(esi->8) == 6)
Wat ch process object -h an dle-t ables bein g creat ed:
bpx ntoskrnl!ExAllocatePoolWithTag IF (esp->c == Obtb)
Wat ch a t h read st at e become t ermin at ed (en um == 4):
bpmb _thread->29 IF byte(_thread->29) == 4)
Wat ch a h eap block (230CD8) get freed:
bpx ntddl!RtlFreeHeap IF (esp->c == 230CD8)
Wat ch a specific process make a syst em call:
bpint 2E if (process == _process)
Man y of t h e previous examples use t h e thread an d process in t rin sic
fun ct ion s provided by Soft ICE. Th ese fun ct ion s refer t o t h e act ive t h read
or process in t h e operat in g syst em. In some cases, t h e examples precede
t h e fun ct ion n ame wit h an un derscore _. Th is is a special feat ure t h at
BETA REVI EW
makes it easier t o refer t o a dyn amic value such as a regist ers con t en t s or
t h e curren t ly run n in g t h read or process as a con st an t . Th e followin g
examples sh ould h elp t o clarify t h is con cept :
Th is example set s a con dit ion al breakpoin t t h at will be t riggered if
t h e dyn amic (run -t ime) value of t h e EAX regist er equals it s curren t
value.
bpx eip IF (eax == _eax)
Th is is equivalen t t o:
? EAX
00010022
bpx eip IF (eax == 10022)
Th is example set s a con dit ion al breakpoin t t h at will be t riggered if
t h e value of an execut in g t h reads t h read-id mat ch es t h e t h read-id of
t h e curren t ly execut in g t h read.
bpx eip IF (tid == _tid)
This is equivalent to:
? tid
8
bpx eip IF (tid == 8)
Wh en you precede a fun ct ion n ame or regist er wit h an un derscore in an
expression , t h e fun ct ion is evaluat ed immediat ely an d remain s con st an t
t h rough out t h e use of t h at expression .
Condi t i ona l Br ea k poi nt Count Funct i ons
Soft ICE support s t h e abilit y t o mon it or an d con t rol breakpoin t s based on
t h e n umber of t imes a part icular breakpoin t h as or h as n ot been
t riggered. You can use t h e followin g coun t fun ct ion s in con dit ion al
expression s:
BPCOUNT
BPMISS
BPTOTAL
BPLOG
BPINDEX
BPCO U N T
Th e value for t h e BPCOUNT fun ct ion is t h e curren t n umber of t imes t h at
t h e breakpoin t h as been evaluat ed as TRUE.
BETA REVI EW
Use t h is fun ct ion t o con t rol t h e poin t at wh ich a t riggered breakpoin t
causes a popup t o occur. Each t ime t h e breakpoin t is t riggered, t h e con di-
t ion al expression associat ed wit h t h e breakpoin t is evaluat ed. If t h e
con dit ion evaluat es t o TRUE, t h e breakpoin t in st an ce coun t (BPCOUNT)
in cremen t s by on e. If t h e con dit ion al evaluat es t o FALSE, t h e breakpoin t
miss in st an ce coun t (BPMISS) in cremen t s by on e.
Th e fift h t ime t h e breakpoin t t riggers, t h e BPCOUNT equals 5, so t h e
con dit ion al expression evaluat es t o TRUE an d Soft ICE pops up.
bpx myaddr IF (bpcount==5)
Use BPCOUNT on ly on t h e righ t h an d side of compoun d con dit ion al
expression s for BPCOUNT t o in cremen t correct ly:
bpx myaddr if (eax==1) && (bpcount==5)
Due t o t h e early-out algorit h m employed by t h e expression evaluat or, t h e
BPCOUNT==5 expression will n ot be evaluat ed un less EAX==1. (Th e C
lan guage works t h e same way.) Th erefore, by t h e t ime BPCOUNT==5 get s
evaluat ed, t h e expression is TRUE. BPCOUNT will be in cremen t ed an d if
it equals 5, t h e full expression evaluat es t o TRUE an d Soft ICE pops up. If
BPCOUNT != 5, t h e expression fails, BPMISS is in cremen t ed an d Soft ICE
will n ot pop up (alt h ough BPCOUNT is n ow 1 great er).
On ce t h e full expression ret urn s TRUE, Soft ICE pops up, an d all in st an ce
coun t s (BPCOUNT an d BPMISS) are reset t o 0.
N o t e : D o N O T u se BPCO UN T b ef o r e t h e co n d i t i o n al ex p r essi o n , o t h er w i se
BPCO UN T w i l l n o t i n c r em en t co r r ect l y :
bpx myaddr if (bpcount==5) && (eax==1)
BPM I SS
Th e value for t h e BPMISS expression fun ct ion is t h e curren t n umber of
t imes t h at t h e breakpoin t was evaluat ed as FALSE.
Th e expression fun ct ion is similar t o t h e BPCOUNT fun ct ion . Use it t o
specify t h at Soft ICE pop up in sit uat ion s wh ere t h e breakpoin t is con t in -
ually evaluat in g t o FALSE. Th e value of BPMISS will always be on e less
t h an you expect , because it is n ot updat ed un t il t h e con dit ion al expres-
sion is evaluat ed. You can use t h e (>=) operat or t o correct t h is delayed
updat e con dit ion .
bpx myaddr if (eax==43) || (bpmiss>=5)
Due t o t h e early-out algorit h m employed by t h e expression evaluat or, if
t h e expression eax==43 is ever TRUE, t h e con dit ion al evaluat es t o TRUE
an d Soft ICE pops up. Ot h erwise, BPMISS is updat ed each t ime t h e con di-
BETA REVI EW
t ion al evaluat es t o FALSE. Aft er 5 con secut ive failures, t h e expression
evaluat es t o TRUE an d Soft ICE pops up.
BPTO TAL
Th e value for t h e BPTOTAL expression fun ct ion is t h e t ot al n umber of
t imes t h at t h e breakpoin t was t riggered.
Use t h is expression fun ct ion t o con t rol t h e poin t at wh ich a t riggered
breakpoin t causes a popup t o occur. Th e value of t h is expression is t h e
t ot al n umber of t imes t h e breakpoin t was t riggered (refer t o t h e Hit s field
in t h e out put of t h e BSTAT comman d) over it s lifet ime. Th is value is
n ever cleared.
Th e first 50 t imes t h is breakpoin t is t riggered, t h e con dit ion evaluat es t o
FALSE an d Soft ICE will n ot pop up. Every t ime aft er 50, t h e con dit ion
evaluat es t o TRUE, an d Soft ICE pops up on t h is an d every subsequen t
t rap.
bpx myaddr if (bptotal > 50)
You can use BPTOTAL t o implemen t fun ct ion alit y iden t ical t o t h at of
BPCOUNT. Use t h e modulo % operat or as follows:
if (!(bptotal%COUNT))
Th e COUNT is t h e frequen cy wit h wh ich you wan t t h e breakpoin t t o
t rigger. If COUNT is 4, Soft ICE pops up every fourt h t ime t h e breakpoin t
t riggers.
BPLO G
Use t h e BPLOG expression fun ct ion t o log t h e breakpoin t t o t h e h ist ory
buffer. Soft ICE does n ot pop up wh en logged breakpoin t s t rigger.
N o t e : Act i o n s o n l y ex ec u t e w h en So f t ICE p o p s u p , so u si n g act i o n s w i t h
t h e BPLO G f u n ct i o n i s p o i n t l ess.
Th e BPLOG expression fun ct ion always ret urn s TRUE. It causes Soft ICE t o
log t h e breakpoin t an d relevan t in format ion about t h e breakpoin t t o t h e
Soft ICE h ist ory buffer.
An y t ime t h e breakpoin t t riggers an d t h e value of EAX equals 1, Soft ICE
logs t h e breakpoin t in t h e h ist ory buffer. Soft ICE will n ot popup.
bpx myaddr if ((eax==1) && bplog)
BPI N D EX
Use t h e BPINDEX expression fun ct ion t o obt ain t h e breakpoin t in dex t o
use wit h breakpoin t act ion s.
BETA REVI EW
Th is expression fun ct ion ret urn s t h e in dex of t h e breakpoin t t h at caused
Soft ICE t o pop up. Th is in dex is t h e same in dex used by t h e BL, BC, BD,
BE, BPE, BPT, an d BSTAT comman ds. You can use t h is value as a parame-
t er t o an y comman d t h at is bein g execut ed as an act ion .
Th e followin g example of a breakpoin t act ion causes t h e BSTAT
comman d t o be execut ed wit h t h e breakpoin t t h at caused t h e act ion t o
be execut ed as it s paramet er:
bpx myaddr do bstat bpindex
Th is example sh ows a breakpoin t t h at uses an act ion t o creat e an ot h er
breakpoin t :
bpx myaddr do t;bpx @esp if(tid==_tid) do \bc bpindex\;g
N o t e : BPIN D EX i s i n t en d ed t o b e u sed w i t h b r eakp o i n t act i o n s, an d cau ses
an er r o r i f i t i s u sed w i t h i n a co n d i t i o n al ex p r essi o n . It s u se o u t si d e o f
act i o n s i s al l o w ed , b u t t h e r esu l t i s u n sp eci f i ed an d y o u sh o u l d n o t
r el y o n i t .
Usi ng Loca l Va r i a bl es i n Condi t i ona l Expr essi ons
Soft ICE let s you use local variable n ames in con dit ion al expression s as
lon g as t h e t ype of breakpoin t is an execut ion breakpoin t (BPX or BPM
X). Soft ICE does n ot recogn ize local symbols in con dit ion al expression s
for ot h er breakpoin t t ypes, such as BPIO or BPMD RW, because t h ey
require an execut ion scope. Th is t ype of breakpoin t is n ot t ied t o a
specific sect ion of execut in g code, so local variables h ave n o mean in g.
Wh en usin g local variables in con dit ion al expression s, fun ct ion s
t ypically h ave a prologue wh ere local variables are creat ed an d an
epilogue wh ere t h ey are dest royed. You can access local variables aft er t h e
prologue code complet es execut ion an d before t h e epilogue code begin s
execut ion . Fun ct ion paramet ers are also t emporarily in accessible usin g
symbol n ames durin g prologue an d epilogue execut ion , because of
adjust men t s t o t h e st ack frame.
To avoid t h ese rest rict ion s, set a breakpoin t on eit h er t h e first or last
source code lin e wit h in t h e fun ct ion body. Well use t h e followin g
foobar fun ct ion t o explain t h is con cept .
Foo b ar Fun ct ion
1:DWORD foobar ( DWORD foo )
2:{
3:DWORDfooTmp=0;
4:
5:if(foo)
BETA REVI EW
6:{
7:fooTmp=foo*2;
8:}else{
9:fooTmp=1;
10:}
11:
12:return fooTmp;
13:}
Source code lin es 1 an d 2 are out side t h e fun ct ion body. Th ese lin es
execut e t h e prologue code. If you use a local variable at t h is poin t , you
receive t h e followin g symbol error:
:BPX foobar if(foo==1)
error: Undefined Symbol (foo)
Set t h e con dit ion al on t h e source code lin e 3, wh ere t h e local variable
fooTmp is declared an d in it ialized, as follows:
:BPX .3 if(foo==0)
Source code lin e 13 marks t h e en d of t h e fun ct ion body. It also begin s
epilogue code execut ion ; t h us, local variables an d paramet ers are out of
scope. To set a con dit ion al at t h e en d of t h e foobar fun ct ion , use source
lin e 12, as follows:
:BPX.12 if(fooTmp==1)
N o t e : Al t h o u g h i t i s p o ssi b l e t o u se l o cal v ar i ab l es as t h e i n p u t t o a b r eak-
p o i n t co m m an d , su ch as BPM D RW, y o u sh o u l d avo i d d o i n g t h i s.
Lo cal v ar i ab l es ar e r el at i v e t o t h e st ack, so t h ei r ab so l u t e ad d r ess
ch an g es each t i m e t h e f u n ct i o n sco p e w h er e t h e var i ab l e i s d ecl ar ed
ex ecu t es. W h en t h e o r i g i n al f u n ct i o n sco p e ex i t s, t h e ad d r ess t i ed t o
t h e b r eakp o i n t n o l o n g er r ef er s t o t h e v al u e o f t h e l o c al v ar i ab l e.
Ref er enci ng t he St a ck i n Condi t i ona l Br ea k poi nt s
If you creat e your symbol file wit h full symbol in format ion , you can
access fun ct ion paramet ers an d local variables t h rough t h eir symbolic
n ames, as described in Using Local Variables in Conditional Expressions on
page 117. If, h owever, you are debuggin g wit h out full symbol in forma-
t ion , you n eed t o referen ce fun ct ion paramet ers an d local variables on
t h e st ack. For example, if you t ran slat ed a module wit h publics on ly or
you wan t t o debug a fun ct ion for an operat in g syst em, referen ce fun ct ion
paramet ers an d local variables on t h e st ack.
N o t e : Th e f o l l o w i n g sec t i o n i s sp eci f i c t o 3 2 - b i t f l at ap p l i c at i o n o r sy st em
co d e.
Fun ct ion paramet ers are passed on t h e st ack, so you n eed t o de-referen ce
t h ese paramet ers t h rough t h e ESP or EBP regist ers. Wh ich on e you use
BETA REVI EW
depen ds on t h e fun ct ion s prologue an d wh ere you set t h e act ual break-
poin t in relat ion t o t h at prologue.
Most 32-bit fun ct ion s h ave a prologue of t h e followin g form:
PUSHEBP
MOVEBP,ESP
SUBESP,size (locals)
Wh ich set s up a st ack frame as follows:
Use eit h er t h e ESP or EBP regist er t o address paramet ers. Usin g t h e
EBP regist er is n ot valid un t il t h e PUSH EBP an d MOV EBP, ESP
in st ruct ion s are execut ed. Also n ot e t h at on ce space for local vari-
ables is creat ed (SUB ESP,size) t h e posit ion of t h e paramet ers relat ive
t o ESP n eeds t o be adjust ed by t h e size of t h e local variables an d an y
saved regist ers.
Typically you set a breakpoin t on t h e fun ct ion address, for example:
BPX IsWindow
Wh en t h is breakpoin t is t riggered, t h e prologue h as n ot been
execut ed, an d paramet ers can easily be accessed t h rough t h e ESP
regist er. At t h is poin t , use of EBP is n ot valid.
N o t e : Th i s assu m es a st ack- b ased cal l i n g co n v en t i o n w i t h ar g u m en t s
p u sh ed r i g h t - t o - l ef t .
To be sure t h at de-referen cin g t h e st ack in a con dit ion al expression
operat es as you would expect , use t h e followin g guidelin es.
Cu r r e n t EBP
Cu r r e n t ESP
PARAM n ESP+(n *4), or EBP+(n *4)+4
Pu sh e d b y
ca ll e r
PARAM #2 ESP+8, or EBP+C
PARAM #1 ESP+4, or EBP+8
RET EIP St ack poin t er on en t ry
Ca ll p r o l o g u e
SAVE EBP Base poin t er (PUSH EBP,
MOV EBP,ESP)
LOCALS+size-1
LOCALS+0
St ack poin t er aft er prologue
(SUB ESP, size (locals))
SAVE EBX opt ion al save of C regist ers
Re g i st e r s
save d b y
co m p i le r
SAVE ESI
SAVE EDI St ack poin t er aft er regist ers
are saved
St ack To p
St ack Bo t t o m
BETA REVI EW
If you set a breakpoin t at t h e exact fun ct ion address, for example,
BPX IsWin dow, use ESP+(param# * 4) t o address paramet ers, wh ere
param# is 1n .
If you set a breakpoin t in side a fun ct ion body (aft er t h e full prologue
h as been execut ed), use EBP+(param# * 4)+4 t o address paramet ers,
wh ere param# is 1n . Be sure t h at t h e rout in e does n ot use t h e EBP
regist er for a purpose ot h er t h an a st ack-frame.
Fun ct ion s t h at are assembly-lan guage based or are opt imized for
frame-poin t er omission may require t h at you use t h e ESP regist er,
because EBP may n ot be set up correct ly.
N o t e : O n ce t h e sp ace f o r l o cal v ar i ab l es i s al l o cat ed o n t h e st ack, t h e l o cal
v ar i ab l es can b e ad d r essed u si n g a n eg at i ve o f f set f r o m EBP. Th e f i r st
l o cal v ar i ab l e i s at EBP-4 . Si m p l e d at a t y p es ar e t y p i cal l y D w o r d si zed ,
so t h ei r o f f set can b e cal cu l at ed i n a m an n er si m i l ar t o f u n ct i o n
p ar am et er s. Fo r ex am p l e, w i t h t w o p o i n t er l o cal v ar i ab l es, o n e w i l l
b e at EBP- 4 an d t h e o t h er w i l l b e at EBP- 8 .
Per f or ma nce
Con dit ion al breakpoin t s h ave some overh ead associat ed wit h run -t ime
evaluat ion . Un der most circumst an ces you see lit t le or n o effect on
performan ce wh en usin g con dit ion al expression s. In sit uat ion s wh ere
you set a con dit ion al breakpoin t on a h igh ly accessed dat a variable or
code sequen ce, you may n ot ice slower syst em performan ce. Th is is due t o
t h e fact t h at every t ime t h e breakpoin t is t riggered, t h e con dit ion al
expression is evaluat ed. If a rout in e is execut ed h un dreds of t imes per
secon d (such as ExAllocat ePool or SwapCon t ext ), t h e fact t h at an y t ype
of breakpoin t wit h or wit h out a con dit ion al is t rapped an d evaluat ed
wit h t h is frequen cy result s in some performan ce degradat ion .
Dupl i ca t e Br ea kpoi nt s
On ce a breakpoin t is set on an address, you can n ot set an ot h er break-
poin t on t h e same address. Wit h con dit ion al expression s, h owever, you
can creat e a compoun d expression usin g t h e logical operat ors (&&) or (|| )
t o t est more t h an on e con dit ion at t h e same address.
Elapsed Time
Soft ICE support s usin g t h e t ime st amp coun t er (RDTSC in st ruct ion ) on
all Pen t ium an d Pen t ium-Pro mach in es. Wh en Soft ICE first st art s, it
displays t h e clock speed of t h e mach in e on wh ich it is run n in g. Every
BETA REVI EW
t ime Soft ICE pops up due t o a breakpoin t , t h e elapsed t ime displays sin ce
t h e last t ime Soft ICE popped up. Th e t ime displays aft er t h e break reason
in secon ds, millisecon ds, or microsecon ds:
Break due to G (ET=23.99 microseconds)
Th e Pen t ium cycle coun t er is h igh ly accurat e, but you must keep t h e
followin g t wo issues in min d:
1 Th ere is overh ead in volved in poppin g Soft ICE up an d down . On a
100MHz mach in e, t h is t akes approximat ely 5 microsecon ds. Th is
n umber varies sligh t ly due t o cach in g an d privilege level ch an ges.
2 If a h ardware in t errupt occurs before t h e breakpoin t goes off, all t h e
in t errupt processin g t ime is in cluded. In t errupt s are off wh en Soft ICE
pops up, so a h ardware in t errupt almost always goes off as soon as
Win dows NT/ 2000/ XP resumes.
Breakpoint St at ist ics
Soft ICE collect s st at ist ical in format ion about each breakpoin t , in cludin g
t h e followin g:
Tot al n umber of h it s, breaks, misses, an d errors
Curren t h it s an d misses
Use t h e BSTAT comman d t o display t h is in format ion . Refer t o t h e SoftICE
Command Reference for more in format ion on t h e BSTAT comman d.
Referring t o Breakpoint s in Expressions
You can combin e t h e prefix BP wit h t h e breakpoin t in dex t o use as a
symbol in an expression . Th is works for all BPX an d BPM breakpoin t s.
Soft ICE uses t h e act ual address of t h e breakpoin t .
To disassemble code at t h e address of t h e breakpoin t wit h in dex 0, use
t h e comman d:
U BP0
Manipulat ing Breakpoint s
Soft ICE provides a variet y of comman ds for man ipulat in g breakpoin t s
such as list in g, modifyin g, delet in g, en ablin g, disablin g, an d recallin g
BETA REVI EW
breakpoin t s. Breakpoin t s are iden t ified by breakpoin t in dex n umbers,
wh ich are n umbers ran gin g from 0 t o FF (h ex). Breakpoin t in dex
n umbers are assign ed sequen t ially as breakpoin t s are added. Th e follow-
in g t able describes t h e breakpoin t man ipulat ion comman ds:
N o t e : Ref er t o t h e SoftICE Command Reference f o r m o r e i n f o r m at i o n o n each
o f t h ese co m m an d s.
Using Embedded Breakpoint s
It may be h elpful for you t o embed a breakpoin t in your program source
rat h er t h an set t in g a breakpoin t wit h Soft ICE. To embed a breakpoin t in
your program, do t h e followin g:
1 Place an INT 1 or INT 3 in st ruct ion at t h e desired poin t in t h e pro-
gram source.
2 To en able Soft ICE t o pop up on such embedded breakpoin t s, use on e
of t h e followin g comman ds:
a SET I1HERE ON for INT 1 breakpoin t s
b SET I3HERE ON for INT 3 breakpoin t s
Tab l e 7 - 2 . So f t ICE Br eakp o i n t M an i p u l at i o n Co m m an d s
Co m m an d D escr i p t i o n
BD D i sab l e a b r eakp o i n t .
BE En ab l e a b r eakp o i n t .
BL Li st cu r r en t b r eakp o i n t s.
BPE Ed i t a b r eakp o i n t .
BPT Use b r eakp o i n t as a t em p l at e.
BC Cl ear ( r em o ve) a b r eakp o i n t .
BH D i sp l ay b r eakp o i n t h i st o r y.
1 2 3
BETA REVI EW
Ch ap t er 8
Using Expressions
Exp r essio n Value s
Sup p o r t ed O p e r at or s
For m in g Exp r e ssion s
Exp r essio n Evaluat or Typ e Syst em
Expression Values
Th e Soft ICE expression evaluat or det ermin es t h e values of expression s
used wit h Soft ICE comman ds an d con dit ion al breakpoin t s. It provides
full operat or preceden ce; support for st an dard C lan guage arit h met ic, bit -
wise, logical, an d in direct ion operat ors; predefin ed macros for dat a t ype
con version ; an d access t o common Soft ICE an d operat in g syst em values.
Th e Soft ICE expression evaluat or parses an d evaluat es expression s
similarly t o t h e way a C or C++ lan guage compiler t ran slat es expression s.
If you are comfort able wit h eit h er lan guage, you are already familiar wit h
t h e grammar an d syn t ax of Soft ICE expression s.
Ot h er t h an t h e maximum len gt h of a Soft ICE comman d lin e (80 ch arac-
t ers), t h ere are n o limit at ion s on t h e complexit y of an expression . You
can combin e mult iple operat ors, operan ds, an d expression s t o creat e
compoun d expression s for con dit ion al breakpoin t s or expression evalua-
t ion .
Th is example uses a compoun d expression t o t rigger a breakpoin t if t h e
first paramet er (ESP+4) passed t o t h e IsWin dow( ) API fun ct ion is an
HWND wit h t h e value of 0x10022 or 0x1001E. If eit h er of t h e t wo
expression s is TRUE, t h e con dit ion al expression is TRUE, an d t h e break-
poin t t riggers:
BPX IsWindow if (esp->4 == 10022) || (esp->4 == 1001E)
N o t e : Th e ex p r essi o n esp - > 4 i s sh o r t h an d n o t at i o n f o r * ( esp + 4 ) .
BETA REVI EW
Support ed Operat ors
Th e Soft ICE expression evaluat or support s t h e followin g operat ors sort ed
by t ype:
Tab l e 8 - 1 . So f t ICE In d i r ect i o n O p er at o r s
In d i r ect i o n O p er at o r s Ex am p l e
- > eb p - > 8 ( g et s D w o r d p o i n t ed t o b y eb p + 8 )
. eax . 1 C ( g et s D w o r d p o i n t ed t o b y eax + 1 c)
* * eax ( g et s D w o r d val u e p o i n t ed t o b y eax )
@ @eax ( g et s D w o r d val u e p o i n t ed t o b y eax )
% ( p h y si cal i n d i r ect i o n ) % eax ( g et s D w o r d val u e f r o m t h e p h y si cal m em o r y
ad d r ess i n eax )
[ ] ( ar r ay su b scr i p t ) Fo o [ 2 ] ( g et s t h e seco n d el em en t o f t h e ar r ay Fo o )
Tab l e 8 - 2 . So f t ICE M at h O p er at o r s
M at h O p er at o r s Ex am p l e
u n ar y + + 4 2 ( d eci m al )
u n ar y - - 4 2 ( d eci m al )
+ eax + 1
- eb p - 4
* eb x * 4
/ Sy m b o l / 2
% ( m o d u l o ) eax % 3
< < ( l o g i cal sh i f t l ef t ) b l < < 1 ( r esu l t i s b l sh i f t ed l ef t b y 1 )
> > ( l o g i cal sh i f t r i g h t ) eax > > 2 ( r esu l t i s eax sh i f t ed r i g h t b y 2 )
Tab l e 8 - 3 . So f t ICE Bi t w i se O p er at o r s
Bi t w i se O p er at o r s Ex am p l e
& ( b i t w i se AN D ) eax & F7
| ( b i t w i se O R) Sy m b o l | 4
^ ( b i t w i se XO R) eb x ^ 0 x FF
~ ( b i t w i se N O T) ~ d x
Ch ap t er 8 Usi n g Ex p r essi o n s 1 2 5
BETA REVI EW
Oper a t or Pr ecedence
Operat or preceden ce wit h in t h e Soft ICE expression evaluat or is equiva-
len t t o t h e C lan guage operat or preceden ce wit h t h e addit ion of t h e
special Soft ICE operat ors. Operat or preceden ce plays a crucial part in
evaluat in g expression s, so t h e order in wh ich you in put expression
operat ors can h ave a dramat ic result on t h e fin al result of t h e expression .
To override t h e default operat or preceden ce t o produce a desired result ,
use paren t h eses t o force t h e order of evaluat ion .
Tab l e 8 - 4 . So f t ICE Lo g i c al O p er at o r s
Lo g i cal O p er at o r s Ex am p l e
! ( l o g i cal N O T) ! eax
& & ( l o g i cal AN D ) eax & & eb x
|| ( l o g i cal O R) eax || eb x
= = ( co m p ar e eq u al i t y ) Sy m b o l = = 4
! = ( co m p ar e i n eq u al i t y ) Sy m b o l ! = al
< eax < 7
> b x > cx
< = eb x < = Sy m b o l
> = Sy m b o l > = Sy m b o l
Tab l e 8 - 5 . So f t ICE Sp eci al O p er at o r s
Sp eci al O p er at o r s Ex am p l e
. ( l i n e n u m b er ) . 1 2 3 ( val u e i s ad d r ess o f l i n e 1 2 3 i n t h e cu r r en t
so u r ce f i l e)
( , ) ( g r o u p i n g sy m b o l s) ( eax + 3 ) * 4
, ( ar g l i st ) f u n ct i o n ( eax , eb x )
: ( seg m en t o p er at o r ) es: eb x
f u n ct i o n w o r d ( Sy m b o l )
# ( p r o t - m o d e sel ect o r ) # es: eb x ( ad d r ess i s p r o t ect ed - m o d e sel ect o r : o f f set )
$ ( r eal - m o d e seg m en t ) $ es: d i ( ad d r ess i s r eal - m o d e seg m en t : o f f set )
BETA REVI EW
Th e followin g t able list s all t h e operat ors in order of preceden ce. Opera-
t ors of equivalen t preceden ce are evaluat ed accordin g t o t h eir associat iv-
it y.
Forming Expressions
Ti p Use t h e ? ( eva l u a t e
exp r essi on ) com m a n d
t o d i sp l a y t h e r esu l t of
a n y exp r essi on .
Th e Soft ICE expression evaluat or accept s a variet y of operan ds, such as
symbols an d n umbers, t h at you can combin e wit h an y Soft ICE operat or.
Soft ICE places an emph asis on providin g flexibilit y of expression , so
in put is as n at ural as possible.
Tab l e 8 - 6 . So f t ICE O p er at o r Pr ec ed en ce
O p er at o r Asso ci at es Co m m en t
( , ) , f u n ct i o n [ , ] l ef t - t o - r i g h t sc o p es, f u n ct i o n ar r ay su b scr i p t
- > , . l ef t - t o - r i g h t i n d i r ect i o n
: l ef t - t o - r i g h t sel ect o r : o f f set
# , $ r i g h t - t o - l ef t sel ect o r o ver r i d es
* , @, %
u n ar y +
u n ar y -
! , ~
r i g h t - t o - l ef t i n d i r ect i o n
d ef au l t r ad i x = = d eci m al
d ef au l t r ad i x = = d eci m al
Li n e N u m b er
* , / , % l ef t - t o - r i g h t
+ , - l ef t - t o - r i g h t
< < , > > l ef t - t o - r i g h t
< , < = , > , > = l ef t - t o - r i g h t
= = , ! = l ef t - t o - r i g h t
& l ef t - t o - r i g h t
^ l ef t - t o - r i g h t
| l ef t - t o - r i g h t
& & l ef t - t o - r i g h t
|| l ef t - t o - r i g h t
co m m a l ef t - t o - r i g h t ar g l i st
BETA REVI EW
N umb er s
Th e Soft ICE expression evaluat or accept s t h e followin g n umeric in put s.
Cha r a ct er Const a nt s
Soft ICE support s t h e use of st an dard C lan guage ch aract er con st an t s such
as \ b, ABCD, or \ x23. Th e default radix for ch aract er con st an t s t h at
begin wit h a backslash \ is decimal. To specify a h ex ch aract er con st an t ,
use an x prefix such as in \ x23.
Tab l e 8 - 7 . So f t ICE Ex p r essi o n In p u t s
In p u t D escr i p t i o n
Hex ad eci m al Hex ad eci m al i s t h e d ef au l t r ad i x f o r al l n u m er i c i n p u t an d o u t p u t .
Th e val i d ch ar act er set f o r h ex ad eci m al n u m b er s i s [ 0 - 9 , A- F] .
Hex ad eci m al i n p u t can b e o p t i o n al l y p r eced ed b y t h e st an d ar d C
l an g u ag e r ad i x i d en t i f i er : 0 x . Ex am p l es o f v al i d h ex ad eci m al n u m -
b er s i n cl u d e:
FF, ABC, 0x123, 0xFFFF0000
Th e sy m b o l i c f o r m o f a val i d h ex ad eci m al n u m b er co u l d co n f l i ct
w i t h a sy m b o l n am e. Fo r ex am p l e, ABC. Use t h e 0 x f o r m t o en su r e
t h at t h e n u m b er i s n o t m i si n t er p r et ed as a sy m b o l n am e.
D eci m al So f t ICE u ses t h e i m p l i ed sem an t i cs o f t h e u n ar y + an d u n ar y -
o p er at o r s t o f o rce t h e d ef au l t r ad i x t o t em p o r ar i l y b eco m e d eci -
m al . Th i s i s b ased o n t h e f act t h at + FF an d - ABC ar e r el at i vel y
u n n at u r al , b u t st i l l l eg al , f o r m s o f say i n g d eci m al 2 5 5 an d - 2 7 4 8 . If
y o u d i r ect l y p r ec ed e a n u m b er w i t h a u n ar y + o r u n ar y - , So f t ICE
at t em p t s t o ev al u at e t h at n u m b er as d eci m al an d , i f t h at f ai l s, as
h ex ad eci m al .
Th e f o l l o w i n g ex am p l es u se t h e u n ar y + an d u n ar y - o p er at o r s t o
af f ect h o w t h e r ad i x o f a n u m b er i s i n t er p r et ed :
? + 4 2
0 0 0 0 0 0 2 A 0 0 0 0 0 0 0 0 4 2 " * "
? - 4 2
FFFFFFD 6 4 2 9 4 9 6 7 2 5 4 ( - 4 2 ) " "
? - 1 a
FFFFFFE6 4 2 9 4 9 6 7 2 7 0 ( - 2 6 ) " "
? + f f
0 0 0 0 0 0 FF 0 0 0 0 0 0 0 2 5 5 " "
? +( 1 2 )
0 0 0 0 0 0 1 2 0 0 0 0 0 0 0 0 1 8 " "
Th e So f t ICE l i n e n u m b er o p er at o r ( . ) al so ch an g es t h e d ef au l t
r ad i x t o d eci m al . Th e u n ar y + o p er at o r i s a N O P f o r ex p r essi o n
eval u at i o n , an d o t h er t h an ch an g i n g t h e d ef au l t r ad i x , i t h as n o
ef f ect .
BETA REVI EW
Regi st er s
Ti p You ca n u se b u i l t - i n
f u n ct i on s t o a ccess
i n d i vi d u a l f l a g s w i t h i n
t h e EFL a n d FL f l a g s
r eg i st er. Ref er t o Built-
in Functions on p a g e
1 2 9 .
Soft ICE support s t h e st an dard n ames for t h e In t el regist er set :
Symbol s
Symbol n ames are t h e symbolic represen t at ion of an address or value.
Th ey are defin ed in symbol t ables, export t ables, or via Soft ICEs NAME
comman d, durin g debuggin g.
Symbol n ames in Soft ICE differ from symbols defin ed in C or C++
programs. All compilers add some form of decorat ion t o t h e n ames
defin ed in a program, an d t h is decorat ion oft en in cludes ch aract ers
wh ich are n ot valid in C/ C++ symbol n ames. Soft ICE t h erefore accept s a
wider ran ge of ch aract ers in symbol n ames t h an a compiler. Table 7-8
sh ows t h e ch aract ers wh ich may be foun d in a legal symbol n ame.
Symbols must begin wit h on e of t h e ch aract ers marked valid as first
symbol ch aract ers in t h e t able.
AH CS EBX FL
AL CX ECX FS
AX D H ED I GS
BH D I ED X IP
BL D L EFL SI
BP D S EIP SP
BX D X ES SS
CH EAX ESI
CL EBP ESP
Tab l e 8 - 8 . Leg al Sy m b o l Ch ar act er s
Ch ar act er s Valid as Fir st Sym b ol Ch ar act e r
A..Z an d a..z Yes
0..9 N o
at sign (@) Yes
dollar sign ($) Yes
un derscore (_) Yes
sin gle back-quot e () Yes
exclamin at ion poin t (!) N o
scope operat or (::) N o
BETA REVI EW
Th e scope operat or (::) is allowed in symbols. However, n ot e t h at t h e
"operat or" is in t h is con t ext simply part of t h e symbol n ame, an d is n ot
fun ct ion in g as a t rue operat or. An y n umber of scope operat ors are
allowed in a symbol n ame, so n amespaces an d n est ed classes will
fun ct ion properly.
Each symbol file loaded in t o Soft ICE is placed in a separat e t able, an d
on ly on e symbol t able can be "act ive" at a t ime. (Refer t o t h e TABLE
comman d in t h e Soft ICE Comman d Referen ce for more in format ion on
ch an gin g t h e act ive t able.)
To specify a symbol from an in act ive symbol t able in an expression ,
precede t h e symbol wit h t h e t able n ame, followed by an exclamat ion
poin t , followed by t h e symbol n ame. For example:
table-name!symbol-name
Symbols t h at are loaded from export t ables or defin ed by t h e NAME
comman d are always act ive, because Soft ICE t reat s t h ese symbol sources
as a h omogen ous un it .
Bui l t - i n Funct i ons
Soft ICE predefin es a n umber of fun ct ion s for use in expression s. Th ey
t ake a variet y of forms an d represen t st at ic values, dyn amic values wit h in
t h e operat in g syst em or Soft ICE, or fun ct ion s t h at can be used wit h in
expression s t o modify values or t ran slat e dat a t ypes.
Use fun ct ion s t h at do n ot t ake argumen t s just like symbols from a
symbol t able. Fun ct ion s t h at accept argumen t s operat e on user-specified
values, lookin g an d beh avin g like C lan guage fun ct ion s an d h ave t h e
followin g form:
FUNC (arg-list)
N o t e : Fu n ct i o n n am es ar e su p er sed ed b y a sy m b o l o f t h e sam e n am e
w i t h i n a sy m b o l t ab l e o r ex p o r t t ab l e.
Th e followin g fun ct ion s are defin ed for Soft ICE:
Tab l e 8 - 9 . So f t ICE Pr ed ef i n ed Fu n ct i o n s
N am e D escr i p t i o n Ex am p l e
By t e Get l o w - o r d er b y t e ? By t e( 0 x 1 2 3 4 ) = 0 x 3 4
Wo r d Get l o w - o r d er w o r d ? Wo r d ( 0 x 1 2 3 4 5 6 7 8 ) = 0 x 5 6 7 8
D w o r d Get l o w - o r d er d w o r d ? D w o r d ( 0 x FF) = 0 x 0 0 0 0 0 0 FF
Hi By t e Get h i g h - o r d er b y t e ? Hi By t e( 0 x 1 2 3 4 ) = 0 x 1 2
BETA REVI EW
Hi Wo r d Get h i g h - o r d er w o r d ? Hi Wo r d ( 0 x 1 2 3 4 5 6 7 8 ) =
0 x 1 2 3 4
Sw o r d Co n ver t b y t e t o si g n ed w o r d ? Sw o r d ( 0 x 8 0 ) = 0 x FF8 0
Lo n g Co n v er t b y t e o r w o r d t o si g n ed
l o n g
? Lo n g ( 0 x FF) = 0 x FFFFFFFF
? Lo n g ( 0 x FFFF) = 0 x FFFFFFFF
WSTR D i sp l ay as Un i co d e st r i n g ? W STR( eax )
Fl at Co n ver t a sel ect o r - r el at i ve
ad d r ess t o a l i n ear ( f l at ) ad d r ess
? Fl at ( f s: 0 ) = 0 x FFD FF0 0 0
CFL Car r y Fl ag ? CFL = b o o l - t y p e
PFL Par i t y Fl ag ? PFL = b o o l - t y p e
AFL Au x i l i ar y Fl ag ? AFL = b o o l - t y p e
Z FL Z er o Fl ag ? Z FL = b o o l - t y p e
SFL Si g n Fl ag ? SFL = b o o l - t y p e
O FL O ver f l o w Fl ag ? O FL = b o o l - t y p e
RFL Resu m e Fl ag ? RFL = b o o l - t y p e
TFL Tr ap Fl ag ? TFL = b o o l - t y p e
D FL D i r ect i o n Fl ag ? D FL = b o o l - t y p e
IFL In t er r u p t Fl ag ? IFL = b o o l - t y p e
N TFL N est ed Task Fl ag ? N TFL = b o o l - t y p e
IO PL IO PL l ev el ? IO PL = cu r r en t IO p r i vi l eg e
l ev el
VM FL Vi r t u al M ach i n e Fl ag ? VM FL = b o o l - t y p e
IRQ L Wi n d o w s N T/ 2 0 0 0 / XP O S IRQ
Level
? IRQ L = u n si g n ed - ch ar
D at aAd
d r
Ret u r n s t h e ad d r ess o f t h e f i r st
d at a i t em d i sp l ay ed i n t h e D at a
w i n d o w
d d @d at aad d r
Co d eAd
d r
Ret u r n s t h e ad d r ess o f t h e f i r st
i n st r u ct i o n d i sp l ay ed i n t h e Co d e
w i n d o w
? co d ead d r
BETA REVI EW
Ead d r Fun ct ion
Th e Eaddr fun ct ion ret urn s t h e effect ive address, if an y, t h at t h e in st ruc-
t ion at t h e curren t EIP uses. Th e EIP regist er poin t s t o t h at in st ruct ion .
N o t e : Th e ef f ect i ve ad d r ess o f t h e cu r r en t i n st r u c t i o n , i f an y, an d t h e v al u e
at t h at ad d r ess al so d i sp l ay i n t h e Reg i st er w i n d o w d i r ect l y b en eat h
t h e f l ag set t i n g s.
Th e x86 processor supplies a variet y of memory addressin g modes such as
regist er+offset an d regist er+regist er. Th e result of comput in g t h e memory
address is called t h e effective address. An in st ruct ion t h at uses a memory
addressin g mode is said t o h ave an effect ive address as it s source or dest i-
Ead d r Ef f ect i ve ad d r ess, i f an y, o f t h e
cu r r en t i n st r u ct i o n . Ref er t o Eaddr
Function on page 131
Ev al u e Cu r r en t v al u e at t h e ef f ect i v e
ad d r ess. Ref er t o Evalue Function on
page 132
Pr o cess KPEB ( Ker n el Pr o c ess En vi r o n -
m en t Bl o ck) o f t h e Act i ve O S
p r o cess
? p r o cess
Th r ead KTEB ( Ker n el Th r ead En vi r o n -
m en t Bl o ck) o f t h e Act i ve O S
t h r ead
? t h r ead
PID Act i ve p r o cess Id ? p i d = = Test 3 2 Pi d
TID Act i ve t h r ead Id ? t i d = = Test 3 2 M ai n Ti d
BPCo u n
t
Br eakp o i n t i n st an ce co u n t . Fo r
t h ese BP f u n ct i o n s, r ef er t o Condi-
tional Breakpoint Count Functions on page
114
b p IF
b p co u n t = = 0 x 1 0
BPTo t al Br eakp o i n t t o t al co u n t b p IF
b p t o t al > 0 x 1 0
BPM i ss Br eakp o i n t i n st an ce m i ss co u n t b p IF
b p m i ss= = 0 x 2 0
BPLo g Br eakp o i n t si l en t l o g b p IF b p l o g
BPIn d ex Cu r r en t Br eakp o i n t In d ex # b p D O b d
b p i n d ex
BETA REVI EW
n at ion . An x86 in st ruct ion n ever h as an effect ive address as bot h source
an d dest in at ion .
Some in st ruct ion s may n ot in volve an effect ive address, eit h er because
on ly regist ers are used or because t h e memory addressin g is don e in a
way specific t o t h e in st ruct ion t ype, such as wit h t h e PUSH an d POP
in st ruct ion s.
Th e curren t in st ruct ion is:
MOV ECX,[ESP+4]
Th e Eaddr fun ct ion ret urn s a value equal t o ESP+4, t h at is, t h e curren t
value of ESP plus 4.
The current instruction is:
ADD BYTE PTR [ESI+EBX+2],55
Th e Eaddr ret urn s t h e result of ESI+EBX+2.
Evalue Fun ct io n
Evalue ret urn s t h e value at t h e effect ive address, if an y, of t h e curren t
in st ruct ion . Th is is n ot n ecessarily t h e same as Eaddr->0, because Evalue
is sen sit ive t o t h e operan d size. Evalue ret urn s a byt e, word, or dword as
appropriat e.
N o t e : Th e ef f ect i ve ad d r ess o f t h e cu r r en t i n st r u c t i o n , i f an y, an d t h e v al u e
at t h at ad d r ess d i sp l ay i n t h e Reg i st er w i n d o w d i r ect l y b en eat h t h e
f l ag set t i n g s.
Expression Evaluat or Type Syst em
Th e Soft ICE expression evaluat or uses a very basic t ype syst em t h at
cat egorizes all expression values in t o on e of t h e followin g t ypes:
N o t e : As a cl ass, f u n ct i o n s d o n o t h av e a t y p e, b u t t h ey r eso l v e i n t o o n e o f
t h e t y p es p r ev i o u sl y l i st ed .
Tab l e 8 - 1 0 . So f t ICE Ex p r essi o n Ty p es
Ty p e Ex am p l e
Li t er al - t y p e 1 , 0 x 8 0 0 0 0 0 0 0 , ABCD
Reg i st er - t y p e EAX, D S, ESP
Sy m b o l - t y p e Po o l Hi t Tag , IsWi n d o w
Ad d r ess- t y p e 4 0 : 1 7 , FS: 1 8 , & Sy m b o l
BETA REVI EW
In most cases, you can ign ore t h e dist in ct ion bet ween t ypes as it is on ly
import an t t o Soft ICE. In t h e cases of symbol-t ype an d address-t ype,
h owever, t h ere are import an t seman t ics or rest rict ion s.
Symbol Type
Th e symbol-t ype is used for symbol n ames t h at are in export or symbol
t ables. In gen eral, t h e t ype represen t s t h e lin ear address of a symbol
wit h in a code or dat a segmen t . Th e symbol t ype also represen t s t h e
con t en t s of memory at t h at lin ear address. Th is is similar t o t h e use of a
variable in a C program, but because Soft ICE is a debugger an d n ot a
compiler, t h ere are a few seman t ic differen ces. Soft ICE det ermin es
wh et h er you mean contents-of or address-of based on t h e con t ext of h ow
you use t h e symbol/ variable in an expression . In gen eral, t h e way Soft ICE
t reat s a symbol seems complet ely n at ural, n ot un like t h at of t h e C
compiler; but , in cases wh ere you are n ot sure h ow Soft ICE in t erpret s t h e
symbol, you can explicit ly st at e:
address-of (&Symbol) or contents-of (*Symbol).
Wh en symbol-t ypes are used in expression s, Soft ICE will, in most cases,
presen t t h e result of t h e expression in t h e correct t ype. For example,
given an array of in t egers declared like t h is:
int TinyArray[] = { 1, 2, 3, 4 };
Th e expression :
?TinyArray[ 1 ]
will cause Soft ICE t o display t h e secon d elemen t of t h e array, wh ich will
be of t ype int.
Alt ern at ely, if you h ave a poin t er-t o-ch ar expression declared like t h is:
char *str = "Twas Brillig"
t h e expression
*str
will result in t h e followin g display:
<char> = 0x54, T, 84
Addr ess Type
Soft ICE t reat s a symbol as an address-t ype if you use it in an expression
wh ere an address-t ype is legal an d it makes sen se t o use an address.
Ot h erwise, Soft ICE aut omat ically in direct s t h e symbol, t akin g t h e
con t en t s of t h e memory t h e symbol represen t s. Th ere are man y opera-
t ion s t h at are illegal or do n ot make sen se for address-t ypes such as mult i-
BETA REVI EW
plicat ion an d division , so a majorit y of t h e operat ors used wit h t h e
symbol-t ype act like a C compiler an d aut omat ically t ake t h e con t en t s-of
at t h e address for t h e symbol.
Th e followin g summary sh ows h ow Soft ICE in t erpret s symbols wit h in
expression s:
Tab l e 8 - 1 1 . So f t ICE Sy m b o l In t er p r et at i o n
Ex am p l e Eq u i val en t Ex p r essi o n
Resu l t Ty p e ( f o r
Sy m b o l )
u Sy m b o l u & Sy m b o l ad d r ess- o f
d b Sy m b o l + 1 d b & Sy m b o l + 1 ad d r ess- o f
d b Sy m b o l + d s: 8 0 0 0 d b * Sy m b o l + d s: 8 0 0 0 co n t en t s- o f
d b Sy m b o l +
Sy m b o l 2
d b & Sy m b o l + * Sy m b o l 2 ad d r ess- o f
? Sy m b o l - 1 ? & Sy m b o l - 1 ad d r ess- o f
? Sy m b o l - d s: 8 0 0 0 ? & Sy m b o l - d s: 8 0 0 0 ad d r ess- o f
? Sy m b o l - Sy m b o l 2 ? * Sy m b o l - * Sy m b o l 2 co n t en t s- o f
? Sy m b o l & & 1 ? * Sy m b o l & & 1 co n t en t s- o f
? Sy m b o l & &
d s: 8 0 0 0
? * Sy m b o l & & d s: 8 0 0 0 co n t en t s- o f
? Sy m b o l & &
Sy m b o l 2
? * Sy m b o l & & * Sy m b o l 2 co n t en t s- o f
? Sy m b o l < = 8 0 0 0 ? * Sy m b o l < = 8 0 0 0 co n t en t s- o f
? Sy m b o l ! =
& Sy m b o l 2
? & Sy m b o l ! = & Sy m b o l 2 ad d r ess- o f
? Sy m b o l = =
Sy m b o l 2
? * Sy m b o l = = * Sy m b o l 2 co n t en t s- o f
? Sy m b o l : 8 0 0 0 ? * Sy m b o l : 8 0 0 0 co n t en t s- o f
? -Sy m b o l ? -* Sy m b o l co n t en t s- o f
? ! Sy m b o l ? ! * Sy m b o l co n t en t s- o f
? Sy m b o l - > 4 ? * ( & Sy m b o l + 4 ) ad d r ess- o f
BETA REVI EW
Th e followin g operat ion s cannot be direct ly performed on or bet ween
address-t ypes:
N o t e : Un l i ke sy m b o l - t y p es, So f t ICE d o es n o t au t o m at i cal l y i n d i r ect an
ad d r ess- t y p e. Yo u m u st ex p l i ci t l y i n d i r ect t h e ad d r ess- t y p e u si n g o n e
o f t h e i n d i r ect i o n o p er at o r s.
I ndi r ect i on Oper a t or s
Th ere is a subt le differen ce bet ween t h e in direct ion operat ors (->) an d (.)
an d t h e in direct ion operat ors (*) an d (@). Th e result of an (->)or (.) opera-
t or is a plain Dword value, wh ile t h e result of (*) an d (@) is an address-
t ype.
Th e followin g expression is illegal, because mult iplicat ion is n ot a valid
operat ion for addresses:
? (*Symbol)*3
If you t ry t h is, you receive t h e error message Expecting value, not address.
However, t h e followin g expression is perfect ly legal, because t h e result of
Symbol->0 is a plain value, n ot an address-t ype:
? (Symbol->0)*3
Th is dist in ct ion is useful wh en performin g mult iple in direct ion s in 16-bit
code, because address-t ype values ret ain segmen t / select or in format ion .
Oper a nd Types
Th e Soft ICE expression evaluat or t reat s all operan d t ypes as Dword
(un sign ed lon g) values. Th is mean s t h at you must man ually in dicat e t h e
Tab l e 8 - 1 2 . In val i d Ex p r essi o n Fo r m s
In v al i d Ex p r essi o n Fo r m Ex am p l e
ad d r ess- t y p e [ * , / , % , < < , > > ] an y - t y p e &Symbol * 4
ad d r ess- t y p e [ + , & , |, ^ ] ad d r ess- t y p e ds:80ff ^ &Symbol
an y - t y p e [ - > , . ] ad d r ess- t y p e ebp->&Symbol2
ad d r ess- t y p e [ : ] an y - t y p e &Symbol : 8000
[ - , . , & ] ad d r ess- t y p e - &Symbol, .&Symbol
(line number)
ad d r ess- t y p e - ad d r ess- t y p e
N o t e: Th i s ex p r essi o n i s i l l eg al o n l y i f ad d r ess
sel ect o r s d o n o t h av e t h e sam e v al u e an d t y p e.
2 3 : 8 f f f - 2 3 : 4 f f 0 ( l eg al )
1b::0 - 23:0 ( i l l eg al )
BETA REVI EW
size of a t ype usin g t ype cast in g or on e of t h e con version fun ct ion s such
as byt e( ) or word( ).
If you de-referen ce memory, Soft ICE always ret urn s a Dword value. Th is
may n ot be suit able, for example, if you are in t erest ed in a byt e value. To
correct ly compare a byt e-value in a con dit ion al expression , it is n ecessary
t o mask off t h e upper 24-bit s, leavin g t h e lower 8-bit s in t act . In t h e
followin g expression , assume Symbol is a byt e value:
BPX EIP IF (Symbol == 32)
Th is expression is likely t o fail because Soft ICE reads a full 32-bit value
an d compares t h at t o (DWORD) 32, or 0x00000032. Th is is probably n ot
wh at you wan t . Th e followin g expression s work correct ly:
BPX EIP IF ((Symbol & FF) == 32)
or
BPX EIP IF (byte(Symbol)== 32)
Use wh ich ever form you prefer; t h ey are equivalen t .
C+ + Type Ca st i ng
Th e expression evaluat or support s t h e followin g:
C++ st yle t ype cast in g
You can use t h e followin g form t o cast an y value t o a defin ed t ype:
TypeName (expression)
N o t e : Typ eN a m e i s case sen si t i v e b ecau se a h ash l o o ku p i s p er f o r m ed
i n st ead o f a l i n ear sear ch .
St ruct ure an d class in direct ion t h rough members
TypeName (expression)->member
Aft er t h e in direct ion performs, t h e n ew t ype of t h e expression is
aut omat ically t ype cast t o t h e t ype of member. Th is allows mult iple
in direct ion s t o occur.
TypeName (expression)->member->member->member
At each in direct ion , t h e value of member is evaluat ed, t h e aut omat ic
t ype cast applied, an d t h e n ext member evaluat ed an d t ype cast un t il
t h e expression is resolved.
Takin g t h e address of a member or t ype
You can use t h e & (address-of) operat or t o t ake t h e address of a st ruc-
t ure or st ruct ure member.
&TypeName(expression)->member[->member[->member]]
Th is allows you t o set BPM st yle breakpoin t s on st ruct ure members.
BETA REVI EW
Displayin g t yped expression s
Wh erever possible, t h e ? (evaluat e expression ) comman d displays t h e
result of an expression as a t ype. Man y n ormal expression s, like regis-
t ers, h ave default t ypes.
For complex t ypes, t h e class or st ruct ure members are expan ded.
On ly members at t h e root level of t h e object are expan ded. Not e t h at
base an d virt ual base classes are con sidered t o be root object s.
Example:
:? LPSTR (*(ebp-30))
char * = 0x009D000C
<"C:\TOMSDEV\WINICE\NTICE"> char = 0x43 , C
Example:
:? STHashTable (a7bcb0)
class STHashTable = {...}
struct STHashNode * * pHashTable = 0x0089000C <{...}>
unsigned long bucketSize = 0x25
class GrowableArray * pHashEntries = 0x00A7BCC0 <{...}>
Example:
:? STHashTable (a7bcb0)->pHashEntries
class GrowableArray * =0x00A7BCC0 <{...}>
unsigned char * arrayBase = 0x00790078 <"">
unsigned char * nextItem = 0x00790078 <"">
unsigned long memAvail = 0x1000
unsigned long elementSize = 0x10
Displayin g poin t ers t o poin t ers
Types t h at are poin t ers t o poin t ers display t h e value poin t ed t o:
typedef LPSTR *LPLPSTR ;
? LPLPSTR (eax)
char **eax = 0x127894 <0x434000>
wh ere 0x127894 represen t s t h e poin t er value an d 0x434000 repre-
sen t s t h e value of t h e poin t er t h at it poin t s t o.
Displayin g un icode st rin gs
Use t h e WSTR t ype cast operat or t o display un icode st rin gs:
? WSTR (eax)
short *eax = <Company Name>
Eva l ua t i ng Symbol s
Wh en dat a t ype in format ion is available, usin g t h e ? (evaluat e expres-
sion ) comman d wit h a symbol yields t h e con t en t s of t h e symbol rat h er
t h an t h e address of t h e symbol. For example, MyVariable is an in t eger
variable con t ain in g t h e value 5, so you get t h e followin g:
BETA REVI EW
? MyVariable
int=0x5,"\0\0\0\x05"
To get t h e address of MyVariable, use t h e followin g:
? &MyVariable
If you use a symbol in con jun ct ion wit h a comman d ot h er t h an ?, be
sure t o add t h e address of t h e & operat or wh ere n eeded. For example,
t h e dat a display comman d (D) t akes an address as a paramet er, so t o
display t h e con t en t s of a symbol, you sh ould add t h e & operat or:
dd &MyVariable
Usi ng I ndi r ect i on W i t h Symbol s
Wh en you creat e your symbol file wit h complet e t ype an d symbol in for-
mat ion , t h e expression evaluat or support s t h e abilit y t o dereferen ce
t h rough a symbol n ame usin g t h at symbols t ype, You can also t ake t h e
address of a member t h rough a symbol:
typedef struct Test
{
DWORDdword ;
LPSTRlpstr ;
} Test ;
Test test={ 1, test String } ;
? test->dword
unsigned long dword=1
? test->lpstr
char *lpstr=0x123456 ,Test String>
? &test
void * =0x123440
? &test->dword
void *=0x123440
? &test->lpstr
void *=0x123444
You can do t h e same t h in g t h rough t ype cast in g, as follows:
Test(eax)->dword or Test(eax)->lpstr
an d
&Test(eax)->dword or &Test(eax)->lpstr
Poi nt er Ar i t hmet i c w i t h Symbol s
Wh en Soft ICE performs arit h met ic on a symbol wh ose t ype is an address,
it will perform C-st yle poin t er arit h met ic by scalin g t h e secon d operan d
by t h e size of t h e first . So, given t h is declarat ion :
BETA REVI EW
long Numbers[] = { 1, 2, 3, 4 };
long *ptr = Numbers;
Th e Soft ICE comman d
? ptr + 1
will be equivalen t t o t h e same expression in C. Th us, t h e offset (1) will be
scaled by t h e size of t h e t ype poin t ed t o by pt r; in t h is case, 4 byt es. Th is
causes Soft ICE t o display t h e secon d elemen t of t h e Numbers array.
Ar r a y Symbol s I n Exp r essi ons
Soft ICEs array operat or allows you t o evaluat e an d display in dividual
members of arrays. It h as a couple of limit at ion s, h owever. First of all,
Soft ICE does n ot allow mult i-dimen sion al array expression s. En t erin g "?
mych ars[1][1]", for example, will produce an error.
Secon dly, un like C an d C++, Soft ICE does n ot t reat poin t ers an d arrays as
equivalen t . Usin g an array operat or on a poin t er t ype will t h erefore
produce un predict able result s.
BETA REVI EW
1 4 1
BETA REVI EW
Ch ap t er 9
Loading Symbols for Syst em
Component s
Lo ad in g Exp or t Sym b o ls f o r D LLs an d EX Es
U sin g U n n am ed En t r y Poin t s
U sin g Exp o r t N am es in Exp r essio n s
U sin g W in d o w s N T/ 2 0 0 0 / X P Sym b ol File s w it h Sof t I CE
U sin g W in d o w s 9 x Sym b o l ( . SYM ) File s w it h So f t I CE
Loading Export Symbols for DLLs and EXEs
Export s are an aspect of t h e 16-bit an d 32-bit Win dows execut able
format s t h at en able dyn amic (run -t ime) lin kin g, usually bet ween an
execut able t h at import s t h e fun ct ion s an d a .DLL t h at export s t h e
fun ct ion s.
Th e in format ion in t h e execut able file format associat es an ASCII n ame
an d an ordin al n umber, or somet imes just an ordin al n umber, t o an en t ry
poin t in t h e module. It is advan t ageous t o load t h e export in format ion as
symbols in t o t h e debugger, part icularly wh en debuggin g in format ion is
n ot available. Export s are ordin arily used on ly by DLLs, but occasion ally
an .EXE may h ave export s as well; NTOSKRNL.EXE is such a case.
You can set t h e Soft ICE in it ializat ion set t in gs t o load export symbols for
an y 16-bit or 32-bit .DLL or .EXE. Wh en Soft ICE loads, it loads t h e export
files an d makes t h eir symbols available for use in an y Soft ICE expression .
Th ey are also aut omat ically displayed wh en disassemblin g code. To see a
list of all export ed symbols t h at Soft ICE kn ows about , use t h e EXP
comman d. Refer t o Modifying SoftICE Initialization Settings on page 161 for
more in format ion about pre-loadin g export s.
Wh en displayin g 32-bit export s in Soft ICE, if t h e module is n ot yet
loaded, t h e ordin al segmen t displays as FE: an d t h e offset is t h e offset
from t h e 32-bit image base. On ce t h e module is mapped in t o an y
BETA REVI EW
process, select or:offset appears. Th e offset n ow con t ain s t h e image base
address added in .
Wh en a 32-bit module is un loaded from all processes t h at migh t h ave
open ed it , all addresses ret urn t o t h e ordin al FE:offset address.
N o t e : W h en a . D LL i s m ap p ed i n t o t w o p r o cesses at d i f f er en t b ase v i r t u al
ad d r esses, t h e ex p o r t t ab l e u ses t h e b ase ad d r ess o f t h e f i r st p r o cess
t o o p en t h e . D LL, b u t t h e ad d r esses w i l l b e w r o n g f o r t h e o t h er. Yo u
can n o r m al l y av o i d t h i s b y ch o o si n g an ap p r o p r i at e p r ef er r ed l o ad
ad d r ess f o r t h e . D LL o r b y r eb asi n g t h e . D LL.
Th e on ly 16-bit export s loaded are t h ose from t h e n on -residen t export
sect ion ; t h is is usually most or all of t h e export s for t h e module.
Using Unnamed Ent ry Point s
For 32-bit export s, Soft ICE sh ows all export ed en t ry poin t s even if t h ey
do n ot h ave n ames associat ed wit h t h em. For 16-bit export s, Soft ICE on ly
sh ows n ames. For export ed en t ry poin t s wit h out n ames, Soft ICE forms a
n ame in t h e followin g format :
ORD_xxxx
wh ere xxxx is t h e ordin al n umber.
Names of t h is form can overlap, because mult iple DLLs can h ave
un n amed ordin als. To be sure you are usin g t h e correct symbol, precede
t h e symbol wit h t h e module n ame followed by an exclamat ion poin t .
To refer t o KERNEL32 export ordin al n umber on e, use t h e followin g
expression :
KERNEL32!ORD_0001
Th e n umber followin g t h e ORD_ prefix does n ot require t h e correct
n umber of leadin g zeroes; eit h er ORD_0001 or ORD_1 is accept able. Th e
followin g expression is equivalen t t o t h e precedin g example:
KERNEL32!ORD_1
Using Export Names in Expressions
Soft ICE search es all 32-bit export t ables prior t o search in g 16-bit export
t ables. Th is mean s t h at if t h e same n ame exist s in more t h an on e t ype of
t able, Soft ICE uses t h e 32-bit export t able. If you n eed t o override t h is
beh avior, precede t h e export symbol wit h t h e module n ame followed by
an exclamat ion poin t .
Ch ap t er 9 Lo ad i n g Sy m b o l s f o r Sy st em Co m p o n en t s 1 4 3
BETA REVI EW
Wh en specifyin g t h e symbol GlobalAlloc, Soft ICE uses t h e 32-bit export
symbol from KERNEL32.DLL rat h er t h an t h e 16-bit export symbol of t h e
same n ame in KRNL386.EXE. You can access t h e 16-bit version of Global-
Alloc by specifyin g t h e complet e export symbol n ame:
KERNEL!GlobalAlloc
Also, for each t ype of export (32-bit an d 16-bit ), t h e search order is
con t rolled by t h e order in wh ich t h e export s are loaded.
Loa di ng Expor t s Dyna mi ca l l y
To load 32-bit export s dyn amically, do t h e followin g:
2 Eit h er ch oose LOAD EXPORTS from t h e File men u or click t h e LOAD
EXPORTS but t on .
3 Th e Load Export s win dow appears.
4 Select t h e files you wan t t o load an d click OPEN.
Using Windows NT/ 2000/ XP Symbol Files wit h Soft ICE
Microsoft supplies debuggin g in format ion for most Win dows NT/ 2000/
XP compon en t s. You can fin d t h e debug in format ion on t h e Win dows
CD-ROM, or as a down load from Microsoft . Th e Symbol Ret riever t ool,
in cluded wit h Soft ICE, is a con ven ien t way of ret rievin g symbol in forma-
t ion direct ly from Microsoft s public symbol server for an y given syst em
compon en t .
In older version s of t h e operat in g syst em, Microsoft supplied debug
in format ion in t h e form of .DBG files, wh ich con t ain ed COFF debug dat a
for t h e correspon din g compon en t . Sin ce Win dows 2000, debug in forma-
t ion h as been available in t h e form of .PDB files, wh ich are in Microsoft s
Program Dat abase format . Th e procedure for loadin g symbol in format ion
from t h ese t wo file format s is sligh t ly differen t .
To load .DBG files in t o Soft ICE, use Symbol Loader t o t ran slat e t h e file
in t o an .NMS file an d load it . To load a .PDB file in t o Soft ICE, open t h e
module itself wit h Symbol Loader, t h en t ran slat e t o an .NMS file an d load.
If t h e symbol file pat h is set up correct ly, Symbol Loader will fin d t h e
correct .PDB file aut omat ically an d t ran slat e it .
Symbol files n eed t o be t ran slat ed t o .NMS files on ly on ce, un less t h e
module in quest ion ch an ges. On ce t ran slat ed, .NMS files can be loaded
quickly an d simply by double-clickin g on t h em in an Explorer win dow.
BETA REVI EW
Soft ICE can also load .NMS files aut omat ically on st art up; you can add
files t o t h is list usin g t h e Set t in gs applicat ion .
Using Windows 9x Symbol ( .SYM) Files wit h Soft ICE
Th e Win dows 9x DDK in cludes symbol in format ion for some syst em
modules in t h e form of .SYM files. Use eit h er Symbol Loader or NMSYM
t o t ran slat e t h e .SYM files in t o NMS format an d load t h em in t o Soft ICE
1 4 5
BETA REVI EW
Ch ap t er 1 0
Remot e Debugging wit h
Soft ICE
I n t r o d uct ion
Typ e s o f Rem ot e Con n ect ion s
D SR N am esp ace Ext en sion
Rem ot e D eb ug g in g D et ails
SI REM O TE U t ilit y ( H o st Com p ut er )
N ET Co m m an d ( Tar g e t Com p ut er )
Int roduct ion
Th ere may be t imes durin g t h e developmen t process wh en you n eed
Soft ICE t o do more t h an sin gle-mach in e debuggin g, an d remot e debug-
gin g is required. For example, you may wan t t o debug Open GL/ Direct 3D
programmin g, Video playback, or a Video Display Driver, an d t h e
mach in e bein g debugged is locat ed in an ot h er office, at a cust omers sit e,
or on t h e ot h er side of t h e world. For t h is t ype of debuggin g sit uat ion ,
Soft ICE provides an ext en sive array of remot e debuggin g opt ion s.
Th is ch apt er describes t h e t ypes of remot e con n ect ion s available an d
h ow t o con figure Soft ICE for each con n ect ion t ype.
Types of Remot e Connect ions
Soft ICE offers remot e debuggin g t h rough t h e followin g met h ods:
Direct Null Modem con n ect ion .
Dial-up Modem.
Net work In t erface Card (NIC) in t erface. Wit h t h e NIC opt ion , you
h ave t h e abilit y t o debug an y mach in e t h at h as an IP address wit h
t h e proper con figurat ion an d con n ect ion .
BETA REVI EW
Th rough all t ypes of remot e con n ect ion , t h e Soft ICE screen remain s
visible on t h e t arget comput er, un less on e addit ion al st ep is t aken . (For
defin it ion purposes, t h e target computer is t h e comput er t h at h as t h e
Soft ICE debugger run n in g on it . Th is is t h e mach in e t h at is bein g
debugged. Th e host computer is t h e mach in e t h at run s t h e Soft ICE fron t
en d, siremot e.exe.)
To preven t t h e Soft ICE screen from bein g visible on t h e t arget comput er,
ch an ge t h e Soft ICE con figurat ion opt ion t o Headless Mode usin g t h e
DriverSt udio Con figurat ion dialog Soft ICE In it ializat ion Gen eral Set t in gs
page. Remember t h at set t in g t h is opt ion t o Headless Mode will
preven t t h e in put devices on t h e t arget from fun ct ion in g.
Alt ern at ively, you could go t o t h e regist ry an d ch an ge t h e en t ry at
HKLM\System\CurrentControlSet\Services\Ntice t it led
NullVGA. Set t h e value of NullVGA t o 1, an d reboot . Th is will allow
in put on t h e t arget comput er wh ile preven t in g t h e display of t h e Soft ICE
screen .
W h ich t yp e of r em o t e con n ect io n is r ig h t f or m e?
Th is depen ds upon man y fact ors, t h e first of wh ich is location. If t h e
t arget comput er is at a remote location, your opt ion s are eit h er debug-
gin g over a n et work, or debuggin g over a dial-up modem. If t h e t arget
mach in e is a local mach in e (i.e., locat ed in t h e same office), t h en serial
debuggin g or local n et work (LAN) debuggin g is most appropriat e.
W h at ar e t h e ad van t ag es/ d isad van t ag es f o r each t yp e of
con n ect ion ?
Th e followin g t able list s t h e con n ect ion advan t ages an d disadvan t ages .
Tab l e 1 0 - 1 . Co n n ect i o n Ad v an t ag es/ D i sad v an t ag es
Con n e ct io n Typ e Ad van t ag e D i sad van t ag e
Ser i al Co n n ect i o n
N o ad d i t i o n al h ar d w ar e
r eq u i r ed o t h er t h an n u l l
m o d em cab l e.
D ecen t p er f o r m an ce.
M ach i n e m u st b e
l o cat ed w i t h i n r each o f
n u l l m o d em cab l e.
Per f o r m an ce at sl o w er
co n n ect i o n sp eed s.
N o t su p p o r t ed i n t h e
D r i ver St u d i o Rem o t e
D at a ex t en si o n .
Ch ap t er 1 0 Rem o t e D eb u g g i n g w i t h So f t ICE 1 4 7
BETA REVI EW
DSR Namespace Ext ension
Bot h DriverSt udio an d t h e Soft ICE Driver Suit e h ave a feat ure called t h e
DriverSt udio Remot e Dat a (DSR) n amespace ext en sion . Th is feat ure will
allow you t o mon it or t h e st at us of your en t ire n et work from on e
locat ion . From t h is on e locat ion you can st art Soft ICE, ch an ge con figura-
t ion paramet ers for all t ools in t h e suit e, con n ect t o a remot e mach in e,
N IC Un i ver sal
N et w o r k D r i v er
Per f o r m an ce cl o se t o t h at o f
si n g l e m ach i n e d eb u g g i n g .
Ab i l i t y t o d eb u g an y m ach i n e
at o n e l o cat i o n .
Ab i l i t y t o d eb u g o v er t h e
i n t er n et t h r o u g h t cp / i p
p r o t o co l ( f i r ew al l r est r i c t i o n s
an d i p l i m i t at i o n s ap p l y ) .
Uses an y PCI b ased N IC car d .
Can b e u sed f o r b o o t t i m e
d eb u g g i n g .
Fu l l su p p o r t o f t h e
D r i ver St u d i o Rem o t eD at a
N am eSp ace Ex t en si o n .
Fi r ew al l s g et i n t h e
w ay ( can b e
ci rcu m v en t ed w i t h
VPN , SSH) .
M ach i n es m ay n eed t o
b e o n sam e su b n et .
N et w o r k p er f o r m an ce
can d ecr ease i f u si n g
t h e SIVN IC ( So f t ICE
Vi r t u al N IC) ( ad d i t i o n al
d et ai l s b el o w ) .
N IC Sp eci al i zed
N et w o r k D r i v er s
Per f o r m an ce cl o se t o t h at o f
si n g l e m ach i n e d eb u g g i n g .
D o es n o t i n t er f er e w i t h
n o r m al n et w o r k t r af f i c.
Ab i l i t y t o d eb u g an y m ach i n e
co n n ect ed t o y o u r l o cal
su b n et , as w el l as m ach i n es
d i r ect l y co n n ect ed t o t h e
In t er n et .
Fu l l su p p o r t o f t h e
D r i ver St u d i o Rem o t eD at a
N am eSp ace Ex t en si o n .
Can n o t b e u sed t o
d eb u g ear l y b o o t t i m e
d r i v er s.
Req u i r es o n e o f 3
cl asses o f n et w o r k
car d s.
M o d em Can co n n ect t o an y m ach i n e
t h at h as a m o d em .
Fi r ew al l s ar e n o t a c o n cer n .
Sl o w.
M o d em h ar d w ar e m u st
b e p r esen t i n b o t h
m ach i n es.
Ph o n e l i n e i s t i ed u p .
Tab l e 1 0 - 1 . Co n n ect i o n Ad v an t ag es/ D i sad v an t ag es
Con n e ct io n Typ e Ad van t ag e D i sad van t ag e
BETA REVI EW
collect Boun dsCh ecker, TrueCoverage, TrueTime
, an d Crash Dump
files, an d fin ally debug t h at mach in e wit h Soft ICE.
N o t e : In o r d er t o d eb u g t h e r em o t e m ach i n e t h r o u g h t h e D r i v er St u d i o
Rem o t e D at a ex t en si o n , y o u w i l l n eed t o h ave ei t h er t h e UN D o r t h e
Sp eci al i zed n et w o r k d r i v er s i n st al l ed .
Th e screen sh ot below sh ows a t ypical debuggin g en viron men t .
Fi g u r e 1 0 -1 . Ty p i cal D eb u g g i n g En v i r o n m en t Scr een
From t h is pict ure you can see t h at t h ere are four main t ypes of icon s:
BETA REVI EW
By righ t -clickin g on an icon , you can ch oose t o ch an ge t h e opt ion s, st art
Soft ICE, or reboot t h e mach in e. By default , t h e folder view con t ain s
st at ic in format ion from a sn apsh ot at a given poin t in t ime.
It is possible t o refresh t h e display man ually by ch oosin g View Refresh
or specify an in t erval of t ime. To set t h e t ime in t erval, first righ t -click on
t h e DriverSt udio Remot eDat a icon . Th en , ch oose Propert ies, an d select
your Refresh In t erval.
Th is icon mean s t h at DriverSt udio is run n in g an d you
can con figure, reboot , an d view t h e out put from t h e
ot h er DriverSt udio Tools, as well as st art Soft ICE.
Th is icon sign ifies t h at Soft ICE is run n in g wit h t h e
n et work en abled on t h is part icular mach in e. If a red
t it le bar is displayed, it sign ifies t h at someon e is already
con n ect ed t o t h e mach in e an d t h at an at t empt t o debug
t h at mach in e will fail. If t h ere is n o red t it le bar visible,
you can con n ect t o it by righ t -clickin g t h e folder an d
select in g Con n ect t o Soft ICE.
Th is icon sign ifies t h at Soft ICE is curren t ly popped-up
on t h is part icular mach in e. A red t it le bar on t h e icon
mean s t h at it is bein g debugged by someon e. If t h ere is
n o red t it le bar visible, you can con n ect t o it by righ t -
clickin g t h e folder an d select in g Con n ect t o Soft ICE.
Th is blue screen icon sign ifies t h e ban e of every
developer t h e dreaded blue screen of deat h . A red
border aroun d t h e blue screen icon mean s t h at
someon e is con n ect ed t o t h is mach in e an d is debuggin g
it . A gray border in dicat es t h at you can con n ect t o it by
righ t -clickin g t h e folder an d select in g Con n ect t o
Soft ICE.
BETA REVI EW
Remot e Debugging Det ails
Each t ype of n et workin g h as cert ain requiremen t s an d may require
preparat ion st eps. Please be sure t o follow all direct ion s closely.
Speci a l i zed N et w or k Dr i ver s
D e scr ip t io n
Th e specialized n et work drivers offer t h e best in all-aroun d performan ce
wit h min imal in t rusion upon t h e syst em an d n et work st acks. However,
t h eir limit at ion s may preclude you from usin g t h em. Th e t wo main
limit at ion s are:
1 Th ey can n ot be used for early boot -mode debuggin g, an d
2 You must use on e of t h e t h ree support ed classes of n et work cards.
Th e specialized n et work drivers will run on all Win dows NT based
operat in g syst ems as well as t h e Win 9x based operat in g syst ems.
H ar d w ar e Req uir em en t s
A n et work card based on an y of t h e t h ree classes of n et work cards:
Novell NE2000 series of cards
3com 3c90x series of cards, in cludin g t h e 3C905, 3C900, 3C920,
3C921, an d all varian t s of t h ose cards
In t el E100 series of cards.
I n st allat ion
In st allat ion an d removal is st raigh t forward.
To in st all t h e specialized n et work drivers:
1 Go t o Control Panel.
2 Ch oose Networking and Dial-up Connections.
3 Righ t click on Local Area Connection.
4 Ch oose properties.
5 Click on Configure.
6 Click on Driver.
BETA REVI EW
7 Click on Update Driver.
8 Click on Next.
9 Ch oose Specify a location
1 0 Browse t o your \ program files\ compuware\ driverst udio\ soft ice\ n et -
work\ folder, an d ch oose t h e appropriat e subfolder. From h ere,
ch oose t h e appropriat e.in f file: i.e., n t 4, win 9x (oemxxxx.in f) or file-
n ame.in f (for Win 2K an d lat er plat forms).
If an y messages appear regardin g Driver Sign in g, t h ese messages
can be safely ign ored.
1 1 Aft er in st allat ion is complet e, reboot your comput er.
Est ab lish in g a Con n ect io n
Est ablish in g a con n ect ion for t h e specialized n et work drivers is iden t ical
t o t h at for t h e Un iversal Net work Driver. (See Un iversal Net work
Driver on page 151.)
Rem o val
Use t h e followin g procedure t o un in st all t h e specialized n et work drivers.
1 Go t o Control Panel.
2 Ch oose Networking and Dial-up Connections.
3 Righ t -click on Local Area Connection.
4 Ch oose properties.
5 Click on Configure.
6 Click on Driver.
7 Click on Update Driver.
8 Click on Next.
9 Ch oose Search for a suitable driver for my device. Follow t h e
prompt s from t h ere.
Uni ver sa l N et w or k Dr i ver
D e scr ip t io n
Th e Un iversal Net work Driver (UND) works on all PCI based n et work
cards for t h e Win dows 2000, Win dows XP (an d lat er) Operat in g Syst ems.
Two drivers are supplied wit h t h e UND. Th e first driver allows Soft ICE t o
BETA REVI EW
in t eract wit h t h e n et workin g card. Th is driver preven t s n ormal n et work
t raffic, e-mail, web browsin g, or file sh arin g t o occur on t h at NIC card.
To get aroun d t h is limit at ion we suggest usin g a secon d n et work card
wh ich is dedicat ed t o Soft ICE. If t h is is impract ical, we provide an
addit ion al driver called t h e Soft ICE Virt ual NIC (SIVNIC). Th is driver
allows t h e NIC t o be sh ared bet ween Soft ICE an d n ormal Win dows
n et workin g.
N o t e : Yo u w i l l n o t i ce a d ecr ease i n Wi n d o w s n et w o r ki n g p er f o r m an ce
w h en u si n g t h e SIVN IC. As su ch , i t i s su g g est ed t h at y o u i n st al l a
seco n d n et w o r k car d t h at i s f o r t h e ex cl u si ve u se o f So f t ICE.
Th e on ly h ardware requiremen t is a PCI-based Net work Card on t h e
target mach in e. Th e h ost can h ave an y t ype of n et work card (i.e., most
built -in lapt op NIC cards are PCI based).
N o t e : At t h i s t i m e t h er e i s n o su p p o r t f o r PCM CIA o r USB n et w o r k car d s.
I n st allat ion
SIDN Installation. In st allin g t h e SIDN driver (t h e base driver used by
Soft ICE for debuggin g) is don e t h rough t h e supplied UNDSETUP.EXE
applicat ion wh ich is locat ed in c:\ program files\ compuware\ driverst u-
dio\ soft ice\ n et work\ un d. Run t h is applicat ion an d ch oose t h e n et work
card t h at you wish t o at t ach t o t h e UND. Follow t h e prompt s an d reboot
your mach in e.
BETA REVI EW
Fi g u r e 1 0 -2 . N et w o r k Set u p Scr een
SIVNIC Installation. If Win dows n et workin g is required on t h e t arget
comput er (an d it is n ot pract ical t o in st all a secon d n et work card), you
will n eed t o in st all t h e SIVNIC.
1 Open t h e Con t rol Pan el an d select Add/ Remove Hardware.
2 Wh en t h e wizard open s, select Add/ Troubleshoot, click Next, select
Add a new device, t h en specify t h at you wan t t o select t h e device
from a list .
3 Wh en t h e list of h ardware t ypes appears, select Network adapter,
click Have disk, an d browse t o:
Program Files\Compuware\DriverStudio\SoftICE\Network\UND\VNIC
4 Select sivnic.inf from t h e list , an d con t in ue t h rough t h e remain in g
prompt s.
N o t e : If y o u r u n i n t o p r o b l em s w i t h t h e VN IC, p r ess Esc d u r i n g t h e b o o t
p r o c ess w h en t h e UN D d r i ver p r o m p t s y o u . Th i s w i l l ab o r t t h e
l o ad i n g o f t h e UN D , as w el l as t h e VN IC.
5 On ce t h e SIVNIC is in st alled, reboot your comput er.
BETA REVI EW
Rem o val
To uninstall the SIVNIC, simply delet e it from t h e device list , or use t h e
Remove opt ion in t h e Hardware Wizard.
To uninstall the UND, rerun t h e UNDSETUP.EXE program an d ch oose
t h e Un in st all Opt ion .
Est ab lish in g a N et w o r k Con n ect io n
N o t e : Pr esen t ed h er e ar e t h e easi est m et h o d s o f set t i n g u p a co n n ect i o n
b et w een t h e h o st an d t ar g et co m p u t er s. Th er e ar e ad d i t i o n al
o p t i o n s su ch as p assw o r d p r o t ect i n g , IP l i m i t i n g , g at ew ay an d
su b n et m asks t h at can b e sp eci f i ed . Pl ease r ef er t o t h e Sof t I CE
Com m a n d Ref er en ce f o r f u l l d et ai l s. Al so , at t h e en d o f t h i s ch ap t er
ar e ad d i t i o n al d et ai l s o n t h e n et w o r ki n g co m m an d s u sed w i t h
So f t I CE.
TARGET SIDE: On t h e t arget comput er, you h ave several opt ion s for
st art in g Soft ICE n et workin g. You can :
1 Ch oose Enable Network Support from t h e Soft ICE Set t in gs-Net work
Debuggin g dialog. Th e easiest set up opt ion is t o accept all t h e
default s. Wh en Soft ICE is rest art ed, n et workin g will be en abled wit h
t h e opt ion s on t h is screen .
2 From t h e comman d lin e You can st art an d st op n et workin g from
t h e comman d lin e wit h in Soft ICE. Th e easiest way t o st art n et work-
in g is n et set up dh cp. To st op n et workin g, use n et st op an d t o
rest art it n et set up dh cp or n et st art .
3 From t h e in it st rin g You can specify t h e same comman d lin es as in
St ep 2 above.
HOST SIDE: On t h e h ost side, you h ave t wo ways t o con n ect .
To st art n et workin g on t h e t arget comput er wit h t h e default options:
1 Click on t h e DriverSt udio Remot e Dat a Namespace.
2 Righ t -click on t h e comput er you wish t o debug.
3 Ch oose Connect to SoftICE.
OR
1 Go t o a comman d prompt .
2 Run t h e comman d lin e equivalen t for con n ect in g t o a Soft ICE t arget .
3 Ch an ge t o t h e Soft ICE direct ory.
BETA REVI EW
4 If you st art ed Soft ICE debuggin g on t h e t arget wit h t h e default
opt ion s, you can con n ect t o t h e mach in e by t ypin g in t h e followin g
comman d:
siremote [machinename]
N o t e : If y o u d o n t kn o w t h e m ach i n e n am e, y o u can su p p l y t h e IP ad d r ess
o f t h e m ach i n e, i n st ead . To g et t h e IP ad d r ess f r o m t h e m ach i n e w i t h
So f t I CE, t y p e n et st at u s f r o m t h e So f t ICE co m m an d l i n e an d n o t e
t h e IP ad d r ess.
If you st art ed n et work debuggin g on t h e Soft ICE t arget wit h addit ion al
opt ion s such as password, or if you n eed t o specify a default gat eway or
subn et mask, you will n eed t o use t h e SIREMOTE comman d lin e ut ilit y
wit h t h e appropriat e opt ion s. (See The SIREMOTE Utility (Host Computer)
page 158, or t ype siremote /help on t h e comman d lin e.)
Ser i a l Connect i on
D e scr ip t io n
Serial con n ect ion offers t h e easiest of t h e remot e con n ect ion opt ion s. It s
performan ce is quit e good at a baud rat e of 57600 an d n ear sin gle-
mach in e performan ce rat e of 115200 baud.
Th ere are t wo Serial Con n ect ion h ardware requiremen t s:
1 A serial port dedicat ed t o Soft ICE use on bot h t h e h ost an d t arget
comput ers.
2 A n ull modem cable.
N o t e : Th ese cab l es a r ead i l y av ai l ab l e at y o u r l o cal co m p u t er st o r e. If y o u
w i sh t o m ake o n e y o u r sel f , see t h e ap p en d i x f o r sp eci f i cs o n cr eat i n g
a n u l l m o d em cab l e.
I n st allat ion
To in st all a serial con n ect ion , perform t h e followin g t wo st eps:
1 Con n ect t h e cable bet ween t h e t wo mach in es. You may wan t t o con -
firm t h at t h e con n ect ion bet ween t h e t wo mach in es is valid by usin g
an y dumb t ermin al program. (HyperTerm sh ips wit h Win dows.)
2 Make sure t h at your con n ect ion opt ion s are set t o t h e appropriat e
set t in gs. If you are run n in g Win 2K or Win XP, you will n eed t o use
t h e Soft ICE Set t in gs ut ilit y t o ch oose wh ich comport you will be
BETA REVI EW
usin g for debuggin g. For t h e followin g example, we will be remot e
debuggin g on COM1 at a speed of 115200 baud.
Rem o val
Th ere are n o special requiremen t s t o un in st all ot h er t h an removin g t h e
cable, if so desired. If you are run n in g Win 2K or Win XP (an d lat er), you
will wan t t o ch an ge Serial Con n ect ion in t h e Soft ICE Set t in gs dialog back
t o None.
To est ablish a con n ect ion you must first t urn on t h e serial debuggin g
opt ion wit h in Soft ICE on t h e t arget comput er (as sh own in t h e followin g
figure).
Fi g u r e 1 0 -3 . Est ab l i sh i n g a Co n n ect i o n
Now, con n ect t o t h e t arget from t h e h ost comput er.
TARGET SIDE: En able serial debuggin g usin g on e of t h e followin g
met h ods:
Click on t h e Aut o Con n ect (via n ull modem) opt ion on t h e Serial
Debuggin g page of Soft ICE set t in gs. (You will n eed t o reboot your
mach in e for t h e ch an ges t o t ake effect .)
BETA REVI EW
OR
From t h e Soft ICE comman d lin e t ype in NET COMx baudrat e
(wh ere COMx is on e of four possible port s COM1, COM2, COM3, or
COM4 an d baudrate is on e of four speeds 19200, 38400, 57600, or
115200).
OR
Add t h e NET COMx baudrate t o t h e in it lin e on t h e Gen eral t ab.
HOST SIDE: En able serial debuggin g as follows:
1 From t h e t arget side, you will n eed t o open up a comman d prompt
an d n avigat e t o t h e Soft ICE direct ory.
2 Execut e t h e SIREMOTE COMx baudrat e (wh ere COMx is t h e comport
t o wh ich t h e cable is con n ect ed an d baudrate is your con n ect speed.)
M odem
D e scr ip t io n
You can operat e Soft ICE remot ely over a modem. Th is is part icularly
useful for debuggin g program fault s t h at occur at an en d-user sit e t h at
you can n ot reproduce locally.
Wh en you operat e Soft ICE over a modem, t h e local PC run s bot h Soft ICE
an d t h e applicat ion you are debuggin g. Th e remot e PC beh aves as a
dumb t ermin al t h at serves t o display t h e out put for your Soft ICE session
an d t o accept keyboard in put . Soft ICE does n ot provide mouse support
for t h e remot e comput er.
Soft ICE h as t h e followin g h ardware requiremen t s for t h e modems you
use t o con n ect t h e local an d remot e syst ems:
Th e modem must accept t h e in dust ry-st an dard AT comman ds such
as ATZ an d ATDT, an d ret urn s st an dard result codes such as RING an d
CONNECT.
Th e modem must execut e a reliable error det ect in g an d correct in g
prot ocol such as V.42 or MNP5. Th is is import an t because t h e com-
mun icat ion prot ocol used by Soft ICE does not include error detec-
tion.
BETA REVI EW
Wh en usin g Soft ICE over a modem, eit h er t h e local or remot e part y can
dial t o in it iat e a con n ect ion .
Do t h e followin g t o est ablish a con n ect ion wh ere t h e local Soft ICE user
(you) dials t h e remot e user:
1 Have t h e remot e user run SIREMOTE.EXE.
2 In voke t h e DIAL comman d on your mach in e.
A con n ect ion is est ablish ed an d t h e remot e user is in con t rol of
Soft ICE.
Do t h e followin g t o est ablish a con n ect ion wh ere t h e remot e user dials
t h e local Soft ICE user:
1 Local Soft ICE user in vokes t h e ANSWER comman d t o prepare t o
an swer a call.
2 Remot e user dials out usin g SIREMOTE.EXE..
A con n ect ion is est ablish ed an d t h e remot e user is in con t rol of
Soft ICE.
Rem o val
Th ere are n o special requiremen t s t o un in st all t h e modem con n ect ion .
SIREMOTE Ut ilit y ( Host Comput er)
Th e support applicat ion , siremote.exe, is t h e fron t en d for all of Soft ICE
remot e debuggin g opt ion s. Wh en usin g t h e DriverSt udio Remot e Dat a
n amespace ext en sion t o con n ect t o Soft ICE on a remot e t arget , you are
essen t ially issuin g a blin d comman d of siremot e ipaddressoft arget .
Th e comman d lin e opt ion s for siremot e.exe vary based upon wh at t ype
of con n ect ion you are usin g.
Serial Con n ect ion Th e on ly opt ion s are COMport an d Baudrat e. For
example:
Siremote COM1 115200 Th is will con n ect t o a remot e t arget wit h
t h e h ost s com port of COM1 at a speed of 115200.
For n et work con n ect ion s, t h e comman ds are similar. For example:
Siremote cartman Th is will con n ect t o t h e remot e t arget n amed
cart man .
BETA REVI EW
Siremote 192.168.0.10 secret Th is will con n ect t o t h e t arget
mach in e wit h an IP address of 192.168.0.10 an d a password of
secret .
NET Command ( Target Comput er)
On t h e t arget comput er, as specified earlier, you can en able remot e
debuggin g eit h er t h rough t h e user in t erface, or from t h e comman d lin e
wit h in Soft ICE. Th e easiest met h od is t o use t h e Soft ICE Set t in gs con fig-
urat ion ut ilit y.
N o t e : An y ch an g es m ad e h er e w i l l t ake ef f ect t h e n ex t t i m e So f t ICE st ar t s.
Th i s m o st o f t en m ean s o n t h e n ex t r eb o o t .
On lin e Help can be viewed by issuin g t h e NET HELP comman d from
wit h in Soft ICE.
:net help
NET SETUP <IP address|DHCP> [MASK=<subn et mask>] [GATEWAY=<IP
address>] [ALLOW=<IP address| ANY>]
[PASSWORD=<password>]
NET START <IP address| DHCP> [MASK=<subn et mask>] [GATEWAY=<IP
address>]
NET COMx [baud-rat e]
NET ALLOW <IP address| ANY> [AUTO] [PASSWORD=<password>]
NET PING <IP address>
NET RESET - Reset t h e curren t con n ect ion
NET DISCONNECT - Reset t h e curren t con n ect ion
NET STOP - Close con n ect ion an d disable n et workin g
NET HELP
NET STATUS
BETA REVI EW
1 6 1
BETA REVI EW
Ch ap t er 1 1
Cust omizing Soft ICE
M od if yin g Sof t I CE I n it ializ at io n Set t in g s
M od if yin g Gen er al Set t in g s
Pr e- load in g Sym b ols an d So urce Co d e
Pr e- load in g Exp o r t s
Co n f ig ur in g Rem ot e D eb ug g in g
M od if yin g Ke yb oar d M ap p in g s
W o r kin g w it h Per sist en t M acr o s
Se t t in g Tr oub lesh o ot in g O p t ion s
Modifying Soft ICE Init ializat ion Set t ings
Soft ICE provides a variet y of user-defin ed set t in gs t h at det ermin e your
debuggin g en viron men t at in it ializat ion . Th ese set t in gs are cat egorized as
follows:
Gen eral Provides a variet y of useful Soft ICE set t in gs, in cludin g an
in it ializat ion st rin g of comman ds t h at aut omat ically execut es wh en
you st art Soft ICE.
Symbols Specifies .NMS symbol files t o load at in it ializat ion for
debuggin g device drivers.
Export s Specifies DLLs an d EXEs from wh ich t o load export sym-
bols at in it ializat ion .
Remot e Debuggin g: In t ern et Con t rol Defin e paramet ers for in t er-
n et access remot e debuggin g over st an dard TCP/ IP et h ern et con n ec-
t ion .
Remot e Debuggin g: Dial up Con t rol Set s a default t eleph on e n um-
ber an d modem in it ializat ion st rin gs for remot e debuggin g over a
serial port .
BETA REVI EW
Keyboard Mappin gs Assign s Soft ICE comman ds t o fun ct ion keys.
Macro Defin it ion s Defin es your own comman ds t o use wit h in
Soft ICE.
Troublesh oot in g Provides solut ion s t o pot en t ial problems.
To modify t h e Soft ICE in it ializat ion set t in gs, do t h e followin g:
2 From wit h in Symbol Loader, ch oose SOFTICE INITIALIZATION SET-
TINGS... from t h e Edit men u.
Soft ICE displays t h e followin g Soft ICE In it ializat ion Set t in gs win dow.
Fi g u r e 1 1 -1 . So f t ICE In i t i al i zat i o n Set t i n g s
3 Select t h e t ab t h at represen t s t h e set t in gs you wan t t o modify.
4 Modify t h e set t in gs an d click OK.
N o t e : Th e f o l l o w i n g sec t i o n s d escr i b e t h ese set t i n g s.
Ch ap t er 1 1 Cu st o m i zi n g So f t ICE 1 6 3
BETA REVI EW
5 Reboot your comput er an d run Soft ICE t o apply your ch an ges.
Modifying General Set t ings
Modify t h e Gen eral Soft ICE in it ializat ion set t in gs as follows:
I ni t i a l i za t i on St r i ng
INITIALIZATION STRING execut es a series of comman ds wh en Soft ICE in it ial-
izes. By default , INITIALIZATION STRING con t ain s t h e X (exit ) comman d
delimit ed wit h a semi-colon , as follows:
X;
You migh t wan t t o add addit ion al comman ds t o INITIALIZATION STRING t o
ch an ge t h e Ct rl-D h ot key sequen ce t h at pops up t h e Soft ICE win dow, t o
ch an ge Soft ICE win dow sizes, t o in crease t h e n umber of lin es displayed
by Soft ICE, or t o use t h e Serial comman d for remot e debuggin g. If you
are debuggin g a device driver, you migh t wan t t o remove t h e X
comman d (or t h e semicolon t h at follows it ) t o preven t Soft ICE from
aut omat ically exit in g upon in it ializat ion .
To add comman ds t o INITIALIZATION STRING, t ype on e or more semicolon
delimit ed comman ds before t h e X (exit ) comman d. Comman ds are
processed in t h e order in wh ich you place t h em. Th us, placin g a
comman d aft er t h e X comman d, mean s t h e comman d does n ot execut e
un t il you pop up t h e Soft ICE win dow. If you t ype a comman d wit h out a
semicolon , Soft ICE loads t h e comman d in t o t h e Comman d win dow, but
does n ot execut e it .
Th e followin g in it ializat ion st rin g swit ch es Soft ICE t o 50-lin e mode,
ch an ges t h e h ot key sequen ce t o Alt -Z, t oggles t h e Regist er win dow on ,
an d exit s from Soft ICE:
LINES 50;ALTKEY ALT Z;WR;X;
N o t e : If y o u t y p e a st r i n g t h at ex ceed s t h e w i d t h o f t h e In i t i al i zat i o n f i el d ,
t h e f i el d au t o m at i cal l y scr o l l s h o r i zo n t al l y t o al l o w y o u t o v i ew t h e
i n f o r m at i o n as y o u en t er i t .
Hi st or y Buf f er Si ze
HISTORY BUFFER SIZE det ermin es t h e size of t h e Soft ICE h ist ory buffer. By
default , t h e Hist ory buffer size is 256KB.
Th e Soft ICE h ist ory buffer con t ain s all t h e in format ion displayed in t h e
Comman d win dow. Th us, savin g t h e Soft ICE h ist ory buffer t o a file is
BETA REVI EW
useful for dumpin g large amoun t s of dat a, disassemblin g code, loggin g
breakpoin t s wit h t h e BPLOG comman d, an d list in g Win dows messages
logged by t h e BMSG comman d. Refer t o Saving the Command Window History
Buffer to a File on page 75.
Tr a ce Buf f er Si ze ( W i nd ow s 9 x Onl y)
Th is set t in g det ermin es t h e size of t h e t race buffer. Th e t race buffer can
main t ain back t race for t h e BPR an d BPRW comman ds. By default , TRACE
BUFFER SIZE is set t o 8 KB.
Tot a l RAM (W i ndow s 9 x Onl y)
Th is set t in g in dicat es t h e amoun t of ph ysical memory in st alled in your
syst em. Set TOTAL RAM t o a value equal t o or great er t h an t o t h e amoun t
of memory on your syst em.
Due t o subt le arch it ect ural differen ces bet ween syst ems, Soft ICE can n ot
det ect t h e amoun t of ph ysical memory in st alled in your comput er un der
Win dows 9x. To map t h e relat ion sh ip bet ween lin ear an d ph ysical
memory, Soft ICE uses a default value of 128 MB. Wh ile t h is value is
reason able for most curren t developmen t syst ems wit h 128 MB or less of
ph ysical memory, t h is does n ot work correct ly on syst ems wit h larger
ph ysical address spaces. Th is is due t o t h e fact t h at appropriat e dat a st ruc-
t ures for memory pages above 128 MB are n ot creat ed.
If your syst em con t ain s less t h an 128 MB of ph ysical memory, you can
save a small amoun t of memory by set t in g t h is field t o t h e righ t value.
Th e memory savin gs result because fewer dat a st ruct ures are n eeded t o
map ph ysical memory.
Di spl a y Di a gnost i c M essa ges
DISPLAY DIAGNOSTIC MESSAGES det ermin es wh et h er or n ot Soft ICE t urn s on
verbose mode t o display addit ion al in format ion , such as module loadin g
an d un loadin g, in t h e Comman d win dow. By default , DISPLAY DIAGNOSTIC
MESSAGES is t urn ed on .
Tr a p N M I
TRAP NMI det ermin es wh et h er Non -maskable in t errupt (NMI) t rappin g is
t urn ed on or off. By default , TRAP NMI is t urn ed on . NMI t rappin g is
useful if you h ave a mean s of gen erat in g an NMI, such as a breakout
swit ch . Gen erat in g an NMI allows you t o en t er Soft ICE even wh en all
BETA REVI EW
in t errupt s are disabled. Simple ISA-based breakout swit ch es are available.
Con t act Compuware for more in format ion .
Low erca se Di sa ssembl y
LOWERCASE DISASSEMBLY det ermin es wh et h er or n ot Soft ICE uses lower-
case let t ers for disassemblin g in st ruct ion s. By default , LOWERCASE DISAS-
SEMBLY is t urn ed off.
Pre-loading Symbols and Source Code
Use t h e Symbols in it ializat ion set t in gs in con jun ct ion wit h t h e Module
Tran slat ion set t in gs t o pre-load symbols an d source code wh en you st art
Soft ICE. Pre-loadin g symbols an d source code is useful for debuggin g
device drivers.
To pre-load symbols or source code, do t h e followin g:
1 In t h e Module Tran slat ion set t in gs, select SYMBOLS AND SOURCE CODE if
you wan t your source code loaded in addit ion t o t h e symbols.
2 Select PACKAGE SOURCE WITH SYMBOL TABLE.
3 In Symbol Loader, ch oose Tran slat e from t h e Module men u t o t ran s-
lat e t h e module t o a .NMS symbol file.
Ti p You ca n u se t h e
Sym b o l Lo a d er
co m m a n d - l i n e u t i l i t y,
N M SYM , t o sp eci f y t h e
ou t p u t f i l e n a m e.
4 Use t h e Symbols Soft ICE In it ializat ion set t in gs t o add your .NMS
symbol file t o t h e Symbols list . Th e followin g sect ion describes h ow
t o do t h is.
N o t e : N o r m al l y, y o u r . N M S sy m b o l f i l e h as t h e sam e b ase n am e as t h e f i l e
y o u t r an sl at ed . Wi t h Wi n d o w s 9 x , So f t ICE can n o t p r e- l o ad f i l es w i t h
l o n g f i l e n am es, b ecau se So f t I CE i s i n r eal - m o d e D O S w h en i t i n i t i al -
i zes. If y o u r m o d u l e i s a l o n g f i l e n am e, cr eat e t h e . N M S f i l e, r en am e
t h e . N M S f i l e t o an ei g h t - ch ar act er n am e w i t h t h e ex t en si o n . N M S,
an d sel ect t h e r en am ed . N M S f i l e w h en y o u ad d i t t o t h e sy m b o l s
l i st .
BETA REVI EW
Addi ng Symbol Fi l es t o t he Symbol s Li st
Ti p W h en you sel ect
PACKAGE SO U RCE W I TH
SYM BO L TABLE, so u r ce
f i l es a r e p a r t o f t h e
. N M S sym b ol f i l e. Th u s,
t h er e a r e n o r est r i ct i on s
on sou rce f i l e n a m e
l en g t h s even w i t h i n
Wi n d ow s 9 x.
From t h e Symbols t ab in t h e Soft ICE In it ializat ion set t in gs, do t h e follow-
in g:
1 Click ADD.
Soft ICE displays a browse win dow for you t o locat e t h e .NMS files
t h at con t ain t h e symbols an d source code you wan t t o pre-load.
2 Select on e or more .NMS symbol files an d click OK.
3 Every t ime you modify your source code, ret ran slat e your module t o
creat e a n ew version of t h e .NMS symbol file.
Removi ng Symbol s a nd Source Code Pr e- Loa di ng
To preven t Soft ICE from pre-loadin g t h e symbols or source code associ-
at ed wit h a part icular file, select t h e file in t h e symbols list an d click
REMOVE.
Reser vi ng Symbol M emor y
SYMBOL BUFFER SIZE specifies, in kilobyt es, t h e amoun t of memory t o
reserve for st orin g cert ain t ypes of debug in format ion (for example, lin e
n umber in format ion ). Wit h Soft ICE for Win dows 9x, t h is memory region
also serves as a buffer for h oldin g .NMS images at boot t ime. By default ,
Soft ICE reserves 1024KB for Win dows 9x an d 512KB for Win dows NT/
2000/ XP.
Typically 512KB is adequat e. However, you may n eed t o in crease t h e
SYMBOL BUFFER SIZE un der t h e followin g circumst an ces:
If you are debuggin g large programs, use 1024KB or more.
If you are usin g Win dows 9x, an d you are loadin g symbols at boot
t ime, det ermin e t h e t ot al size of all t h e .NMS files t h at are loaded at
boot t ime an d set t h e SYMBOL BUFFER SIZE t o t h is n umber.
To det ermin e h ow much symbol memory is available, use t h e TABLE
comman d. Not e t h at most symbol in format ion is st ored in dyn amically-
allocat ed memory.
Pre-loading Export s
Use t h e Export in it ializat ion set t in gs t o select files from wh ich Soft ICE
can ext ract export in format ion upon Soft ICE in it ializat ion . Ext ract in g
BETA REVI EW
export in format ion is useful for debuggin g DLLs wh en n o debuggin g
in format ion is available.
Ext r act in g Exp o r t I n f o r m at ion
To select on e or more files from wh ich t o ext ract export in format ion , do
t h e followin g:
1 Click ADD. Soft ICE displays a browse win dow for you t o locat e t h e
files.
N o t e : If y o u ar e co n n ect ed t o a n et w o r k, y o u can cl i c k NETWORK t o d i sp l ay
t h e co n t en t s o f n et w o r ked d r i v es.
2 Select on e or more files from wh ich t o ext ract t h e in format ion an d
click OK.
3 Soft ICE places t h e files you select ed in t h e Export s list .
Rem o vin g Files f r om t h e Exp o r t s List
To remove a file from t h e Export s list , select t h e file an d click REMOVE.
Configuring Remot e Debugging
Remot e Soft ICE allows you t o use a st an dard in t ern et con n ect ion t o
remot ely con t rol Soft ICE. Th is allows great er flexibilit y an d easier access
for debuggin g fun ct ion s. Remot e Soft ICE is support ed by Win dows 9x
an d Win dows NT/ 2000/ XP.
Requi r ement s f or Remot e Sof t I CE Suppor t
Th e mach in e t h at run s Soft ICE is referred t o as t h e target mach in e.
Th e t arget mach in e requires a support ed et h ern et adapt er t h at is con -
n ect ed t o t h e local IP n et work.
Curren t ly support ed Et h ern et adapt ers are:
NE2000 an d compat ibles (use NE2000.SYS)
3Com 3C90X (use EL90X.SYS)
In t el E100 Series Net work Adapt er
Th e mach in e t h at con t rols t h e t arget mach in e is called t h e host
mach in e.
BETA REVI EW
Th e h ost must be con n ect ed t o an IP n et work t h at is direct ly or in di-
rect ly con n ect ed t o t h e IP n et work of t h e t arget mach in e. Th e h ost
must also be run n in g Win dows 9x or Win dows NT/ 2000/ XP.
Set t i ng Up Sof t I CE f or Remot e Debuggi ng
Verify t h e t arget syst em is operat in g properly usin g a support ed adapt er
an d driver. Replace t h e adapt er driver file (for Win dows NT/ 2000/ XP, it s
in t h e \ WINNT\ SYSTEM32\ DRIVERS direct ory; for Win down s 9x, it s in
t h e \ WINDOWS\ SYSTEM direct ory) wit h t h e file of t h e same n ame from
t h e dist ribut ion . Ren ame t h e origin al driver file in case you n eed it again .
Aft er replacin g t h e driver file, you will n eed t o reboot t h e syst em in order
t o use Remot e Soft ICE.
N o t e : In f o r m at i o n f o r c o n f i g u r i n g So f t ICE f o r r em o t e d eb u g g i n g o ver a
ser i al cab l e can b e f o u n d i n t h e D r i ver St u d i o a n d So f t I CE D r i ver Su i t e
I n st a l l a t i on Gu i d e.
Ena bl i ng Remot e Debuggi ng f r om t he Ta r get Si de
On ce t h e correct adapt er an d driver is in st alled, Soft ICE will n ot allow
remot e debuggin g un t il it is en abled usin g t h e NET comman ds. Th e
followin g comman ds are available:
NET START
NET ALLOW
NET PING
NET RESET
NET STOP
NET HELP
NET STATUS
N ET START Co m m an d
Th e NET START comman d (NET START <IP address|DHCP>
[MASK=<subnet mask>] [GATEWAY=<IP address>]) en ables t h e IP
st ack wit h in Soft ICE. Th is comman d iden t ifies your IP paramet ers t o
Soft ICE (IP address, subn et mask, an d gat eway address). If your local
n et work support s DHCP (Dyn amic Host Con figurat ion Prot ocol), you
can t ell Soft ICE t o obt ain t h e IP paramet ers from your n et work DHCP
server. At t h is poin t , t h e IP st ack is run n in g but Soft ICE does n ot allow
remot e debuggin g un t il you get an IP address.
BETA REVI EW
N ET ALLO W Com m an d
Th e NET ALLOW comman d (NET ALLOW <IP address| ANY> [AUTO]
[PASSWORD=<password>]) defin es wh ich mach in es can be used t o
remot ely con t rol Soft ICE.
A remot e mach in e can be defin ed as a specific IP address, or ANY IP
address.
If t h e AUTO opt ion was specified on t h e NET ALLOW comman d,
t h en it is n ot n ecessary t o issue t h e NET ALLOW comman d t o en able
a n ew session aft er closin g t h e curren t session .
Access t o Soft ICE con t rol can also be qualified wit h a case-sen sit ive
password.
Wh en you begin a remot e debuggin g session , Soft ICE will pop up on t h e
t arget mach in e, n o mat t er wh at t h e curren t st at e of t h e mach in e.
N ET PI N G Com m an d
Th e NET PING comman d (NET PING <IP address>) allows you t o do a
basic n et work con n ect ivit y t est by sen din g an ICMP Ech o Request (PING)
packet t o an IP address. Soft ICE sen ds t h e request an d in dicat es if it
receives a respon se wit h in four secon ds.
N ET RESET Co m m an d
Th e NET RESET comman d t ermin at es an y act ive remot e debuggin g
session , or can cels t h e effect of t h e previous NET ALLOW comman d. Use
t h e NET ALLOW comman d t o re-en able remot e debuggin g.
N ET STO P Com m an d
Th e NET STOP comman d t ermin at es an y act ive remot e debuggin g
session , or can cels t h e effect of t h e previous NET ALLOW comman d. It
also disables t h e IP st ack an d t h e n et work adapt er.
N ET H ELP Com m an d
Th e NET HELP comman d sh ows a list of t h e available n et work
comman ds wit h t h eir respec-t ive syn t ax.
N ET STATU S Com m an d
Th e NET STATUS comman d sh ows t h e curren t st at us of t h e n et work
adapt er (if t h e NET START comman d h as been issued, t h is in cludes t h e
BETA REVI EW
n ode address). It also displays t h e cur-ren t IP paramet ers (IP address,
subn et mask, an d gat eway) an d t h e st at us of t h e remot e debuggin g
con n ect ion .
St a r t i ng t he Remot e Debug gi ng Sessi on
On ce t h e t arget is set up for remot e debuggin g, t h e remot e mach in e can
issue t h e SIREMOTE comman d. Followin g is t h e syn t ax for t h e
SIREMOTE comman d.
SIREMOTE <target IP address> [<password>]
Th e t ar g et I P ad d r ess is t h e IP address assign ed t o t h e et h ern et adapt er in
t h e t arget mach in e. If t h e t arget mach in e uses a password, specify t h e
case-sen sit ive password on t h e comman d lin e.
SIREMOTE t ries t o creat e a con n ect ion t o t h e t arget mach in e. If t h e t arget
mach in e respon ds, SIREMOTE aut h en t icat es t h e remot e mach in e wit h
t h e specified password (blan k if n o password is bein g used). If t h e t arget
accept s t h e aut h en t icat ion of t h e remot e mach in e, Soft -ICE makes t h e
con n ect ion an d SIREMOTE obt ain s t h e curren t screen paramet ers of t h e
t arget mach in e. A con sole win dow emulat es t h e Soft ICE display, wh ich is
visible on bot h t h e t arget an d remot e mach in es.
All st an dard Soft ICE keys react wh et h er t h ey are en t ered from t h e remot e
or t arget keyboard. Th e on ly except ion is t h at t h e pop-up key on t h e
remot e mach in e is always Ct rl-D, even if it is redefin ed on t h e t arget
mach in e.
To t ermin at e t h e remot e Soft ICE session , press Ct rl-Break on t h e remot e
keyboard, or use t h e NET RESET comman d from t h e t arget mach in e.
Conf i gur i ng Remot e Debuggi ng w i t h a M od em
Th e Remot e Debuggin g set t in gs allow you t o defin e t h e t ype of serial
con n ect ion , an d preset a modem in it ializat ion st rin g an d ph on e n umber
for t h e DIAL an d ANSWER comman ds. Alt ern at ely, you can specify t h ese
paramet ers direct ly wh en usin g t h e comman ds. Refer t o your modem
documen t at ion for t h e exact comman ds for your part icular modem.
Te lep h o n e N um b e r
TELEPHONE NUMBER preset s a ph on e n umber for t h e DIAL comman d, for
example, 717-555-1212.
BETA REVI EW
Ser ial Con n ect ion ( W in d ow s 9 x O n ly)
If you are usin g Soft ICE for Win dows 9x, an d are debuggin g a remot e
syst em, ch oose t h e commun icat ion s port on t h e local syst em (COM1,
COM2, COM3, or COM4) t h at you are usin g for serial commun icat ion .
Wh en you are t h rough debuggin g t h e remot e syst em, ch an ge t h is set t in g
t o Non e. By default , SERIAL CONNECTION is set t o Non e.
N o t e : If y o u ar e u si n g So f t ICE f o r Wi n d o w s N T/ 2 0 0 0 / XP, So f t ICE au t o m at i -
cal l y d et er m i n es y o u r ser i al co n n ec t i o n .
D I AL I n it ializ at ion St r in g
DIAL INITIALIZATION STRING preset s t h e modem in it ializat ion st rin g for t h e
DIAL ccomman d, for example, ATX0.
AN SW ER I n it ializ at io n St r in g
ANSWER INITIALIZATION STRING preset s t h e modem in it ializat ion st rin g for
t h e ANSWER comman d, for example, ATX0.
Modifying Keyboard Mappings
Use Keyboard Mappin gs t o reassign comman ds t o Soft ICE fun ct ion keys
or t o specify n ew on es. You can assign Soft ICE comman ds t o an y of t h e
t welve fun ct ion keys or key combin at ion s in volvin g Sh ift , Ct rl, or Alt
an d a fun ct ion key.
N o t e : Key b o ar d m ap p i n g s assu m es t h at y o u ar e u si n g a Q WERTY key -
b o ar d l ay o u t . If y o u h ap p en t o b e u si n g a n o n - Q W ERTY l ay o u t key -
b o ar d , y o u w i l l n eed t o co p y t h e i n cl u d ed ke ym ap . exe u t i l i t y p r o -
g r am i n t o y o u r \ w i n n t \ sy st em 3 2 \ d r i ver s d i r ect o r y an d ex ecu t e
keym ap . If So f t ICE i s cu r r en t l y r u n n i n g , r eb o o t y o u r sy st em so t h e
ch an g es can t ake ef f ect . Ru n n i n g key m ap w i l l r em ap al l t h e key -
b o ar d sc an co d es t o t h e key b o ar d l ay o u t t h at i s cu r r en t l y b ei n g u sed
b y Wi n d o w s. Th e o n e key co m b i n at i o n t h at can n o t b e r em ap p ed i s
t h e p o p u p h o t key. Th e p o p u p h o t key w i l l al w ay s b e t h e t h i r d ch ar -
act er f r o m t h e l ef t o n t h e seco n d r o w ab o v e t h e sp ace b ar. To r eset
t h e key b o ar d scan co d es b ack t o t h ei r d ef au l t s, r u n ke ym ap / U SA. '
Comma nd Synt a x
Wh en modifyin g an d creat in g fun ct ion keys, you can use an y valid
Soft ICE comman d an d t h e ch aract ers; caret (^) an d semicolon (;). Place a
caret (^) at t h e begin n in g of a comman d t o in st ruct Soft ICE t o execut e
BETA REVI EW
t h e comman d wit h out placin g it in t h e comman d lin e. Th e semicolon
beh aves like t h e En t er key an d in st ruct s Soft ICE t o execut e t h e
comman d. You can place on e or more semicolon s in t h e same st rin g.
M odi f yi ng Funct i on Keys
Soft ICE uses t h e followin g abbreviat ion s for t h e Fun ct ion , Alt , Ct rl, an d
Sh ift keys:
To modify t h e Soft ICE comman d assign ed t o a fun ct ion key, do t h e
followin g:
1 Select t h e fun ct ion key you wan t t o modify from t h e list of keyboard
mappin gs an d click ADD.
2 Ch an ge t h e comman d in t h e Comman d field an d click OK.
Cr ea t i ng Funct i on Keys
To assign a comman d t o a n ew fun ct ion key or fun ct ion key combin a-
t ion , do t h e followin g:
1 Det ermin e a fun ct ion key or fun ct ion key combin at ion t o wh ich n o
comman ds are assign ed.
2 Click ADD.
3 Select t h e fun ct ion key you wan t t o use from t h e Key list .
4 Select a modifier. To assign a comman d t o a fun ct ion key, click NONE.
To assign a comman d t o a fun ct ion key combin at ion , select SHIFT,
CTRL, or ALT.
5 Type a comman d in t h e Comman d field an d click OK.
Del et i ng Funct i on Keys
To delet e a fun ct ion key assign men t , ch oose t h e fun ct ion key an d click
REMOVE.
Tab l e 1 1 - 1 . Fu n ct i o n Key Ab b r ev i at i o n s
Ke y Ab b r eviat io n Exam p le
Fu n ct i o n F F1
Al t A AF1
Ct r l C CF1
Sh i f t S SF1
BETA REVI EW
Rest or i ng Funct i on Keys
Th e followin g t able list s t h e default fun ct ion key assign men t s.
You can modify in dividual fun ct ion key assign men t s or click RESTORE
DEFAULTS t o rest ore all t h e keys you edit ed or removed t o t h eir origin al
set t in gs. RESTORE DEFAULTS does n ot remove an y fun ct ion keys you
creat e.
Working wit h Persist ent Macros
Macros are user-defin ed comman ds t h at you can use in t h e same way as
built -in comman ds. Th e defin it ion , or body, of a macro con sist s of a
sequen ce of comman d in vocat ion s. Th e allowable set of comman ds
in cludes ot h er user-defin ed macros an d comman d-lin e argumen t s.
Th ere are t wo ways t o creat e macros. You can creat e run -t ime macros t h at
exist un t il you rest art Soft ICE or persist en t macros t h at are saved in t h e
in it ializat ion file an d aut omat ically loaded wit h Soft ICE. Th is sect ion
describes h ow t o creat e persist en t macros. Refer t o Using Run-time Macros
on page 73 for more in format ion about creat in g run -t ime Macros.
Tab l e 1 1 - 2 . D ef au l t Fu n ct i o n Key Assi g n m en t s
Ke y Assi g n m e n t Key Assig n m en t
F1 H; F12 ^P RET;
F2 ^WR; SF3 ^FORMAT;
F3 ^SRC; AF1 ^WR;
F4 ^RS; AF2 ^WD;
F5 ^X; AF3 ^WC;
F6 ^EC; AF4 ^WW;
F7 ^HERE; AF5 CLS;
F8 ^T; AF11 dd dataaddr->0;
F9 ^BPX; AF12 dd dataaddr->4;
F10 ^P; F12 ^P RET;
F11 ^G @SS:ESP; SF3 ^FORMAT;
BETA REVI EW
Cr ea t i ng Per si st ent M a cr os
To creat e a persist en t macro, do t h e followin g:
1 Click ADD.
Th e Add Macro defin it ion win dow appears.
2 Type t h e n ame of t h e macro in t h e Name field.
Th e macro n ame may be from t h ree t o eigh t ch aract ers lon g an d may
con t ain an y alph a-n umeric ch aract er or un derscore (_). It must
in clude at least on e alph abet ic ch aract er. A macro-n ame can n ot
duplicat e an exist in g Soft ICE comman d.
3 Type t h e macro defin it ion in t h e Defin it ion field.
Th e defin it ion of a macro is a sequen ce of Soft ICE comman ds or
ot h er macros separat ed by semicolon s. You are n ot required t o t ermi-
n at e t h e fin al comman d wit h a semicolon . Comman d-lin e
argumen t s t o t h e macro can be referen ced an ywh ere in t h e macro
body wit h t h e syn t ax %<parameter#>, wh ere parameter# is a n umber
bet ween on e an d eigh t .
Example: The command MACRO asm = a %1 defines an alias for
the A (ASSEMBLE) command. The %1 is replaced with the first
argument following asm or simply removed if no argument is
supplied.
If you need to embed a literal quote character () or a
percent sign (%) within the macro body, precede the character
with a backslash character (\). To specify a literal backslash
character, use two consecutive backslashes (\\).
N o t e : Al t h o u g h i t i s p o ssi b l e f o r a m acr o t o cal l i t sel f r ecu r si v el y, i t i s n o t
p ar t i cu l ar l y u sef u l , b ecau se t h er e i s n o p r o g r am m at i c w ay t o t er m i -
n at e t h e m acr o . If t h e m acr o cal l s i t sel f as t h e l ast co m m an d o f t h e
m acr o ( t ai l r ecu r si o n ) , t h e m acr o ex ecu t es u n t i l y o u u se t h e ESC key
t o t er m i n at e i t . If t h e r ecu r si v e c al l i s n o t t h e l ast co m m an d i n t h e
m acr o , t h e m acr o ex ecu t es 3 2 t i m es ( t h e n est i n g l i m i t ) .
4 Click OK. Soft ICE places your persist en t macro in t h e Macro Defin i-
t ion s list .
M acr o D ef in it io n Exam p les
Th e followin g t able provides examples of legal macro comman ds.
Tab l e 1 1 - 3 . Leg al M acr o Co m m an d s
Le g al N am e Le g al D ef in i t i on Exam p le
Q ex p ad d r ex p l o r er ; Q u er y % 1 Q ex p
BETA REVI EW
Th e followin g t able provides examples of illegal macro comman ds:
St a r t i ng a nd St oppi ng Per si st ent M a cr os
Type t h e n ame of t h e persist en t macro t o execut e it . To st op t h e execu-
t ion of a persist en t macro, press t h e ESC key.
Set t in g t h e M acr o Lim it
Use MACRO LIMIT t o specify t h e maximum n umber of macros an d break-
poin t act ion s you can defin e durin g a Soft ICE session . Th is n umber
Q ex p 1 4 0 0 0 0
1 sh o t b p x % 1 d o \ b c b p i n d ex \ 1 sh o t ei p
o r
1 sh o t @esp
d d t d d t h r ead d d t
d d p d d p r o cess d d p
t h r t h r ead % 1 t i d t h r
o r
t h r - x
d m y f i l e m acr o m y f i l e = \ TABLE % 1 ; f i l e
\ % 1 \
d m y f i l e m y t ab l e
m y f i l e m y f i l e. c
Tab l e 1 1 - 4 . Il l eg al M acr o Co m m an d s
I lle g al N am e or
D ef in i t i on
Exp lan at ion
Name: DD
Definition: dd
dataaddr
Th i s m acr o u ses t h e n am e o f a So f t ICE co m m an d .
So f t ICE co m m an d s can n o t b e r ed ef i n ed .
Name: AA
Definition: addr %1
Th e m acr o co m m an d n am e i s t o o sh o r t . A m acr o
n am e m u st b e b et w een 3 an d 8 ch ar act er s l o n g .
Name: tag
Definition: ? *(%2-4)
Th e m acr o b o d y r ef er en ces p ar am et er % 2 w i t h o u t
r ef er en ci n g p ar am et er % 1 . Yo u can n o t r ef er en ce
p ar am et er % n + 1 w i t h o u t r ef er en ci n g p ar am et er
% n .
Tab l e 1 1 - 3 . Leg al M acr o Co m m an d s
Le g al N am e Le g al D ef in i t i on Exam p le
BETA REVI EW
in cludes bot h run -t ime macros an d persist en t macros. Th e default value
of 32 is t h e min imum value. Th e maximum value is 256.
M od if yin g Per sist e n t M acr os
To modify a persist en t macro, do t h e followin g:
1 Select t h e persist en t macro you wan t t o modify an d click ADD.
2 In t h e Add macro defin it ion s win dow, modify t h e Name an d Defin i-
t ion fields as appropriat e, t h en click OK.
D elet in g Per sist en t M acr os
To delet e a persist en t macro, select t h e macro you wan t t o delet e an d
click REMOVE.
Set t ing Troubleshoot ing Opt ions
Ti p I f you w a n t t o
r et u r n a l l t h e
t r o u b l esh oot i n g
set t i n g s t o t h ei r or i g i n a l
st a t es, cl i ck RESTORE
DEFAULTS.
Th e followin g set t in gs let you t roublesh oot Soft ICE. Modify t h ese
set t in gs on ly wh en direct ed t o do so by Compuware Tech n ical Support or
t o remedy t h e specific sit uat ion s described wit h in t h is documen t at ion .
By default , t h e Troublesh oot in g set t in gs are all t urn ed off.
Di sa bl e M ouse Suppor t
If you are h avin g problems usin g your mouse in Soft ICE, select DISABLE
MOUSE SUPPORT.
Di sa bl e N um Lock a nd Ca ps Lock Pr ogr a mmi ng
Ti p I f you ve t u r n ed on
m or e t h a n on e
t r o u b l esh oot i n g set t i n g
a n d you w a n t t o t u r n
a l l t h e set t i n g s of f , u se
Rest o r e D ef a u l t s
i n st ea d of cl i cki n g ea ch
i n d i vi d u a l ch eck b o x.
If your keyboard locks or beh aves errat ically wh en you load Soft ICE,
select DISABLE NUM LOCK AND CAPS LOCK PROGRAMMING. If t h is does n ot
solve t h e problem an d you are usin g Win dows NT/ 2000/ XP, t ry t h e DO
NOT PATCH KEYBOARD DRIVER set t in g.
BETA REVI EW
Do N ot Pa t ch Keyboa r d Dr i ver (W i ndow s N T/ 2 0 0 0 / XP Onl y)
If your keyboard locks or beh aves errat ically wh en you load Soft ICE,
select t h is set t in g t o preven t Soft ICE from pat ch in g t h e keyboard driver.
Wh en you select t h is opt ion , Soft ICE uses an alt ern at e, t ypically less
robust , met h od for keyboard h an dlin g. If t h is does n ot solve t h e
problem, t ry t h e DISABLE NUM LOCK AND CAPS LOCK PROGRAMMING set t in g.
Di sa bl e M a ppi ng of N on- Pr esent Pa ges
Soft ICE at t empt s t o fin d a page in ph ysical memory even if t h e page t able
en t ry is marked as n ot presen t . Select DISABLE MAPPING OF NON-PRESENT
PAGES t o t urn off t h is feat ure.
Di sa bl e Pent i um Suppor t
Soft ICE aut omat ically det ect s wh et h er or n ot you are usin g a Pen t ium
processor. If you are usin g a n ew CPU wit h wh ich Soft ICE is un familiar
an d Soft ICE mist aken ly det ermin es t h at you are usin g a Pen t ium proces-
sor, select t h is set t in g t o t urn off Pen t ium support .
Di sa bl e Thr ea d- Speci f i c St eppi ng
Th e P (st ep over) comman d is t h read sen sit ive. Th e ret urn breakpoin t set
by t h e P comman d t riggers on ly for t h e t h read t h at was act ive wh en t h e
P comman d was issued. Not e t h at you would n ormally wan t t o be in t h e
same t h read you are debuggin g. To t urn off t h is feat ure, select DISABLE
THREAD-SPECIFIC STEPPING.
BETA REVI EW
1 7 9
BETA REVI EW
Ch ap t er 1 2
Exploring Windows NT
O ve r vie w
I n sid e t h e W in d ow s N T Ke r n e l
W in 3 2 Sub syst em
Overview
Wit h out qualificat ion , t h e Win dows NT operat in g syst em family
(Win dows NT, Win dows 2000, an d Win dows XP) represen t s an in credible
feat of soft ware en gin eerin g an d syst em design . It is h ard t o imagin e a
design of such complexit y reach in g all of it s goals, in cludin g t h ree of t h e
most difficult : port abilit y, reliabilit y, an d ext en sibilit y, wit h out compro-
misin g eit h er in t erfaces or implemen t at ion . Yet , someh ow t h e syst em
en gin eers at MicroSoft wh o design an d develop t h e Win dows NT operat -
in g syst em family h ave man aged t o keep each an d every compon en t of
t h ese syst ems smoot h ly in t erlocked, n ot un like t h e precision gears of a
fin ely-made wat ch . If you are goin g t o writ e Win dows NT family applica-
t ion s, you sh ould explore wh at lies ben eat h your applicat ion code: t h e
operat in g syst em. Th e kn owledge you gain from t h e t ime you in vest t o
go ben eat h your applicat ion an d in t o t h e dept h s of t h e syst em, will
ben efit bot h you an d t h e applicat ion or driver t h at you are creat in g.
Th is ch apt er provides a quick overview of t h e more pert in en t an d in t er-
est in g aspect s of t h e basic Win dows NT Operat in g Syst em. By combin in g
t h is in format ion wit h available referen ce mat erial an d a lit t le pract ical
applicat ion usin g Soft ICE, you sh ould be able t o gain a basic un derst an d-
in g of h ow t h e compon en t s of Win dows NT fit t oget h er.
Resources f or Adva nced Debugg i ng
Microsoft provides several resources for advan ced Win dows NT debug-
gin g in cludin g: ch ecked build, t h e Win dows NT DDK, .DBG files, an d
Kern el Debugger Ext en sion s.
BETA REVI EW
Ch ecked Build
If you are n ot curren t ly usin g t h e ch ecked build (t h at is, t h e debug
version ) of Win dows NT, you are missin g a lot of valuable in format ion
an d debuggin g support t h at t h e operat in g syst em provides. Th e ch ecked
build con t ain s a wealt h of in format ion t h at is absen t from t h e free build
(ret ail version ). Th is in cludes basic debug messages, special flags used by
t h e kern el compon en t s t h at allow you t o t race t h e syst ems operat ion ,
an d relat ively st rict san it y ch eckin g of most syst em API calls. Th e size
an d layout of syst em dat a st ruct ures as well as t h e implemen t at ion of
syst em APIs in t h e ch ecked build are n early iden t ical t o t h at of t h e free
build. Th is allows you t o learn an d explore usin g t h e more verbose
ch ecked build, but st ill feel complet ely comfort able if you en d up debug-
gin g un der t h e free build. All in all, if you wan t t o writ e more robust
applicat ion s an d drivers, use t h e ch ecked build.
W in d o w s N T D D K
Th e Win dows NT DDK con t ain s h eader files, sample code, on -lin e h elp,
an d special t ools t h at let you query various kern el compon en t s. Th e most
obvious an d useful resource is NTDDK.H. Alt h ough t h ere is quit e a bit of
in format ion missin g from t h is h eader file, en ough pert in en t in format ion
is available t o make it wort h st udyin g. Besides t h e basic dat a st ruct ures
n eeded for device driver developmen t , syst em dat a st ruct ures are
described (some complet ely, ot h ers briefly, man y n ot at all). Th ere are
also man y API prot ot ypes an d t ype en umerat ion s t h at are useful for bot h
explorat ion an d developmen t . Th ere are also useful commen t s about t h e
syst em design , as well as rest rict ion s an d limit at ion s. Most of t h e ot h er
h eader files in t h e DDK are specific t o t h e more esot eric aspect s of t h e
syst em, but NTDEF.H, BUGCODES.H, an d NTSTATUS.H are gen erally
useful.
Th e Win dows NT DDK in cludes a few ut ilit ies t h at are of gen eral in t erest .
For example, POOLMON.EXE allows you t o mon it or syst em pool usage,
an d OBJDIR.EXE provides in format ion on t h e Object Man ager h ierarch y
an d in format ion about a specific object wit h in t h e h ierarch y. Soft ICE for
Win dows NT provides similar fun ct ion alit y wit h t h e OBJDIR, DEVICE,
an d DRIVER comman ds. Th e ut ilit y DRIVERS.EXE, like t h e Soft ICE MOD
comman d, list s all drivers wit h in t h e syst em, in cludin g basic in format ion
about t h e driver. Some version s of t h e Win dows NT DDK in clude a sign if-
ican t ly more powerful version of t h e st an dard PSTAT.EXE ut ilit y. PSTAT is
a Win 32 con sole applicat ion t h at provides summary in format ion on
processes an d t h reads. In cluded wit h t h e Win 32 SDK an d t h e Visual C++
compiler, are t wo ut ilit ies wort h n ot in g: PVIEW an d SPY++. Bot h provide
Ch ap t er 1 2 Ex p l o r i n g Wi n d o w s N T 1 8 1
BETA REVI EW
in format ion on processes an d t h reads, an d SPY++ provides HWND an d
CLASS in format ion .
Th e Win dows NT DDK also in cludes h elp files an d referen ce man uals for
device driver developmen t , as well as sample code. Th e sample code is
most useful, because it provides you wit h t h e in format ion n ecessary for
creat in g act ual Win dows NT device drivers. Simply fin d somet h in g in
your area of in t erest , build t h at sample, an d st ep t h rough it wit h Soft ICE.
. D BG File s
Ti p Usi n g . D BG f i l es i s
p r o b a b l y t h e m ost
i m p or t a n t a sp ect of
set t i n g u p you r
d evel o p m en t a n d
d eb u g g i n g
en vi r on m en t . Sel ect
t h ose com p o n en t s t h a t
a r e m ost r el eva n t t o
you r d evel op m en t
n eed s, f i n d t h e
co r r esp on d i n g . D BG f i l e
a n d u se Sym b o l Loa d er
t o cr ea t e a . N M S f i l e
t h a t So f t I CE ca n l o a d .
Microsoft provides a separat e DBG file for every dist ribut ed execut able
file wit h bot h t h e ch ecked an d free builds of t h e Win dows NT operat in g
syst em. Th is in cludes t h e syst ems compon en t s t h at make up t h e kern el
execut ive, device drivers, Win 32 syst em DLLs, sub-syst em processes,
con t rol pan el applet s, an d even accessories an d games. Th e .DBG files
con t ain basic debug in format ion similar t o t h e PUBLIC defin it ion s of a
.MAP file. Every API an d global variable, export ed or ot h erwise, h as a
basic defin it ion (for example, n ame, sect ion an d offset ). Advan ced t ype
in format ion such as st ruct ures an d locals is n ot provided, but h avin g
access t o a public defin it ion for each API makes debuggin g t h rough
syst em calls a lot easier.
Regardless of your specific area of in t erest , load symbols for t h e followin g
key syst em compon en t s. Th e most import an t compon en t s are list ed in
bold t ypeface.
Tab l e 1 2 - 1 . Key Sy st em Co m p o n en t Sy m b o l s
Com p o n e n t D escr i p t io n
N TO SKRN L. EX E Th e Wi n d o w s N T Ker n el . ( M o st o f t h e o p er at -
i n g sy st em r esi d es h er e. )
HAL. D LL Th e Har d w ar e Ab st r act i o n Lay er. Im p o r t an t
p r i m i t i v es f o r N TO SKRN L.
N TD LL. D LL Basi c i m p l em en t at i o n o f t h e Wi n 3 2 API, an d
f u n ct i o n al i t y t r ad i t i o n al l y at t r i b u t ed t o KER-
N EL. Al so t h e i n t er f ace b et w een USER an d
SYSTEM m o d e. Essen t i al l y r ep l aces
KERN EL3 2 . D LL.
CSRSS. EXE Th e Wi n 3 2 su b sy st em ser v er p r o cess. M o st
su b sy st em cal l s ar e r o u t ed t h r o u g h t h i s p r o -
cess.
W I N SRV. D LL Un d er Wi n d o w s N T 3 . 5 1 , t h e co r e i m p l em en -
t at i o n o f USER an d GD I f u n ct i o n al i t y. O n l y
l o ad ed i n t h e co n t ex t o f CSRSS.
BETA REVI EW
Reso urces
Th e followin g resources provide ext en sive in format ion for developin g
drivers an d applicat ion s for Win dows NT:
Microsoft Developers Network (MSDN)
MSDN is publish ed quart erly, on CD-ROM, an d it con t ain s a wealt h
of in format ion an d art icles on all aspect s of programmin g Microsoft
operat in g syst ems. Th is is on e of t h e on ly places wh ere you can fin d
pract ical in format ion on writ in g Win dows NT device drivers.
Inside Windows NT - Helen Cust er, Microsoft Press
Inside Windows NT provides a h igh -level view of t h e design for t h e
Win dows NT operat in g syst em. Each of t h e major sub-syst ems is
t h orough ly discussed, an d man y block diagrams illumin at e in t ern al
dat a st ruct ures, policies, an d algorit h ms. Alt h ough t h e con t en t s of
t h is book may seem h igh ly abst ract ed from t h e act ual operat in g
syst em implemen t at ion , on ce you st ep in t o OS code wit h Soft ICE,
man y of t h e h igh er level relat ion sh ips become clear. Curren t ly, t h is is
t h e most valuable set of in format ion on Win dows NT operat in g
syst em in t ern als. You will gain t h e most ben efit from t h e in format ion
in t h is book if you use Soft ICE t o explore t h e act ual implemen t at ion
of t h e syst em design .
Advanced Windows - Jeffery Rich t er, Microsoft Press
Advanced Windows is an excellen t resource for t h e syst ems programmer
developin g Win 32 applicat ion s an d syst em code. Rich t er presen t s
ext en sive discussion s of processes, t h reads, memory man agemen t ,
an d syn ch ron izat ion object s. Relevan t sample code an d ut ilit ies are
also provided.
W I N 3 2 K. SYS A sy st em d evi ce d r i ver t h at r ep l aces W IN -
SRV. D LL an d m i n i m i zes i n t er - p r o cess co m m u -
n i cat i o n b et w een ap p l i cat i o n s an d CSRSS.
M ay n o t b e avai l ab l e f o r al l v er si o n s o f t h e O S.
USER3 2 . D LL Basi c i m p l em en t at i o n o f USER f u n ct i o n al i t y.
M o st l y st u b s t o W IN SRV. D LL ( v i a LPC t o
CSRSS) . M o r e r ecen t v er si o n s co n t ai n m o r e
i m p l em en t at i o n t o m i n i m i ze co n t ex t sw i t ch es.
KERN EL3 2 . D LL. So m e b asi c i m p l em en t at i o n o f t r ad i t i o n al KER-
N EL f u n ct i o n al i t y, b u t m o st l y st u b s t o
N TD LL. D LL.
Tab l e 1 2 - 1 . Key Sy st em Co m p o n en t Sy m b o l s
Com p o n e n t D escr i p t io n
BETA REVI EW
Inside t he Windows NT Kernel
To gain a basic un derst an din g of Win dows NT, look at t h e plat form from
man y differen t perspect ives. A gen eral kn owledge of h ow Win dows NT
works at differen t levels en ables you t o un derst an d t h e con st rain t s an d
assumpt ion s in volved in design in g ot h er aspect s of t h e operat in g syst em.
Th is sect ion explain s t h e most crit ical compon en t of t h e operat in g
syst em, t h e Win dows NT Kern el. It describes h ow Win dows NT con fig-
ures t h e core operat in g syst em dat a st ruct ures, such as t h e IDT an d TSS,
an d h ow t o use correspon din g Soft ICE comman ds t o illust rat e t h e
Win dows NT con figurat ion of t h e CPU. It also examin es a gen eral map of
t h e Win dows NT syst em memory area, describin g import an t syst em dat a
st ruct ures an d examin in g t h e crit ical role t h ey play wit h in t h e operat in g
syst em.
A majorit y of t h e in format ion in t h is sect ion is based on t h e implemen t a-
t ion det ails of t h e followin g t wo modules:
Hardware Abst ract ion Layer (HAL.DLL)
HAL is t h e Win dows NT h ardware abst ract ion layer. It s purpose is t o
isolat e as man y h ardware plat form depen den cies as possible in t o on e
module. Th is makes t h e Win dows NT kern el code h igh ly port able.
Various part s of t h e kern el use plat form depen den t code, but on ly for
performan ce con siderat ion s.
Th e primary respon sibilit y of t h e HAL is t o deal wit h very low-level
h ardware con t rol such as In t errupt con t roller programmin g,
h ardware I/ O, an d mult iprocessor in t er-commun icat ion . Man y of t h e
HAL rout in es are dedicat ed t o dealin g wit h specific bus t ypes (PCI,
EISA, ISA) an d bus adapt er cards. HAL also con t rols basic fault
h an dlin g an d in t errupt dispat ch .
Th e Kern el (NTOSKRNL.EXE)
Th e vast majorit y of t h e Win dows NT operat in g syst em resides in t h e
Win dows NT Kern el, or Kern el Execut ive. Th is is t h e kern el-level
fun ct ion alit y t h at all ot h er syst em compon en t s, such as t h e Win 32
subsyst em, are built upon . Th e Kern el Execut ive Services cover a
broad ran ge of fun ct ion alit y, in cludin g:
Memory Man agemen t
Object Man ager
Process an d Th read creat ion an d man ipulat ion
Process an d Th read sch edulin g
Local Procedure Call (LPC) facilit ies
Securit y Man agemen t
Except ion h an dlin g
BETA REVI EW
VDM h ardware emulat ion
Syn ch ron izat ion primit ives, such as Semaph ores an d Mut an t s
Run Time Library
File Syst em
I/ O subsyst ems
M a na gi ng t he I nt el Archi t ect ur e
On e of t h e fun damen t al requiremen t s of st art in g a prot ect ed-mode
operat in g syst em is t h e set up of CPU arch it ect ure, policies, an d address
space t h at t h e operat in g syst em will use. Syst em in it ializat ion is coordi-
n at ed bet ween NTLDR, NTDETECT, NTOSKRNL, an d HAL. Use t h e
followin g Soft ICE comman ds t o obt ain a gen eral idea of h ow Win dows
NT uses t h e In t el arch it ect ure t o provide a secure an d robust en viron -
men t .
N o t e : Th e SoftICE Command Reference p r o v i d es d et ai l ed i n f o r m at i o n ab o u t
u si n g each co m m an d .
I D T ( I n t er r up t D escr ip t o r Tab le)
Win dows NT creat es an IDT for 255 in t errupt vect ors an d maps it in t o
t h e syst em lin ear address space. Th e first 48 in t errupt vect ors are gen er-
ally used by t h e kern el t o t rap except ion s, but cert ain vect ors provide
operat in g syst em services or ot h er special feat ures. Use t h e Soft ICE IDT
comman d t o view t h e Win dows NT In t errupt Descript or Table.
Tab l e 1 2 - 2 . So f t ICE Ar ch i t ect u r e Co m m an d s
Com m an d D escr ip t io n
ID T D i sp l ay i n f o r m at i o n o n t h e In t er r u p t D escr i p t o r Tab l e
TSS D i sp l ay i n f o r m at i o n ab o u t t h e Task St at e Seg m en t
GD T D i sp l ay i n f o r m at i o n o n t h e Gl o b al D escr i p t o r Tab l e
LD T D i sp l ay i n f o r m at i o n o n t h e Lo cal D escr i p t o r Tab l e
Tab l e 1 2 - 3 . In t er r u p t D escr i p t o r Tab l e
I n t e r r up t # Pur p ose
2 N M I. A Task g at e i s i n st al l ed h er e so t h e O S h as a cl ean set o f
r eg i st er s, p ag e- t ab l es, an d l ev el 0 st ack. Th i s en ab l es t h e o p er at -
i n g sy st em t o co n t i n u e p r o cessi n g l o n g en o u g h t o t h r o w a Blue
Screen.
BETA REVI EW
In t errupt vect ors 0x30 - 0x3F are mapped by t h e primary an d secon dary
in t errupt con t rollers, so h ardware in t errupt s for IRQ0 t h rough IRQ15 are
vect ored t h rough t h ese IDT en t ries. In man y cases, t h ese h ardware in t er-
rupt vect ors are n ot h ooked, so t h e syst em assign s default st ub rout in es
for each on e. As devices require t h e use of t h ese h ardware in t errupt s, t h e
device driver request s t o be con n ect ed. Wh en t h e in t errupt is n o lon ger
n eeded, t h e device driver request s t o be discon n ect ed.
Th e default st ubs are n amed KiUn expect edIn t errupt #, wh ere # represen t s
t h e un expect ed in t errupt . To det ermin e wh ich in t errupt vect or is
assign ed t o a part icular st ub, add 0x30 t o t h e Un expect edIn t errupt #. For
example, KiUn expect edIn t errupt 2 is act ually vect ored t h rough IDT
vect or 32 (0x30 + 2).
In t errupt s for Virt ual DOS mach in es (VDM), wh ich in clude t h e WOW
(16-bit Win dows on Win dow) subsyst em, do n ot vect or direct ly t h rough
t h e IDT. For a VDM, in t errupt s are emulat ed by t riggerin g a gen eral
prot ect ion fault t h at special VDM code wit h in NTOSKRNL h an dles. In
most cases, t h e in t errupt is even t ually reflect ed back t o t h e VDM for
servicin g. MS-DOS In t errupt 21 is h an dled as a special case (sin ce an
act ual IDT en t ry exist s). Th is could be for performan ce reason s, compat i-
bilit y issues, or bot h .
8 D o u b l e Fau l t . A Task g at e i s i n st al l ed h er e so t h e O S h as a cl ean
set o f r eg i st er s, p ag e- t ab l es, an d l ev el 0 st ack. Th i s en ab l es t h e
o p er at i n g sy st em t o co n t i n u e p r o cessi n g l o n g en o u g h t o t h r o w
a Blue Screen.
2 1 M S- D O S In t 2 1 t r ap . O n l y u sed f o r Vi r t u al D O S M ach i n es ( VM D )
an d W O W.
2 A Ser v i ce t o g et t h e cu r r en t t i ck co u n t .
2 B, 2 C D i r ect t h r ead sw i t ch ser v i ces.
2 D D eb u g ser vi ce.
2 E Ex ecu t e Sy st em Ser vi ce. Wi n d o w s N T t r an si t i o n s f r o m u ser
m o d e t o sy st em m o d e u si n g IN T 2 E. Fo r m o r e i n f o r m at i o n , r ef er
t o t h e N TCALL co m m an d i n t h e SoftICE Command Reference.
3 0 - 3 7 Pr i m ar y In t er r u p t Co n t r o l l er ( IRQ 0 - IRQ 7 ) .
3 0 - HAL cl o ck i n t er r u p t ( IRQ 0 ) .
3 8 - 3 F Seco n d ar y In t er r u p t Co n t r o l l er ( IRQ 8 - IRQ 1 5 ) .
Tab l e 1 2 - 3 . In t er r u p t D escr i p t o r Tab l e
I n t e r r up t # Pur p ose
BETA REVI EW
Drivers may in st all an d un in st all in t errupt h an dlers as n ecessary, usin g
IoCon n ect In t errrupt an d IoDiscon n ect In t errupt . Th ese rout in es creat e
special t h un k object s, allocat ed from t h e Non -Pageable Pool, wh ich
con t ain dat a an d code t o man age simult an eous use of t h e same in t errupt
h an dler by on e or more drivers.
TSS ( Task St at e Se g m en t )
Th e purpose of t h e TSS is t o save t h e st at e of t h e processor durin g t ask or
con t ext swit ch es. For performan ce reason s, Win dows NT does n ot use
t h is arch it ect ural feat ure an d main t ain s on e base TSS t h at all processes
sh are. As n ot ed in t h e previous sect ion on t h e Win dows NT IDT, ot h er
TSS dat a t ypes exist , but are on ly used durin g except ion al con dit ion s t o
en sure t h at t h e syst em will n ot spon t an eously reboot before Win dows
NT can properly crash it self. Use t h e Soft ICE TSS comman d t o view t h e
curren t TSS.
Th e TSS con t ain s t h e offset from t h e base of t h e TSS t o t h e st art of t h e I/ O
bit map. Th e I/ O bit map det ermin es wh ich port s, if an y, t h e code execut -
in g at Rin g 3 can access direct ly. Un der Win dows NT 3.51, wh en execut -
in g in a VDM, t h e TSS con t ain s a valid offset t o a I/ O bit map t h at t raps
direct I/ O for subsequen t emulat ion by t h e operat in g syst em. Wh en
execut in g a Win 32 applicat ion , t h e TSS con t ain s an invalid offset (it
poin t s beyon d t h e segmen t limit of t h e TSS). Th is forces t h e operat in g
syst em t o t rap all direct I/ O.
In side t h e act ual TSS dat a st ruct ure, t h e on ly field of real in t erest is t h e
address of t h e Level 0 st ack. Th is is t h e st ack t h at is used wh en t h e CPU
t ran sit ion s from user mode t o syst em mode.
GD T ( G lob al D e scr ip t o r Tab le )
Win dows NT is a flat , 32-bit arch it ect ure. Th us wh ile it st ill n eeds t o use
select ors, it uses t h em min imally. Most Win 32 applicat ion s an d drivers
are complet ely un aware t h at select ors even exist . Th e followin g is abbre-
viat ed out put from t h e Soft ICE GDT comman d t h at sh ows t h e select ors
in t h e Global Descript or Table.
GD Tb ase= 8 0 0 3 6 0 0 0 Li m i t = 0 3 FF
0 0 0 8 Co d e3 2 Base= 0 0 0 0 0 0 0 0 Li m = FFFFFFFF D PL= 0 P RE
0 0 1 0 D at a3 2 Base= 0 0 0 0 0 0 0 0 Li m = FFFFFFFF D PL= 0 P RW
0 0 1 B Co d e3 2 Base= 0 0 0 0 0 0 0 0 Li m = FFFFFFFF D PL= 3 P RE
0 0 2 3 D at a3 2 Base= 0 0 0 0 0 0 0 0 Li m = FFFFFFFF D PL= 3 P RW
0 0 2 8 TSS3 2 Base= 8 0 0 0 B0 0 0 Li m = 0 0 0 0 2 0 AB D PL= 0 P B
BETA REVI EW
Not e t h at t h e first four select ors address t h e en t ire 4GB lin ear address
ran ge. Th ese are flat select ors t h at Win 32 applicat ion s an d drivers use.
Th e first t wo select ors h ave a DPL of zero an d are used by device drivers
an d syst em compon en t s t o map syst em code, dat a, an d st acks. Th e selec-
t ors 1B an d 23 are for Win 32 applicat ion s an d map user level code, dat a,
an d st acks. Th ese select ors are con st an t values an d t h e Win dows NT
syst em code makes frequen t referen ces t o t h em usin g t h eir lit eral values.
Th e select or value 30h addresses t h e Kern el Processor Con t rol Region an d
is always mapped at a base address of 0xFFDFF000. Wh en execut in g
syst em code, t h is select or is st ored in t h e FS segmen t regist er. Amon g it s
man y ot h er purposes, t h e Processor Con t rol Region main t ain s t h e
curren t kern el mode except ion frame at offset 0.
Similarly, t h e select or value 3Bh is a user-mode select or t h at maps t h e
curren t user t h read en viron men t block (UTEB). Th is select or value is
st ored in t h e FS segmen t regist er wh en execut in g user level code an d h as
t h e curren t user-mode except ion frame at offset 0. Th e base address of
t h is select or varies depen din g on wh ich user-mode t h read is run n in g.
Wh en a t h read swit ch occurs, t h e base address of t h is GDT select or en t ry
is updat ed t o reflect t h e curren t UTEB.
Select or value 48h is an LDT t ype select or an d is on ly used for VDM
processes. Win 32 applicat ion s an d drivers do n ot use LDT select ors.
Wh en a Win 32 process is act ive, t h e In t el CPUs LDT regist er is NULL. In
t h is case, t h e Soft ICE LDT comman d gives you a No LDT error message.
Wh en a VDM or 16-bit WOW process is act ive, a valid LDT select or is set ,
an d it comes from t h is GDT select or. Durin g a process con t ext swit ch ,
LDT select or in format ion wit h in t h e kern el process en viron men t block
(KPEB) is poked in t o t h is select or t o set t h e appropriat e base address an d
limit .
LD T ( Local D e scr ip t or Tab le )
Un der Win dows NT, Local Descript or Tables are per process dat a st ruc-
t ures an d are on ly used for Virt ual DOS Mach in es (VDM). Th e 16-bit
WOW box (Win dows On Win dows) is execut ed wit h in a NTVDM process
0 0 3 0 D at a3 2 Base= FFD FF0 0 0 Li m = 0 0 0 0 1 FFF D PL= 0 P RW
0 0 3 B D at a3 2 Base= 7 FFD E0 0 0 Li m = 0 0 0 0 0 FFF D PL= 3 P RW
0 0 4 3 D at a1 6 Base= 0 0 0 0 0 4 0 0 Li m = 0 0 0 0 FFFF D PL= 3 P RW
0 0 4 8 LD T Base=E1 5 6 C0 0 0 Li m =0 0 0 0 FFEF D PL=0 P
0 0 5 0 TSS3 2 Base= 8 0 1 4 3 FE0 Li m = 0 0 0 0 0 0 6 8 D PL= 0 P
0 0 5 8 TSS3 2 Base= 8 0 1 4 4 0 4 8 Li m = 0 0 0 0 0 0 6 8 D PL= 0 P
BETA REVI EW
an d h as an LDT. Like Win dows 3.1, t h e LDT for a WOW con t ain s t h e
select ors for every 16-bit prot ect ed mode code an d dat a segmen t for each
16-bit applicat ion or DLL t h at is loaded. It also con t ain s t h e select ors for
each t ask dat abase, module dat abase, local h eaps, global allocat ion s, an d
all USER an d GDI object s t h at require t h e creat ion of a select or. Un der a
WOW, because t h e n umber of select ors n eeded can be quit e large, a full
LDT is creat ed wit h a majorit y of t h e en t ries in it ially reserved. Th ese
reserved select ors are allocat ed as n eeded. Un der a n on -WOW VDM, t h e
size of t h e LDT is sign ifican t ly smaller.
W i ndow s N T Syst em M emor y M a p
Win dows NT reserves t h e upper 2GB of t h e lin ear address space for
syst em use. Th e address ran ge 0x80000000 - 0xFFFFFFFF maps syst em
compon en t s such as device drivers, syst em t ables, syst em memory pools,
an d syst em dat a st ruct ures such as t h reads an d processes. Wh ile you
can n ot creat e an exact map of t h e Win dows NT syst em memory space,
you can cat egorize areas t h at are set aside for specific usage. Th e follow-
in g Syst em Memory Map diagram gives you a rough idea of wh ere
operat in g syst em in format ion is locat ed. Remember t h at a majorit y of
t h ese syst em areas could be mapped an ywh ere wit h in t h e syst em address
space, but are gen erally in t h e address ran ges sh own .
Syst em Code area
Boot drivers an d t h e NTOSKRNL an d HAL compon en t s are loaded in
t h e Syst em Code address space. Non -boot drivers are loaded in t h e
Non Paged syst em address space n ear t h e t op of t h e lin ear address
space. You can use t h e Soft ICE MOD an d MAP32 comman ds t o
examin e t h e base address an d ext en t s of boot drivers loaded in t h is
memory area. Th is is also wh ere t h e TSS, IDT, an d GDT syst em dat a
st ruct ures are mapped.
N o t e : LD T d at a st r u ct u r es ar e cr eat ed f r o m t h e Pag ed Po o l ar ea.
Syst em View area
Th e Syst em View address space is symbolically referen ced, but does
n ot ever seem t o be mapped un der Win dows NT 3.51. Un der n ewer
version s of Win dows NT, t h e Syst em View address space maps t h e
global t ables for GDI an d USER object s. You can use t h e Soft ICE
OBJTAB comman d t o view in format ion about t h e USER object t able.
Syst em Tables Area
Th is region of lin ear memory maps process page t ables an d relat ed
dat a st ruct ures. Th is is on e of t h e few areas of syst em memory t h at is
n ot t ruly global, in t h at each process h as un ique page t ables. Wh en
BETA REVI EW
Win dows NT execut es a process con t ext swit ch , t h e ph ysical address
of t h e process Page Direct ory is ext ract ed from t h e kern el process
en viron men t block (KPEB) an d loaded in t o t h e CR3 regist er. Th is
causes t h e process page t ables t o be mapped in t h is memory area.
Alt h ough t h e lin ear addresses remain t h e same, t h e ph ysical memory
used t o back t h is area con t ain s process-specific values. In Soft ICE
t ermin ology, t h e Page Direct ory is essen t ially an Address Con t ext .
Wh en you use t h e Soft ICE ADDR comman d t o ch an ge t o a specific
process con t ext , you are loading the Page Directory information for this
process.
To man age t h e mappin g of lin ear memory t o ph ysical memory,
Win dows NT reserves a 4MB region of t h e syst em lin ear address space
for Page Tables. Th is 4MB region represen t s t h e en t ire ran ge of
memory n ecessary t o fully defin e a Page Direct ory an d complet e set
of page t ables. Th e n eed for a 4MB region can be calculat ed given
t h at t h ere is on e Page Direct ory st ruct ure wh ich con t ain s en t ries for
1024 Page Tables. To map a 4GB lin ear address space, each Page Table
must map a 4MB region of lin ear address space (4GB / 1024). Each
Page Table is a mult iple of t h e CPU page size (wh ich is 4KB un der
Win dows NT), so mult iplyin g 1024 by 4096 (t h e page size) yields t h e
expect ed 4MB value. Th us an operat in g syst em t h at uses pagin g an d
a 4KB page size requires 4MB of memory t o map t h e en t ire address
space. Win dows NT, Win dows 95 an d Win dows 98 t ake t h e simple
an d efficien t approach of usin g a con t iguous region of lin ear memory
for t h is purpose.
Th e diagram on t h e n ext page sh ows t h e syst em memory map for
Win dows NT.
In t h is design , t h e Page Direct ory is act ually performin g t wo
fun ct ion s. In addit ion t o bein g t h e Page Direct ory, represen t in g 4GB,
it also serves as a page t able, represen t in g 4MB in t h e address ran ge
0xC0000000 - 0xC03FFFFF. Th e Page Direct ory maps t h e 4MB region
wh ere t h e process page t ables are mapped (0xC0000000-
0xC03FFFFF), so t h e Page Direct ory en t ry t h at maps t h is area must
poin t t o it self. If you use t h e Soft ICE PAGE comman d, t h e ph ysical
address of t h e Page Direct ory displayed at t h e t op of t h e comman d
out put mat ch es t h e ph ysical address for t h e en t ry t h at maps t h e
0xC0000000 - 0xC03FFFFF memory ran ge. If you use t h e Soft ICE
ADDR comman d t o obt ain t h e CR3 (t h e CR3 regist er con t ain s t h e
ph ysical address of t h e Page Direct ory) value for t h e curren t process
an d supply t h is value as in put t o t h e Soft ICE PHYS comman d, all t h e
lin ear addresses t h at are mapped t o t h e ph ysical address of t h e Page
Direct ory are displayed. On e of t h e addresses is 0xC0300000.
BETA REVI EW
Fi g u r e 1 2 -1 . Wi n d o w s N T Sy st em M em o r y M ap
Th e followin g examples illust rat es h ow all t h ese values in t errelat e.
Import an t values are sh ow in bold t ypeface.
Use t h e ADDR comman d t o obt ain t h e physical address of t h e
Page Direct ory (CR3).
:addr
CR3 LDT Base:Limit KPEB Addr PID Name
00030000 FF116020 0002 System
0115A000 FF0AAA80 0051 RpcSs
0073B000 FF083020 004E nddeagnt
BETA REVI EW
Use t h e ph ysical address as in put t o t h e PHYS comman d t o
obt ain all lin ear addresses t h at map t o t h at ph ysical page (on e
ph ysical page may be mapped t o more t h an on e lin ear address,
an d on e lin ear address may be mapped t o more t h an on e page).
:phys 1F6E000
C0300000
Use t h e lin ear address (C0300000) an d run it t h rough t h e PAGE
comman d t o verify t h e ph ysical page for t h at lin ear address.
:page C0300000
Linear Physical Attributes
C0300000 01F6E000 P D A S RW
Use t h e PAGE comman d wit h out an y paramet ers t o view t h e
mappin g of t h e en t ire lin ear address ran ge. Th is is useful for
obt ain in g t h e ph ysical address of t h e Page Direct ory an d verify-
in g t h at t h e operat in g syst em page t ables are mapped at lin ear
address 0xC0000000. Th e out put for t h is comman d is abbrevi-
at ed.
00653000 E13BB000:0C3F FF080020 0061 ntvdm
00AEE000 FF07A600 0069 Explorer
01084000 FF06ECA0 0077 FINDFAST
010E9000 FF06CDE0 007B MSOFFICE
*01F6E000 FF088C60 006A WINWORD
01E0A000 FF09CCA0 008B 4NT
017D3000 E1541000:018F FF09C560 006D ntvdm
00030000 80140BA0 0000 Idle
:page
Page Directory Physical=01F6E000
Physical Attributes Linear Address Range
01358000 P A S RW A0000000 - A03FFFFF
017F0000 P A S RW A0400000 - A07FFFFF
01727000 P A S RW A0800000 - A0BFFFFF
:addr
BETA REVI EW
Syst e m Pag e Tab le En t r ies an d Pr ot oPTEs
Th e acron ym, PTE, wh ich appears in various places on t h e syst em map,
st an ds for Page Table En t ry. A Page Table En t ry is on e of t h e 1024 en t ries
t h at is con t ain ed in a Page Table. Each PTE describes on e page of
memory, in cludin g it s ph ysical address an d at t ribut es. Because Win dows
NT also run s on n on -In t el plat forms, an d because t h e operat in g syst em
may n eed t o ext en d t h e t ypes of page-level prot ect ion beyon d wh at an y
part icular CPU may provide, Win dows NT virt ualizes t h e CPU PTE wit h
wh at is referred t o as a Prot oPTE. Th e Prot oPTE is similar t o t h e In t el
Arch it ect ure PTE, but in cludes at t ribut es t h at are n ot provided by t h e
In t el PTE. By overloadin g t h e mean in g of an at t ribut e bit wit h in an In t el
PTE, t h e operat in g syst em can gain con t rol on a page fault , an d examin e
t h e ext en ded at t ribut es of t h e correspon din g Prot oPTE t o det ermin e wh y
t h e operat in g syst em request ed t h at t h e fault occur. Th rough out NTOSK-
RNL, man ipulat ion s are performed on t h e Prot oPTE abst ract ion , an d
t ran slat ed t o t h e act ual CPU PTE t ype. Not e t h at t h e operat in g syst em
also compares t h e Prot oPTE t o it s correspon din g CPU PTE t o en sure t h eir
con sist en cy. Th is effect ively preven t s an applicat ion or device driver
from direct ly man ipulat in g t h e page t able en t ries.
Paged Pool Area: Th e Paged Pool syst em memory area is wh ere
n t oskrn l!ExAllocat ePool an d it s relat ed fun ct ion s allocat e memory
t h at can be paged t o disk. Th is is in direct con t rast t o t h e Non -Paged
pool area. Non -Paged pool allocat ion s are n ever paged t o disk an d are
design ed for rout in es such as In t errupt Han dlers t h at n eed h igh per-
forman ce or n eed a guaran t ee t h at a piece of in format ion is always
available for use.
Win dows NT makes ext en sive use of t h e Paged pools, as t h is is wh ere
most operat in g syst em object s are creat ed. Not e t h at t h e st art in g
address an d t h e size an d n umber of paged pools is det ermin ed
dyn amically durin g syst em in it ializat ion . On ly use t h e addresses
presen t ed h ere as a guidelin e. For t h e act ual addresses, load t h e
symbols for NTOSKRNL an d examin e t h e appropriat e variables t h at
describe t h e paged pool con figurat ion . (To see several of t h em, use
t h e Soft ICE SYM comman d wit h t h e Paramet er MmPaged*.)
01F6E000 P A S RW C0000000 - C03FFFFF
0066F000 P A S RW C0400000 - C07FFFFF
00041000 P A S RW C0C00000 - C0FFFFFF
00042000 P A S RW C1000000 - C13FFFFF
BETA REVI EW
Alt h ough t h ere is on e Paged Pool area, t h ere are mult iple paged
pools. Th e n umber is det ermin ed durin g syst em in it ializat ion . Paged
pool allocat ion s occur wit h relat ively h igh frequen cy an d t h ose
accesses must be t h read safe, so h avin g on e dat a st ruct ure wh ich
must be own ed exclusively by on e t h read durin g memory allocat ion
or deallocat ion creat es a bot t len eck. To avoid pot en t ial t raffic jams
an d reduced syst em performan ce, mult iple pool descript ors are
creat ed, each wit h it s own privat e dat a st ruct ures, in cludin g an
execut ive spin lock for t h read syn ch ron izat ion . Th us, t h e more paged
pools creat ed, t h e more t h reads t h at can perform paged pool alloca-
t ion s simult an eously, in creasin g t h e t h rough put of t h e syst em. An
import an t design n ot e, in case you plan on usin g similar t ech n iques
in your driver or applicat ion , is t h at t h e overh ead for a Paged Pool (or
Non -Paged Pool) descript or is very min imal. Th us it s pract ical for
four or five of t h em t o exist . However, det ermin e t h at an act ual
bot t len eck exist s before creat in g elaborat e sch emes t o solve a n on -
exist en t problem.
Non-Paged System Area: Th is lin ear region is in t en ded for syst em
compon en t s an d dat a st ruct ures t h at n eed t o be presen t in memory
at all t imes. Th is in cludes n on -boot drivers, kern el mode t h read
st acks, t wo Non -Paged memory pools, an d t h e Page Frame Dat abase.
Alt h ough it is con t radict ory t o say t h at it ems in t h e Non -Paged Sys-
t em area can become n ot presen t ; t h e t rut h is t h at t h ey can be. Spe-
cifically, kern el t h read st acks an d process address spaces can be made
n ot presen t , an d oft en are.
Th e Non -Paged pool is similar t o t h e Paged Pool wit h t h e except ion
t h at object s creat ed in t h e Non -Paged pool are n ot discarded from
memory for an y reason . Th e Non -Paged pool is used t o allocat e key
syst em dat a st ruct ures such as kern el process an d t h read en viron -
men t blocks. Th ere is a secon d Non -Paged pool used for memory
allocat ion s t h at must succeed. At syst em in it ializat ion , NTOSKRNL
reserves a small amoun t of ph ysical memory for crit ical allocat ion s,
an d saves t h is memory for use by t h e must succeed pool. Th e size of
an allocat ion from t h e must succeed pool must be less t h an on e page
(4KB). If t h e must succeed allocat ion can n ot be sat isfied, or t h e
request ed allocat ion size is larger t h an 4KB, t h e syst em t h rows a Blue
Screen.
Processor Control Region: At t h e h igh en d of t h e syst em memory
area is t h e Processor Con t rol Region . Here, Win dows NT main t ain s
Processor Con t rol Block (PCRB) dat a st ruct ures for each processor
wit h in t h e syst em an d a global dat a st ruct ure, t h e Processor Con t rol
Region t h at reflect s t h e curren t st at e of t h e syst em. Th e Processor
BETA REVI EW
Con t rol Region (PCR) con t ain s key pieces of in format ion about t h e
curren t st at e of t h e syst em, such as t h e curren t ly run n in g kern el
t h read; t h e curren t in t errupt request level (IRQL); t h e curren t excep-
t ion frame; base addresses of t h e IDT, TSS, an d GDT; an d kern el
t h read st ack poin t ers. Small port ion s of t h e PCR an d PCRB dat a st ruc-
t ures are documen t ed in NTDDK.H.
In man y cases, device driver writ ers n eed t o kn ow t h e curren t IRQL at
wh ich t h ey are execut in g. Alt h ough you could look in side t h e PCR
dat a st ruct ure at offset 0x24, it is simpler t o use t h e Soft ICE in t rin sic
fun ct ion , IRQL, as follows:
? IRQL
00000002h
Th e most common piece of dat a accessed from t h e PCRB is t h e
curren t kern el t h read poin t er. Th is is at offset 4 wit h in t h e PCRB, but
is gen erally referen ced t h rough t h e PCR at offset 0x124. Th is works
because t h e PCRB is n est ed wit h in t h e PCR at offset 0x120. Code t h at
accesses t h e curren t t h read is usually of t h e form:
mov reg, FS:[124].
Remember t h at wh ile execut in g in syst em mode, t h e FS regist er is set
t o a GDT select or wh ose base address poin t s t o t h e begin n in g of t h e
PCR. Soft ICE makes it much easier t o get t h e curren t t h read poin t er
or t h read id by usin g t h e in t rin sic fun ct ion s thread or tid:
? thread
FF088E90h
? tid
71h
For more ext en sive in format ion on t h e curren t t h read use t h e follow-
in g comman ds:
Th e curren t process is n ot st ored as part of t h e PCR or PCRB.
Win dows NT referen ces t h e curren t process t h rough t h e curren t
:thread tid
TID Krnl TEB StackBtm StkTop StackPtr User TEB Process(Id)
0071 FF0889E0 FC42A000 FC430000 FC42FE5C 7FFDE000 WINWORD(6A)
:thread thread
0071 FF0889E0 FC42A000 FC430000 FC42FE5C 7FFDE000 WINWORD(6A)
BETA REVI EW
t h read. Code such as t h e followin g obt ain s t h e curren t process
poin t er:
Win32 Subsyst em
I nsi de CSRSS
Th e Win 32 subsyst em server process CSRSS implemen t s t h e Win 32 API.
Th e Win 32 API provides man y differen t t ypes of service, in cludin g
fun ct ion alit y t radit ion ally at t ribut ed t o t h e origin al Win dows compo-
n en t s KERNEL, USER, an d GDI. Alt h ough t h ese st an dard modules exist in
t h e form of 32-bit DLLs un der Win dows NT 3.51, an d t o a lesser degree
un der n ew version s of t h e operat in g syst em, most of t h e core fun ct ion al-
it y is act ually implemen t ed in WINSRV.DLL wit h in t h e CSRSS process.
Calls t h at are t radit ion ally associat ed wit h on e of t h e st an dard Win dows
compon en t s are t ypically implemen t ed as st ubs t h at call ot h er modules,
for example, NTDLL.DLL, or use in t er-process commun icat ion t o CSRSS
for servicin g.
Most USER an d GDI API calls are rout ed t h rough t h e appropriat e 32-bit
module in t h e process address space. Th ere, t h ey are packaged as Local
Procedure Call (LPC) messages an d rout ed t o CSRSS for processin g. As
you migh t imagin e, t h is LPC mech an ism, alt h ough much more
opt imized t h an a t rue Remot e Procedure Call (RPC), h as much more
overh ead t h an a simple fun ct ion call. It is surprisin g t o t h in k t h at every
t ime your applicat ion calls t h e IsWin dow fun ct ion in USER32.DLL, it
must be packaged for LPC an d sen t as a subsyst em message t o CSRSS. For
CSRSS t o be able t o process t h is message, a process swit ch must occur an d
a worker t h read must be awoken an d dispat ch ed. Th e specific service
must be det ermin ed, paramet ers must be validat ed, an d fin ally t h e
service must be execut ed. Wh en everyt h in g is complet e on t h e CSRSS
side, a LPC reply must be made t o t h e clien t (your applicat ion ), wh ich
in volves an ot h er process swit ch an d un packagin g of t h e LPC reply.
Wh ew! All t h at just t o det ermin e if a h an dle represen t s a valid win dow.
In t h eir design of a fort h comin g version of Win dows NT, Microsoft is
workin g t o remove as much of t h is overh ead as possible. First , t h ey are
movin g much of t h e fun ct ion alit y of WINSRV.DLL in t o t h e act ual
USER32 an d GDI32 modules t h at are loaded in t o your applicat ion s
mov eax, FS:[124] ; get the current thread (KTEB)
mov esi, [eax+40h] ; get the threads process pointer (KPEB)
BETA REVI EW
address space. Th is allows t h e most common services t o execut e as simple
fun ct ion calls; n o LPC is n ecessary. Secon d, rat h er t h an makin g a con t ext
swit ch in t o CSRSS t o access fun ct ion alit y in WINSRV.DLL, a n ew syst em
driver, WIN32K.SYS allows USER an d GDI services t o execut e more
efficien t ly t h rough a simple t ran sit ion from user t o syst em mode. Havin g
WIN32K.SYS as a device driver t h at provides applicat ion services allows
Win dows NT t o main t ain a h igh level of en capsulat ion an d robust n ess,
wh ile providin g a much more efficien t pseudo clien t -server service arch i-
t ect ure.
Alt h ough CSRSS execut es as a separat e process, it st ill h as a big impact on
t h e address space of every Win 32 applicat ion . If you use t h e Soft ICE
HEAP32 comman d on your process, you will n ot ice at least t wo h eaps
t h at your applicat ion did n ot specifically creat e, but were creat ed on it s
beh alf. Th e first is t h e default process h eap t h at was creat ed durin g
process in it ializat ion . Th e secon d is a h eap specifically creat ed by CSRSS.
Th ere may be ot h er h eaps in your applicat ion address space t h at were n ot
creat ed by your process. Th ese h eaps are gen erally locat ed very h igh in
t h e user-mode address space an d appear if you use t h e Soft ICE QUERY
comman d, but do n ot appear in t h e out put of t h e HEAP32 comman d.
Th e reason for t h is is quit e simple: for each user-mode process, a list of
process h eaps is main t ain ed an d t h e Soft ICE HEAP32 comman d uses t h is
list t o en umerat e t h e h eaps for a process. If t h e h eap was n ot creat ed by
or on beh alf of your applicat ion , it does n ot appear in t h e process h eap
list . Th e Soft ICE QUERY comman d t raverses t h e user-mode address space
for your applicat ion , usin g t h e Soft ICE WHAT en gin e t o iden t ify region s
of memory t h at are mapped. Wh en t h e WHAT en gin e en coun t ers a
region wh ose base address is equivalen t t o a h eap t h at is list ed as part of
t h e process h eap list , it is iden t ified as a h eap. If t h e WHAT en gin e
can n ot iden t ify a region as a h eap in t h is man n er, it probes t h e dat a area
lookin g for key sign at ures t h at iden t ify t h e area as h eap or h eap segmen t .
Heaps t h at exist in t h e process address space, but t h at are n ot en umer-
at ed in t h e process h eap list , were mapped in t o t h e process address space
by an ot h er process. In most cases, t h is mappin g is don e by CSRSS.
Durin g subsyst em in it ializat ion , CSRSS creat es a h eap at a well-kn own
base address. Wh en n ew processes are creat ed, t h is h eap is mapped in t o
t h eir address spaces at t h e same well-kn own base address. Th eoret ically,
mappin g t h e h eap of on e process at t h e same base address of an ot h er
process allows bot h processes t o use t h at h eap. In pract ice, t h ere are
issues t h at migh t preven t t h is from workin g un der all circumst an ces
syn ch ron izat ion bein g on e such issue. Not e t h at un der n ewer version s of
Win dows NT, more t h an on e h eap may be mapped in t o t h e process
address space, an d t h ose h eaps may be mapped at differen t base
BETA REVI EW
addresses in differen t processes. Th e Soft ICE QUERY comman d n ot es t h is
con dit ion in it s out put . Also, n ew version s of t h e operat in g syst em use
h eaps t h at are creat ed in t h e syst em address space, an d t h ese h eaps are
somet imes mapped in t o t h e user address space. Win dows NT allows t h e
creat ion of h eaps wit h in t h e syst em address space usin g APIs export ed
from NTOSKRNL. Th ese APIs are similar t o t h e same APIs export ed from
t h e user-mode module, NTDLL.DLL.
USER a nd GDI Obj ect s
Un der Win dows NT 3.51, t h e prot ect ed Win 32 subsyst em process, CSRSS,
provides a majorit y of t h e t radit ion al USER fun ct ion alit y. APIs an d dat a
st ruct ures provided by t h e WINSRV.DLL module man age win dow classes,
an d win dow dat a st ruct ures, as well as man y ot h er USER dat a t ypes.
Un der Win dows NT 3.51, t h e followin g USER object t ypes exist . Object
t ype IDs are list ed in paren t h eses.
FREE ( 0 ) O b j ect En t r y i s u n u sed / i n v al i d .
H W N D ( 1 ) Wi n d o w O b j ect s.
M EN U ( 2 ) Wi n d o w s M EN U o b j ect .
I CO N / CU RSO R ( 3 ) Wi n d o w s ICO N o r CURSO R o b j ect .
D EFERW I N D O W PO S ( 4 ) O b j ect r et u r n ed b y t h e
Beg i n D ef er Wi n d o w Po si t i o n API.
H O O K ( 5 ) Wi n d o w s Ho o k t h u n k.
TH READ I N FO ( 6 ) CSRSS Cl i en t Th r ead In st an ce D at a.
Q U EU E ( 7 ) Wi n d o w s m essag e q u eu e.
CPD ( 8 ) Cal l Pr o ced u r e D at a t h u n k.
ACCELERATO R ( 9 ) Accel er at o r Tab l e O b j ect .
W I N D O W STATI O N ( 0 xA)
D ESKTO P ( 0 xB) O b j ect r ep r esen t i n g a d eskt o p w i n d o w
h i er arch y.
D D EO BJECT ( 0 xC) D D E O b j ect s su ch as st r i n g s.
BETA REVI EW
Newer version s of Win dow NT add/ redefin e t h e followin g USER object
t ypes.
Rat h er t h an main t ain in g per-process dat a st ruct ures for USER an d GDI
object t ypes, CSRSS main t ain s a mast er h an dle t able for all processes. Th e
USER an d GDI object s are segregat ed in t o t wo differen t t ables t h at h ave
t h e same basic st ruct ure an d seman t ics. WINSRV provides dist in ct
Han dle Man ager APIs for man agin g t h e t wo differen t t ables. You can
iden t ify t h e h an dle man ager API n ames by t h e HM prefix in fron t of t h e
API n ame, an d t h e GDI specific rout in es by t h e g appen ded t o t h is
prefix. Th e rout in e HMAllocObject creat es USER object t ypes, wh ile
HmgAlloc is a GDI object t ype API t h at creat es GDI object t ypes.
Th e man agemen t of USER an d GDI h an dles is relat ively st raigh t forward,
an d it s design is a good example of h ow t o implemen t basic man agemen t
of abst ract object t ypes. Specifically, t h is API uses a simple, but robust ,
t ech n ique for creat in g un ique h an dles an d man agin g referen ce coun t s.
Th e design also provides for h an dle opaquen ess wh ich preven t s applica-
t ion s, in cludin g USER32 an d CSRSS, from direct ly man ipulat in g t h e
object s out side t h e h an dle man ager. Preven t in g clien t s, in cludin g it self,
from direct ly man ipulat in g t h e object dat a allows t h e h an dle man ager t o
en sure t h at referen ce coun t s an d syn ch ron izat ion issues are man aged
correct ly.
Th e mast er object t ables main t ain ed by t h e Han dle Man ager are
growable arrays of fixed size en t ries. Th e followin g t able list s t h e fields for
D ESKTO P ( - - - ) Th i s O b j ect t y p e h as b een r em o v ed . Th i s t y p e
i s n o w a ker n el o b j ect t h at i s m an ag ed b y t h e
Ker n el O b j ect M an ag er.
Q U EU E ( - - - ) Th i s O b j ect t y p e h as b een r em o v ed .
W I N D O W STATI O N ( 0 xD ) Ch an g ed O b j ect t y p e ID . Al so ex i st s as a
ker n el o b j ect .
D D EO BJECT ( 0 xA) Ch an g ed O b j ect t y p e ID .
KEYBO ARD LAYO U T ( 0 xE) N ew O b j ect t y p e. O b j ect t o d escr i b e a
key b o ar d l ay o u t .
CLI PBO ARD FO RM AT ( 7 ) N ew O b j ect t y p e. Reg i st er ed Cl i p b o ar d
Fo r m at s.
BETA REVI EW
an object t able. On ly column s wit h bold field h eaders are part of t h e
en t ry. Th e column s wit h italicized h eaders are for illust rat ion on ly.
Th e Object Poin t er field poin t s t o t h e act ual object dat a. Th is poin t er is
gen erally from on e of t h e CSRSS h eaps or t h e Paged Pool. Th e t ype field
is t h e en umerat ion for t h e object t ype. Th e In st an ce Coun t field creat es
un ique h an dles. Th e Flags field is used by t h e Han dle Man ager t o n ot e
special con dit ion s, such as wh en a t h read locks an object for exclusive
use.
H o w H an d le Values Ar e Cr eat ed
In it ially, all object t able In st an ce coun t s are set t o 1. Wh en a n ew Object
En t ry is allocat ed, t h e In st an ce Coun t is combin ed wit h t h e t able in dex
t o creat e a un ique h an dle value. Wh en referen ces are made t o an object ,
t h e t able en t ry port ion of t h e h an dle is ext ract ed an d used t o in dex in t o
t h e t able. As part of t h e h an dle validat ion , t h e in st an ce coun t is ext ract ed
from t h e t able en t ry an d compared t o t h e h an dle bein g validat ed. If t h e
in st an ce coun t does n ot mat ch t h e t able en t ry in st an ce coun t , t h e
h an dle is bogus. Th e followin g example illust rat es t h ese con cept s:
To creat e an object h an dle from an object t able en t ry:
Object Handle = Table Entry Index + (InstanceCount << 16);
To validat e an object h an dle:
ObjectTable [LOWORD(handle)]. InstanceCount ==
HIWORD(handle);
Wh en an object is dest royed, all fields are rein it ialized t o zero an d t h e
curren t In st an ce Coun t for t h at en t ry is in cremen t ed by on e. Th us, wh en
t h e object t able en t ry is reused, it gen erat es a differen t h an dle value for
t h e n ew object .
N o t e : Th e act u al o b j ect t y p e i s n o t p ar t o f t h e o b j ect h an d l e v al u e. Th i s
m ean s t h at g i ven an o b j ect h an d l e, an ap p l i cat i o n can n o t d i r ect l y
d et er m i n e i t s t y p e. I t i s n ecessar y t o d er ef er en ce t h e o b j ec t t ab l e
en t r y t o o b t ai n t h e o b j ect t y p e.
En t r y
O b je ct
Po in t e r
( D W O RD )
O w n e r
( D W O RD )
Typ e
( BYT E)
Fl ag s
( BYT E)
I n st a n ce
Co u n t
( W O RD )
H a n d l e Va l u e
0 N ULL N ULL FREE ( 0 ) 0 0 0 0 0 1 0 0 0 1 0 0 0 0
1 HEAP * HEAP * D ESKTO P ( 0 C) 0 0 0 0 0 1 0 0 0 1 0 0 0 1
2 HEAP * HEAP * HW N D ( 0 4 ) 0 1 0 0 0 3 0 0 0 3 0 0 0 2
BETA REVI EW
Th is t ech n ique for creat in g un ique h an dle values is simple an d efficien t ,
an d makes validat ion t rivial. Imagin e t h e case wh ere a process creat es a
win dow an d obt ain s a h an dle t o t h at win dow. Durin g subsequen t
program execut ion , t h e process dest roys t h e win dow but ret ain s t h e
h an dle value. If t h e process uses t h e h an dle aft er t h e win dow is
dest royed, t h e h an dle value is in valid an d t h e t ype it poin t s t o h as an
object t ype of FREE. Th is con dit ion is caugh t , an d t h e program is n ot be
able t o use t h e h an dle successfully. In t h e mean t ime, if an ot h er process
creat es a n ew object , it is likely t h at t h e en t ry origin ally for t h e n ow
dest royed win dow will be reused. If t h e origin al program uses t h e in valid
win dow h an dle, t h e h an dle in st an ce coun t s n o lon ger mat ch , an d t h e
validat ion fails.
Object t ables are n ot process specific, so USER an d GDI object h an dles
values are n ot un ique t o a specific process. HWND h an dles are un ique
across t h e en t ire Win 32 subsyst em. On e process n ever h as an HWND
h an dle value t h at is duplicat ed in an y ot h er process.
U SER O b ject Tab le
Use t h e Soft ICE OBJTAB comman d t o display all t h e object en t ries wit h in
t h e USER object t able. Th e OBJTAB comman d is relat ively flexible, allow-
in g a h an dle or t able en t ry in dex t o be specified. It also support s t h e
display of object s by t ype usin g abbreviat ion s for t h e object t ype n ames.
To see a list of object t ype n ames t h at t h e OBJTAB comman d can use,
specify t h e -H opt ion on t h e OBJTAB comman d lin e.
Th e Object Poin t er field can referen ce t h e object specific dat a for an
object t able en t ry. All object s h ave a gen eric h eader t h at is main t ain ed by
t h e object man ager, wh ich in cludes t h e object h an dle value an d a t h read
referen ce coun t . Most object t ypes also con t ain a poin t er t o a deskt op
object an d/ or a poin t er t o it s own er.
Th e followin g example sh ows an object t able en t ry for a win dow h an dle
an d a dat a dump of t h e object h eader main t ain ed by t h e h an dle
man ager. Key in format ion from t h e comman d out put is list ed in bold.
BETA REVI EW
1 Use t h e Soft ICE OBJTAB comman d t o fin d an arbit rary win dow h an -
dle an d obt ain t h e object poin t er. In t h is example, t h e h an dle value is
0x1000C an d t h e own er field is 0xE12E7008:
2 Dumpin g 0x20 byt es of t h e object dat a reveals t h e followin g:
Th e value 0x1001C, at offset 0, is t h e object h an dle value. Th e field at
offset 4, wh ich con t ain s t h e value six (6), is t h e object referen ce
coun t . Th e value at offset 0x0C, of 0xFF0E45D8, is a poin t er t o t h e
win dows deskt op object .
3 Verify t h is usin g t h e Soft ICE WHAT comman d as follows:
:what ff0e45d8
The value FF0E45D8 is (a) Kernel Desktop object (handle=0068) for
winlogon(21)
Th e value at offset 0x14, of 0xE12E7008, is t h e same value t h at was
in t h e object en t ry own er field.
4 Dumpin g 0x20 byt es at t h e address of t h e own er dat a reveals t h e fol-
lowin g:
5 Th e value (0x1001B) at offset 0 of t h e own er dat a looks like an object
h an dle, but it is a t h read in format ion object . Th e followin g example
uses t h e OBJTAB comman d wit h 0x1001B as t h e paramet er t o sh ow
t h e t ype for t h e own er dat a.
:objtab hwnd
Object Type Id Handle Owner Flags
E12E9EA8 Hwnd 01 0001001C E12E7008 00
:dd e12e9ea8 l 20
0010:E12E9EA8 0001001C 00000006 00000000 FF0E45D8
0010:E12E9EB8 00000000 E12E7008 00000000 00000000
:dd e12e7008 l 20
0010:E12E7008 0001001B 00000000 00000000 E12E9C34
0010:E12E7018 E17DB714 00000000 00000000 00000000
:objtab 1001b
Object Type Id Handle Owner Flags
E12E7008 Thread Info 06 0001001B 00000000 00
BETA REVI EW
M on it or in g U SER O b ject Cr eat io n
If you do a con siderable amoun t of Win 32 applicat ion developmen t , t h e
HMAllocObject API is a con ven ien t place t o mon it or creat ion of object
t ypes such as win dows. Use t h e Soft ICE MACRO comman d t o creat e a
breakpoin t t emplat e t h at can t rap creat ion of specific object t ypes as
follows:
:MACRO obx = bpx winsrv!HMAllocObject if (esp->c == %1)
Th e HMAllocObject API is implemen t ed in WINSRV.DLL an d t h e object
t ype bein g creat ed is t h e t h ird paramet er, wh ich t ran slat es t o Dword pt r
esp [ 0Ch ]. Th e syn t ax esp->c dereferen ces t h e request ed object t ype,
an d is equivalen t t o *(esp+c). Th e %1 port ion of t h e con dit ion al
expression is a place h older for argumen t replacemen t . Wh en you
execut e t h e OBX macro, t h e argumen t provided is in sert ed in t o t h e
macro st ream at t h e %1:
:OBX 1 -> bpx winsrv!HMAllocObject if (esp->c == 1)
Wh en t h is breakpoin t is in st an t iat ed, it t raps all calls t o HMAllocObject
t h at creat es win dow object t ypes.
Pr ocess Addr ess Spa ce
Th e address space for a user-mode process is mapped in t o t h e lower 2GB
of lin ear memory at addresses 0x00000000 - 0x7FFFFFFF. Th e upper 2GB
of lin ear memory is reserved for t h e operat in g syst em kern el an d device
drivers.
In gen eral, each Win 32 applicat ion s process address space h as t h e
followin g region s of lin ear memory mapped for t h e correspon din g
purpose.
Tab l e 1 2 - 4 . Pr o cess Ad d r ess Sp ac e
Li n e ar Ad d r ess Ran g e Pur p ose
0 x 0 0 0 0 0 0 0 0 - 0 x 0 0 0 0 FFFF Pr o t ect ed r eg i o n . Usef u l f o r d et ect i n g
N ULL p o i n t er w r i t es.
0 x 0 0 0 1 0 0 0 0 D ef au l t l o ad ad d r ess f o r Wi n 3 2 p r o cesses.
0 x 7 0 0 0 0 0 0 0 - 0 x 7 8 0 0 0 0 0 0 Ty p i cal r an g e f o r Wi n 3 2 su b sy st em D LLs
t o b e l o ad ed .
0 x 7 FFB0 0 0 0 - 0 x 7 FFD 3 FFF AN SI an d O EM co d e p ag es. Un i co d e
t r an sl at i o n t ab l e( s) .
0 x 7 FFD E0 0 0 - 0 x 7 FFD EFFF Pr i m ar y u ser - m o d e t h r ead en vi r o n m en t
b l o ck.
BETA REVI EW
Un der Win dows NT, t h e lowest an d h igh est 64KB region s in t h e user-
mode address space are reserved an d are n ever mapped t o ph ysical
memory. Th e 64KB at t h e bot t om of t h e lin ear address space is design ed
t o h elp cat ch writ es t h rough NULL poin t ers.
Th e default load address for processes un der Win dows NT is 0x10000.
Processes oft en ch an ge t h eir load address t o a differen t base address.
Applicat ion s t h at were design ed t o run on Win dows 95 an d Win dows 98
h ave a default load address of 0x400000. Use t h e lin ker or t h e REBASE
ut ilit y t o set t h e default load address of a DLL or EXE.
Th e lin ear ran ge at 0x70000000 is an approximat ion of t h e area wh ere
Win 32 subsyst em modules load. Use t h e Soft ICE MOD, MAP32, or
QUERY comman ds t o obt ain in format ion on modules loaded in t h is
ran ge.
Th e user process en viron men t block is always mapped at 0x7FFDF000,
wh ile t h e processs primary user-mode t h read en viron men t block is on e
page below t h at at 0x7FFDE000. As a process creat es ot h er worker
t h reads, t h ey are mapped on page boun daries at t h e curren t , h igh est
un used lin ear address.
Th e followin g use of t h e Soft ICE THREAD comman d sh ows h ow each
subsequen t t h read is placed on e page below t h e previous t h read:
To fin d out more about t h e user-mode address space of a process, use t h e
Soft ICE QUERY comman d. Th e QUERY comman d provides a h igh -level
view of t h e lin ear region s t h at were reserved an d/ or commit t ed. It uses
t h e Soft ICE WHAT en gin e t o iden t ify t h e con t en t s of a lin ear ran ge. From
0 x 7 FFD F0 0 0 - 0 x 7 FFD FFFF User - m o d e p r o cess en vi r o n m en t b l o ck
( UPEB) .
0 x 7 FFE0 0 0 0 - 0 x 7 FFE0 FFF M essag e q u eu e r eg i o n .
0 x 7 FFFF0 0 0 - 0 x 7 FFFFFFF Pr o t ect ed r eg i o n .
:thread winword
006B FFA7FDA0 FEAD7000 FEADB000 FEADAE64 7FFDE000 WINWORD(83)
007C FF0A0AE0 FEC2A000 FEC2D000 FEC2CE18 7FFDD000 WINWORD(83)
009C FF04E4E0 FC8F9000 FC8FC000 FC8FBE18 7FFDC000 WINWORD(83)
Tab l e 1 2 - 4 . Pr o cess Ad d r ess Sp ac e
Li n e ar Ad d r ess Ran g e Pur p ose
BETA REVI EW
it s out put you see t h e process h eaps, modules, an d memory-mapped
files, as well as t h e t h read st acks an d t h read en viron men t blocks.
Hea p API
H eap Ar ch it ect ur e
Every user-mode applicat ion direct ly or in direct ly uses t h e Heap API
rout in es, wh ich are export ed from KERNEL32 an d NTDLL. Heaps are
design ed t o man age large areas of lin ear memory an d sub-allocat e
smaller memory blocks from wit h in t h is region . Th e core implemen t a-
t ion of t h e Heap API rout in e is con t ain ed wit h in NTDLL, but some of t h e
applicat ion in t erfaces such as HeapCreat e an d HeapValidat e are export ed
from KERNEL32. For some API rout in es, such as HeapFree, t h ere is n o
code implemen t at ion wit h in KERNEL32, so t h ey are fixed by t h e loader
t o poin t at t h e act ual implemen t at ion wit h in NTDLL.
N o t e : Th e t ech n i q u e o f f i x i n g an ex p o r t i n o n e m o d u l e t o t h e ex p o r t o f
an o t h er m o d u l e i s cal l ed Sn ap p i n g .
Alt h ough t h e Heap API rout in es used by applicat ion s are relat ively
st raigh t forward an d design ed for ease of use, t h e implemen t at ion an d
dat a st ruct ures un dern eat h are quit e soph ist icat ed. Th e man agemen t of
h eap memory h as come quit e a lon g way from t h e st an dard C run -t ime
library rout in es malloc() an d free(). Specifically, t h e Heap API h an dles
allocat ion s of large, n on -con t iguous region s of lin ear memory, wh ich are
used for sub-allocat ion an d t o opt imize coalescin g of adjacen t blocks of
free memory. Th e Heap API also performs fast look-ups of best -fit block
sizes t o sat isfy allocat ion request s, provides t h read-safe syn ch ron izat ion ,
an d supplies ext en sive h eap in format ion an d debuggin g support .
Th e primary h eap dat a st ruct ure is large, at approximat ely 1400 byt es, for
a free build an d t wice t h at for a ch ecked build. Th is does n ot in clude t h e
size of ot h er dat a st ruct ures t h at h elp man age lin ear address region s. A
vast majorit y of t h is overh ead is at t ribut ed t o 128 doubly-lin ked list
n odes t h at man age free block ch ain s. Small blocks, less t h an 1KB in size,
are st ored wit h ot h er blocks of t h e same size in doubly lin ked list s. Th is
makes fin din g a best -fit block very fast . Blocks larger t h an 1KB are st ored
in on e sort ed, doubly-lin ked list . Th is is an obvious example of a t ime
versus space t rade-off, wh ich could be import an t t o t h e performan ce of
your applicat ion .
To un derst an d t h e design an d implemen t at ion of t h e Heap API, it is
import an t t o realize t h at a Win 32 h eap is n ot n ecessarily composed of
on e sect ion of con t iguous lin ear memory. For growable h eaps, it migh t
be n ecessary t o allocat e man y lin ear region s, usin g Virt ualAlloc, wh ich
BETA REVI EW
will gen erally be n on -con t iguous. Special dat a st ruct ures t rack all t h e
lin ear address region s t h at comprise t h e h eap. Th ese dat a st ruct ures are
call Heap Segmen t s. An ot h er import an t aspect of t h e Heap API design is
t h e use of t h e t wo-st age process of reservin g an d commit t in g virt ual
memory t h at is provided by t h e Virt ualAlloc an d relat ed APIs. Man agin g
wh ich memory is reserved an d wh ich memory is commit t ed requires
special dat a st ruct ures kn own as Un commit t ed Ran ge Tables, or UCRs for
sh ort .
Th e Nt dll!Rt lCreat eHeap() API implemen t s h eap creat ion an d in it ializa-
t ion . Th is rout in e allocat es t h e in it ial virt ual region wh ere t h e h eap
resides an d builds t h e appropriat e dat a st ruct ures wit h in t h e h eap. Th e
h eap dat a st ruct ure an d Heap Segmen t #1 reside wit h in t h e in it ial 4KB
(on e page) of t h e virt ual memory t h at is in it ially allocat ed for t h e h eap.
Heap Segmen t #1 resides just beyon d t h e h eap h eader. Heap Segmen t #1
is in it ialized t o man age t h e in it ial virt ual memory allocat ed for t h e h eap.
An y commit t ed memory beyon d Heap Segmen t #1 is immediat ely avail-
able for allocat ion t h rough HeapAlloc(). If an y memory wit h in Heap
Segmen t #1is reserved, a UCR t able en t ry is used t o t rack t h e un commit -
t ed ran ge.
N o t e : Ker n el 3 2 ! Heap Al l o c( ) i s Sn ap p ed t o N t d l l ! Rt l Al l o cat eHeap .
Besides t h e 128 free list s men t ion ed above, t h e h eap h eader dat a st ruc-
t ure con t ain s 8 UCR t able en t ries, wh ich sh ould be sufficien t for small
h eaps, alt h ough as man y UCRs as are n ecessary can be creat ed. It also
con t ain s a t able for sixt een (16) Heap Segmen t poin t ers. A h eap can
n ever h ave more t h an sixt een segmen t s, as n o provision is made for
allocat in g ext ra segmen t s en t ries. If t h e h eap requires t h read syn ch ron i-
zat ion , t h e h eap h eader appen ds a crit ical sect ion dat a st ruct ure t o t h e
en d of t h e fixed size port ion of t h e h eap h eader precedin g Heap Segmen t
#1.
Th e diagram on t h e n ext page is a h igh -level illust rat ion of h ow a t ypical
h eap is con st ruct ed, an d h ow t h e most import an t pieces relat e t o each
ot h er.
Th e left side of t h e diagram represen t s a region of virt ual memory t h at is
allocat ed for t h e h eap. Th e h eap h eader appears at t h e begin n in g of t h e
allocat ed memory an d is followed by Heap Segmen t #1. Th e first en t ry
wit h in t h e h eaps segmen t t able poin t s t o t h is dat a st ruct ure. Commit t ed
memory immediat ely follows Heap Segmen t #1. Th is memory is in it ially
marked as a free block. Wh en an allocat ion request is made, assumin g
t h is block of memory is large en ough , a port ion is used t o sat isfy t h e
allocat ion an d t h e remain der con t in ues t o be marked as a free block.
Beyon d t h e commit t ed region is an area of memory t h at is reserved for
BETA REVI EW
Fi g u r e 1 2 -2 . Ty p i cal Heap Co n st r u ct i o n
fut ure use. Wh en an allocat ion request requires more memory t h an is
curren t ly commit t ed, a port ion of t h is area is commit t ed t o sat isfy t h e
request .
Heap Segmen t #1 t racks t h e virt ual memory region in it ially allocat ed for
t h e h eap. Th e st art in g address for t h e h eap segmen t equals t o t h e base
address of t h e h eap an d t h e en d ran ge poin t s t o t h e en d of t h e allocat ed
memory. A port ion of t h e h eap in t h e diagram is in a reserved st at e, t h at
is, it h as n ot been commit t ed, so t h e h eap segmen t uses an available UCR
en t ry t o t rack t h e area. Wh en memory must be commit t ed t o sat isfy an
allocat ion request , all UCR en t ries main t ain ed by a part icular segmen t
are examin ed t o det ermin e if t h e size of t h e un commit t ed ran ge is large
BETA REVI EW
en ough t o sat isfy t h e allocat ion . To in crease performan ce, t h e h eap
segmen t t racks t h e largest available UCR ran ge an d t h e t ot al n umber of
un commit t ed pages wit h in t h e virt ual memory region of t h e h eap
segmen t .
On t h e righ t side of t h e diagram, a secon d area of virt ual memory was
allocat ed an d is man aged by Heap Segmen t #2. Addit ion al h eap segmen t s
are creat ed wh en an allocat ion request exceeds t h e size of t h e largest
un commit t ed ran ge wit h in t h e exist in g segmen t . Th is is on ly t rue if t h e
size of t h e request ed allocat ion is less t h an t h e h eaps VMt h resh old.
Wh en t h e request ed allocat ion size exceeds t h e VMTh resh old, t h e h eap
block is direct ly allocat ed t h rough Virt ualAlloc an d a n ew h eap segmen t
is n ot creat ed.
As men t ion ed previously, a small n umber of UCR en t ries are provided
wit h in t h e h eap h eader. For illust rat ion purposes, t h is diagram sh ows a
UCR TABLE en t ry t h at was allocat ed specifically t o in crease t h e n umber
of UCR en t ries t h at are available. Th e n eed t o creat e an ext ra UCR t able is
gen erally rare, an d is usually a sign t h at a large n umber of segmen t s were
creat ed or t h at t h e h eap segmen t s are fragmen t ed.
Fragmen t at ion of virt ual memory can occur wh en t h e Heap API begin s
decommit t in g memory durin g t h e coalescin g of free blocks. Decommit -
t in g memory is t h e t erm used t o describe revert in g memory from a
commit t ed st at e t o a reserved or un commit t ed st at e. Wh en a free block
span s more t h an on e ph ysical page (4k), t h at page becomes a can didat e
for bein g decommit t ed. If cert ain decommit t h resh old values are sat is-
fied, t h e Heap man ager begin s decommit t in g free pages. Wh en t h ose
pages are n ot con t iguous wit h an exist in g un commit t ed ran ge, a n ew
UCR en t ry must be used t o t rack t h e ran ge.
Th e followin g examples use t h e Soft ICE HEAP32 comman d t o examin e
t h e default h eap for t h e Explorer process.
1 Use t h e -S opt ion of t h e HEAP32 comman d t o display segmen t in for-
mat ion for t h e default h eap:
2 Use t h e -X opt ion of t h e HEAP32 comman d t o display ext en ded
in format ion about t h e default h eap:
BETA REVI EW
:heap32 -s 140000
Base Id Cmmt/Psnt/Rsvd Segments Flags Process
00140000 01 001C/0018/00E4 1 00000002 Explorer
01 00140000-00240000 001C/0018/00E4 E4000
Heap segment memory range
Largest UCR
Heap segment count
:heap32 -x 140000
Ext en ded Heap Summary for h eap 00140000 in Explorer
Heap Base: 140000 Heap Id: 1 Process: Explorer
Total Free: 6238 Alignment: 8 Log Mask: 10000
Seg Reserve: 100000 Seg Commit: 2000
Committed: 112k Present: 96k Reserved: 912k
Flags: GROWABLE
DeCommit: 1000 Total DeC: 10000 VM Alloc: 7F000
Default size for commits VM threshold Default size of a heap segment
BETA REVI EW
3 Use t h e -B opt ion of t h e HEAP32 comman d t o display t h e base
addresses of h eap blocks wit h in t h e default h eap:
In t h e above out put , you can see h ow t h e h eap h eader is followed by
Heap Segmen t #1 an d t h at t h e first allocat ed block is just beyon d t h e
Heap Segmen t dat a st ruct ure.
M an ag in g H e ap Blo cks
As discussed in t h e precedin g sect ion , t h e Heap API uses t h e Win 32
Virt ual Memory API rout in es t o allocat e large region s of t h e lin ear
address space an d uses h eap segmen t s t o man age commit t ed an d un com-
mit t ed ran ges. Th e act ual sub-allocat ion en gin e t h at man ages t h e alloca-
t ion an d deallocat ion of t h e memory blocks used by your applicat ion is
built on t op of t h is fun ct ion alit y. To t rack allocat ed an d free blocks, t h e
Heap API creat es a h eader for each block.
Th e diagram on t h e n ext page illust rat es h ow t h e h eap man ager t racks
blocks of contiguous memory. Th e h eap man ager also t racks n on -con t igu-
ous free blocks in doubly-lin ked list s, but t h e n ode poin t ers for t h e n ext
an d previous lin ks are n ot st ored in t h e block h eader. In st ead, t h e h eap
man ager uses t h e first t wo Dwords wit h in t h e h eap block memory area.
.As sh own in t h e diagram, each block st ores it s un it size as well as t h e
un it size of t h e previous block. Th e un it size represen t s t h e n umber of
h eap un it s occupied by t h e h eap block. Th e previous un it size is t h e
n umber of h eap un it s occupied by t h e previous h eap block. Usin g t h ese
t wo values, t h e h eap man ager is able t o walk con t iguous h eap blocks.
Heap un it s represen t t h e base gran ularit y of allocat ion s made from a
h eap. Th e size of an allocat ion request is roun ded upwards as n ecessary,
so t h at it is an even mult iple of t h is gran ularit y. Rat h er t h an usin g a
gran ularit y of 1 byt e, t h e h eap man ager uses a gran ularit y of 8 byt es. Th is
mean s t h at all allocat ion s are an even mult iple of 8 byt es, an d t h at
allocat ion sizes can be con vert ed t o un it s by roun d up an d dividin g by 8.
For example, if a process request s an allocat ion of 32 byt es, t h e n umber
of un it s is 32 / 8 = 4. If t h e allocat ion request was 34 byt es, t h e allocat ion
size is roun ded upward t o an even mult iple of 8. In t h is example, t h e 34
:heap32 -b 140000
Base Type Size Seg# Flags
00140000 HEAP 580 01
00140580 SEGMENT 38 01
001405B8 ALLOC 30 01
BETA REVI EW
Fi g u r e 1 2 -3 . Co n t i g u o u s M em o r y Tr acki n g
byt es request ed would be roun ded t o an allocat ion of 40 byt es, or 5 un it s.
Th e process request in g t h e allocat ion is un aware of an y roun din g t o
sat isfy un it gran ularit y an d proceeds as if t h e allocat ion request of 34
byt es was act ually 34 byt es.
By usin g a un it size of 8, t h e t ypes of allocat ion made by most applica-
t ion s can be recorded usin g on e word value wit h t h e rest rict ion t h at t h e
maximum size of a h eap block, in un it s, is t h e largest un sign ed sh ort or
0xFFFF. Th is makes t h e t h eoret ical maximum size of a h eap block in
byt es, 0xFFFF * 8, or 524,280 byt es. (Th is limit at ion is documen t ed in t h e
Win 32 HeapAlloc API documen t at ion .) Does t h at mean t h at a program
can n ot allocat e a h eap block great er t h an 512k? Well, yes an d n o. A h eap
block larger t h an 512k can n ot be allocat ed, but t h ere is n ot h in g t o
preven t t h e Heap API from usin g Virt ualAlloc t o allocat e a region of
lin ear memory t o sat isfy t h e request . Th is is exact ly wh at t h e h eap
man ager does if t h e size of t h e request ed allocat ion exceeds t h e h eaps
VMTh resh old. Th e value of VMTh resh old is st ored in t h e h eap h eader
an d by default is 520,192 byt es (or 0xFE000 un it s). Wh en t h e h eap
man ager allocat es a large h eap block usin g Virt ualAlloc, t h e result in g
st ruct ure is referred t o as a Virt ually Allocat ed Block (VAB).
Th e h eap man ager walks con t iguous h eap blocks by con vert in g t h e
curren t h eap blocks un it size in t o byt es an d addin g t h at t o t h e h eap
blocks base address. Th e address of t h e previous h eap block is calculat ed
in a similar man n er, con vert in g t h e un it size of t h e previous block t o
BETA REVI EW
byt es an d subt ract in g it from t h e h eap blocks base address. Th e h eap
man ager walks con t iguous h eap blocks durin g coalescin g free blocks,
sub-allocat in g a smaller block from a larger free block, an d wh en validat -
in g a h eap or h eap en t ry.
Un it sizes are import an t for free block list man agemen t as t h e array of
128 doubly-lin ked list s in side t h e h eap h eader t rack free blocks by un it
size. Free blocks t h at h ave a un it size in t h e ran ge from 1 t o 127 are
st ored in t h e free list at t h e correspon din g array in dex. Th us, all free
blocks of un it size 32 are st ored in Heap->FreeList s[32]. Because it is n ot
possible t o h ave a h eap block t h at is 0 un it s, t h e free list at array in dex
zero st ores all h eap blocks t h at are larger t h an 127 un it s; t h ese en t ries are
sort ed by size in ascen din g order. Because a majorit y of allocat ion s made
by a process are less t h an 128 un it s (1024 byt es or 1K), t h is is a fast way
t o fin d an exact or best fit block t o sat isfy an allocat ion . Blocks of 128
un it s or great er are allocat ed much less frequen t ly, so t h e overh ead of
doin g a lin ear search of on e free list does n ot h ave a large impact on t h e
overall performan ce of most applicat ion s.
Th e flags field wit h in t h e h eap block h eader den ot es special at t ribut es of
t h e block. On e bit is used t o mark a block as allocat ed versus free.
An ot h er is used if it is a VAB. An ot h er is used t o mark t h e last block
wit h in a commit t ed region . Th e last block wit h in a commit t ed region is
referred t o as a sen t in el block, an d in dicat es t h at n o more con t iguous
blocks follow. Usin g t h is flag is much fast er t h an det ermin in g if a h eap
block address is valid by walkin g t h e h eap segmen t s UCR ch ain . An ot h er
flag is used t o mark a block for free or busy-t ail ch eckin g. Wh en a process
is debugged, t h e h eap man ager marks t h e block in cert ain ways. Th us,
wh en an allocat ed block is released or a free block is reallocat ed, t h e h eap
man ager can det ermin e if t h e h eap block was overwrit t en in an y way.
Th e ext ra in fo fields of t h e h eap block h eader h ave differen t usage
depen din g on wh et h er t h e block is allocat ed or free. In an allocat ed
block, t h e first field records t h e n umber of ext ra byt es t h at were allocat ed
t o sat isfy gran ularit y or align men t requiremen t s. Th e secon d field is a
pseudo-t ag. Heap t ags an d pseudo t ags are beyon d t h e scope of t h is
discussion .
For a free block, t h e ext ra in fo fields h old byt e an d bit -mask values t h at
access a free-list -in -use bit -field main t ain ed wit h in t h e h eap h eader. Th is
bit -field provides quicker lookups wh en a small block n eeds t o be
allocat ed. Each bit wit h in t h e bit -field represen t s on e of t h e 127 small
block free list s, an d if t h e correspon din g bit is set , t h at free list con t ain s
on e or more free en t ries. A zero bit mean s t h at a free en t ry of t h at size is
n ot available an d a larger block will n eed t o be sub-allocat ed from. Th e
first ext ra in fo field h olds t h e byt e in dex in t o t h e bit -field array. Th e
BETA REVI EW
secon d ext ra in fo field h olds t h e in vert ed mask of t h e bit posit ion wit h in
t h e bit -field. Not e t h at t h is applies t o Win dows NT 3.51 on ly. Newer
version s of Win dows NT st ill use t h e free list bit -field, but do n ot st ore
t h e byt e in dex or bit -mask values. Th e h eap block memory array is also
differen t depen din g on t h e allocat ed st at e of t h e free block. For allocat ed
blocks, t h is is t h e act ual memory used by your applicat ion . For free
blocks, t h e first t wo Dwords (1 un it ) are used as n ext an d previous poin t -
ers t h at lin k free blocks t oget h er in a doubly-lin ked list . If t h e process
t h at allocat ed t h e h eap block is bein g debugged, an allocat ed h eap block
also con t ain s a busy-t ail sign at ure at t h e en d of t h e block. Free blocks are
marked wit h a special t ag t h at can det ect if a st ray poin t er writ es in t o t h e
h eap memory area, or t h e process con t in ues t o use t h e block aft er it was
deallocat ed.
Th e followin g diagram sh ows t h e basic arch it ect ure of an allocat ed h eap
block.
Fi g u r e 1 2 -4 . Basi c Arc h i t ect u r e o f an Al l o cat ed Heap Bl o ck
Th e port ion labeled Extra Bytes is memory t h at was n eeded t o sat isfy t h e
h eap un it size or h eap align men t requiremen t s. Th is memory area sh ould
n ot be used by t h e allocat in g process, but t h e h eap man ager does n ot
direct ly prot ect t h is area from bein g overwrit t en . Th e busy-t ail sign at ure
appears just beyon d t h e en d of t h e memory allocat ed for use by t h e
process. If an applicat ion writ es beyon d t h e size of t h e area request ed,
t h is sign at ure is dest royed an d t h e h eap man ager sign als t h e debugger
wit h a debug message an d an INT 3. It is possible for a process t o writ e
in t o t h e ext ra byt es area wit h out dist urbin g t h e busy-t ail sign at ure. In
t h is case, t h e overwrit e is n ot caugh t . Th e Heap API provides an opt ion
for in it ializin g h eap memory t o zero upon allocat ion . If t h is opt ion is n ot
specified wh en debuggin g, t h e h eap man ager fills t h e allocat ed memory
block wit h a special sign at ure. You can use t h is sign at ure t o det ermin e if
t h e memory block was properly in it ialized in your code.
Th e followin g diagram sh ows t h e basic arch it ect ure of a free h eap block.
Fi g u r e 1 2 -5 . Basi c Arc h i t ect u r e o f a Fr ee Heap Bl o ck
BETA REVI EW
Wh en a block is deallocat ed an d t h e process is bein g debugged, t h e h eap
man ager writ es a special sign at ure in t o t h e h eap memory area. Wh en t h e
block is allocat ed at some poin t in t h e fut ure, t h e h eap man ager ch ecks
t h at t h e t ag byt es are in t act . If an y of t h e byt es was ch an ged, t h e h eap
man ger out put s a debug message an d execut es an INT 3 in st ruct ion . Th is
is a good t h in g if t h e debugger you are usin g t raps t h e INT 3, but most
debuggers ign ore t h is debug-break because it was n ot set by t h e debugger.
As an aside, h avin g t h e Free List Node poin t ers at t h e begin n in g of t h e
memory block is somewh at flawed, because a program t h at con t in ues t o
use a free block is more likely t o overwrit e dat a at t h e begin n in g of t h e
block t h an dat a at t h e en d. Because t h ese poin t ers are crucial t o n avigat -
in g t h e h eap, an in valid poin t er even t ually causes an except ion . Wh en
t h is except ion occurs, it can be quit e difficult t o t rack t h is overwrit e back
t o t h e origin al free block.
Th e followin g t wo examples sh ow h ow t o use t h e Soft ICE HEAP32
comman d t o aid in mon it orin g an d debuggin g Win 32 h eap issues.
Th e first example uses t h e HEAP32 comman d t o walk all t h e en t ries for
t h e h eap based at 0x140000. Th e -B opt ion of t h e HEAP32 comman d
causes t h e base address an d size in format ion t o display as t h e h eap
man ager would view t h e in format ion . Wit h out t h e -B opt ion , t h e
HEAP32 comman d sh ows base addresses an d sizes as viewed by t h e appli-
cat ion t h at allocat ed t h e memory. Th e out put is abbreviat ed for clarit y
an d t h e t wo h eap blocks t h at appear in bold t ype are used t o examin e t h e
h eap block h eader in t h e secon d example.
To examin e t h e con t en t s of an allocat ed h eap block an d a free block, t h e
secon d example dumps memory at t h e base address of t h e h eap block at
0x143FE0. En ough memory is dumped t o sh ow t h e subsequen t block,
wh ich is a free block at address 0x144008.
Th e h eap block h eader fields from t h e memory dump at address
0x143FE0 are iden t ified wit h call-out s. Th is h eap block is 5 un it s in size
:HEAP32 -b 140000
Base Type Size Seg# Flags
00140000 HEAP 580 01
00140580 SEGMENT 38 01 TAGGED | BUSYTAIL
001405B8 ALLOC 40 01
. . .
00143FE0 ALLOC 28 01 TAGGED | BUSYTAIL
00144008 FREE FF8 01 FREECHECK | SENTINEL
BETA REVI EW
(40 byt es) an d 0x1C byt es of t h at size is overh ead for t h e h eap block
h eader (1 un it ), busy-t ail (1 un it ), un it align men t (1 Dword), an d an ext ra
un it left over from a previous allocat ion .
Th e h eap block immediat ely followin g t h is is a free block t h at begin s at
address 0x144008. Th is block is 0x1FF un it s an d t h e size of t h e previous
block is 5 un it s. For free blocks 1KB or larger (80+ un it s), t h e Free List
byt e posit ion an d bit -mask values are n ot used an d are zero. Th e flag for
t h is h eap block in dicat es t h at it is a sen t in el (bit 4, or 0x10). Immediat ely
followin g t h e h eap h eader is t h e locat ion wh ere t h e h eap man ager h as
placed a doubly-lin ked list n ode for t rackin g free blocks. Th e poin t er
values for t h e n ext an d previous fields of t h e n ode are bot h 0x1400B8.
Aft er t h e free list n ode, t h e h eap man ager t agged all t h e blocks memory
wit h a special sign at ure t h at is validat ed t h e n ext t ime t h e block is
allocat ed, coalesced wit h an ot h er block, or a h eap validat ion is
performed.
0010:00143FE0 0005 0006 00 07 1C 00
0010:00143FE8 00000000 00000000 60A25F52
0010:00143FF4 ABABABAB ABABABAB
0010:00143FFC FEEEFEEE 00000000 00000000
Unit size
Previous unit size
Unused bytes Busy tail signature
Heap memory area
Segment number Flags
Extra bytes
Tag
BETA REVI EW
0010:00144008 01FF 0005 00 14 00 00
0010:00144010 001400B8 001400B8
0010:00144018 FEEEFEEE FEEEFEEE FEEEFEEE FEEEFEEE
Unit size
Previous unit size
Doubly linked free list node
Free check signature
Segment number Flags
Free list byte position
Free list bit mask
BETA REVI EW
2 1 7
BETA REVI EW
Ap p en d i x A
Error Messages
All b r e ak r e g ist e r s use d , use in RAM o n ly
You were t ryin g t o set a BPX breakpoin t in ROM an d all t h e debug
regist ers were already used. BPX will st ill work in RAM, because it uses
t h e INT 3 met h od. You must clear on e of t h e BPM-st yle breakpoin t s
before t h is will work.
At t a ch t o se r i al d e vi ce h a s FAI LED
Th e in it ial serial h an dsh akin g sequen ce failed. Th is migh t h appen if t h e
wron g serial port is select ed, t h e t arget mach in e is n ot run n in g
SERIAL.EXE, or t h e serial cable is fault y.
BPM b r e akp o in t li m it e xce e d e d
On ly four BPM-st yle breakpoin t s are allowed due t o rest rict ion s of x86
processors. You must clear on e of t h e BPM-st yle breakpoin t s before t h is
will work.
BPM D ad d r e ss m ust b e o n D W o r d b o un d ar y
Th e address specified in BPMD did n ot st art on a Dword boun dary. A
Dword boun dary must h ave t h e t wo least sign ifican t bit s of t h e address
equal 0.
BPM W ad d r ess m ust b e o n W o r d b o u n d a r y
Th e address specified in BPMW did n ot st art on a Word boun dary. A
Word boun dary must h ave t h e least sign ifican t bit of t h e address equal 0.
Br e akp o i n t s n o t al lo w e d w i t h in So f t I CE
You can n ot set breakpoin t s in Soft ICE code.
Can n ot i n t e r r up t t o a le ss p r i vil e g e d le ve l
You can n ot use t h e GENINT comman d t o go from a lower level t o a
h igh er privilege level. Th is is a rest rict ion of t h e x86 processor.
BETA REVI EW
D e b ug r e g ist e r is alr e a d y b e in g use d
Debug-regist er specified in BPM comman d was already used in a previous
BPM comman d.
D up licat e b r e a kp o in t
Th e specified breakpoin t already exist s.
Exp e ct in g value, n o t ad d r ess
Th e expression evaluat or broadly classifies operan ds as addresses an d
values. Addresses h ave a select or/ segmen t an d offset compon en t even if
t h e address is flat . Cert ain operat ors such as * an d / expect on ly plain
values, n ot addresses, an d an at t empt t o use t h em on addresses produces
t h is message. In some cases usin g t h e in direct ion operat ors produces an
address; refer t o Supported Operators on page 124 for det ails.
Exp r e ssio n ?? W h at e xp r e ssio n ?
Th e expression evaluat or did n ot fin d an yt h in g t o evaluat e. Not e t h at in
some older version s of Soft ICE t h e ? comman d could be used t o get h elp.
Th is is n o lon ger t h e case; use t h e H comman d (F1).
I n t 0 D f a ult i n So f t I CE at ad d r e ss X X X X X o f f se t X X X X X
Fault Co d e = X X X X
(or the following message)
I n t 0 E Fa ult i n So f t I CE at ad d r e ss X X X X X o f f se t X X X X X
Fault Co d e = X X X X
Th ese t wo messages are in t ern al Soft ICE errors. Th e code wit h in Soft ICE
caused eit h er a gen eral prot ect ion fault (0D) or a page fault (0E). Th e
offset is t h e offset wit h in t h e code t h at caused t h e fault . Please writ e
down t h e in format ion con t ain ed in t h e message an d e-mail or call us.
Th ese messages also display t h e values in t h e regist ers. Be sure t o writ e
down t h ese values also.
I n valid D e b ug r e g ist e r
A BPM debug-regist er great er t h an 3 was specified. Valid debug regist ers
are DR0, DR1, DR2, an d DR3.
N o co d e at t h is lin e n um b e r
Th e lin e n umber specified in t h e comman d h as n o code associat ed wit h
it .
N o cur r e n t so ur ce f i le
You en t ered t h e SS comman d an d t h ere was n o source file curren t ly on
t h e screen .
Ap p en d i x A Er r o r M essag es 2 1 9
BETA REVI EW
N o em b ed d ed I N T 1 o r I N T 3
Th e ZAP comman d did n ot fin d an embedded in t errupt 1 or in t errupt 3
in t h e code. Th e ZAP comman d on ly works if t h e INT 1 or INT 3
in st ruct ion is t h e on e before t h e curren t CS:EIP.
N o f il e s f o un d
Th e curren t symbol t able does n ot h ave an y source files loaded for it .
N o LD T
Th is message displays wh en you use cert ain 16-bit Win dows in format ion
comman ds (HEAP, LHEAP, LDT, an d TASK) an d t h e curren t con t ext is n ot
set t o t h e proper NTVDM process.
N o Lo cal H e ap
Th e LHEAP comman d specified a select or t h at h as n o local h eap.
N o m o r e W at ch var i ab l e s al lo w e d
A maximum of eigh t wat ch variables are allowed.
N o se a r ch in p r o g r e ss
You specified t h e S comman d wit h out paramet ers an d n o search was in
progress. You must first specify S wit h an address an d a dat a-list for
paramet ers. To search for subsequen t occurren ces of t h e dat a-list , use t h e
S comman d wit h n o paramet ers.
N O _SI Z E
Durin g an A comman d, t h e assembler can n ot det ermin e wh et h er you
wan t ed t o use byt e, word, or double word.
N o sym b o l t ab l e
You en t ered t h e SYM, SS, or FILE comman d an d t h ere are n o symbols
curren t ly presen t .
N o TSS
You en t ered t h e TSS comman d wh ile t h ere was n o valid t ask st at e
segmen t in t h e syst em.
O n ly val id in so u r ce m o d e
You can n ot use t h e SS comman d in mixed mode or code mode.
Pa g e n o t p r e se n t
Th e specified address was marked n ot presen t in t h e page t ables. Wh en
Soft ICE was t ryin g t o access in format ion , it accessed memory t h at was in
a page marked n ot presen t .
BETA REVI EW
Pa r a m et e r i s w r o n g si z e
On e of t h e paramet ers you en t ered in t h e comman d was t h e wron g size.
For example, if you use t h e EB or BPMB comman ds wit h a word value
in st ead of a byt e value.
Pa t t er n n o t f o un d
Th e S comman d did n ot fin d a mat ch in it s search for t h e dat a-list .
Pr e ss C t o co n t in ue , an d R t o r e t ur n t o So f t I CE
Soft ICE popped up due t o a fault (06, 0C, 0D, 0E). Press R t o ret urn
con t rol t o Soft ICE. Press C t o pass t h e fault on t o t h e Win dows fault
h an dler.
So f t I CE is n o t act i ve
Th is message displays on t h e h elp lin e on mon och rome an d serial
displays wh en Soft ICE is n o lon ger act ive.
Sp e ci f ie d n a m e n o t f oun d
You t yped TABLE wit h an in valid t able-n ame. Type TABLE wit h n o
paramet ers t o see a list of valid t able n ames.
Sym b o l n o t d e f in e d ( m ysym b o l)
You referred t o a n on -exist en t symbol. Use t h e SYM comman d t o get a
list of symbols for t h e curren t symbol t able.
2 2 1
BETA REVI EW
Ap p en d i x B
Support ed Display Adapt ers
Th e followin g t able list s t h e display adapt ors Soft ICE support ed wh en t h e
product most recen t ly sh ipped. However, Compuware regularly adds n ew
display adapt or support t o en h an ce Soft ICE. You can down load t h e lat est
support files from t h e Compuware FTP or BBS sit es. Refer t o Installing
SoftICE in Getting Stared with DriverStudio for more in format ion about
down loadin g support files.
Sup p or t e d D i sp lay Ad ap t or s
St an dard Display Adapt er
(VGA)
Act ix Graph icsEn gin e 32I VL Act ix Graph icsEn gin e 32VL
Plus
Act ix Graph icsEn gin e 64 Act ix Graph icsEn gin e Ult ra
64
Act ix Graph icsEn gin e Ult ra
Plus
Act ix Graph icsEn gin e Ult ra
VL Plus
Act ix ProSTAR Act ix ProSTAR 64
ATI 8514-Ult ra ATI Graph ics Pro Turbo ATI Graph ics Pro Turbo PCI
ATI Graph ics Ult ra ATI Graph ics Ult ra Pro ATI Graph ics Ult ra Pro EISA
ATI Graph ics Ult ra Pro PCI ATI Graph ics Van t age ATI Graph ics Won der
ATI Graph ics Xpression ATI 3d Xpression PCI ATI VGA Won der
ATI Video Xpression PCI ATI Win Turbo Boca SuperVGA
Boca SuperX Boca Voyager Cardin al VIDEOcolor
Cardin al VIDEOspect rum Ch ips & Tech n ologies 64310
PCI
Ch ips & Tech n ologies
65545 PCI
Ch ips & Tech n ologies 65548
PCI
Ch ips & Tech n ologies
Accelerat or
Ch ips & Tech n ologies Super
VGA
Cirrus Logic Cirrus Logic 5420 Cirrus Logic 5430 PCI
Cirrus Logic New Cirrus Logic PCI Cirrus Logic RevC
Cirrus Logic 7542 PCI Cirrus Logic 7543 PCI Compaq Qvision 2000
DEC PC76H-EA DEC PC76H-EB DEC PC76H-EC
DEC PCXAG-AJ DEC PCXAG-AK DEC PCXAG-AN
BETA REVI EW
DFI WG-1000 DFI WG-1000VL Plus DFI WG-1000VL/ 4 Plus
DFI WG-3000P DFI WG-5000 DFI WG-6000VL
Diamon d Edge 3D 2200XL Diamon d Edge 3D 3200XL Diamon d Edge 3D 3400XL
Diamon d SpeedSt ar Diamon d SpeedSt ar 24 Diamon d SpeedSt ar 24X
Diamon d SpeedSt ar 64 Diamon d SpeedSt ar Pro Diamon d SpeedSt ar Pro SE
Diamon d St ealt h 3D 2000 Diamon d St ealt h 24 Diamon d St ealt h 32
Diamon d St ealt h 64 2001 Diamon d St ealt h 64 (S3 964) Diamon d St ealt h 64 (S3
968)
Diamon d St ealt h 64 Video Diamon d St ealt h Pro Diamon d St ealt h SE
Diamon d Viper OAK Diamon d Viper PCI Diamon d Viper VLB
Diamon d St ealt h VRAM ELSA WINNER 1000AVI ELSA WINNER 1000PRO
ELSA WINNER 1000Trio ELSA WINNER 1000 VL ELSA WINNER 1280
ELSA WINNER 2000PRO ELSA WINNER 2000 VL ELSA WINNER/ 2-1280
Gen oa Digit al Video Wizard
1000
Gen oa Ph an t om 32I Gen oa Ph an t om 64
Gen oa Win dowsVGA 24
Turbo
Gen oa Win dowsVGA 64
Turbo
Hercules Dyn amit e
Hercules Dyn amit e Pro Hercules Graph it e 64 Hercules Graph it e
Termin at or 64
Hercules Graph it e
Termin at or Pro
IBM 8514 IBM Th in kPad 755CX
IBM Th in k Pad 365XD Mat rox MGA Impression Lit e Mat rox MGA Impression
Plus
Mat rox MGA Impression
Plus 220
Mat rox MGA Ult ima Plus Mat rox MGA Ult ima Plus
200
Mat rox MGA Millen n ium Number Nin e GXE Number Nin e GXE64
Number Nin e GXE64 Pro Number Nin e 9FX Vision 330 Number Nin e 9FX Mot ion
531
Number Nin e 9FX Mot ion
771
Number Nin e Flash Poin t 32 Number Nin e Flash Poin t 64
Number Nin e Imagin e 128 Number Nin e Realit y 332 Nvidia NVI Media
Con t roller
Oak Tech n ology 087 Oak Tech n ology Super VGA Orch id Fah ren h eit 1280
Plus
Orch id Fah ren h eit Pro 64 Orch id Fah ren h eit VA Orch id Kelvin 64
Orch id Kelvin EZ Orch id ProDesign er II Paradise Accelerat or Port s
OCall
Paradise Accelerat or VL Plus Paradise Bah amas Paradise Barbados 64
Sup p or t ed D isp lay Ad ap t or s
Ap p en d i x B Su p p o r t ed D i sp l ay Ad ap t er s 2 2 3
BETA REVI EW
Paradise Super VGA S3 805 S3 911/ 924
S3 928 PCI S3 Trio32/ 64 PCI S3 ViRGE PCI
S3 Vision 864/ 964 PCI S3 Vision 868/ 968 PCI Spider 32 VLB
Spider 32Plus VLB Spider 64 Spider Taran t ula 64
STB Ergo MCX STB Horizon STB Horizon Plus
STB Ligh t Speed STB MVP-2X STB MVP-4X
STB Nit ro STB Pegasus STB PowerGraph Pro
STB PowerGraph VL-24 Triden t 9420 PCI Triden t Cyber 93XX
Triden t Super VGA Tsen g Labs Tsen g Labs ET4000
Tsen g Labs ET4000/ W32 Tsen g Labs ET6000 Video Logic 928Movie
Video Seven VRAM/ VRAM
II/ 1024i
West ern Digit al West ern Digit al (512K)
Weit ek Power 9000 Weit ek Power 9100
Sup p or t ed D isp lay Ad ap t or s
BETA REVI EW
2 2 5
BETA REVI EW
Ap p en d i x C
Troubleshoot ing Soft ICE
If you en coun t er an y of t h e followin g problems, t ry t h e correspon din g
solut ion . If you en coun t er furt h er difficult ies, t ech n ical support is avail-
able from our Tech n ical Support Hot lin e or via our Fron t Lin e Support
Web sit e.
Tech n ical Support Hot lin e: 1-800-538-7822
Fron t Lin e Support Web Sit e: h t t p:/ / fron t lin e.compuware.com.
Pr ob le m So lut ion
Th e So f t ICE scr een i s b l ack o r
u n r ead ab l e.
Ei t h er y o u r d i sp l ay ad ap t o r d o es n o t m at ch t h e
d i sp l ay ad ap t o r set at i n st al l at i o n o r So f t ICE d o es
n o t su p p o r t y o u r d i sp l ay ad ap t o r. Ref er t o
Appendix B: o n p ag e 2 2 1 .
Th e PC cr ash es w h en y o u r u n
So f t ICE an d y o u ar e n o t u si n g a
Pen t i u m o r Pen t i u m - Pr o p r o ces-
so r.
So f t ICE i n co r r ect l y d et er m i n ed t h at y o u r sy st em
i s u si n g a Pen t i u m p r o cesso r. M o d i f y t h e So f t ICE
In i t i al i zat i o n Set t i n g s t o d i sab l e Pen t i u m su p p o r t .
Ref er t o Setting Troubleshooting Options o n
p ag e 1 7 6 .
Th e PC cr ash es w h en y o u r u n
So f t ICE f o r Wi n d o w s 9 x .
So f t ICE d o es n o t su p p o r t t h e sh u t d o w n o p t i o n
RESTART THE COMPUTER IN MS-DOS MODE?.
If y o u r el o ad So f t ICE af t er ch o o si n g t h i s o p t i o n ,
So f t ICE ev en t u al l y cr ash es.
In st ead , ch an g e t h e st at em en t Bo o t GUI= 1 t o
Bo o t GUI= 0 w i t h i n t h e Wi n d o w s 9 5 an d Wi n d o w s
9 8 h i d d en f i l e M SD O S. SYS. Th en , ch o o se SHUT
DOWN THE COMPUTER? t o ex i t t o D O S.
Yo u h av e d i f f i cu l t y est ab l i sh i n g a
m o d em co n n ect i o n .
Th e m o d em i s r et u r n i n g r esu l t co d es So f t ICE
d o es n o t ex p ect . So f t ICE l o o ks f o r t h e co d es O K,
CO M N ECT, an d RIN G. Pl ace ATXO i n t h e i n i t i al -
i zat i o n st r i n g .
BETA REVI EW
Th e m o u se b eh aves er r at i cal l y
w i t h i n So f t ICE.
Pr ess Ct r l - M .
Wi n d o w s N T o n l y : t h e m o u se
p o i n t er b eh av es er r at i cal l y i n t h e
So f t ICE sc r een .
M o vi n g t h e m o u se w h i l e t h e So f t ICE scr een p o p s
u p , can cau se Wi n d o w s N T an d t h e m o u se h ar d -
w ar e t o b eco m e o u t o f sy n ch r o n i zat i o n . Sw i t ch
t o a f u l l scr een D O S b o x .
Yo u r key b o ar d l o cks o r b eh av es
er r at i cal l y w h en y o u l o ad So f t ICE.
M o d i f y t h e So f t ICE In i t i al i zat i o n Set t i n g s t o d i s-
ab l e n u m l o ck an d c ap s l o ck p r o g r am m i n g . If t h i s
d o es n o t w o r k an d y o u ar e u si n g Wi n d o w s N T,
i n st r u ct So f t ICE n o t t o p at ch t h e key b o ar d d r i v er.
Ref er t o Setting Troubleshooting Options o n
p ag e 1 7 6 .
Wi n d o w s 9 x cr ash es w h en
at t em p t i n g t o scan f o r ser i al p o r t s.
If y o u p l ac ed t h e SERIAL co m m an d i n t h e In i t i al -
i zat i o n st r i n g , So f t ICE est ab l i sh es a co n n ect i o n t o
t h e p o r t b ef o r e Wi n d o w s 9 x i n i t i al i zes. W h en
Wi n d o w s 9 x i n i t i al i ze, i t m i g h t scr am b l e t h e co n -
n ect i o n . D i sab l e t h e p o r t sel ect ed i n t h e D evi ce
M an ag er. Th e D ev i ce M an ag er i s l o cat ed w i t h i n
t h e Sy st em Pr o p er t i es i n y o u r Co n t r o l Pan el .
Pr o b le m Sol ut i on
2 2 7
BETA REVI EW
Ap p en d i x D
Kernel Debugger Ext ensions
Soft ICE for Win dows NT/ 2000/ XP support s Kern el Debugger (KD)
Ext en sion s writ t en for Win DBG. Soft ICE will t ake a Win DBG ext en sion ,
con vert it t o a Kern el mode driver, an d allow t h e user t o execut e
in format ion al comman ds. Users can also writ e t h eir own ext en sion s
followin g t h e Win DBG in t erface (as foun d in Wdbgext s.h ), an d con vert
t h em for use in Soft ICE.
To prepare a KD Ext en sion for use wit h Soft ICE:
1 Use t h e KD2SYS or KD2SYSXLAT program t o con vert t h e DLL t o a
syst em driver. Th is program:
a Copies t h e DLL t o t h e \ SYSTEMROOT\ SYSTEM32\ DRIVERS
direct ory an d gives it an ext en sion of .SYS
b Modifies t h e file t o t ell t h e syst em t h at t h e file can be loaded as a
syst em driver an d redirect man y API calls t o Soft ICE
c Creat es t h e n ecessary keys in t h e syst em regist ry t o iden t ify t h e
n ew file as a syst em driver
2 Reboot t h e syst em. Wh en an y syst em drivers (services) are added or
removed from your syst em, it must be reboot ed. Th is allows t h e
service con t rol man ager t o refresh t h e list of services in t h e syst em.
3 If you are st art in g Soft ICE man ually, you will n eed t o st art t h e
ext en sion , in t h is case by usin g t h e NET START <KDExt en sion
n ame> comman d from t h e comman d prompt t o load t h e ext en sion
in t o Soft ICE.
If you are usin g ot h er st art modes, t h e ext en sion will be st art ed
aut omat ically at t h e appropriat e t ime. Furt h er, wh en you ch an ge t h e
BETA REVI EW
st art mode of Soft ICE usin g t h e St art up Mode Set up sh ort cut , all
ext en sion s will be ch an ged t o st art wit h Soft ICE.
4 Aft er t h e service is st art ed, press Ct rl-D t o open t h e Soft ICE win dow.
Type !? or !h elp t o get a list of t h e comman ds an d a sh ort
explan at ion of each on e.
Th e requiremen t s for usin g Kern el Debugger Ext en sion s are list ed below:
1 You must h ave t h e curren t NTOSKRNL.n ms loaded. Tran slat e t h e
.dbg file an d use Loader32 t o aut omat ically load t h e file wh en
Soft ICE st art s.
2 No file IO is allowed in a KD Ext en sion . Th e DLL will be con vert ed,
but an y at t empt t o call a file IO fun ct ion will result in t h e comman d
t h at issued t h e request bein g t ermin at ed.
3 Do n ot use except ion h an dlin g in a KD Ext en sion . Again , t h e
ext en sion will con vert , but an y comman d t h at at t empt s t o execut e
an except ion h an dler will be t ermin at ed.
4 A default st ack of 32k an d a default h eap of 8k are allocat ed wh en
Soft ICE st art s. Th ese values can be in creased or decreased via t h e
regist ry keys: KDHeapSize an d KDSt ackSize
(HKey_LocalMach in e\ Curren t Con t rolSet \ Services\ NTICE).
If you ch an ge t h e values usin g t h e regist ry keys, a reboot will be
n ecessary t o refresh t h e values.
2 2 9
Glossary
In t er r u p t D escr i p t o r
Tab l e ( ID T)
Table poin t ed t o by t h e IDTR regist er, wh ich defin es t h e in t errupt /
except ion h an dlers. Use t h e IDT comman d t o display t h e t able.
M AP f i l e Human -readable file con t ain in g debug dat a, in cludin g global symbols
an d usually lin e n umber in format ion.
M M X Mult imedia ext en sion s t o t h e In t el Pen t ium an d Pen t ium-Pro processors.
O b j ect Represen t s an y h ardware or soft ware resource t h at n eeds t o be sh ared as
an object . Also, t h e t erm sect ion is somet imes called an object . Refer t o
section.
O n e- Sh o t Br eakp o i n t Breakpoin t t h at on ly goes off on ce. It is cleared aft er t h e first t ime it goes
off or t h e n ext t ime Soft ICE pops up for an y reason .
O r d i n al Fo r m Wh en a symbol t able is n ot relocat ed, it is said t o be in it s ordin al form;
in t h is st at e, t h e select ors are sect ion n umbers or segmen t n umbers (for
16 bit ).
Po i n t -an d - Sh o o t
Br eakp o i n t
Breakpoin t you set by movin g t h e cursor in t o t h e code win dow usin g t h e
BPX or HERE comman d.
Rel o c at e Adjust program addresses t o accoun t for t h e programs act ual load
address.
Sect i o n In t h e PE file format , a ch un k of code or dat a sh arin g various at t ribut es.
Each sect ion h as a n ame an d an ordin al n umber.
St i cky Br eakp o i n t Breakpoin t t h at remain s un t il you remove it . It remain s even t h rough
un loadin g an d reloadin g of your program.
SYM Fi l e File con t ain in g debug dat a, in cludin g global symbols an d usually lin e
n umber in format ion . Th e SYM file is usually derived from a MAP file.
Sy m b o l Tab l e Soft ICE-in t ern al represen t at ion of t h e debuggin g in format ion , for
example, symbols an d lin e n umbers associat ed wit h a specific module.
Vi r t u al Br eakp o i n t Breakpoin t t h at can be set on a symbol or a source lin e t h at is n ot yet
loaded in memory.
2 3 1
BETA REVI EW
Index
Symbols
+ (plus sign ), 82, 84
. (dot ) comman d, 80
A
A comman d, 80
ADDR comman d, 189, 190
Address
space, 202
t ype, 133
Alt -C, 76
Alt -D, 87
ALTKEY comman d, 59
Alt -L, 21, 81
Alt -R, 85
Alt -W, 83
ANSWER comman d, 158
ANSWER in it ializat ion st rin g, 171
Applicat ion s
buildin g, 34
debuggin g, 32
Arrays
collapsin g, 20
expan din g, 20
Assign in g expression s, 90
B
baudrat e, 157
BC comman d, 29, 122
BD comman d, 29, 122
BE comman d, 122
BH comman d, 122
Bit wise operat ors, 124
BL comman d, 22, 28, 122
BMSG comman d, 104, 109
Borlan d compiler, 34
BPCOUNT fun ct ion , 114
BPE comman d, 27, 122
BPINDEX expression fun ct ion , 116
BPINT comman d, 104, 107
BPIO comman d, 104, 109
BPLOG expression fun ct ion , 116
BPM comman d, 104, 106
BPMD comman d, 28
BPMISS expression fun ct ion , 115
BPT comman d, 122
BPTOTAL expression fun ct ion , 116
BPX
breakpoin t , 26
comman d, 22, 80, 104, 106
Breakpoin t act ion , 105
set t in g, 112
Breakpoin t in dex, 121, 122
Breakpoin t s
BPCOUNT fun ct ion , 114
BPINDEX, 116
BPLOG fun ct ion , 116
BPMISS fun ct ion , 115
BPTOTAL fun ct ion , 116
BPX, 26
clearin g, 29
con dit ion al, 25, 112
con dit ion al expression , 105
con t ext , 111
crit eria t o t rigger, 111
disablin g, 29
duplicat e, 120
BETA REVI EW
elapsed t ime, 121
embedded, 122
execut ion , 104, 105
expression s, 121
I/ O, 104, 108
INT 1 an d INT 3, 122
in t errupt , 104, 107
man ipulat in g, 121
memory, 28, 104, 106
on e-sh ot , 21
poin t -an d-sh oot , 22
st at ist ics, 121
st icky, 22, 103
t ypes, 104
usin g, 103
virt ual, 111
win dow message, 104, 109
BSTAT comman d, 116, 117, 121
Buildin g
applicat ion s, 34
debug in format ion , 16
Built -in fun ct ion s, 129
C
ch an ge regist ry en t ry, 146
Ch aract er con st an t s, 127
Ch ecked build, 180
CLASS comman d, 23
Clearin g
breakpoin t s, 29
Closin g
Code win dow, 76
Dat a win dow, 87
FPU St ack win dow, 93
Locals win dow, 81
Regist er win dow, 85
Soft ICE win dows, 62
Wat ch win dow, 83
Code mode, 78
Code win dow, 17, 60, 76
closin g, 76
disassembled in st ruct ion , 78
en t erin g comman ds, 80
JUMP, 79
modes, 77
movin g t h e cursor t o, 63, 76
NO JUMP, 79
open in g, 76
resizin g, 76
scrollin g, 76
st rin gs, 79
Collapsin g
arrays, 20
st acks, 82
st rin gs, 20
st ruct ures, 20
t yped expression s, 84
Comman d h ist ory
recallin g, 73
Comman d lin e argumen t s
passin g, 38
comman d prompt , 157
Comman d win dow, 60, 69
associat ed comman ds, 76
h ist ory buffer, 75
scrollin g, 70
Comman ds
. (dot ), 80
A, 80
ALTKEY, 59
ANSWER, 158
BC, 29, 122
BD, 29, 122
BE, 122
BH, 122
BL, 22, 28, 122
BMSG, 104, 109
BPE, 27, 122
BPINT, 104, 107
BPIO, 104, 109
BPM, 104
BPMD, 28
BPX, 22, 80, 104, 106
BSTAT, 121
CLASS, 23
CR, 87
D, 87, 90, 91
DATA, 87
I n d ex 2 3 3
BETA REVI EW
DEX, 90, 91
DIAL, 158
E, 91
edit in g, 72
en t erin g, 68, 70
FILE, 18, 80
FORMAT, 87, 90
G, 21, 28, 85, 87
H, 23, 69
HERE, 21, 80, 106
HWND, 26, 110
IDT, 107
in format ional, 23
LINES, 61
LOADER32, 44, 45
LOCALS, 82
MACRO, 74
P, 20, 85, 87, 177
recallin g, 73
S, 91
SET, 70, 76, 80
SRC, 20, 80
SS, 80
SYM, 25
syn t ax, 70
T, 87
TABLE, 24
TABS, 80
TYPES, 82
U, 19, 21, 80
WATCH, 83
WC, 76
WD, 87
WF, 93
WL, 81
WR, 85
WS, 91
WW, 83
WX, 92
X, 28
Comman ds T, 85
comman ds, Un iversal Video Driver, 58
Compiler opt ion s
32-bit , 34
Compilers
Borlan d, 34
Delph i, 34
MASM, 35
Microsoft Visual C++, 35
Syman t ec C++, 35
Wat com C++, 35
Con dit ion al breakpoin t s, 112
coun t fun ct ion s, 114
performan ce, 120
set t in g, 25
Con dit ion al expression
breakpoin t s, 105
con n ect ion ben efit s/ disadvan t ages, 146
Con t rollin g Soft ICE win dows, 61
Copyin g dat a, 67
Coun t fun ct ion s
con dit ion al expression s, 114
CPU flags, 85
CR comman d, 87
Creat in g
Persist en t Macros, 173
CSRSS, 195
Ct rl-D, 59
Cursor
movin g amon g win dows, 63
Cust omizin g Soft ICE, 161
Cyclin g Dat a win dows, 87
D
D comman d, 87, 90, 91
Dat a
copyin g, 67
past in g, 67
DATA comman d, 87
Dat a win dow, 60, 87
assign in g expression s, 90
closin g, 87
cyclin g t h rough , 87
fields, 89
format , 87
open in g, 87
BETA REVI EW
resizin g, 87
scrollin g, 88
viewin g addresses, 87
DBG files, 181
Debug in format ion
buildin g, 16
Debuggin g
applicat ion s, 32
device drivers, 32
feat ures, 7
gen erat in g in format ion , 34
preparin g t o, 141
resources, 179
Delet in g
symbol t ables, 42
wat ch , 84
Delph i compiler, 34
DEVICE comman d, 180
Device drivers
debuggin g, 32
DEX comman d, 90, 91
DIAL comman d, 158
DIAL in it ializat ion st rin g, 171
Dial-up Modem, 145
dial-up modem, 146
Direct Null Modem con n ect ion , 145
Disable mappin g of n on -presen t pages, 177
Disable mouse support , 176
Disable Num Lock an d Caps Lock program-
min g, 176
Disable Pen t ium support , 177
Disable t h read-specific st eppin g, 177
Disablin g
breakpoin t s, 29
Soft ICE, 59
Disassembled in st ruct ion
Code win dow, 78
Display adapt ers
support ed, 221
Display comman d, 68
Display diagn ost ic messages, 164
Displayin g regist ers, 94
DLL export s, 141
Do n ot pat ch keyboard driver, 177
DRIVER comman d, 180
DriverSt udio Remot e Dat a (DSR) n amespace
ext en sion , 147
DSR Namespace Ext en sion , 147
Duplicat e breakpoin t s, 120
E
E comman d, 91
Eaddr fun ct ion , 131
EBP regist er, 119
Edit in g
comman ds, 72
flags, 86
memory, 90
regist ers, 86
Effect ive address, 85
Embedded breakpoin t s, 122
En ablin g serial debuggin g, h ost , 157
En ablin g serial debuggin g, t arget , 156
En t erin g comman ds, 68, 70
syn t ax, 70
En t ry poin t s, 142
un n amed, 142
Error messages, 217, 227
ESP regist er, 119
est ablish a serial con n ect ion , 156
Est ablish in g a con n ect ion , specialized n et work
drivers, 151
Est ablish in g a Modem Con n ect ion , 158
Evalue fun ct ion , 132
Execut ion breakpoin t s, 104, 105
Expan din g
arrays, 20
st acks, 82
st rin gs, 20
st ruct ures, 20
t yped expression s, 84
Export In format ion , 167
Export n ames
expression s, 142
Export s, 161
DLL, 141
Expression evaluat or, 123
built -in fun ct ion s, 129
I n d ex 2 3 5
BETA REVI EW
ch aract er con st an t s, 127
expression values, 132
formin g expression s, 126
in direct ion operat ors, 135
n umbers, 127
operan ds, 135
operat ors, 124
regist ers, 128
symbols, 128
Expression t ypes, 132
Expression values
address-t ype, 132
lit eral-t ype, 132
regist er-t ype, 132
symbol-t ype, 132
Expression s, 123
assign in g, 90
breakpoin t s, 121
export n ames, 142
formin g, 126
wat ch in g, 83
F
Fault t rappin g, 95
Fault s
t rappin g, 95
Fields
Dat a win dow, 89
FILE comman d, 18, 80
Flags, 85
edit in g, 86
FORMAT comman d, 87, 90
Format t in g
Dat a win dow, 87
Formin g expression s, 126
FPU St ack win dow, 60, 93
closin g, 93
displayin g regist ers, 94
movin g t h e cursor t o, 63
open in g, 93
Fun ct ion keys, 71, 171
modifyin g, 171
Fun ct ion s
built -in , 129
expression evaluat or, 129
G
G comman d, 21, 28, 85, 87
GDI object s, 197
GDIDEMO applicat ion , 14
GDT comman d, 186
Gen eral set t in gs, 161
modifyin g, 163
Global Descript or Table, 184, 186
H
H comman d, 23, 69
Han dle values, 199
Hardware Requiremen t s, Specialized Net work
Drivers, 150
Headless Mode, 146
Heap
API, 204
arch it ect ure, 204
blocks, 209
HEAP32 comman d, 196, 207
Help
for Soft ICE, xiv, 68
for Symbol Loader, xiv
Help lin e, 18, 60, 68
HERE comman d, 21, 80, 106
Hist ory buffer, 75
Hist ory buffer size, 163
h ost comput er, 146
HWND comman d, 26, 110
I
I/ O breakpoin t s, 104, 108
IDT comman d, 107, 184
In direct ion operat ors, 124, 135
In format ion
BETA REVI EW
Help lin e, 68
In format ion al comman ds, 23
In it ializat ion file, 161
In it ializat ion set t in gs
Remot e Debuggin g, 161
In it ializat ion st rin g, 163
In it ializat ion st rin gs
modem, 170
in st allat ion , specialized n et work drivers, 150
in st allin g a serial con n ect ion , 155
INT 1 in st ruct ion
breakpoin t s, 122
INT 3 in st ruct ion
breakpoin t s, 122
In t el arch it ect ure, 184
In t ern et paramet ers
Remot e Debuggin g, 161
In t errupt
breakpoin t s, 104, 107
Descript or Table, 184
J
JUMP st rin g, 79
K
Kern el
Win dows NT, 183
Keyboard Mappin gs, 162
modifyin g, 171
L
LDT comman d, 187
LINES comman d, 61
LOADER32, 44, 45
LOADER32.EXE, 43
Loadin g
modules, 35
Soft ICE, 14, 33
source, 35
symbols, 24
Loadin g Export s Dyn amically, 143
Local Descript or Table, 184, 187
local n et work (LAN) debuggin g, 146
LOCALS comman d, 82
Locals win dow, 60, 81
closin g, 81
open in g, 81
resizin g, 81
scrollin g, 81
Logical operat ors, 125
Lowercase disassembly, 165
M
MACRO comman d, 74, 202
Macro Defin it ion s, 162
Macro limit , 175
Macros
defin it ion s, 173
recusion , 74, 174
Run -t ime, 73
Man ipulat in g breakpoin t s, 121
MAP32 comman d, 188, 203
MASM compiler, 35
Mat h operat ors, 124
MAXIMIZE, 58
Memory
breakpoin t s, 28, 104, 106
edit in g, 90
map of syst em memory, 188
Messages
error, 217, 227
Microsoft Visual C++ compiler, 35
Mixed mode, 78
MMX regist ers, 93
MOD comman d, 180, 203
Modem, 157
con n ect ion , 145, 157
h ardware requiremen t s, 157
in it ializat ion st rin gs, 170
I n d ex 2 3 7
BETA REVI EW
modem, 157
Modem Hardware Requiremen t s, 157
Modes
Code, 77
Code win dow, 77
Mixed, 77
Source, 77
Modifyin g
fun ction keys, 171
Gen eral set t in gs, 163
Soft ICE In it ializat ion set t in gs, 161, 162
Modules
loadin g, 35
t ran slat in g, 35
Mouse comman ds
Display, 68
Previous, 68
Un -Assemble, 68
Wh at , 68
Movin g t h e cursor, 63
Movin g t h e Soft ICE Win dow, 61
N
Navigat in g
Soft ICE, 57, 95
Nest in g limit, 74
NET ALLOW, 159
NET comman d, 159
NET COMx, 159
NET DISCONNECT, 159
NET HELP, 169
NET HELP comman d, 159
NET PING, 159
NET RESET, 159, 169
NET SETUP, 159
NET START, 159
NET STATUS, 169
NET STOP, 159, 169
n et work, 146
Net work In t erface Card (NIC) in t erface, 145
NMAKE comman d, 16
NMS file, 36
NMSYM.EXE, 45
NO JUMP st rin g, 79
Non Paged Syst em area, 193
NTCALL comman d, 185
NTOSKRNL.EXE, 183
n ull modem cable, 155
O
OBJDIR comman d, 180
OBJTAB comman d, 188, 200
On e-sh ot breakpoin t s, 21
Open in g
Code win dow, 76
Dat a win dow, 87
FPU St ack win dow, 93
Locals win dow, 81
Regist er win dow, 85
Wat ch win dow, 83
Operan d sizes, 135
Operat ors
bit wise, 124
expression evaluat or, 124
in direct ion , 124, 135
logical, 125
mat h , 124
preceden ce, 125
special, 125
P
P comman d, 20, 22, 85, 87, 177
Packagin g source files, 40
PAGE comman d, 189
Page Table En t ry, 192
Paged Pool Syst em area, 192
Passin g comman d lin e argumen t s, 38
Past in g dat a, 67
Persist en t Macros, 173
PHYS comman d, 189
Preceden ce operat ors, 125
BETA REVI EW
Pre-loadin g
source, 165
symbols, 165
Preparin g t o debug, 141
Previous comman d, 68
Process address space, 202
Processor Con t rol Region , 193
Prot oPTEs, 192
PTE, 192
Q
QUERY comman d, 196, 203
R
Recallin g
comman d h ist ory, 73
refresh t h e display man ually, 149
Regist er win dow, 60, 85
closin g, 85
CPU flags, 85
open in g, 85
Regist ers, 85
edit in g, 86
Remot e Debuggin g, 161, 170
Remot e Debuggin g Det ails, 150
Remot e Debuggin g, NET comman ds, 168
Remot e Debuggin g, st art session , 170
remot e locat ion , 146
removin g a serial con n ect ion , 156
Removin g t h e modem con n ect ion , 158
Requiremen t s, Remot e Debuggin g, 167
Reservin g
symbol memory, 166
Resizin g
Code win dow, 76
Dat a win dow, 87
Locals win dow, 81
Soft ICE screen , 61
Wat ch win dow, 83
Run -t ime macros, 73
S
S comman d, 91
Scrollin g
Code win dow, 76
Comman d win dow, 70
Dat a win dow, 88
Locals win dow, 81
Wat ch win dow, 83
win dows, 63
Serial
con n ect ion , 171
Serial Con n ect ion , 155
Serial con n ect ion , 155
Serial Con n ect ion h ardware requiremen t s, 155
serial debuggin g, 146
serial port , 155
SERIAL.EXE, 158
SET comman d, 70, 76, 80
Set t in g
breakpoin t act ion s, 112
breakpoin t s, 21, 22
con dit ion al breakpoin t s, 25, 112
execut ion breakpoin t s, 105
I/ O breakpoin t s, 108
in t errupt breakpoin t s, 107
memory breakpoin t s, 28, 106
source file search pat h , 38
win dow message breakpoin t s, 109
Set t in g Video Memory size, 59
SIREMOTE, 157
SIREMOTE n et work con n ect ion s, 158
SIREMOTE Serial Con n ect ion , 158
SIREMOTE support applicat ion , 158
SIREMOTE, con n ect in g t o a remot e t arget , 158
SIVNIC In st allat ion , 153
Soft ICE
cust omizin g, 161
disablin g, 59
feat ures, 7
I n d ex 2 3 9
BETA REVI EW
in format ion al comman ds, 23
in it ializat ion file, 161
loadin g, 14, 33
modem con n ect ion , 145, 157
n avigat in g t h rough , 57, 95
overview, 7
product overview, 7
user in t erface, 9, 60
Soft ICE In it ializat ion set t in gs
Export s, 161
Gen eral, 161
Macro Defin it ion s, 162
modifyin g, 161, 162
Symbols, 161
Troublesh oot in g, 162
Soft ICE screen , 60, 146
resizin g, 61
Soft ICE win dows
closin g, 62
Code, 60, 76
Comman d, 60, 69
con t rollin g, 61
Dat a, 60, 87
FPU St ack, 60, 93
Locals, 60
open in g, 62
Regist er, 60, 85
resizin g, 62
Wat ch , 60, 82
Sort in g symbol t ables, 42
Source
loadin g, 35
mode, 77
packagin g, 40
pre-loadin g, 165
specifying, 42
t ran slat in g, 35
Special operat ors, 125
Specialized Net work Driver, 150
Specialized n et work drivers, 148
specialized n et work drivers, 150
Specifyin g Source Files, 42
SRC
comman d, 20, 78, 80
file, 42
SS comman d, 80
St ack frame, 20, 119
St acks
collapsin g, 82
expan din g, 82
St icky breakpoin t s, 22, 103
St rin gs
Code win dow, 79
collapsin g, 20
expan din g, 20
St ruct ures
collapsin g, 20
expan din g, 20
SYM comman d, 25, 192
Syman t ec C++ compiler, 35
Symbol buffer size, 166
Symbol Loader, 11, 17, 35, 162
comman d lin e in t erface, 43
comman d-lin e ut ilit y, 45
Symbol t ables
delet in g, 42
sort in g, 42
Symbols, 128, 161
pre-loadin g, 165
reservin g memory, 166
t ables, 24
t ype, 133
Syst em
Code area, 188
memory map, 188
Tables Syst em area, 188
View Syst em area, 188
Syst em Page Table En t ries, 192
T
T comman d, 85, 87
TABLE comman d, 24
Tables, 24
TABS comman d, 80
Tail recursion , 74
t arget comput er, 146
t arget mach in e, 146
BETA REVI EW
Task St at e Segmen t , 184, 186
t ech n ical support , 225
Teleph on e n umber, 170
THREAD comman d, 203
Time st amp coun t er, 120
Tot al RAM, 164
Trace buffer size, 164
Tran slat in g
modules, 35
source, 35
Trap NMI, 164
Triggerin g
breakpoin t s, 111
Troublesh oot in g, 162
error messages, 217, 227
Soft ICE, 225
Troublesh oot in g Opt ion s, 176
TSS comman d, 186
t ype of remot e con n ect ion , 146
Typed expression s
collapsin g, 84
expan din g, 84
TYPES comman d, 82
t ypes of debuggin g icon s, 148
t ypical debuggin g en viron men t , 148
U
U comman d, 19, 21, 80
Un -Assemble comman d, 68
UND, 151
UND (Un iversal Net work Driver), 148
UND Hardware Requiremen t s, 152
UND In st allat ion , 152
UND Removal, 154
UND, Est ablish in g a Net work Con n ect ion , 154
un in st allin g specialized n et work drivers, 151
Un iversal Net work Driver, 151
Un iversal Video Driver, 58
USER
object creat ion , 202
Object Table, 200
object s, 197
User-defin ed
comman ds, 173
set t in gs, 161
V
Viewin g
addresses, 87
Virt ual breakpoin t s, 111
W
Wat ch
delet in g, 84
WATCH comman d, 83
Wat ch win dow, 60, 82
closin g, 83
fields, 84
open in g, 83
resizin g, 83
scrollin g, 83
Wat ch in g
expression s, 83
Wat com C++ compiler, 35
WC comman d, 76
WD comman d, 87
WF comman d, 93
WHAT comman d, 201
Wh at comman d, 68
Win 32 subsyst em, 195
Win dow message breakpoin t s, 104, 109
Win dows
Code, 17, 60, 76
Comman d, 60
compon en t s, 195
Dat a, 60, 87
FPU St ack, 60, 93
Locals, 60, 81
movin g t h e cursor amon g, 63
Regist er, 60, 85
scrollin g, 63
I n d ex 2 4 1
BETA REVI EW
Wat ch , 60, 82
Win dows NT
DDK, 180
explorin g, 179
kern el, 183
referen ces, 182
syst em memory map, 188
WL comman d, 81
WR comman d, 85
WS comman d, 91
WW comman d, 83
WX comman d, 92
X, Y, Z
X comman d, 28
BETA REVI EW

Using SoftICE

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Using SoftICE

Uploaded by

Copyright:

Available Formats

Using Soft I CE

Reader copyrigh t 1987-2003 Adobe Syst ems In corporat ed. All

is an advan ced, all-purpose debugger t h at can debug virt ually

even t s from wit h in t h e

You might also like