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
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
|
.. _sample_plugin:
Integrating a plugin
=====================
.. toctree::
Overview
________
This section shows how a VPP plugin developer can modify VPP scripts to add and load their plugin as a node in VPP.
As an example we will integrate the **Sample Plugin** found in *vpp/src/examples/sample-plugin/sample* The VPP Sample Plugin is a small plugin that demonstrates simple implementation of a macswap algorithim. Since it is a VPP plugin, it has runtime integration with the VPP graph hierachy, API, and CLI.
This section will not go into the details of the plugin itself. For a deeper dive into the sample plugin see the annotations in `sample.c <https://docs.fd.io/vpp/18.11/da/d30/sample_8c.html>`_, or go to the next page for general VPP C API usage.
Setup
_____
Each plugin has their own automake file (\*.am) used by *configure.ac*, as well as a separate directory containing C files for the plugin. The directory containing these for each plugin is *vpp/src/plugins*
To get a basic idea for how a VPP automake plugin file specifies its C files, here is part of the Sample Plugin automake file, *sample.am*
.. code-block:: console
sample_plugin_la_SOURCES = \
sample/sample.c \
sample/node.c \
sample/sample_plugin.api.h
API_FILES += sample/sample.api
nobase_apiinclude_HEADERS += \
sample/sample_all_api_h.h \
sample/sample_msg_enum.h \
sample/sample.api.h
The Sample Plugin is located in *vpp/src/examples/sample-plugin/sample*, so as mentioned above we will need to copy its contents into *vpp/src/plugins*
In your */vpp* directory, or the directory above */src*, run:
.. code-block:: console
$ cp -r src/examples/sample-plugin/sample src/plugins
$ cp src/examples/sample-plugin/sample.am src/plugins
Modifying configure.ac and Makefile.am
______________________________________
We now need to modify the plugin sections of the VPP automake and configuration scripts so that VPP builds correctly with your new plugin.
Using a text editor such as *vi*, add the following entry to the plugins section in *vpp/src/configure.ac*
.. code-block:: console
PLUGIN_ENABLED(sample)
For reference, the plugins section of that file looks like this:
.. code-block:: console
###############################################################################
# Plugins
###############################################################################
# Please keep alphabetical order
PLUGIN_ENABLED(abf)
PLUGIN_ENABLED(acl)
PLUGIN_ENABLED(avf)
PLUGIN_ENABLED(cdp)
PLUGIN_ENABLED(dpdk)
PLUGIN_ENABLED(flowprobe)
Using a text editor such as *vi*, now add the following entry to the plugins section in *vpp/src/plugins/Makefile.am*
.. code-block:: console
if ENABLE_SAMPLE_PLUGIN
include sample.am
endif
For reference, the plugins section of that file looks something like this:
.. code-block:: console
vppapitestpluginsdir = ${libdir}/vpp_api_test_plugins
vpppluginsdir = ${libdir}/vpp_plugins
if ENABLE_ABF_PLUGIN
include abf.am
endif
if ENABLE_ACL_PLUGIN
include acl.am
endif
if ENABLE_AVF_PLUGIN
include avf.am
endif
Building and Running
____________________
Build VPP by using the main Makefile found in */vpp/Makefile*
.. code-block:: console
$ make build
.. note::
If you want to have a fresh debug build and compile every VPP file from scratch, you can wipe all compiled files and build VPP with:
.. code-block:: console
$ make rebuild
However this will take much longer than just running *make build*
Run VPP and make sure the plugin is loaded. Below is the command for running the VPP debug binary, accompanied with sample output.
.. code-block:: console
$ make run
vlib_plugin_early_init:361: plugin path /vpp/build-root/install-vpp_debug-native/vpp/lib/vpp_plugins:/vpp/build-root/install-vpp_debug-native/vpp/lib64/vpp_plugins
load_one_plugin:189: Loaded plugin: abf_plugin.so (ACL based Forwarding)
load_one_plugin:189: Loaded plugin: acl_plugin.so (Access Control Lists)
load_one_plugin:189: Loaded plugin: avf_plugin.so (Intel Adaptive Virtual Function (AVF) Device Plugin)
load_one_plugin:191: Loaded plugin: cdp_plugin.so
...
load_one_plugin:189: Loaded plugin: sample_plugin.so (Sample of VPP Plugin)
...
load_one_vat_plugin:67: Loaded plugin: avf_test_plugin.so
load_one_vat_plugin:67: Loaded plugin: mactime_test_plugin.so
load_one_vat_plugin:67: Loaded plugin: sample_test_plugin.so
...
_______ _ _ _____ ___
__/ __/ _ \ (_)__ | | / / _ \/ _ \
_/ _// // / / / _ \ | |/ / ___/ ___/
/_/ /____(_)_/\___/ |___/_/ /_/
DBGvpp#
.. note::
Notice when running the debug build that (\*_test_plugin.so) is also loaded, which is meant for testing your plugin.
To enable the sample plugin, use this command:
.. code-block:: console
DBGvpp# sample macswap <interface name>
To disable the sample plugin, use this command:
.. code-block:: console
DBGvpp# sample macswap <interface name> disable
Great! Now you've successfully added your plugin as a VPP node.
Additional remarks
__________________
How the build process works for plugins is that the (\*.api) plugin file is automatically translated to a JSON file (\*.api.json) in *vpp/build-root/install-vpp_debug-native/vpp/share/vpp/api/plugins*, which the code generator then parses and generates a C header file (\*.api.h) in *vpp/build-root/install-vpp_debug-native/vpp/include/vpp_plugins/\**.
After the build process is completed you finally end up with two plugin files (\*_plugin.so and \*_test_plugin.so) found in *vpp/build-root/install-vpp_debug-native/vpp/lib64/vpp_plugins* and *vpp/build-root/install-vpp_debug-native/vpp/lib64/vpp_api_test_plugins* respectively, that are loaded at runtime during a debug binary run of VPP (*make run*).
|
