← Back to branch summary

~ubuntu-branches/ubuntu/utopic/xen/utopic

« back to all changes in this revision

Viewing changes to tools/debugger/gdbsx/README

  • Committer: Bazaar Package Importer
  • Author(s): Bastian Blank
  • Date: 2010-05-06 15:47:38 UTC
  • mto: (1.3.1) (15.1.1 sid) (4.1.1 experimental)
  • mto: This revision was merged to the branch mainline in revision 3.
  • Revision ID: james.westby@ubuntu.com-20100506154738-agoz0rlafrh1fnq7
Tags: upstream-4.0.0
Import upstream version 4.0.0

Show diffs side-by-side

added added

removed removed

Lines of Context:
tools/debugger/gdbsx/README
 
1
 
 
2
                            gdbsx: gdbserver for xen
 
3
 
 
4
 
 
5
Welcome to gdbsx. gdbsx is a gdbserver program to debug guest kernels and 
 
6
kernel modules. It runs on dom0 running on xen hypervisor and allows debug 
 
7
of 32 or 64bit PV or HVM elf guest binaries. It can also be run standalone, 
 
8
without remote gdb, to dump context of any/all VCPUs of any guest.
 
9
 
 
10
It is divided in two parts, gx and xg. The former interacts with remote gdb,
 
11
while latter interacts with xen and exports public APIs that can be used to 
 
12
create a plug in for any other debugger or binary type.
 
13
 
 
14
 
 
15
USAGE:
 
16
   - boot with gdbsx enabled hypervisor (eg, on OVM: xen-64bit-debug.gz)
 
17
   - copy gdbsx binary to the dom0 (assume hostname is "dom0"), then:
 
18
 
 
19
   USAGE 1:
 
20
   - dom0> gdbsx -c 1 64 : displays VCPU contexts for 64bit guest with domid 1
 
21
 
 
22
   USAGE 2:
 
23
   - dom0> gdbsx -a 2 64 9999
 
24
             connects to a 64bit guest with domid 2 and waits for gdb connection
 
25
   - now, connect to the above gdbsx from a remote system or dom0 as: 
 
26
      bash> gdb ./vmlinux             (exact matching vmlinux of guest kernel)
 
27
      (gdb) target remote dom0:9999 
 
28
 
 
29
   - Additionally, to debug loadable kernel modules, please do following:
 
30
      (gdb) p init_mm.pgd[3]
 
31
      $1 = {pgd = 0x1b874f027}
 
32
      (gdb) monitor pgd3 0x1b874f027  (Make sure value is in HEX)
 
33
      pgd3val set to: 0x1b874f027
 
34
 
 
35
   - use gdb as normal, breakpoints, single step, etc...
 
36
   - when need to break into gdb, instead of ctrl-c, just do "xm pause <domid>"
 
37
     on dom0 to pause the guest. this will break into gdb right away.
 
38
   - detach/quit from gdb (leave gdbsx alone) to gracefully exit.
 
39
   - if ctrl-c or core-dumped, make sure to do xm unpause if guest still paused.
 
40
 
 
41
   - multiple vcpus: 
 
42
         o  gdb>set scheduler-locking on   : for single step of correct vcpu.
 
43
 
 
44
         o  since gdb is not kernel debugger, vcpus are emulated via threads
 
45
            Thus, gdb>info threads : will show all vcpus. Then, switch thread 
 
46
            to get to another vcpu, etc...  Remember, gdb has it's own [thread]
 
47
            id, off by 1. 
 
48
 
 
49
   - See below for some useful gdb macros. Please email me if you've more.
 
50
 
 
51
 
 
52
NOTES:
 
53
   - For now, it is not possible to run gdbsx on a guest and gdb inside 
 
54
     the same guest at the same time.
 
55
   - To report problems, please run gdbsx with -d and collect output.
 
56
   - VCPU offlining is not supported. Thus [0-NUMVCPUs] are all assumed active.
 
57
 
 
58
TIPS:
 
59
   - make sure firewall is disabled on dom0 if running gdb on a different host.
 
60
   - Must be at least gdb version 6.5-16.x to debug el5 kernels.
 
61
 
 
62
BUILD: (if you don't have access to binary):
 
63
   - first compile the hypervisor: xen> make gdbsx=y
 
64
         To have both kdb and gdbsx, xen> make kdb=y gdbsx=y
 
65
         (NOTE: kdb is not required for gdbsx)
 
66
   - install the hypervisor and reboot
 
67
   - now go to, tools/debugger/gdbsx and do make
 
68
     On 32bit system, a 32bit binary will be built with support for both 32
 
69
     and 64bit guests. On 64bit system, a 64bit binary will be built with 
 
70
     support for both.
 
71
 
 
72
 
 
73
Mukesh Rathor
 
74
Oracle Corporation,
 
75
Redwood Shores,  CA  USA
 
76
mukesh[dot]rathor[at]oracle[dot]com
 
77
 
 
78
 
 
79
------------------------------------------------------------------------------
 
80
 
 
81
USEFUL gdb macros:
 
82
 
 
83
# Courtesy Zhigang W (http://10.182.120.78/tech/vt/ovm/debug/gdbinit.macros):
 
84
 
 
85
define ps
 
86
        dont-repeat
 
87
        set $tasks = (struct list_head *)init_task->tasks
 
88
        set $offset = (unsigned long)&init_task->tasks - (unsigned long)&init_task
 
89
        set $task = $tasks
 
90
        set $task_entry = (struct task_struct *)((unsigned long)$task - $offset)
 
91
        printf "Pointer       PID      Command\n"
 
92
        printf "%-14p%-9d%s\n", $task_entry, $task_entry->pid, $task_entry->comm
 
93
        set $task = $task->next
 
94
        while $task != $tasks
 
95
                set $task_entry = (struct task_struct *)((unsigned long)$task - $offset)
 
96
                if ($task_entry->pid) != 0
 
97
                        printf "%-14p%-9d%s\n", $task_entry, $task_entry->pid, $task_entry->comm
 
98
                end
 
99
                set $task = $task->next
 
100
        end
 
101
end
 
102
 
 
103
document ps
 
104
Report a snapshot of the current processes.
 
105
end
 
106
 
 
107
 
 
108
define lsmod
 
109
        dont-repeat
 
110
        # 4 for 32bit kernels. 8 for 64bit kernels.
 
111
        set $sz = sizeof(long)     
 
112
        set $mod = (struct list_head *)modules
 
113
        printf "modptr      address     name\n"
 
114
        while 1
 
115
                set $mod_entry = (struct module *)((unsigned long)$mod - $sz)
 
116
                if ($sz == 4)
 
117
                        printf "%08lx  %08lx  %s\n", $mod_entry,      \
 
118
                               $mod_entry->module_core, $mod_entry->name 
 
119
                else
 
120
                        printf "%016lx  %016lx  %s\n", $mod_entry,      \
 
121
                               $mod_entry->module_core, $mod_entry->name 
 
122
                end
 
123
                set $mod = $mod->next
 
124
                if ($mod == &modules)
 
125
                        loop_break
 
126
                end
 
127
        end
 
128
end
 
129
 
 
130
document lsmod
 
131
Show the list of modules loaded in the Linux kernel.
 
132
end
 
133
 
 
134
define log
 
135
        dont-repeat
 
136
        printf "%s", log_buf
 
137
end
 
138
 
 
139
document log
 
140
Dump system message buffer.
 
141
end
 
142
 
 
143
------------------------------------------------------------------------------