Added some user documentation to sample plugin.
Change-Id: I518910f80499307e8fcac8dcef7baaeab5ea8e35
Signed-off-by: Ray Kinsella <ray.kinsella@intel.com>
@ref src/vppinfra | VPP core library
test | Unit tests
@ref src/vpp/api | Not-yet-relocated API bindings
-
+@ref src/examples | VPP example code
## Getting started
# These must be left-anchored paths for the regexp below to work.
DOXY_EXCLUDE ?= \
$(DOXY_SRC)/vlib/buffer.c \
- $(DOXY_SRC)/vpp-api/lua \
- $(DOXY_SRC)/examples/sample-plugin
+ $(DOXY_SRC)/vpp-api/lua
# Generate a regexp for filenames to exclude
DOXY_EXCLUDE_REGEXP = ($(subst .,\.,$(shell echo '$(strip $(DOXY_EXCLUDE))' | sed -e 's/ /|/g')))
- @subpage span_doc
- @subpage srv6_doc
- @subpage srmpls_doc
+- @subpage sample_plugin_doc
* See the License for the specific language governing permissions and
* limitations under the License.
*/
-/*
- *------------------------------------------------------------------
- * sample.c - simple MAC-swap API / debug CLI handling
- *------------------------------------------------------------------
+/**
+ * @file
+ * @brief Sample Plugin, plugin API / trace / CLI handling.
*/
#include <vnet/vnet.h>
};
/* *INDENT-ON* */
-/* Action function shared between message handler and debug CLI */
+/**
+ * @brief Enable/disable the macswap plugin.
+ *
+ * Action function shared between message handler and debug CLI.
+ */
int sample_macswap_enable_disable (sample_main_t * sm, u32 sw_if_index,
int enable_disable)
return 0;
}
+/**
+ * @brief CLI command to enable/disable the sample macswap plugin.
+ */
VLIB_CLI_COMMAND (sr_content_command, static) = {
.path = "sample macswap",
.short_help =
.function = macswap_enable_disable_command_fn,
};
-/* API message handler */
+/**
+ * @brief Plugin API message handler.
+ */
static void vl_api_sample_macswap_enable_disable_t_handler
(vl_api_sample_macswap_enable_disable_t * mp)
{
REPLY_MACRO(VL_API_SAMPLE_MACSWAP_ENABLE_DISABLE_REPLY);
}
-/* Set up the API message handling tables */
+/**
+ * @brief Set up the API message handling tables.
+ */
static clib_error_t *
sample_plugin_api_hookup (vlib_main_t *vm)
{
#undef _
}
+/**
+ * @brief Initialize the sample plugin.
+ */
static clib_error_t * sample_init (vlib_main_t * vm)
{
sample_main_t * sm = &sample_main;
VLIB_INIT_FUNCTION (sample_init);
+/**
+ * @brief Hook the sample plugin into the VPP graph hierarchy.
+ */
VNET_FEATURE_INIT (sample, static) =
{
.arc_name = "device-input",
--- /dev/null
+# Sample plugin for VPP {#sample_plugin_doc}
+
+## Overview
+
+This is the VPP sample plugin demonstrates how to create a new plugin that integrates
+with VPP. The sample code implements a trival macswap algorithim that demonstrates plugin
+runtime integration with the VPP graph hierachy, api and cli.
+
+For deeper dive information see the annotations in the sample code itself. See [sample.c](@ref sample.c)
+
+## How to build and run the sample plugin.
+
+Now (re)build VPP.
+
+ $ make wipe
+
+Define environmental variable 'VPP_WITH_SAMPLE_PLUGIN=yes' with a process scope
+
+ $ VPP_WITH_SAMPLE_PLUGIN=yes make build
+
+or a session scope, and build VPP.
+
+ $ export VPP_WITH_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: snat_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