ceph/src/spdk/doc/gdb_macros.md

   1 # GDB Macros User Guide {#gdb_macros}
   2
   3 # Introduction
   4
   5 When debugging an spdk application using gdb we may need to view data structures
   6 in lists, e.g. information about bdevs or threads.
   7
   8 If, for example I have several bdevs, and I wish to get information on bdev by
   9 the 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
  17 g_bdev_mgr->bdevs->tqh_first->internal->link->tqe_next->internal->link->tqe_next->name
  18 $7 = 0x7f7dcc215a00 "test_vols3"
  19 (gdb) p
  20 g_bdev_mgr->bdevs->tqh_first->internal->link->tqe_next->internal->link->tqe_next
  21 $8 = (struct spdk_bdev *) 0x7f7dcc2c7c08
  22 ~~~
  23
  24 At this stage, we can start looking at the relevant fields of our bdev which now
  25 we know is in address 0x7f7dcc2c7c08.
  26
  27 This can be somewhat troublesome if there are 100 bdevs, and the one we need is
  28 56th in the list...
  29
  30 Instead, we can use a gdb macro in order to get information about all the
  31 devices.
  32
  33 Examples:
  34
  35 Printing bdevs:
  36
  37 ~~~{.sh}
  38 (gdb) spdk_print_bdevs
  39
  40 SPDK object of type struct spdk_bdev at 0x7f7dcc1642a8
  41 ((struct spdk_bdev*) 0x7f7dcc1642a8)
  42 name 0x7f7dcc0b21b0 "test_vols1"
  43
  44 ---------------
  45
  46 SPDK object of type struct spdk_bdev at 0x7f7dcc216008
  47 ((struct spdk_bdev*) 0x7f7dcc216008)
  48 name 0x7f7dcc0b1a70 "test_vols2"
  49
  50 ---------------
  51
  52 SPDK object of type struct spdk_bdev at 0x7f7dcc2c7c08
  53 ((struct spdk_bdev*) 0x7f7dcc2c7c08)
  54 name 0x7f7dcc215a00 "test_vols3"
  55
  56 ---------------
  57 ~~~
  58
  59 Finding a bdev by name:
  60
  61 ~~~{.sh}
  62 (gdb) spdk_find_bdev test_vols1
  63 test_vols1
  64
  65 SPDK object of type struct spdk_bdev at 0x7f7dcc1642a8
  66 ((struct spdk_bdev*) 0x7f7dcc1642a8)
  67 name 0x7f7dcc0b21b0 "test_vols1"
  68 ~~~
  69
  70 Printing  spdk threads:
  71
  72 ~~~{.sh}
  73 (gdb) spdk_print_threads
  74
  75 SPDK object of type struct spdk_thread at 0x7fffd0008b50
  76 ((struct spdk_thread*) 0x7fffd0008b50)
  77 name 0x7fffd00008e0 "reactor_1"
  78 IO 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
 108 Printing nvmf subsystems:
 109
 110 ~~~{.sh}
 111 (gdb) spdk_print_nvmf_subsystems
 112
 113 SPDK object of type struct spdk_nvmf_subsystem at 0x7fffd0008d00
 114 ((struct spdk_nvmf_subsystem*) 0x7fffd0008d00)
 115 name "nqn.2014-08.org.nvmexpress.discovery", '\000' <repeats 187 times>
 116 nqn "nqn.2014-08.org.nvmexpress.discovery", '\000' <repeats 187 times>
 117 ID 0
 118
 119 ---------------
 120
 121 SPDK object of type struct spdk_nvmf_subsystem at 0x7fffd0055760
 122 ((struct spdk_nvmf_subsystem*) 0x7fffd0055760)
 123 name "nqn.2016-06.io.spdk.umgmt:cnode1", '\000' <repeats 191 times>
 124 nqn "nqn.2016-06.io.spdk.umgmt:cnode1", '\000' <repeats 191 times>
 125 ID 1
 126 ~~~
 127
 128 # Loading The gdb Macros
 129
 130 Copy the gdb macros to the host where you are about to debug.
 131 It is best to copy the file either to somewhere within the PYTHONPATH, or to add
 132 the destination directory to the PYTHONPATH. This is not mandatory, and can be
 133 worked around, but can save a few steps when loading the module to gdb.
 134
 135 From gdb, with the application core open, invoke python and load the modules.
 136
 137 In the example below, I copied the macros to the /tmp directory which is not in
 138 the 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
 151 On most systems, the data directory is /usr/share/gdb. The python script should
 152 be copied into the python/gdb/function (or python/gdb/command) directory under
 153 the data directory, e.g. /usr/share/gdb/python/gdb/function.
 154
 155 If the python script is in there, then the only thing you need to do when
 156 starting 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
 161 above prior to starting gdb.
 162
 163 Exmaple .gdbinit:
 164
 165 ~~~{.sh}
 166 source /opt/km/install/tools/gdb_macros/gdb_macros.py
 167 ~~~
 168
 169 When starting gdb you still have to call spdk_load_macros.
 170
 171 # Why Do We Need to Explicitly Call spdk_load_macros
 172
 173 The reason is that the macros need to use globals provided by spdk in order to
 174 iterate the spdk lists and build iterable representations of the list objects.
 175 This will result in errors if these are not available which is very possible if
 176 gdb is used for reasons other than debugging spdk core dumps.
 177
 178 In the example bellow, I attempted to load the macros when the globals are not
 179 available causing gdb to fail loading the gdb_macros:
 180
 181 ~~~{.sh}
 182 (gdb) spdk_load_macros
 183 Traceback (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)
 194 RuntimeError: No symbol table is loaded.  Use the "file" command.
 195 Error occurred in Python command: No symbol table is loaded.  Use the "file"
 196 command.
 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
 210 The 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
 218 Other 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)