diff options
| -rw-r--r-- | README.md | 2 | ||||
| -rw-r--r-- | doxygen/Makefile | 3 | ||||
| -rw-r--r-- | doxygen/user_doc.md | 1 | ||||
| -rw-r--r-- | src/examples/sample-plugin/sample/sample.c | 30 | ||||
| -rw-r--r-- | src/examples/sample-plugin/sample_plugin_doc.md | 66 |
5 files changed, 92 insertions, 10 deletions
@@ -45,7 +45,7 @@ Directory name | Description @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 diff --git a/doxygen/Makefile b/doxygen/Makefile index abaca185..b6ba5887 100644 --- a/doxygen/Makefile +++ b/doxygen/Makefile @@ -74,8 +74,7 @@ DOXY_INPUT := $(subst $(WS_ROOT)/,,$(DOXY_INPUT)) # 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'))) diff --git a/doxygen/user_doc.md b/doxygen/user_doc.md index becc2e0a..c0a05bd9 100644 --- a/doxygen/user_doc.md +++ b/doxygen/user_doc.md @@ -16,3 +16,4 @@ Several modules provide operational, dataplane-user focused documentation. - @subpage span_doc - @subpage srv6_doc - @subpage srmpls_doc +- @subpage sample_plugin_doc diff --git a/src/examples/sample-plugin/sample/sample.c b/src/examples/sample-plugin/sample/sample.c index 2f8ac4c9..3929ac23 100644 --- a/src/examples/sample-plugin/sample/sample.c +++ b/src/examples/sample-plugin/sample/sample.c @@ -12,10 +12,9 @@ * 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> @@ -65,7 +64,11 @@ VLIB_PLUGIN_REGISTER () = { }; /* *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) @@ -135,6 +138,9 @@ macswap_enable_disable_command_fn (vlib_main_t * vm, return 0; } +/** + * @brief CLI command to enable/disable the sample macswap plugin. + */ VLIB_CLI_COMMAND (sr_content_command, static) = { .path = "sample macswap", .short_help = @@ -142,7 +148,9 @@ VLIB_CLI_COMMAND (sr_content_command, static) = { .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) { @@ -156,7 +164,9 @@ static void vl_api_sample_macswap_enable_disable_t_handler 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) { @@ -188,6 +198,9 @@ setup_message_id_table (sample_main_t * sm, api_main_t *am) #undef _ } +/** + * @brief Initialize the sample plugin. + */ static clib_error_t * sample_init (vlib_main_t * vm) { sample_main_t * sm = &sample_main; @@ -214,6 +227,9 @@ static clib_error_t * sample_init (vlib_main_t * vm) VLIB_INIT_FUNCTION (sample_init); +/** + * @brief Hook the sample plugin into the VPP graph hierarchy. + */ VNET_FEATURE_INIT (sample, static) = { .arc_name = "device-input", 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 00000000..9348094c --- /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 |