From 8fa01c17aa65c03b1f25f9accaa5bb0f9d0862c4 Mon Sep 17 00:00:00 2001
From: Dave Barach <dave@barachs.net>
Date: Thu, 16 May 2019 12:16:29 -0400
Subject: DOC ONLY: document VLIB_INIT_FUNCTION scheme

Change-Id: I15c4256621da6c8d47b1a7c41755ee6587996757
Signed-off-by: Dave Barach <dave@barachs.net>
---
 docs/gettingstarted/developers/vlib.md | 53 +++++++++++++++++++++++++++++++---
 1 file changed, 49 insertions(+), 4 deletions(-)

(limited to 'docs')

diff --git a/docs/gettingstarted/developers/vlib.md b/docs/gettingstarted/developers/vlib.md
index f25b0bab54b..462168618b2 100644
--- a/docs/gettingstarted/developers/vlib.md
+++ b/docs/gettingstarted/developers/vlib.md
@@ -15,10 +15,11 @@ Init function discovery
 vlib applications register for various \[initialization\] events by
 placing structures and \_\_attribute\_\_((constructor)) functions into
 the image. At appropriate times, the vlib framework walks
-constructor-generated singly-linked structure lists, calling the
-indicated functions. vlib applications create graph nodes, add CLI
-functions, start cooperative multi-tasking threads, etc. etc. using this
-mechanism.
+constructor-generated singly-linked structure lists, performs a
+topological sort based on specified constraints, and calls the
+indicated functions. Vlib applications create graph nodes, add CLI
+functions, start cooperative multi-tasking threads, etc. etc. using
+this mechanism.
 
 vlib applications invariably include a number of VLIB\_INIT\_FUNCTION
 (my\_init\_function) macros.
@@ -32,6 +33,50 @@ other libraries such as VNET. In the latter case, it may be necessary to
 explicitly reference symbol(s) otherwise large portions of the library
 may be AWOL at runtime.
 
+### Init function construction and constraint specification
+
+It's easy to add an init function:
+
+```
+   static clib_error_t *my_init_function (vlib_main_t *vm)
+   {
+      /* ... initialize things ... */
+
+      return 0; // or return clib_error_return (0, "BROKEN!");
+   }
+   VLIB_INIT_FUNCTION(my_init_function);
+```
+
+As given, my_init_function will be executed "at some point," but with
+no ordering guarantees.
+
+Specifying ordering constraints is easy:
+
+```
+   VLIB_INIT_FUNCTION(my_init_function) =
+   {
+      .runs_before = VLIB_INITS("we_run_before_function_1",
+                                "we_run_before_function_2"),
+      .runs_after = VLIB_INITS("we_run_after_function_1",
+                               "we_run_after_function_2),
+    };
+```
+
+It's also easy to specify bulk ordering constraints of the form "a
+then b then c then d":
+
+```
+   VLIB_INIT_FUNCTION(my_init_function) =
+   {
+      .init_order = VLIB_INITS("a", "b", "c", "d"),
+   };
+```
+
+It's OK to specify all three sorts of ordering constraints for a
+single init function, although it's hard to imagine why it would be
+necessary.
+
+
 Node Graph Initialization
 -------------------------
 
-- 
cgit 1.2.3-korg