From 331016abf55cee9772394bd890c71e3a64547df1 Mon Sep 17 00:00:00 2001
From: Dave Barach <dave@barachs.net>
Date: Mon, 14 Sep 2020 10:21:11 -0400
Subject: 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
---
 docs/gettingstarted/developers/add_plugin.rst | 60 ++++++++++++++++++++++++---
 1 file changed, 55 insertions(+), 5 deletions(-)

(limited to 'docs')

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
-- 
cgit 1.2.3-korg