Difference between revisions of "VPP/How To Build The Sample Plugin"

From fd.io
< VPP
Jump to: navigation, search
(Initial content)
 
(Install the vpp-dev package)
 
(8 intermediate revisions by 4 users not shown)
Line 14: Line 14:
  
 
For example:
 
For example:
 +
    sudo sh
 +
    cd /usr/share/doc/vpp/examples
 +
    tar cf - . | (cd /tmp; tar xf -)
 +
    cd /tmp/sample-plugin
 +
    gunzip -f *gz sample/*gz
 +
    libtoolize
 +
    aclocal
 +
    autoconf
 +
    autoheader
 +
    automake --add-missing
 +
    chmod +x configure
 +
    vpp_plugin_configure
 +
    make
 +
    sudo make install
  
    $ cd /usr/share/doc/vpp/examples
+
Check to be sure that make installed sample_plugin.so in /usr/lib/vpp_plugins, and sample_test_plugin.so in /usr/lib/vpp_api_test_plugins.
    $ tar cf - . | (cd /tmp; tar xf -)
+
    $ cd /tmp/sample-plugin
+
    $ gunzip -f *gz sample/*gz
+
    $ chmod +x configure
+
    $ ./configure --with-plugin-toolkit
+
    $ make
+
    # sudo make install
+
  
 +
It's very important to use the "vpp_plugin_configure" script, to compile the plugin with the same CFLAGS settings that were used to compile the vpp engine. Certain data structures change size dpending e.g. on "-DDPDK=[0|1]", leading to subtle misbehavior. You've been warned.
  
 
== Install the Sample Plug-in ==
 
== Install the Sample Plug-in ==
Line 35: Line 43:
 
  # start vpp
 
  # start vpp
  
Note: if you start the vpp data plane manually ("# vpe unix interactive"), you should see a cheerful message of the form:  
+
Note: if you start the vpp data plane manually ("# vpp unix interactive"), you should see a cheerful message of the form:  
  
 
  load_one_plugin:75: Loaded plugin: /usr/lib/vpp_plugins/sample_plugin.so.0.0.0
 
  load_one_plugin:75: Loaded plugin: /usr/lib/vpp_plugins/sample_plugin.so.0.0.0
Line 41: Line 49:
 
== Test the Sample (macswap) Plug-in ==
 
== Test the Sample (macswap) Plug-in ==
  
Try the sample application, which diverts all packets from specific physical interfaces to a graph node which swaps rx packet src and dst MAC addresses. To configure data plane, execute /cisco/bin/vpe_api_test:
+
Try the sample application, which diverts all packets from specific physical interfaces to a graph node which swaps rx packet src and dst MAC addresses. To configure data plane, execute /usr/bin/vpp_api_test:
  
  # vpe_api_test
+
  # vpp_api_test
 
  load_one_plugin:49: Loaded plugin: /usr/lib/vpp_api_test_plugins/sample_test_plugin.so.0.0.0
 
  load_one_plugin:49: Loaded plugin: /usr/lib/vpp_api_test_plugins/sample_test_plugin.so.0.0.0
 
  vat#  
 
  vat#  

Latest revision as of 12:29, 28 June 2016

Introduction

This page explains how to build the sample vpp-engine plug-in. Anything that can be done by code compiled into the VPP engine itself can also be done from a plug-in.

Setting Up

Test the VPP executable, if you have not done so already. Verify proper operation. We recommend that you do not try to build the sample plug-in until you verify that basic operations of the VPP application work as expected.

Install the vpp-dev package

Copy the sample plug-in sources to the directory of your choice, and decompress the individual files.

For example:

   sudo sh
   cd /usr/share/doc/vpp/examples
   tar cf - . | (cd /tmp; tar xf -)
   cd /tmp/sample-plugin
   gunzip -f *gz sample/*gz
   libtoolize
   aclocal
   autoconf
   autoheader
   automake --add-missing
   chmod +x configure
   vpp_plugin_configure
   make
   sudo make install

Check to be sure that make installed sample_plugin.so in /usr/lib/vpp_plugins, and sample_test_plugin.so in /usr/lib/vpp_api_test_plugins.

It's very important to use the "vpp_plugin_configure" script, to compile the plugin with the same CFLAGS settings that were used to compile the vpp engine. Certain data structures change size dpending e.g. on "-DDPDK=[0|1]", leading to subtle misbehavior. You've been warned.

Install the Sample Plug-in

The sample plug-in (generated) Makefile installs the data-plane plug-in in /usr/lib/vpp_plugins. Similarly, it installs the API test harness plug-in in /usr/lib/vpp_api_test_plugins.

Take a look at the sample data-plane and API test client plug-in source code.

Start the VPP data-plane:

# start vpp

Note: if you start the vpp data plane manually ("# vpp unix interactive"), you should see a cheerful message of the form:

load_one_plugin:75: Loaded plugin: /usr/lib/vpp_plugins/sample_plugin.so.0.0.0

Test the Sample (macswap) Plug-in

Try the sample application, which diverts all packets from specific physical interfaces to a graph node which swaps rx packet src and dst MAC addresses. To configure data plane, execute /usr/bin/vpp_api_test:

# vpp_api_test 
load_one_plugin:49: Loaded plugin: /usr/lib/vpp_api_test_plugins/sample_test_plugin.so.0.0.0
vat# 

Note the cheerful message which confirms that the api test tool has loaded its plug-in.

  vat# dump_interface_table
   # displays a list of interfaces, similar to the following:
   
   Interface                sw_if_index    
   GigabitEthernet2/2/0     5              
   GigabitEthernet2/3/0     6              
   GigabitEthernet2/4/0     7              
   GigabitEthernet2/5/0     8              
   GigabitEthernet2/6/0     9              
   GigabitEthernet2/7/0     10             
   local0                   0      
   
   # to enable the mac-swap plugin on a specific interface:
   vat# sample_macswap_enable_disable <interface-name>
   
   # to disable the mac-swap plugin on a specific interface:
   vat# sample_macswap_enable_disable <interface-name> disable
   
   # capture a packet trace, with the swap plugin enabled
   
   vat# exec trace add dpdk-input 10

When you inspect the packet trace, you should see something similar to the output shown below. [If the trace buffer is empty, please make sure that the interface is up...]

   vat# exec show trace
   
   # Note the "sample" trace, which demonstrates that the plugin is working
   # Note also the src and dst mac addresses are swapped...
    
    00:11:32:956278: dpdk-input
    GigabitEthernet2/2/0 rx queue 0
    buffer 0x18db40: current data 0, length 102, free-list 0, 
           totlen-nifb 0, trace 0x9
    PKT MBUF: port 0, nb_segs 1, pkt_len 102
      buf_len 2304, data_len 102, ol_flags 0x0
    IP4: 00:55:56:b7:05:03 -> 00:50:56:b7:05:bd
    ICMP: 6.0.2.2 -> 6.0.2.6
      tos 0x00, ttl 64, length 84, checksum 0x47f1
      fragment id 0xe2b0, flags DONT_FRAGMENT
    ICMP echo_request checksum 0x245f
    00:11:32:956286: sample
    SAMPLE: sw_if_index 5   <================ 
    00:11:32:956290: GigabitEthernet2/2/0-output
    GigabitEthernet2/2/0
    IP4: 00:50:56:b7:05:bd -> 00:55:56:b7:05:03
    ICMP: 6.0.2.2 -> 6.0.2.6
      tos 0x00, ttl 64, length 84, checksum 0x47f1
      fragment id 0xe2b0, flags DONT_FRAGMENT
    ICMP echo_request checksum 0x245f
    00:11:32:956291: GigabitEthernet2/2/0-tx
    GigabitEthernet2/2/0 tx queue 0
    buffer 0x18db40: current data 0, length 102, free-list 0, 
           totlen-nifb 0, trace 0x9
    IP4: 00:50:56:b7:05:bd -> 00:55:56:b7:05:03
    ICMP: 6.0.2.2 -> 6.0.2.6
      tos 0x00, ttl 64, length 84, checksum 0x47f1
      fragment id 0xe2b0, flags DONT_FRAGMENT
    ICMP echo_request checksum 0x245f