gdb-xsource - A gdb command for enhanced debugging scripting.

[ZC Miao <hellwolf dot misty at gmail dot com>]

gdb-xsource - A gdb command for enhanced debugging scripting.

* Motivation
When debugging some complicated applications such as linux kernel, using
gdb to
examining data is quite useful. And most of the time, the data
structures of
these applications is also complicated, so the scripting facility from
gdb
called "Sequences" is provided to make life easier. But unfortunately,
that
functionality is unexpectedly limited, for example, it's even not easy
to
compare a string variable with a user-provided string.
This package is intended to work around the lame functionality from gdb.
It
provides a new command "xsource" to gdb, you can enrich this command
with
whatever executable files as long as they return valid gdb sequences.


* Sample use
Here provides some sample use to show you more what is gdb-xsource :

** Mimic of list_entry
In linux kernel there's a well-known trick called list_entry to get list
entry
from it's member and type, here is the mock using gdb-xsource:
File list_entry:
[code]
#!/bin/sh

[ $# -lt 4 ] && echo "printf \"Usage : list_entry ret ptr member
type...\n\"" && exit 1

RET=$1
PTR=$2
MEMBER=$3
shift 3
TYPE="$@"

cat <<EOF
set \$$RET = ($TYPE*)((unsigned char*)($PTR)-(unsigned
int)&((($TYPE*)0)->$MEMBER))
EOF
[/code]
This is a shell script which is provided by gdb-xsource package. It
store the
list entry to parameter 'ret' of which parameter 'ptr' is its 'member'
(parameter), and the type of 'ret' is 'type'(parameter).
In order to see how to use this, let's see the following example:

**  Implement ps command when debugging linux
By using gdb-xsource, you can directly show a simple ps command when
debugging
with linux kernel.
File ps:
[code]
#!/bin/sh

cat <<\EOF
set $_ps_p = &init_task
set $_ps_end = 0
while $_ps_end != 1
    printf "%d\t\t%d\t\t\t%s\n", $_ps_p->pid, $_ps_p->parent->pid,
$_ps_p->comm
    xsource list_entry _ps_p $_ps_p->tasks.next tasks struct task_struct
    if $_ps_p == &init_task
        set $_ps_end = 1
    end
end
EOF
[/code]
This is also a shell script. It uses list_entry command introduced
above.
Now in gdb, you simply type "xsource ps", then you will get what you can
expect
from ps command on a running linux system.

* Get & Install & Use it
** Get from git repository
You can clone it by using the following command in your shell:
[code]
$ git-clone http://linuxfire.com.cn/~hellwolf/git/gdb-xsource.git
[/code]
A sweet gitweb interface is also available:
http://linuxfire.com.cn/~hellwolf/cgi-bin/gitweb.cgi?p=gdb-xsource.git

** Install it
After you clone the repository, you need these further steps to use
xsource in
your gdb session:
- Set environment parameters
[code]
export GDB_XSOURCE_ROOT=/path/to/your/gdb-xsource
export GDB_XSOURCE_DIRS=:/path1:/path2
[/code]
GDB_XSOURCE_ROOT is the root directory of the package.
GDB_XSOURCE_DIRS is the available directories to find xsource commands.
It's
colon separated.
Set these in your ~/.bash_profile or other places.
- Set gdbinit file
Add this to your ~/.gdbinit file:
[code]
source /path/to/gdb-xsource/xsource.gdb
[/code]

** Create and run xsource commands
Put executable file in GDB_XSOURCE_DIRS, then in gdb you can use them
by:
[code]
(gdb) xsource name args...
[/code]
Where 'name' is the executable file name, and up to 9 args is supported
currently. The xsource command will firstly search from
GDB_XSOURCE_DIRS, then
from GDB_XSOURCE_ROOT/xsource.d, and stop searching whenever executable
file
called 'name' is found. If the xsource command find the executable file,
it will
call the executable file with args, and execute its output as gdb
sequences. Here recursions are supported, which means you can call
'xsource'
command recursively in your scripts.

** Debugging your xsource commands
Whenever an error occurs, you can check the error information from gdb,
and
examining accordingly the generated gdb sequences from file
'/tmp/xsource.current'.


* Contact me
This package is published under the licenses under WTFPL, do what ever
you want
to the codes. And if you have any suggestion and advice, feel free to
cantact
me, my contacts:
- Name: ZC Miao
- Email: hellwolf.misty@gmail.com

--
ZC Miao (hellwolf.misty@gmail.com)
Blog http://hellwolf.cublog.cn

gpg --keyserver pgp.mit.edu --recv-key 0x6B174C6F

we need to split main into"core" and "wtf-uses-this"