docs: A little cleanup and added some gdb examples.

docs: Added section on running VPP for developers.

Change-Id: I98b5c6f1c9fee60b297e3947e78ec33f950f598a
Signed-off-by: andrew <andrew.olechtchouk@gmail.com>

4 files changed, 210 insertions, 18 deletions

diff --git a/docs/gettingstarted/developers/building.rst b/docs/gettingstarted/developers/building.rst
index 18fa943a6fb..a408b510ca0 100644
--- a/docs/gettingstarted/developers/building.rst
+++ b/docs/gettingstarted/developers/building.rst
@@ -10,7 +10,7 @@ To get started developing with VPP you need to get the sources and build the pac
 .. _setupproxies:
 
 Set up Proxies
---------------
+--------------------------
 
 Depending on the environment, proxies may need to be set. 
 You may run these commands:
@@ -22,7 +22,7 @@ You may run these commands:
 
 
 Get the VPP Sources
--------------------
+-----------------------------------
 
 To get the VPP sources and get ready to build execute the following:
 
@@ -32,7 +32,7 @@ To get the VPP sources and get ready to build execute the following:
     $ cd vpp
 
 Build VPP Dependencies
-----------------------
+--------------------------------------
 
 Before building, make sure there are no FD.io VPP or DPDK packages installed by entering the following
 commands:
@@ -44,7 +44,7 @@ commands:
 
 There should be no output, or packages showing after each of the above commands.
 
-Run this to install the dependencies for FD.io VPP. 
+Run these commands to install the dependencies for FD.io VPP. 
 If it hangs during downloading at any point, you may need to set up :ref:`proxies for this to work <setupproxies>`.
 
 .. code-block:: console
@@ -71,11 +71,12 @@ If it hangs during downloading at any point, you may need to set up :ref:`proxie
     done.
     done.
 
-Build VPP (Debug Mode)
-----------------------
+Build VPP (Debug)
+----------------------------
 
-This build version contains debug symbols which is useful to modify VPP. The command below will build debug version of VPP. 
-This build will come with /build-root/vpp_debug-native.
+This build version contains debug symbols which is useful to modify VPP. The command
+below will build debug version of VPP. The binaries when building the debug images
+can be found in /build-root/vpp_debug-native.
 
 .. code-block:: console
 
@@ -99,24 +100,23 @@ This build will come with /build-root/vpp_debug-native.
     make[1]: Leaving directory '/home/vagrant/vpp-master/build-root'
 
 Build VPP (Release Version)
----------------------------
+-----------------------------------------
 
-To build the release version of FD.io VPP.
-This build is optimized and will not create debug symbols.
-This build will come with /build-root/build-vpp-native
+To build the release version of FD.io VPP. This build is optimized and will not create debug symbols.
+The binaries when building the release images can be found in /build-root/vpp-native.
 
 .. code-block:: console
 
-    $ make release
+    $ make build-release
 
 
 Building Necessary Packages
----------------------------
+--------------------------------------------
 
 To build the debian packages, one of the following commands below depending on the system:
 
 Building Debian Packages
-^^^^^^^^^^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^^^^^^^^^^
 
 .. code-block:: console
 
@@ -124,13 +124,13 @@ Building Debian Packages
 
 
 Building RPM Packages
-^^^^^^^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^^^^^^^^
 
 .. code-block:: console
 
     $ make pkg-rpm
 
-The packages will be found in the build-root directory.
+Once the packages are builty they can be found in the build-root directory.
 
 .. code-block:: console
     
@@ -143,9 +143,18 @@ The packages will be found in the build-root directory.
     vpp-api-lua_18.07-rc0~456-gb361076_amd64.deb     vpp-lib_18.07-rc0~456-gb361076_amd64.deb
     vpp-api-python_18.07-rc0~456-gb361076_amd64.deb  vpp-plugins_18.07-rc0~456-gb361076_amd64.deb
 
-Packages built installed end up in build-root directory. Finally, the command below installs all built packages.
+Finally, the packages can be installed with the following:
+
+For Ubuntu:
 
 .. code-block:: console
 
    $ sudo bash
    # dpkg -i *.deb
+
+For Centos or Redhat:
+
+.. code-block:: console
+
+   $ sudo bash
+   # rpm -ivh *.rpm
diff --git a/docs/gettingstarted/developers/gdb_examples.rst b/docs/gettingstarted/developers/gdb_examples.rst
new file mode 100644
index 00000000000..b2ef65bcd83
--- /dev/null
+++ b/docs/gettingstarted/developers/gdb_examples.rst
@@ -0,0 +1,141 @@
+.. _gdb_examples:
+
+.. toctree::
+
+GDB Examples
+===============
+
+In this section we have a few useful gdb commands.
+
+Starting GDB
+----------------------------
+
+Once at the gdb prompt VPP can be started with the following:
+
+.. code-block:: console
+
+   (gdb) run -c /etc/vpp/startup.conf
+   Starting program: /scratch/vpp-master/build-root/install-vpp_debug-native/vpp/bin/vpp -c /etc/vpp/startup.conf
+    [Thread debugging using libthread_db enabled]
+    Using host libthread_db library "/lib/x86_64-linux-gnu/libthread_db.so.1".
+    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/lib64/vpp_plugins
+    ....
+
+Backtrace
+----------------------------
+
+If you encounter issues when running VPP, such as VPP terminating due to a segfault
+or abort signal, you can run the VPP debug binary and then execute **backtrace** or **bt**.
+
+.. code-block:: console
+
+    (gdb) bt
+    #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
+    #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
+    #2  0x00007ffff78daa77 in dispatch_pending_node (vm=0x7ffff7b89a40 <vlib_global_main>, pending_f    rame_index=6, last_time_stamp=1058123652965565) at /scratch/vpp-master/build-data/../src/vlib/main.c:1138
+    ....
+
+Get to the GDB prompt
+---------------------------------------
+
+When running VPP is running get to the command prompt with CTRL-c.
+
+Breakpoints
+---------------------------------------
+
+When at the GDB prompt set a breakpoint like so:
+
+.. code-block:: console
+
+    (gdb) break ip4_icmp_input
+    Breakpoint 4 at 0x7ffff6b9c00b: file /scratch/vpp-master/build-data/../src/vnet/ip/icmp4.c, line 142.
+
+List the breakpoints already set:
+
+.. code-block:: console
+
+    (gdb) i b
+    Num     Type           Disp Enb Address            What
+    1       breakpoint     keep y   0x00007ffff6b9c00b in ip4_icmp_input at /scratch/vpp-master/build-data/../src/vnet/ip/icmp4.c:142
+        breakpoint already hit 3 times
+    2       breakpoint     keep y   0x00007ffff6b9c00b in ip4_icmp_input at /scratch/vpp-master/build-data/../src/vnet/ip/icmp4.c:142
+    3       breakpoint     keep y   0x00007ffff640f646 in tw_timer_expire_timers_internal_1t_3w_1024sl_ov 
+        at /scratch/vpp-master/build-data/../src/vppinfra/tw_timer_template.c:775
+
+Delete a breakpoint:
+
+.. code-block:: console
+
+    (gdb) del 2
+    (gdb) i b
+    Num     Type           Disp Enb Address            What
+    1       breakpoint     keep y   0x00007ffff6b9c00b in ip4_icmp_input at /scratch/vpp-master/build-data/../src/vnet/ip/icmp4.c:142
+	breakpoint already hit 3 times
+    3       breakpoint     keep y   0x00007ffff640f646 in tw_timer_expire_timers_internal_1t_3w_1024sl_ov 
+        at /scratch/vpp-master/build-data/../src/vppinfra/tw_timer_template.c:775
+
+Step/Next/List
+---------------------------------------
+
+Step through the code using (s)tep into, (n)ext, and list some lines before and after where you are with list.
+
+.. code-block:: console
+
+    Thread 1 "vpp_main" hit Breakpoint 1, ip4_icmp_input (vm=0x7ffff7b89a40 <vlib_global_main>, node=0x7fffb6bb6900, frame=0x7fffb6709480)
+        at /scratch/jdenisco/vpp-master/build-data/../src/vnet/ip/icmp4.c:142
+    142	{
+    (gdb) n
+    143	  icmp4_main_t *im = &icmp4_main;
+    (
+    (gdb) list
+    202	      vlib_put_next_frame (vm, node, next, n_left_to_next);
+    203	    }
+    204	
+    205	  return frame->n_vectors;
+    206	}
+    207	
+    208	/* *INDENT-OFF* */
+    209	VLIB_REGISTER_NODE (ip4_icmp_input_node,static) = {
+    210	  .function = ip4_icmp_input,
+    211	  .name = "ip4-icmp-input",
+
+Examining Data and packets
+-----------------------------------------------
+
+To look at data and packets use e(x)amine or (p)rint.
+
+
+For example in this code look at the ip packet:
+
+.. code-block:: console
+
+    (gdb) p/x *ip0
+    $3 = {{ip_version_and_header_length = 0x45, tos = 0x0, length = 0x5400,
+    fragment_id = 0x7049, flags_and_fragment_offset = 0x40, ttl = 0x40, protocol = 0x1,
+    checksum = 0x2ddd, {{src_address = {data = {0xa, 0x0, 0x0, 0x2},
+    data_u32 = 0x200000a, as_u8 = {0xa, 0x0, 0x0, 0x2}, as_u16 = {0xa, 0x200},
+    as_u32 = 0x200000a}, dst_address = {data = {0xa, 0x0, 0x0, 0xa}, data_u32 = 0xa00000a,
+    as_u8 = {0xa, 0x0, 0x0, 0xa}, as_u16 = {0xa, 0xa00},  as_u32 = 0xa00000a}},
+    address_pair = {src = {data = {0xa, 0x0, 0x0, 0x2}, data_u32 = 0x200000a,
+    as_u8 = {0xa, 0x0, 0x0, 0x2}, as_u16 = {0xa, 0x200},  as_u32 = 0x200000a},
+    dst = {data = {0xa, 0x0, 0x0, 0xa}, data_u32 = 0xa00000a, as_u8 = {0xa, 0x0, 0x0, 0xa},
+    as_u16 = {0xa, 0xa00}, as_u32 = 0xa00000a}}}}, {checksum_data_64 =
+    {0x40704954000045, 0x200000a2ddd0140}, checksum_data_64_32 = {0xa00000a}},
+    {checksum_data_32 = {0x54000045, 0x407049, 0x2ddd0140, 0x200000a, 0xa00000a}}}
+      
+Then the icmp header
+
+.. code-block:: console
+
+    (gdb) p/x *icmp0
+    $4 = {type = 0x8, code = 0x0, checksum = 0xf148}
+
+Then look at the actual bytes:
+
+.. code-block:: console
+
+    (gdb) x/50w ip0
+    0x7fde9953510e:	0x54000045	0x00407049	0x2ddd0140	0x0200000a
+    0x7fde9953511e:	0x0a00000a	0xf1480008	0x03000554	0x5b6b2e8a
+    0x7fde9953512e:	0x00000000	0x000ca99a	0x00000000	0x13121110
+    0x7fde9953513e:	0x17161514	0x1b1a1918	0x1f1e1d1c	0x23222120
diff --git a/docs/gettingstarted/developers/index.rst b/docs/gettingstarted/developers/index.rst
index a5d71a9a5c3..661567fcb67 100644
--- a/docs/gettingstarted/developers/index.rst
+++ b/docs/gettingstarted/developers/index.rst
@@ -16,6 +16,8 @@ The Developers section covers the following areas:
    :maxdepth: 2
 
    building
+   running_vpp
+   gdb_examples
    softwarearchitecture
    infrastructure
    vlib
diff --git a/docs/gettingstarted/developers/running_vpp.rst b/docs/gettingstarted/developers/running_vpp.rst
new file mode 100644
index 00000000000..4c717af3e19
--- /dev/null
+++ b/docs/gettingstarted/developers/running_vpp.rst
@@ -0,0 +1,40 @@
+.. _running_vpp:
+
+.. toctree::
+
+Running VPP
+===========
+
+After build the VPP binaries, there a several to run the images you've built. These is useful when
+if you need to run VPP without  installing the packages. For instance if you want to run VPP with GDB.
+
+Without GDB
+_________________________
+
+To run the VPP images, that you've build without GDB.
+
+Running the release image:
+
+.. code-block:: console
+
+   # make run-release
+   #
+
+With GDB
+_________________________
+
+With the following commands you can run VPP and then be dropped into the GDB prompt.
+
+Running the release image:
+
+.. code-block:: console
+
+   # make debug-release
+   (gdb)
+
+Running the debug image:
+
+.. code-block:: console
+
+   # make debug
+   (gdb)