src/examples/sample-plugin/sample_plugin_doc.md

   1 # Sample plugin for VPP    {#sample_plugin_doc}
   2
   3 ## Overview
   4
   5 This is the VPP sample plugin demonstrates how to create a new plugin that integrates
   6 with VPP. The sample code implements a trival macswap algorithim that demonstrates plugin
   7 runtime integration with the VPP graph hierachy, api and cli.
   8
   9 For deeper dive information see the annotations in the  sample code itself. See [sample.c](@ref sample.c)
  10
  11 ## How to build and run the sample plugin.
  12
  13 Now (re)build VPP.
  14
  15         $ make wipe
  16
  17 Define environmental variable 'VPP_WITH_SAMPLE_PLUGIN=yes' with a process scope
  18
  19         $ VPP_WITH_SAMPLE_PLUGIN=yes make build
  20
  21 or a session scope, and build VPP.
  22
  23         $ export VPP_WITH_SAMPLE_PLUGIN=yes
  24         & make build
  25
  26 Now run VPP and make sure the plugin is loaded.
  27
  28         $ make run
  29         ...
  30         load_one_plugin:184: Loaded plugin: memif_plugin.so (Packet Memory Interface (experimetal))
  31         load_one_plugin:184: Loaded plugin: sample_plugin.so (Sample of VPP Plugin)
  32         load_one_plugin:184: Loaded plugin: nat_plugin.so (Network Address Translation)
  33         ...
  34         DBGvpp#
  35
  36 ## How to create a new plugin
  37
  38 To create a new plugin based on the sample plugin, copy and rename the sample plugin directory and automake config.
  39
  40         cp -r src/examples/sample-plugin/sample src/plugins/newplugin
  41         cp src/examples/sample-plugin/sample.am src/plugins/newplugin.am
  42
  43 Add the following entry to the plugins section of `src/configure.ac`.
  44
  45         PLUGIN_ENABLED(newplugin)
  46
  47 Add the following entry to the plugins section of `src/plugins/Makefile.am`
  48
  49         if ENABLE_NEWPLUGIN
  50         include newplugin.am
  51         endif
  52
  53 Now (re)build VPP.
  54
  55         $ make wipe
  56         $ make build
  57
  58 ## Configuration
  59
  60 To enable the sample plugin
  61
  62         sample macswap <interface name>
  63
  64 To disable the sample plugin
  65
  66         sample macswap <interface name> disable