扩展SoftICE－－3

Chapter 4: Extending Soft-Ice
-----------------------------

In this chapter you will find some guidelines for writing helper VxD\'s for extending
Soft-Ice, or other system debuggers (Soft-Ice is the best tool , so don\'t bother with
other debuggers , does not worth the effort).You can develop those VxD\'s in assembly language
or in C/C++.If you choose to write them in C I recommend you buying Vtools from Vireo Software,
this is a great tool.It is not very hard to write them totally in assembly , so this is also
a good choice.
In the first place we will need a unique device id.This is not mandatory but in
the sample VxD who accompanies this article I\'ve used this device ID to prevent loading the
VxD if it\'s already loaded (duplicate init strings in system.ini or registry).
The  loading order is not very important as long as you not relay on third-party
VxD\'s to carry out part of your routines.The only VxD\'s  required  to be loaded before our
device are the VMM and the Debug Device.No special precautions required since vmm.vxd and debug
device have Init_Order equal to 0. This number means that the VMM will start loading VxD\'s
starting with lower values first and finishing with UNDEFINED_INIT_ORDER values last.So simply
specifying UNDEFINED_INIT_ORDER will be OK.
The next thing very important is the Virtual Device\'s control procedure.You should
always put this procedure in a locked code segment.This routine is a callback who responds
at messages broadcasted by Vmm and directs our VxD to take appropriate measures (generally this
routine merely pass control to user code procedures responsible with managing those messages.
Remember that returning with Carry Flag set from your handlers means that an error occurred ,
 and a cleared Carry Flag means that everything went OK.A debug helper VxD should manage at
least two messages.They are Device_Init and Debug_Query.If your plan to write your VxD as a
Dynamic loadable device driver the control procedure is REQUIRED to manage more two messages.
Those are Sys_Dynamic_Device_Init and Sys_Dynamic_Device_Exit.Talking from ring3 user code
to your device is also possible (see Chapter7 for details).In this case I recommend you to use
the DEVICE_IO control mechanism.For this to be possible you must also process W32_DeviceIocontrol
message and write an appropriate handler to dispatch control to your procedures.Please note
that even if your VxD does not handle any messages , a control procedure is still required.
We already said that the Control Procedure must be in a looked code segment.Also
the procedures that handles Debug_Query events and .dot commands are required to be in looked
code segments.This is due to the way in which system debuggers pass control to those handlers.
Also when you build the VxD the debug level passed to MASM must be at least one.This is because
if you do a retail build on a VxD a lots of Debug Macros defined in Vmm.inc becomes unavailable.
Your code will compile and link without any problem , but you will notice that your Trace_Out
messages and other debug macros there stripped out.
If your device provide a handler for Debug_Query message , issuing a type one dot
command ( a dot followed by your VxD name ) will be automatic processed.You can strip this out
if you want , processing Debug_Query is not required.
To use type two dot commands you are required to inform the debugger about their
existence.The best place where you can do this is inside the handler for Device_Init message.
This handler can be safely put in a discardable code segment , so after completely initializing
the device and registering dots this code will be discarded (You never have enough RAM , so
even if you think that several Kb  are not much ...).You always must try to keep pagelocked
code and data at the very minimum.
Before you try to register a dot command you should always check if a system debugger
is present.Issueing INT 41h without a system debugger installed cause protection faults.
If such a protection fault occurs inside a Device_Init message handler of a statically loaded
device , not only the device will not complete initialization but also Windows95 itself will
fail initialization.The simplest way to check for a debugger is to use  Test_Debug_Installed
provided by vmm (VxdCall Test_Debug_Installed).This will return with zero flag clear if
a debugger is present.If ZF if set the a system level debugger is not present.
If the debugger is not present then you should not load your device.You simply
do this by returning with CF set from the Device_Init message , informing the virtual machine
manager that the initialization procedure failed . The VMM will not load the device.
Once you are sure that a debugger is present you can proceed with registering dot
commands . This is accomplished by INT 41h with Ax set to 70h.The other registers must be set
as following:
BL = dot command to register.Example mov bl , \'z\'.Used to inform the debugger
that it should respond at a .Z command transferring control as below.
ESI must contain the linear address of the dot command handler routine.
EDI must contain the linear address of the help string.The help string must
    end with a CR
The following special restriction apply to the handler:
1.The handler must stay on the same stack used when called Int41h
2.The handler must not change provided flat CS , DS , and try to access invalid
selectors or  memory.
3.The handler is runned on ring0.

After you register the dot command you will can access it from within your debugger.
When you don\'t wont the command anymore you should de-register it.
If your VxD is statically loaded there is no point in de-registering dot command , since the
code will be there until Windows shuts down. But if your VxD is designed to be a dynamically
loaded VxD care must be take.If you unload the VxD and a de-register of the dot command is
not performed , the dot command will be considerated as available by debugger , and you can
call it.The only problem is that since the VxD who provide the handler is no longer in memory,
control will be passed to garbage instructions,...I think you get my point.So is a very good
idea to de-register dot commands in a dynamic VxD. De-registering is performed calling INT 41h
whit AX set to 72h and BL containing the command you want to de-register.Your best choice is
to this thing inside the handler for Sys_Dynamic_Device_Exit.
Also , while processing a dot or a Debug_Query message , it is not a good idea to
try to leave Soft-Ice by pressing the assigned hot-key.This will hang your machine imediatly.
Now several things about the dot command handler routine.When the debugger calls the
handler it will set DS and CS to a flat selector. Usually the flat CS will be 28h.It also
load the first character of the command line in the AL register.The handler routine must
perform a far return (you must return to the debugger which resides in another code segment).
Note that this is not sensed by assembler so it\'s your duty to explicitly use RETF.The value
returned in AX register can be 0 , indicating that all went OK , any other value means that
an error occurred (usualy a command line error).The first thing you should do after entering
your handler is to parse the command line. This can be accomplished by using INT 41h , AX=77h
(Get command line character) . A pointer to the current character in command line is
maintained by the debugger.The value specified in BL register choose how this pointer
is managed.Also the flag specified in BL sets the way in which one or more blank spaces are
treated.They can be ignored , the pointer value will be updated to the next valid character
in the command line or you can choose to parse them as well.The GetCommandLine function will
return with AH set to 0 if end of line was encountered , and a value !0 otherwise.The
command line character is retrieved in AL.
Not much things left to say.It\'s up to you in which way you will used the facilities
presented here.Your code runs on ring 0 , so you can do just about anything you imagine.The
only thing I want to say is that you should take care about what you are doing.Programming
in ring0 requires a very serious understanding of protection mechanism , page-mode memory
management , x86 internal architecture and the way in which Windows\'95 virtual memory manager
manages those facilities.Remember , you have absolute power but using it in a wrong way can
cause your machine to hang , and you can cause loose of data from your hard drives.Fair warning!