xref: /spdk/doc/gdb_macros.md (revision 877573897ad52be4fa8989f7617bd655b87e05c4) 
1# GDB Macros User Guide {#gdb_macros}
2
3## Introduction
4
5When debugging an spdk application using gdb we may need to view data structures
6in lists, e.g. information about bdevs or threads.
7
8If, for example I have several bdevs, and I wish to get information on bdev by
9the name 'test_vols3', I will need to manually iterate over the list as follows:
10
11~~~{.sh}
12(gdb) p g_bdev_mgr->bdevs->tqh_first->name
13$5 = 0x7f7dcc0b21b0 "test_vols1"
14(gdb) p g_bdev_mgr->bdevs->tqh_first->internal->link->tqe_next->name
15$6 = 0x7f7dcc0b1a70 "test_vols2"
16(gdb) p
17g_bdev_mgr->bdevs->tqh_first->internal->link->tqe_next->internal->link->tqe_next->name
18$7 = 0x7f7dcc215a00 "test_vols3"
19(gdb) p
20g_bdev_mgr->bdevs->tqh_first->internal->link->tqe_next->internal->link->tqe_next
21$8 = (struct spdk_bdev *) 0x7f7dcc2c7c08
22~~~
23
24At this stage, we can start looking at the relevant fields of our bdev which now
25we know is in address 0x7f7dcc2c7c08.
26
27This can be somewhat troublesome if there are 100 bdevs, and the one we need is
2856th in the list...
29
30Instead, we can use a gdb macro in order to get information about all the
31devices.
32
33Examples:
34
35Printing bdevs:
36
37~~~{.sh}
38(gdb) spdk_print_bdevs
39
40SPDK object of type struct spdk_bdev at 0x7f7dcc1642a8
41((struct spdk_bdev*) 0x7f7dcc1642a8)
42name 0x7f7dcc0b21b0 "test_vols1"
43
44---------------
45
46SPDK object of type struct spdk_bdev at 0x7f7dcc216008
47((struct spdk_bdev*) 0x7f7dcc216008)
48name 0x7f7dcc0b1a70 "test_vols2"
49
50---------------
51
52SPDK object of type struct spdk_bdev at 0x7f7dcc2c7c08
53((struct spdk_bdev*) 0x7f7dcc2c7c08)
54name 0x7f7dcc215a00 "test_vols3"
55
56---------------
57~~~
58
59Finding a bdev by name:
60
61~~~{.sh}
62(gdb) spdk_find_bdev test_vols1
63test_vols1
64
65SPDK object of type struct spdk_bdev at 0x7f7dcc1642a8
66((struct spdk_bdev*) 0x7f7dcc1642a8)
67name 0x7f7dcc0b21b0 "test_vols1"
68~~~
69
70Printing  spdk threads:
71
72~~~{.sh}
73(gdb) spdk_print_threads
74
75SPDK object of type struct spdk_thread at 0x7fffd0008b50
76((struct spdk_thread*) 0x7fffd0008b50)
77name 0x7fffd00008e0 "reactor_1"
78IO Channels:
79        SPDK object of type struct spdk_io_channel at 0x7fffd0052610
80        ((struct spdk_io_channel*) 0x7fffd0052610)
81        name
82        ref 1
83        device 0x7fffd0008c80 (0x7fffd0008ce0 "nvmf_tgt")
84        ---------------
85
86        SPDK object of type struct spdk_io_channel at 0x7fffd0056cd0
87        ((struct spdk_io_channel*) 0x7fffd0056cd0)
88        name
89        ref 2
90        device 0x7fffd0056bf0 (0x7fffd0008e70 "test_vol1")
91        ---------------
92
93        SPDK object of type struct spdk_io_channel at 0x7fffd00582e0
94        ((struct spdk_io_channel*) 0x7fffd00582e0)
95        name
96        ref 1
97        device 0x7fffd0056c50 (0x7fffd0056cb0 "bdev_test_vol1")
98        ---------------
99
100        SPDK object of type struct spdk_io_channel at 0x7fffd00583b0
101        ((struct spdk_io_channel*) 0x7fffd00583b0)
102        name
103        ref 1
104        device 0x7fffd0005630 (0x7fffd0005690 "bdev_mgr")
105        ---------------
106~~~
107
108Printing nvmf subsystems:
109
110~~~{.sh}
111(gdb) spdk_print_nvmf_subsystems
112
113SPDK object of type struct spdk_nvmf_subsystem at 0x7fffd0008d00
114((struct spdk_nvmf_subsystem*) 0x7fffd0008d00)
115name "nqn.2014-08.org.nvmexpress.discovery", '\000' <repeats 187 times>
116nqn "nqn.2014-08.org.nvmexpress.discovery", '\000' <repeats 187 times>
117ID 0
118
119---------------
120
121SPDK object of type struct spdk_nvmf_subsystem at 0x7fffd0055760
122((struct spdk_nvmf_subsystem*) 0x7fffd0055760)
123name "nqn.2016-06.io.spdk.umgmt:cnode1", '\000' <repeats 191 times>
124nqn "nqn.2016-06.io.spdk.umgmt:cnode1", '\000' <repeats 191 times>
125ID 1
126~~~
127
128## Loading The gdb Macros
129
130Copy the gdb macros to the host where you are about to debug.
131It is best to copy the file either to somewhere within the PYTHONPATH, or to add
132the destination directory to the PYTHONPATH. This is not mandatory, and can be
133worked around, but can save a few steps when loading the module to gdb.
134
135From gdb, with the application core open, invoke python and load the modules.
136
137In the example below, I copied the macros to the /tmp directory which is not in
138the PYTHONPATH, so I had to manually add the directory to the path.
139
140~~~{.sh}
141(gdb) python
142>import sys
143>sys.path.append('/tmp')
144>import gdb_macros
145>end
146(gdb) spdk_load_macros
147~~~
148
149## Using the gdb Data Directory
150
151On most systems, the data directory is /usr/share/gdb. The python script should
152be copied into the python/gdb/function (or python/gdb/command) directory under
153the data directory, e.g. /usr/share/gdb/python/gdb/function.
154
155If the python script is in there, then the only thing you need to do when
156starting gdb is type "spdk_load_macros".
157
158## Using .gdbinit To Load The Macros
159
160.gdbinit can also be used in order to run automatically run the manual steps
161above prior to starting gdb.
162
163Example .gdbinit:
164
165~~~{.sh}
166source /opt/km/install/tools/gdb_macros/gdb_macros.py
167~~~
168
169When starting gdb you still have to call spdk_load_macros.
170
171## Why Do We Need to Explicitly Call spdk_load_macros
172
173The reason is that the macros need to use globals provided by spdk in order to
174iterate the spdk lists and build iterable representations of the list objects.
175This will result in errors if these are not available which is very possible if
176gdb is used for reasons other than debugging spdk core dumps.
177
178In the example below, I attempted to load the macros when the globals are not
179available causing gdb to fail loading the gdb_macros:
180
181~~~{.sh}
182(gdb) spdk_load_macros
183Traceback (most recent call last):
184  File "/opt/km/install/tools/gdb_macros/gdb_macros.py", line 257, in invoke
185    spdk_print_threads()
186  File "/opt/km/install/tools/gdb_macros/gdb_macros.py", line 241, in __init__
187    threads = SpdkThreads()
188  File "/opt/km/install/tools/gdb_macros/gdb_macros.py", line 234, in __init__
189    super(SpdkThreads, self).__init__('g_threads', SpdkThread)
190  File "/opt/km/install/tools/gdb_macros/gdb_macros.py", line 25, in __init__
191    ['tailq'])
192  File "/opt/km/install/tools/gdb_macros/gdb_macros.py", line 10, in __init__
193    self.list = gdb.parse_and_eval(self.list_pointer)
194RuntimeError: No symbol table is loaded.  Use the "file" command.
195Error occurred in Python command: No symbol table is loaded.  Use the "file"
196command.
197~~~
198
199## Macros available
200
201- spdk_load_macros: load the macros (use --reload in order to reload them)
202- spdk_print_bdevs: information about bdevs
203- spdk_find_bdev: find a bdev (substring search)
204- spdk_print_io_devices: information about io devices
205- spdk_print_nvmf_subsystems: information about nvmf subsystems
206- spdk_print_threads: information about threads
207
208## Adding New Macros
209
210The list iteration macros are usually built from 3 layers:
211
212- SpdkPrintCommand: inherits from gdb.Command and invokes the list iteration
213- SpdkTailqList: Performs the iteration of a tailq list according to the tailq
214  member implementation
215- SpdkObject: Provides the __str__ function so that the list iteration can print
216  the object
217
218Other useful objects:
219
220- SpdkNormalTailqList: represents a list which has 'tailq' as the tailq object
221- SpdkArr: Iteration over an array (instead of a linked list)
222