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>
This commit is contained in:
andrew
@ -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
|
||||
|
||||
141
docs/gettingstarted/developers/gdb_examples.rst
Normal file
141
docs/gettingstarted/developers/gdb_examples.rst
Normal file
@ -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
|
||||
@ -16,6 +16,8 @@ The Developers section covers the following areas:
|
||||
:maxdepth: 2
|
||||
|
||||
building
|
||||
running_vpp
|
||||
gdb_examples
|
||||
softwarearchitecture
|
||||
infrastructure
|
||||
vlib
|
||||
|
||||
40
docs/gettingstarted/developers/running_vpp.rst
Normal file
40
docs/gettingstarted/developers/running_vpp.rst
Normal file
@ -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)
|
||||
Reference in New Issue
Block a user