Special Command—Advanced Programming Techniques for WinDbg Scripts

Special Command—Advanced Programming Techniques for WinDbg Scripts
rafarah Microsoft

link:http://blogs.msdn.com/b/debuggingtoolbox/archive/2009/01/31/special-command-advanced-programming-techniques-for-windbg-scripts.aspx

 

11,545 Points 3 3 2 Recent Achievements New Blog Rater Blog Commentator II Blog Party Starter View Profile
31 Jan 2009 12:32 AM Comments 5
It has been a long time since my last post, but I’m back on the blog.
The article for today is about the black art of WinDbg scripting. When I first started creating my scripts, I learned by trial and error. It was tough; however, it gave me the basis to create the technique that has proven to be useful when creating scripts.
If you’ve been following my blog, you should know the PowerDbg tool. PowerDbg is another approach to create scripts for WinDbg; however, it’s more useful when creating large and complex scripts. By the way, the next version is going to use a COM object; thus it’s going to be easier to use, more powerful, and faster.
The purpose of this article is to explain the most used commands and the techniques I use to create scripts.
 

1-   Declaring Variables
 

Variables are created as aliases not as real variables. I’m going to use the term “variable”, but in fact we’re talking about aliases.
Aliases are very flexible. You can, for instance, create an alias that has a block of commands.
Here is the way to create and delete variables:
 

as [alias type] <alias Name> <value>
 

Where [alias type] can be:
 

/ma             Sets the alias equivalent equal to the null-terminated ASCII string that begins at Address.
/mu             Sets the alias equivalent equal to the null-terminated Unicode string that begins at Address.
/msa              Sets the alias equivalent equal to the ANSI_STRING structure that is located at Address.
/msu              Sets the alias equivalent equal to the UNICODE_STRING that is structure located at Address.
Address         Specifies the location of the virtual memory that is used to determine the alias equivalent.
/x                    Sets the alias equivalent equal to the 64-bit value of Expression.
Expression     Specifies the expression to evaluate. This value becomes the alias equivalent.
/f                    Sets the alias equivalent equal to the contents of the File file. You should always use the /f switch together with aS, not with as.
File              Specifies the file whose contents become the alias equivalent. File can contain spaces, but you should never enclose File in quotation marks. If you specify an invalid file, you receive an "Out of memory" error message.
/c                    Sets the alias equivalent equal to the output of the commands that CommandString specify. The alias equivalent includes carriage returns if they are present within the command display and a carriage return at the end of the display of each command (even if you specify only one command).
Example:
 

as ${/v:ScriptName} myscripts\\test_script.txt
 

The example above creates an alias ScriptName that represents the path described above.
Notice that I’m using ${/v:}
Why is that?
If you don’t use ${/v:}, you’ll have problems to delete the alias. You can see in some of my old scripts I used this approach, so if you call the script two times in a row an error occurs because the alias couldn’t be deleted!
 

${} is an alias interpreter.
 

The options are:
 

/d                Evaluates to one or zero depending on whether the alias is currently defined. If the alias is defined, ${/v:Alias} is replaced by 1; if the alias is not defined, ${/v:Alias} is replaced by 0.
 

/f                    Evaluates to the alias equivalent if the alias is currently defined. If the alias is defined, ${/f:Alias} is replaced by the alias equivalent; if the alias is not defined, ${/f:Alias} is replaced by an empty string.
 

/n                    Evaluates to the alias name if the alias is currently defined. If the alias is defined, ${/n:Alias} is replaced by the alias name; if the alias is not defined, ${/n:Alias} is not replaced but retains its literal value of ${/n:Alias}.
 

/v                    Prevents any alias evaluation. Regardless of whether Alias is defined, ${/v:Alias} always retains its literal value of ${/v:Alias}.
 

To simplify follow this template when creating “variables”:
 

as [alias type] ${/v:<alias name>} <alias value>
 

 

 

 

2-   Freeing Variables (aliases)
 

The way to delete “variables” is:
 

ad ${/v:<variable name>}
 

Example:
 

as ${/v:ScriptName} myscripts\\test_script.txt    (creating alias)
 

ad ${/v:ScriptName}  (deleting)
 

So, this is the template:
 

ad ${/v:<variable name>}
 

 

 

3-   Executing Scripts
 

The most common way to call a script is:
 

$$><path\scriptName
 

Example:
 

$$><myscripts\GET_PERFMON.txt
 

If your script accepts arguments you must provide them using:
 

$$>a<path\scriptName argument1 argument2 argument3…
 

Example:
 

$$>a<myscripts\GET_HEADERS.txt kernel32
 

You can use recursive calls and make a script call itself. No secrets here, it’s the exact same command.
 

 

4-   Identifying Arguments
 

If your script accepts arguments, you should verify if the user provided the arguments.
To do that you can test whether the argument was or wasn’t provided, like:
 

.if(${/d:$arg1})
{
    $$ Do something...
}
 

From above you can see the ${/d:} that evaluates the expression to one or zero.
arg1 refers to the first argument, arg2 to the second, and so on.
 

 

 

5-   32/64 bits Compatibility
 

When writing WinDbg scripts, you’ve got to think about 32 and 64 bits compatibility. Most of the time you don’t need to write two scripts to keep compatibility.
The technique is based on this pseudo-register:
 

$ptrsize
 The size of a pointer.
 

 

Example (snippet from a real script):
 

r @$t1 = poi(@$t0) + @$ptrsize;
 

.printf "\n.NET GC Counters\n\n";
.printf "GenCollection 0           = 0n%d\n", poi(@$t1);
.printf "GenCollection 1           = 0n%d\n", poi(@$t1+@$ptrsize);
.printf "GenCollection 2           = 0n%d\n", poi(@$t1+@$ptrsize*2);
.printf "PromotedMemory            = 0n%d\n", poi(@$t1+@$ptrsize*3);
.printf "PromotedMemory 1          = 0n%d\n", poi(@$t1+@$ptrsize*4);
 

Or yet:
 

!do poi(${obj}+(4*@$ptrsize))
 

 

6-   DML – Debug Markup Language
 

If you’ve been following my blog, you know I’m a big DML fan. With DML you can create hyperlinks that execute commands instead of presenting lots of information to the user.
 

To use DML you’ve got to use a variation of the .printf command:
 

.printf /D
 

Note: If you want to learn more about DML, open the DML.DOC that comes with the Debugger.
 

Common usage:
.printf /D "<link cmd=\"dps @$csp poi(@$teb+0x4);ad ${/v:ScriptName}; $$><${ScriptName}\"><b>Symbols</b></link>\n\n"
 

From above:
 

<link cmd=\”Your Command Here \”>
 

I’m using \” instead of “because I’m using them within a pair of “.
 

<b>Your string</b></link>
 

The <b> is to use Bold.
 

Tip: Between <link cmd=\”    \”</link> you could use an alias defined before the DML line. This alias could be a block of code, like:
 

.block
{
    $$ Creating an alias for a block of code!
    as ${/v:OracleCommand} .block
    {
        !DumpObj poi(@$t0+0x14)
        !DumpObj @$t0
        !GCRoot @$t0
    }
}
 

.foreach(obj {!dumpheap -short -type System.Data.OracleClient.OracleCommand } )
{
    .printf /D "<link cmd=\"r @$t0 = ${obj}; ${OracleCommand} ;\"><b>%mu</b></link>\n\n", poi(${obj}+0x14)+0xc
}
 

.printf is very similar to the printf() function from C programming language.
 

 

7-   Pseudo-Registers as Variables
 

Most of the time, you’ll want to use some kind of counter in your script, or save the address of an object, a structure field, etc. To do that you can use pseudo-registers.
 

I talked about it before, so you can read the full article here.
 

 

8-   Legibility May Hurt Your Script
 

I know it’s weird, but it’s the truth.
If you have a command line like:
 

!do poi(@$t0+(4*@$ptrsize))
 

And you decide to improve the legibility adding a few spaces you may end up having an error.
In other words, this line won’t run:
 

!do poi(@$t0 + (4 * @$ptrsize))
 

It’ll fail with this error:
 

Incorrect argument: + (4 * @$ptrsize))
 

The next article has a script as an example of some of the techniques presented above.
 

The possibilities are limited only by your creativity. If you have a cool script and want to show it to the world feel free to post it in this blog.