summaryrefslogtreecommitdiffstats
path: root/docs/gettingstarted
diff options
context:
space:
mode:
authorDave Barach <dave@barachs.net>2020-09-14 10:21:11 -0400
committerFlorin Coras <florin.coras@gmail.com>2020-09-16 03:43:07 +0000
commit331016abf55cee9772394bd890c71e3a64547df1 (patch)
tree3ea8f0923253fd454efad852b6027df4baddf1e3 /docs/gettingstarted
parent23c3d349e52e57600aaaf3ef32e4264fffb2d0db (diff)
docs: improve plugin developer's guide
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
Diffstat (limited to 'docs/gettingstarted')
-rw-r--r--docs/gettingstarted/developers/add_plugin.rst60
1 files changed, 55 insertions, 5 deletions
diff --git a/docs/gettingstarted/developers/add_plugin.rst b/docs/gettingstarted/developers/add_plugin.rst
index 19b935b746a..cf771116095 100644
--- a/docs/gettingstarted/developers/add_plugin.rst
+++ b/docs/gettingstarted/developers/add_plugin.rst
@@ -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