Symbols in ASM?               ASM Source debugging?                Has it sense?
--------------------------------------------------------------------------------

Debugging with NuMega SoftICE
=============================
For working with symbols use Symbol Loader or NMSym.
--------------------------------------------------------------------------------

Exports
=======
You already saw something like kernel32!GetVersion - PE exports are symbols.
It is a difference between 
JMP DWORD PTR [000404000] and JMP DWORD PTR [user32!wsprintfA]
isn't it?
For loading exports of PE file (exe,dll,drv,sys,..) use
Symbol Loader | Load Exports...

--------------------------------------------------------------------------------

Source Symbols
==============

1) COFF type debug info
-----------------------

         ML   /c /coff /Zi MyProg.asm
         LINK MyProg.obj /SUBSYSTEM:WINDOWS /DEBUG /DEBUGTYPE:COFF /BASE:MyBase

Option /BASE is optional, default base is 0x400000.
Note that there's no significant difference between assembling with/without
/Zi option in this debug info type.

It will create file MyProg.exe with Debug directory entry and appended symbol
information. After loading to SoftICE You can see that all symbols are present;
try 'sym'. Source is missing!

!-----------------
  OFFSET Names are not displayed (for both COFF and CV infos) in WinICE, e.g.: 
      PUSH   Variable                 ; sym: PUSH Variable
  but PUSH   OFFSET  Variable         ; sym: PUSH 00401024
      INVOKE Label1, Variable         ; sym: PUSH Variable | CALL Label1 
  but INVOKE Label1, ADDR Variable    ; sym: PUSH 00401024 | CALL Label1 

  NTice displays all fine.
!-----------------

'src' command has no effect in this debug info type.

Stripping COFF type debug info 
------------------------------
You'll need REBASE.exe utility (C compilers have it) - it is standard SDK tool.
         REBASE -b MyBase -x DBGDir MyProg.exe
COFF debug info will be stripped to file DBGDir\exe\MyProg.dbg
There is still appended information (size 0x100) to MyProg.exe - there is
partial path and name of .dbg file (e.g.: dll\bla.dbg sys\alb.sys,..),
nothing more. 
Every Windows NT PE file (from Microsoft) has this appendix - it looks sooo
professionally in my eyes.

If PE was dll,sys,.. .dbg file will be in DBGDir\dll,DBGDir\sys,..
Note that DBGDir mayn't exist - it will be created.
If DBGDir begins with . then exe subdir will not be created and .dbg file will
be in current directory.


Using stripped COFF type debug info
-----------------------------------
All can be done by mouse from NuMega SoftICE Loader; NMSYM is not needed.
Open Module... DBGDir\MyProg.dbg
 - yes Loader can open and load various Modules, not only PEs
Load 
 - .dbg is translated to .NMS (NuMega Symbol file? ;) automatically
 - Symbol Table is created and added to list (see Edit | Symbol Tables...)
 - Symbol Table can be removed only from Edit | Symbol Tables...


2) CodeView type debug info
---------------------------
   is designed for files written in high level languages.

         ML   /c /coff /Zi MyProg.asm 
         LINK MyProg.obj /SUBSYSTEM:WINDOWS /DEBUG

/Zi option should be present.

It will not optimize the resulting .EXE code - there are some additional 
objects, jumps, etc..  because alone /DEBUG or /DEBUG /DEBUGTYPE:CV
turns on /OPT:NOREF
Files MyProg.ilk, MyProg.pdb are created (besides .exe). 
.ilk is MS Linker Database, .pdb is MS C/C++ Program Database.

         ML   /c /coff /Zi MyProg.asm 
         LINK MyProg.obj /SUBSYSTEM:WINDOWS /DEBUG  /RELEASE
         or
         LINK MyProg.obj /SUBSYSTEM:WINDOWS /DEBUG  /OPT:REF

will not create .ilk file, resulting .EXE is not deformed and contains
small appendix with reference to .pdb file.

So pdb is stripped automatically, when You want it to be included in exe
then You must specify /PDB:NONE

'src' works normally. Note that CV debug info in code mode == COFF debug info
Source is present.


Stripping CV appendix 
---------------------
CV appendix is very small, it contains only reference to .pdb file.
This small appendix can be stripped by REBASE to .dbg file too and all works
fine.
         ML     /c /coff /Zi MyProg.asm 
         LINK   MyProg.obj /SUBSYSTEM:WINDOWS /DEBUG /RELEASE  ;pdb created
         REBASE -b MyBase -x DBGDir MyProg.exe                 ;dbg created

Now You have small .dbg file referring to .pdb file, You can debug in all modes.
In case of LINK version => 6 is .exe (has size) like compiled without
/Zi and linked without /DEBUG; has no appendix, but has Debug directory entry
of size 0 and flag Debug stripped ON.
In case of LINK version < 6 is moreover pdb appendix replaced by dbg appendix
  - the same output You'll get when You'll specify /DEBUGTYPE:BOTH and then 
    stripping
--------------------------------------------------------------------------------
TASM32/TLINK32 with debug info options create PE with .debug object, but
it's not compatible to SoftICE nor TD32 - so You have the next reason why
You should use MASM instead of TASM in Win32 programming.
--------------------------------------------------------------------------------
REBASE just uses some functions from IMAGEHLP.dll, see help for this DLL.

P.S. : I included REBASE.exe for NT 3.51, because that for 4.0 doesn't work 
       correctly.
--------------------------------------------------------------------------------
Microsoft on Windows NT CD includes in \SUPPORT\DEBUG\I386\SYMBOLS .dbg files
for every OS PE component. You can try for example winmine (because it remains
unchanged in all SPs):
Expand winmine.db_ winmine.dbg
Open and Load winmine.dbg
Open and Load winmine.exe 
Debug

Not needed to say that .dbg for ntoskrnl,hal,kernel32,... increase 10x exploring
speed. But You must download .dbg for Your actual SP.

There are some interesting secret (=not exported) APIs. For example (ntoskrnl):
MiAddValidPageToWorkingSet, which is used for NTice's command 'pagein'
and many other APIs with exciting names like:
GetMachineBootPointers, KdpPageInData, ...
--------------------------------------------------------------------------------
EliCZ, chemical student, Jul-18-1999
WWW: http://elicz.cjb.net
IRC: EFnet: #win32asm
--------------------------------------------------------------------------------