diff options
| -rw-r--r-- | docs/gettingstarted/developers/building.rst | 45 | ||||
| -rw-r--r-- | docs/gettingstarted/developers/gdb_examples.rst | 141 | ||||
| -rw-r--r-- | docs/gettingstarted/developers/index.rst | 2 | ||||
| -rw-r--r-- | docs/gettingstarted/developers/running_vpp.rst | 40 |
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) |