diff options
Diffstat (limited to 'docs/gettingstarted/developers/add_plugin.rst')
| -rw-r--r-- | docs/gettingstarted/developers/add_plugin.rst | 362 |
1 files changed, 0 insertions, 362 deletions
diff --git a/docs/gettingstarted/developers/add_plugin.rst b/docs/gettingstarted/developers/add_plugin.rst deleted file mode 100644 index cf771116095..00000000000 --- a/docs/gettingstarted/developers/add_plugin.rst +++ /dev/null @@ -1,362 +0,0 @@ -.. _add_plugin: - -Adding a plugin -=============== - -.. toctree:: - -Strategic Choices -_________________ - -Plugins may implement lightly-used, experimental, or test -functionality. In such cases, please disable the plugin by default: - -.. code-block:: console - - /* *INDENT-OFF* */ - VLIB_PLUGIN_REGISTER () = - { - .version = VPP_BUILD_VER, - .description = "Plugin Disabled by Default...", - .default_disabled = 1, - }; - /* *INDENT-ON* */ - -Please do not create processes, or other dynamic data structures -unless the plugin is configured by API or debug CLI. - -Specifically, please don't initialize bihash tables from -VLIB_INIT_FUNCTIONS, *especially* if the bihash template involved -doesn't #define BIHASH_LAZY_INSTANTIATE 1. - -.. code-block:: console - - static clib_error_t * sample_init (vlib_main_t * vm) - { - <snip> - /* DONT DO THIS! */ - BV(clib_bihash_init (h, ...)) - <snip> - } - VLIB_INIT_FUNCTION (sample_init); - -Instead, please add a feature_init function: - -.. code-block:: console - - static void - feature_init (my_main_t * mm) - { - if (mm->feature_initialized == 0) - { - BV(clib_bihash_init)(mm->hash_table, ...) - /* Create Other Things, e.g a periodic process */ - mm->feature_initialized = 1; - } - } - -And call it from debug CLI and API message handlers any time the feature -is enabled. - -How to create a new plugin -__________________________ - -This section shows how a VPP developer can create a new plugin, and -add it to VPP. We assume that we are starting from the VPP <top-of-workspace>. - -As an example, we will use the **make-plugin.sh** tool found in -**./extras/emacs**. make-plugin.sh is a simple wrapper for a comprehensive -plugin generator constructed from a set of emacs-lisp skeletons. - -Change directory to **./src/plugins**, and run the plugin generator: - -.. code-block:: console - - $ cd ./src/plugins - $ ../../extras/emacs/make-plugin.sh - <snip> - Loading /scratch/vpp-docs/extras/emacs/tunnel-c-skel.el (source)... - Loading /scratch/vpp-docs/extras/emacs/tunnel-decap-skel.el (source)... - Loading /scratch/vpp-docs/extras/emacs/tunnel-encap-skel.el (source)... - Loading /scratch/vpp-docs/extras/emacs/tunnel-h-skel.el (source)... - Loading /scratch/vpp-docs/extras/emacs/elog-4-int-skel.el (source)... - Loading /scratch/vpp-docs/extras/emacs/elog-4-int-track-skel.el (source)... - Loading /scratch/vpp-docs/extras/emacs/elog-enum-skel.el (source)... - Loading /scratch/vpp-docs/extras/emacs/elog-one-datum-skel.el (source)... - Plugin name: myplugin - Dispatch type [dual or qs]: dual - (Shell command succeeded with no output) - - OK... - -The plugin generator script asks two questions: the name of the -plugin, and which of two dispatch types to use. Since the plugin name -finds its way into quite a number of places - filenames, typedef -names, graph arc names - it pays to think for a moment. - -The dispatch type refers to the coding pattern used to construct -**node.c**, the *pro forma* data-plane node. The **dual** option -constructs a dual-single loop pair with speculative enqueueing. This -is the traditional coding pattern for load-store intensive graph -nodes. - -The **qs** option generates a quad-single loop pair which uses -vlib_get_buffers(...) and vlib_buffer_enqueue_to_next(...). These -operators make excellent use of available SIMD vector unit -operations. It's very simple to change a quad-single loop-pair to a -dual-single loop pair if you decide to do so later. - -Generated Files ---------------- - -Here are the generated files. We'll go through them in a moment. - -.. code-block:: console - - $ cd ./myplugin - $ ls - CMakeLists.txt myplugin.api myplugin.c myplugin.h - myplugin_periodic.c myplugin_test.c node.c setup.pg - -Due to recent build system improvements, you **don't** need to touch -any other files to integrate your new plugin into the vpp build. Simply -rebuild your workspace from scratch, and the new plugin will appear. - -Rebuild your workspace ----------------------- - -This is the straightforward way to reconfigure and rebuild your workspace: - -.. code-block:: console - - $ cd <top-of-workspace> - $ make rebuild [or rebuild-release] - -Thanks to ccache, this operation doesn't take an annoying amount of time. - -Sanity check: run vpp ---------------------- - -As a quick sanity check, run vpp and make sure that -"myplugin_plugin.so" and "myplugin_test_plugin.so" are loaded: - -.. code-block:: console - - $ cd <top-of-workspace> - $ make run - <snip> - load_one_plugin:189: Loaded plugin: myplugin_plugin.so (myplugin description goes here) - <snip> - load_one_vat_plugin:67: Loaded plugin: myplugin_test_plugin.so - <snip> - DBGvpp# - -If this simple test fails, please seek assistance. - -Generated Files in Detail -_________________________ - -This section discusses the generated files in some detail. It's fine to -skim this section, and return later for more detail. - -CMakeLists.txt --------------- - -This is the build system recipe for building your plugin. Please fix -the copyright notice: - -.. code-block:: console - - # Copyright (c) <current-year> <your-organization> - -The rest of the build recipe is pretty simple: - -.. code-block:: CMake - - add_vpp_plugin (myplugin - SOURCES - myplugin.c - node.c - myplugin_periodic.c - myplugin.h - - MULTIARCH_SOURCES - node.c - - API_FILES - myplugin.api - - API_TEST_SOURCES - myplugin_test.c - ) - -As you can see, the build recipe consists of several lists of -files. **SOURCES** is a list of C source files. **API_FILES** is a -list of the plugin's binary API definition files [one such file is -usually plenty], and so forth. - -**MULTIARCH_SOURCES** lists data plane graph node dispatch function -source files considered to be performance-critical. Specific functions -in these files are compiled multiple times, so that they can leverage -CPU-specific features. More on this in a moment. - -If you add source files, simply add them to the indicated list(s). - -myplugin.h ----------- - -This is the primary #include file for the new plugin. Among other -things, it defines the plugin's *main_t* data structure. This is the -right place to add problem-specific data structures. Please **resist -the temptation** to create a set of static or [worse yet] global -variables in your plugin. Refereeing name-collisions between plugins -is not anyone's idea of a good time. - -myplugin.c ----------- - -For want of a better way to describe it, myplugin.c is the vpp plugin -equivalent of "main.c". Its job is to hook the plugin into the vpp -binary API message dispatcher, and to add its messages to vpp's global -"message-name_crc" hash table. See "myplugin_init (...")" - -Vpp itself uses dlsym(...) to track down the vlib_plugin_registration_t -generated by the VLIB_PLUGIN_REGISTER macro: - -.. code-block:: C - - VLIB_PLUGIN_REGISTER () = - { - .version = VPP_BUILD_VER, - .description = "myplugin plugin description goes here", - }; - -Vpp only loads .so files from the plugin directory which contain an -instance of this data structure. - -You can enable or disable specific vpp plugins from the command -line. By default, plugins are loaded. To change that behavior, set -default_disabled in the macro VLIB_PLUGIN_REGISTER: - -.. code-block:: C - - VLIB_PLUGIN_REGISTER () = - { - .version = VPP_BUILD_VER, - .default_disabled = 1 - .description = "myplugin plugin description goes here", - }; - -The boilerplate generator places the graph node dispatch function -onto the "device-input" feature arc. This may or may not be useful. - -.. code-block:: C - - VNET_FEATURE_INIT (myplugin, static) = - { - .arc_name = "device-input", - .node_name = "myplugin", - .runs_before = VNET_FEATURES ("ethernet-input"), - }; - -As given by the plugin generator, myplugin.c contains the binary API -message handler for a generic "please enable my feature on such and -such an interface" binary API message. As you'll see, setting up the -vpp message API tables is simple. Big fat warning: the scheme is -intolerant of minor mistakes. Example: forgetting to add -mainp->msg_id_base can lead to very confusing failures. - -If you stick to modifying the generated boilerplate with care - -instead of trying to build code from first principles - you'll save -yourself a bunch of time and aggravation - -myplugin_test.c ---------------- - -This file contains binary API message **generation** code, which is -compiled into a separate .so file. The "vpp_api_test" program loads -these plugins, yielding immediate access to your plugin APIs for -external client binary API testing. - -vpp itself loads test plugins, and makes the code available via the -"binary-api" debug CLI. This is a favorite way to unit-test binary -APIs prior to integration testing. - -node.c ------- - -This is the generated graph node dispatch function. You'll need to -rewrite it to solve the problem at hand. It will save considerable -time and aggravation to retain the **structure** of the node dispatch -function. - -Even for an expert, it's a waste of time to reinvent the *loop -structure*, enqueue patterns, and so forth. Simply tear out and -replace the specimen 1x, 2x, 4x packet processing code with code -relevant to the problem you're trying to solve. - -myplugin.api ------------- - -This contains the API message definition. Here we only have defined -a single one named ``myplugin_enable_disable`` and an implicit -``myplugin_enable_disable_reply`` containing only a return value due -to the ``autoreply`` keyword. - -The syntax reference for ``.api`` files can be found at VPP API Language - -Addressing the binary API with this message will run the handler defined -in ``myplugin.c`` as ``vl_api_myplugin_enable_disable_t_handler``. -It will receive a message pointer ``*mp`` which is the struct defined -in ``myplugin.api`` and should return another message pointer ``*rmp``, -of the reply type. That's what ``REPLY_MACRO`` does. - -To be noted, all API messages are in net-endian and vpp is host-endian, -so you will need to use : - -* ``u32 value = ntohl(mp->value);`` -* ``rmp->value = htonl(value);`` - -You can now use this API with :ref:`GoLang bindings <add_plugin_goapi>` - -myplugin_periodic.c -------------------- - -This defines a VPP process, a routine that will run indefinitely and -be woken up intermittently, here to process plugin events. - -To be noted, vlib_processes aren't thread-safe, and data structures -should be locked when shared between workers. - -Plugin "Friends with Benefits" ------------------------------- - -In vpp VLIB_INIT_FUNCTION functions, It's reasonably common to see a -specific init function invoke other init functions: - -.. code-block:: C - - if ((error = vlib_call_init_function (vm, some_other_init_function)) - return error; - -In the case where one plugin needs to call a init function in another -plugin, use the vlib_call_plugin_init_function macro: - -.. code-block:: C - - if ((error = vlib_call_plugin_init_function (vm, "otherpluginname", some_init_function)) - return error; - -This allows sequencing between plugin init functions. - -If you wish to obtain a pointer to a symbol in another plugin, use the -vlib_plugin_get_symbol(...) API: - -.. code-block:: C - - void *p = vlib_get_plugin_symbol ("plugin_name", "symbol"); - -More Examples -------------- - -For more information you can read many example plugins in the directory "./src/plugins". |