ligang/vpp
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: improve plugin developer's guide

Browse Source 
Topics added: disabling lightly-used, experimental, or test plugins
by default. Discourage folks from creating bihash tables, processes
etc. from VLIB_INIT_FUNCTIONs.

Type: docs

Signed-off-by: Dave Barach <dave@barachs.net>
Change-Id: I1235d64971e9ed50f992b75f96b77c934168276a
This commit is contained in:
Dave Barach
2020-09-14 10:21:11 -04:00
committed by Florin Coras
parent 23c3d349e5
commit 331016abf5
1 changed files with 55 additions and 5 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

60
docs/gettingstarted/developers/add_plugin.rst
View File

@ -5,8 +5,61 @@ Adding a plugin
.. toctree::
Overview
________
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>.
@ -15,9 +68,6 @@ 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.
Create your new plugin
----------------------
Change directory to **./src/plugins**, and run the plugin generator:
.. code-block:: console