From 583dc8d3e23a780c85ebe48ea59f0338aad4df17 Mon Sep 17 00:00:00 2001
From: Ray Kinsella <ray.kinsella@intel.com>
Date: Thu, 8 Jun 2017 15:54:19 +0100
Subject: Sample plugin: Add sample plugin documentation

Added some user documentation to sample plugin.

Change-Id: I518910f80499307e8fcac8dcef7baaeab5ea8e35
Signed-off-by: Ray Kinsella <ray.kinsella@intel.com>
---
 src/examples/sample-plugin/sample_plugin_doc.md | 66 +++++++++++++++++++++++++
 1 file changed, 66 insertions(+)
 create mode 100644 src/examples/sample-plugin/sample_plugin_doc.md

(limited to 'src/examples/sample-plugin/sample_plugin_doc.md')

diff --git a/src/examples/sample-plugin/sample_plugin_doc.md b/src/examples/sample-plugin/sample_plugin_doc.md
new file mode 100644
index 00000000000..9348094c210
--- /dev/null
+++ b/src/examples/sample-plugin/sample_plugin_doc.md
@@ -0,0 +1,66 @@
+# 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
-- 
cgit 1.2.3-korg