docs/gettingstarted/developers/gdb_examples.rst

   1 .. _gdb_examples:
   2
   3 .. toctree::
   4
   5 GDB Examples
   6 ===============
   7
   8 In this section we have a few useful gdb commands.
   9
  10 Starting GDB
  11 ----------------------------
  12
  13 Once at the gdb prompt, VPP can be started by running the following commands:
  14
  15 .. code-block:: console
  16
  17    (gdb) run -c /etc/vpp/startup.conf
  18    Starting program: /scratch/vpp-master/build-root/install-vpp_debug-native/vpp/bin/vpp -c /etc/vpp/startup.conf
  19     [Thread debugging using libthread_db enabled]
  20     Using host libthread_db library "/lib/x86_64-linux-gnu/libthread_db.so.1".
  21     vlib_plugin_early_init:361: plugin path /scratch/vpp-master/build-root/install-vpp_debug-native/vpp/lib/vpp_plugins:/scratch/vpp-master/build-root/install-vpp_debug-native/vpp/lib/vpp_plugins
  22     ....
  23
  24 Backtrace
  25 ----------------------------
  26
  27 If you encounter errors when running VPP, such as VPP terminating due to a segfault
  28 or abort signal, then you can run the VPP debug binary and then execute **backtrace** or **bt**.
  29
  30 .. code-block:: console
  31
  32     (gdb) bt
  33     #0  ip4_icmp_input (vm=0x7ffff7b89a40 <vlib_global_main>, node=0x7fffb6bb6900, frame=0x7fffb6725ac0) at /scratch/vpp-master/build-data/../src/vnet/ip/icmp4.c:187
  34     #1  0x00007ffff78da4be in dispatch_node (vm=0x7ffff7b89a40 <vlib_global_main>, node=0x7fffb6bb    6900, type=VLIB_NODE_TYPE_INTERNAL, dispatch_state=VLIB_NODE_STATE_POLLING, frame=0x7fffb6725ac0, last_time_stamp=10581236529    65565) at /scratch/vpp-master/build-data/../src/vlib/main.c:988
  35     #2  0x00007ffff78daa77 in dispatch_pending_node (vm=0x7ffff7b89a40 <vlib_global_main>, pending_frame_index=6, last_time_stamp=1058123652965565) at /scratch/vpp-master/build-data/../src/vlib/main.c:1138
  36     ....
  37
  38 Get to the GDB prompt
  39 ---------------------------------------
  40
  41 When VPP is running, you can get to the command prompt by pressing **CTRL+C**.
  42
  43 Breakpoints
  44 ---------------------------------------
  45
  46 When at the GDB prompt, set a breakpoint by running the commands below:
  47
  48 .. code-block:: console
  49
  50     (gdb) break ip4_icmp_input
  51     Breakpoint 4 at 0x7ffff6b9c00b: file /scratch/vpp-master/build-data/../src/vnet/ip/icmp4.c, line 142.
  52
  53 List the breakpoints already set:
  54
  55 .. code-block:: console
  56
  57     (gdb) i b
  58     Num     Type           Disp Enb Address            What
  59     1       breakpoint     keep y   0x00007ffff6b9c00b in ip4_icmp_input at /scratch/vpp-master/build-data/../src/vnet/ip/icmp4.c:142
  60         breakpoint already hit 3 times
  61     2       breakpoint     keep y   0x00007ffff6b9c00b in ip4_icmp_input at /scratch/vpp-master/build-data/../src/vnet/ip/icmp4.c:142
  62     3       breakpoint     keep y   0x00007ffff640f646 in tw_timer_expire_timers_internal_1t_3w_1024sl_ov
  63         at /scratch/vpp-master/build-data/../src/vppinfra/tw_timer_template.c:775
  64
  65 Delete a breakpoint:
  66
  67 .. code-block:: console
  68
  69     (gdb) del 2
  70     (gdb) i b
  71     Num     Type           Disp Enb Address            What
  72     1       breakpoint     keep y   0x00007ffff6b9c00b in ip4_icmp_input at /scratch/vpp-master/build-data/../src/vnet/ip/icmp4.c:142
  73         breakpoint already hit 3 times
  74     3       breakpoint     keep y   0x00007ffff640f646 in tw_timer_expire_timers_internal_1t_3w_1024sl_ov
  75         at /scratch/vpp-master/build-data/../src/vppinfra/tw_timer_template.c:775
  76
  77 Step/Next/List
  78 ---------------------------------------
  79
  80 Step through the code using (s)tep into, (n)ext, and list some lines before and after where you are with list.
  81
  82 .. code-block:: console
  83
  84     Thread 1 "vpp_main" hit Breakpoint 1, ip4_icmp_input (vm=0x7ffff7b89a40 <vlib_global_main>, node=0x7fffb6bb6900, frame=0x7fffb6709480)
  85         at /scratch/jdenisco/vpp-master/build-data/../src/vnet/ip/icmp4.c:142
  86     142 {
  87     (gdb) n
  88     143   icmp4_main_t *im = &icmp4_main;
  89     (
  90     (gdb) list
  91     202       vlib_put_next_frame (vm, node, next, n_left_to_next);
  92     203     }
  93     204
  94     205   return frame->n_vectors;
  95     206 }
  96     207
  97     208 /* *INDENT-OFF* */
  98     209 VLIB_REGISTER_NODE (ip4_icmp_input_node,static) = {
  99     210   .function = ip4_icmp_input,
 100     211   .name = "ip4-icmp-input",
 101
 102 Examining Data and packets
 103 -----------------------------------------------
 104
 105 To look at data and packets use e(x)amine or (p)rint.
 106
 107
 108 For example in this code look at the ip packet:
 109
 110 .. code-block:: console
 111
 112     (gdb) p/x *ip0
 113     $3 = {{ip_version_and_header_length = 0x45, tos = 0x0, length = 0x5400,
 114     fragment_id = 0x7049, flags_and_fragment_offset = 0x40, ttl = 0x40, protocol = 0x1,
 115     checksum = 0x2ddd, {{src_address = {data = {0xa, 0x0, 0x0, 0x2},
 116     data_u32 = 0x200000a, as_u8 = {0xa, 0x0, 0x0, 0x2}, as_u16 = {0xa, 0x200},
 117     as_u32 = 0x200000a}, dst_address = {data = {0xa, 0x0, 0x0, 0xa}, data_u32 = 0xa00000a,
 118     as_u8 = {0xa, 0x0, 0x0, 0xa}, as_u16 = {0xa, 0xa00},  as_u32 = 0xa00000a}},
 119     address_pair = {src = {data = {0xa, 0x0, 0x0, 0x2}, data_u32 = 0x200000a,
 120     as_u8 = {0xa, 0x0, 0x0, 0x2}, as_u16 = {0xa, 0x200},  as_u32 = 0x200000a},
 121     dst = {data = {0xa, 0x0, 0x0, 0xa}, data_u32 = 0xa00000a, as_u8 = {0xa, 0x0, 0x0, 0xa},
 122     as_u16 = {0xa, 0xa00}, as_u32 = 0xa00000a}}}}, {checksum_data_64 =
 123     {0x40704954000045, 0x200000a2ddd0140}, checksum_data_64_32 = {0xa00000a}},
 124     {checksum_data_32 = {0x54000045, 0x407049, 0x2ddd0140, 0x200000a, 0xa00000a}}}
 125
 126 Then the icmp header
 127
 128 .. code-block:: console
 129
 130     (gdb) p/x *icmp0
 131     $4 = {type = 0x8, code = 0x0, checksum = 0xf148}
 132
 133 Then look at the actual bytes:
 134
 135 .. code-block:: console
 136
 137     (gdb) x/50w ip0
 138     0x7fde9953510e:     0x54000045      0x00407049      0x2ddd0140      0x0200000a
 139     0x7fde9953511e:     0x0a00000a      0xf1480008      0x03000554      0x5b6b2e8a
 140     0x7fde9953512e:     0x00000000      0x000ca99a      0x00000000      0x13121110
 141     0x7fde9953513e:     0x17161514      0x1b1a1918      0x1f1e1d1c      0x23222120