From 6c1f56f08c30eb2ad5d734f9891f8b7f4ef9760d Mon Sep 17 00:00:00 2001
From: Dave Barach <dave@barachs.net>
Date: Fri, 22 Mar 2019 15:49:45 -0400
Subject: [PATCH] DOC-ONLY: improve multi-arch documentation

Document CLIB_MARCH_FN and CLIB_MARCH_FN_SELECT

Signed-off-by: Dave Barach <dave@barachs.net>
Change-Id: I661ba2af79db8205d70fa87203d40a2e31b795e4
---
 .../gettingstarted/developers/multiarch/arbfns.rst | 87 ++++++++++++++++++++++
 docs/gettingstarted/developers/multiarch/index.rst |  1 +
 2 files changed, 88 insertions(+)
 create mode 100644 docs/gettingstarted/developers/multiarch/arbfns.rst

diff --git a/docs/gettingstarted/developers/multiarch/arbfns.rst b/docs/gettingstarted/developers/multiarch/arbfns.rst
new file mode 100644
index 00000000000..d469bd8a140
--- /dev/null
+++ b/docs/gettingstarted/developers/multiarch/arbfns.rst
@@ -0,0 +1,87 @@
+Multi-Architecture Arbitrary Function Cookbook
+==============================================
+
+Optimizing arbitrary functions for multiple architectures is simple
+enough, and very similar to process used to produce multi-architecture
+graph node dispatch functions.
+
+As with multi-architecture graph nodes, we compile source files
+multiple times, generating multiple implementations of the original
+function, and a public selector function.
+
+Details
+-------
+
+Decorate function definitions with CLIB_MARCH_FN macros. For example:
+
+Change the original function prototype...
+
+::
+
+   u32 vlib_frame_alloc_to_node (vlib_main_t * vm, u32 to_node_index,
+                                 u32 frame_flags)
+
+...by recasting the function name and return type as the first two
+arguments to the CLIB_MARCH_FN macro:
+
+::
+
+    CLIB_MARCH_FN (vlib_frame_alloc_to_node, u32, vlib_main_t * vm,
+                   u32 to_node_index, u32 frame_flags)
+
+In the actual vpp image, several versions of vlib_frame_alloc_to_node
+will appear: vlib_frame_alloc_to_node_avx2,
+vlib_frame_alloc_to_node_avx512, and so forth.
+
+
+For each multi-architecture function, use the CLIB_MARCH_FN_SELECT
+macro to help generate the one-and-only multi-architecture selector
+function:
+
+::
+
+    #ifndef CLIB_MARCH_VARIANT
+    u32
+    vlib_frame_alloc_to_node (vlib_main_t * vm, u32 to_node_index,
+    			  u32 frame_flags)
+    {
+      return CLIB_MARCH_FN_SELECT (vlib_frame_alloc_to_node)
+        (vm, to_node_index, frame_flags);
+    }
+    #endif /* CLIB_MARCH_VARIANT */
+
+Once bound, the multi-architecture selector function is about as
+expensive as an indirect function call; which is to say: not very
+expensive.
+
+Modify CMakeLists.txt
+---------------------
+
+If the component in question already lists "MULTIARCH_SOURCES", simply
+add the indicated .c file to the list.  Otherwise, add as shown
+below. Note that the added file "new_multiarch_node.c" should appear in
+*both* SOURCES and MULTIARCH_SOURCES:
+
+::
+
+    add_vpp_plugin(myplugin
+      SOURCES
+      multiarch_code.c
+      ...
+
+      MULTIARCH_SOURCES
+      multiarch_code.c
+      ...
+     )
+
+A Word to the Wise
+------------------
+
+A file which liberally mixes functions worth compiling for multiple
+architectures and functions which are not will end up full of
+#ifndef CLIB_MARCH_VARIANT conditionals. This won't do a thing to make
+the code look any better.
+
+Depending on requirements, it may make sense to move functions to
+(new) files to reduce complexity and/or improve legibility of the
+resulting code.
diff --git a/docs/gettingstarted/developers/multiarch/index.rst b/docs/gettingstarted/developers/multiarch/index.rst
index 48065b8a8e2..a1dfe98bd62 100644
--- a/docs/gettingstarted/developers/multiarch/index.rst
+++ b/docs/gettingstarted/developers/multiarch/index.rst
@@ -9,3 +9,4 @@ This reference guide describes how to use the vpp muli-architecture support sche
    :maxdepth: 1
 
    nodefns
+   arbfns
-- 
2.16.6