src/examples/sample-plugin/sample_plugin_doc.rst


1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97

.. _sample_plugin_doc:

Sample plugin for VPP
=====================

Overview
--------

This is the VPP sample plugin demonstrates how to create a new plugin
that integrates with VPP. The sample code implements a trivial macswap
algorithm that demonstrates plugin runtime integration with the VPP
graph hierarchy, api and cli.

For deeper dive information see the annotations in the sample code
itself. See `sample.c <@ref%20sample.c>`__

How to build and run the sample plugin.
---------------------------------------

Now (re)build VPP.

::

   $ make wipe

Define environmental variable ‘SAMPLE_PLUGIN=yes’ with a process scope

::

   $ SAMPLE_PLUGIN=yes make build

or a session scope, and build VPP.

::

   $ export SAMPLE_PLUGIN=yes
   $ make build

Now run VPP and make sure the plugin is loaded.

::

   $ make run
   ...
   load_one_plugin:184: Loaded plugin: memif_plugin.so (Packet Memory Interface (experimetal))
   load_one_plugin:184: Loaded plugin: sample_plugin.so (Sample of VPP Plugin)
   load_one_plugin:184: Loaded plugin: nat_plugin.so (Network Address Translation)
   ...
   DBGvpp#

How to create a new plugin
--------------------------

To create a new plugin based on the sample plugin, copy and rename the
sample plugin directory and automake config.

::

   cp -r src/examples/sample-plugin/sample src/plugins/newplugin
   cp src/examples/sample-plugin/sample.am src/plugins/newplugin.am

Add the following entry to the plugins section of ``src/configure.ac``.

::

   PLUGIN_ENABLED(newplugin)

Add the following entry to the plugins section of
``src/plugins/Makefile.am``

::

   if ENABLE_NEWPLUGIN
   include newplugin.am
   endif

Now (re)build VPP.

::

   $ make wipe
   $ make build

Configuration
-------------

To enable the sample plugin

::

   sample macswap <interface name>

To disable the sample plugin

::

   sample macswap <interface name> disable