DOCS: Moved multiarch and build system, Incorprated Scott's changes

Change-Id: I5a57846db2d4faac1aa24db4629b612657f59afb
Signed-off-by: John DeNisco <jdenisco@cisco.com>

6 files changed, 1 insertions, 541 deletions

diff --git a/docs/reference/buildsystem/buildrootmakefile.rst b/docs/reference/buildsystem/buildrootmakefile.rst
deleted file mode 100644
index ef736220b25..00000000000
--- a/docs/reference/buildsystem/buildrootmakefile.rst
+++ /dev/null
@@ -1,353 +0,0 @@
-Introduction to build-root/Makefile
-===================================
-
-The vpp build system consists of a top-level Makefile, a data-driven
-build-root/Makefile, and a set of makefile fragments. The various parts
-come together as the result of a set of well-thought-out conventions.
-
-This section describes build-root/Makefile in some detail.
-
-Repository Groups and Source Paths
-----------------------------------
-
-Current vpp workspaces comprise a single repository group. The file
-.../build-root/build-config.mk defines a key variable called
-SOURCE\_PATH. The SOURCE\_PATH variable names the set of repository
-groups. At the moment, there is only one repository group.
-
-Single pass build system, dependencies and components
------------------------------------------------------
-
-The vpp build system caters to components built with GNU autoconf /
-automake. Adding such components is a simple process. Dealing with
-components which use BSD-style raw Makefiles is a more difficult.
-Dealing with toolchain components such as gcc, glibc, and binutils can
-be considerably more complicated.
-
-The vpp build system is a **single-pass** build system. A partial order
-must exist for any set of components: the set of (a before b) tuples
-must resolve to an ordered list. If you create a circular dependency of
-the form; (a,b) (b,c) (c,a), gmake will try to build the target list,
-but there’s a 0.0% chance that the results will be pleasant. Cut-n-paste
-mistakes in .../build-data/packages/.mk can produce confusing failures.
-
-In a single-pass build system, it’s best to separate libraries and
-applications which instantiate them. For example, if vpp depends on
-libfoo.a, and myapp depends on both vpp and libfoo.a, it's best to place
-libfoo.a and myapp in separate components. The build system will build
-libfoo.a, vpp, and then (as a separate component) myapp. If you try to
-build libfoo.a and myapp from the same component, it won’t work.
-
-If you absolutely, positively insist on having myapp and libfoo.a in the
-same source tree, you can create a pseudo-component in a separate .mk
-file in the .../build-data/packages/ directory. Define the code
-phoneycomponent\_source = realcomponent, and provide manual
-configure/build/install targets.
-
-Separate components for myapp, libfoo.a, and vpp is the best and easiest
-solution. However, the “mumble\_source = realsource” degree of freedom
-exists to solve intractable circular dependencies, such as: to build
-gcc-bootstrap, followed by glibc, followed by “real” gcc/g++ [which
-depends on glibc too].
-
-.../build-root
---------------
-
-The .../build-root directory contains the repository group specification
-build-config.mk, the main Makefile, and the system-wide set of
-autoconf/automake variable overrides in config.site. We'll describe
-these files in some detail. To be clear about expectations: the main
-Makefile and config.site file are subtle and complex. It's unlikely that
-you'll need or want to modify them. Poorly planned changes in either
-place typically cause bugs that are difficult to solve.
-
-.../build-root/build-config.mk
-------------------------------
-
-As described above, the build-config.mk file is straightforward: it sets
-the make variable SOURCE\_PATH to a list of repository group absolute
-paths.
-
-The SOURCE\_PATH variable If you choose to move a workspace, make sure
-to modify the paths defined by the SOURCE\_PATH variable. Those paths
-need to match changes you make in the workspace paths. For example, if
-you place the vpp directory in the workspace of a user named jsmith, you
-might change the SOURCE\_PATH to:
-
-SOURCE\_PATH = /home/jsmithuser/workspace/vpp
-
-The "out of the box" setting should work 99.5% of the time:
-
-::
-
-        SOURCE_PATH = $(CURDIR)/..
-
-.../vpp/build-root/Makefile
----------------------------
-
-The main Makefile is complex in a number of dimensions. If you think you
-need to modify it, it's a good idea to do some research, or ask for
-advice before you change it.
-
-The main Makefile was organized and designed to provide the following
-characteristics: excellent performance, accurate dependency processing,
-cache enablement, timestamp optimizations, git integration,
-extensibility, builds with cross-compilation tool chains, and builds
-with embedded Linux distributions.
-
-If you really need to do so, you can build double-cross tools with it,
-with a minimum amount of fuss. For example, you could: compile gdb on
-x86\_64, to run on PowerPC, to debug the Xtensa instruction set.
-
-The PLATFORM variable
----------------------
-
-The PLATFORM make/environment variable controls a number of important
-characteristics, primarily:
-
--  CPU architecture
--  The list of images to build.
-
-With respect to .../build-root/Makefile, the list of images to build is
-specified by the target. For example:
-
-::
-
-       make PLATFORM=vpp TAG=vpp_debug install-deb
-
-builds vpp debug Debian packages.
-
-The main Makefile interprets $PLATFORM by attempting to "-include" the
-file /build-data/platforms.mk:
-
-::
-
-        $(foreach d,$(FULL_SOURCE_PATH), \
-          $(eval -include $(d)/platforms.mk))
-
-By convention, we don't define **platforms** in the
-...//build-data/platforms.mk file.
-
-In the vpp case, we search for platform definition makefile fragments in
-.../vpp/build-data/platforms.mk, as follows:
-
-::
-
-        $(foreach d,$(SOURCE_PATH_BUILD_DATA_DIRS), \
-             $(eval -include $(d)/platforms/*.mk))
-
-With vpp, which uses the "vpp" platform as discussed above, we end up
-"-include"-ing .../vpp/build-data/platforms/vpp.mk.
-
-The platform-specific .mk fragment
-----------------------------------
-
-Here are the contents of .../build-data/platforms/vpp.mk:
-
-::
-
-        MACHINE=$(shell uname -m)
-     
-        vpp_arch = native
-        ifeq ($(TARGET_PLATFORM),thunderx)
-        vpp_dpdk_target = arm64-thunderx-linuxapp-gcc
-        endif
-        vpp_native_tools = vppapigen
-     
-        vpp_uses_dpdk = yes
-     
-        # Uncoment to enable building unit tests
-        # vpp_enable_tests = yes
-     
-        vpp_root_packages = vpp vom japi
-     
-        # DPDK configuration parameters
-        # vpp_uses_dpdk_mlx4_pmd = yes
-        # vpp_uses_dpdk_mlx5_pmd = yes
-        # vpp_uses_external_dpdk = yes
-        # vpp_dpdk_inc_dir = /usr/include/dpdk
-        # vpp_dpdk_lib_dir = /usr/lib
-        # vpp_dpdk_shared_lib = yes
-     
-        # Use '--without-libnuma' for non-numa aware architecture
-        # Use '--enable-dlmalloc' to use dlmalloc instead of mheap
-        vpp_configure_args_vpp = --enable-dlmalloc
-        sample-plugin_configure_args_vpp = --enable-dlmalloc
-     
-        # load balancer plugin is not portable on 32 bit platform
-        ifeq ($(MACHINE),i686)
-        vpp_configure_args_vpp += --disable-lb-plugin
-        endif
-     
-        vpp_debug_TAG_CFLAGS = -g -O0 -DCLIB_DEBUG -DFORTIFY_SOURCE=2 \
-            -fstack-protector-all -fPIC -Werror
-        vpp_debug_TAG_CXXFLAGS = -g -O0 -DCLIB_DEBUG -DFORTIFY_SOURCE=2 \
-            -fstack-protector-all -fPIC -Werror
-        vpp_debug_TAG_LDFLAGS = -g -O0 -DCLIB_DEBUG -DFORTIFY_SOURCE=2 \
-            -fstack-protector-all -fPIC -Werror
-
-        vpp_TAG_CFLAGS = -g -O2 -DFORTIFY_SOURCE=2 -fstack-protector -fPIC -Werror
-        vpp_TAG_CXXFLAGS = -g -O2 -DFORTIFY_SOURCE=2 -fstack-protector -fPIC -Werror
-        vpp_TAG_LDFLAGS = -g -O2 -DFORTIFY_SOURCE=2 -fstack-protector -fPIC -Werror -pie -Wl,-z,now
-
-        vpp_clang_TAG_CFLAGS = -g -O2 -DFORTIFY_SOURCE=2 -fstack-protector -fPIC -Werror
-        vpp_clang_TAG_LDFLAGS = -g -O2 -DFORTIFY_SOURCE=2 -fstack-protector -fPIC -Werror
-
-        vpp_gcov_TAG_CFLAGS = -g -O0 -DCLIB_DEBUG -fPIC -Werror -fprofile-arcs -ftest-coverage
-        vpp_gcov_TAG_LDFLAGS = -g -O0 -DCLIB_DEBUG -fPIC -Werror -coverage
-
-        vpp_coverity_TAG_CFLAGS = -g -O2 -fPIC -Werror -D__COVERITY__
-        vpp_coverity_TAG_LDFLAGS = -g -O2 -fPIC -Werror -D__COVERITY__
-
-Note the following variable settings:
-
--  The variable \_arch sets the CPU architecture used to build the
-   per-platform cross-compilation toolchain. With the exception of the
-   "native" architecture - used in our example - the vpp build system
-   produces cross-compiled binaries.
-
--  The variable \_native\_tools lists the required set of self-compiled
-   build tools.
-
--  The variable \_root\_packages lists the set of images to build when
-   specifying the target: make PLATFORM= TAG= [install-deb \|
-   install-rpm].
-
-The TAG variable
-----------------
-
-The TAG variable indirectly sets CFLAGS and LDFLAGS, as well as the
-build and install directory names in the .../vpp/build-root directory.
-See definitions above.
-
-Important targets build-root/Makefile
--------------------------------------
-
-The main Makefile and the various makefile fragments implement the
-following user-visible targets:
-
-+------------------+----------------------+--------------------------------------------------------------------------------------+
-| Target           | ENV Variable Settings| Notes                                                                                |
-|                  |                      |                                                                                      |
-+==================+======================+======================================================================================+
-| foo              |      bar             | mumble                                                                               |
-+------------------+----------------------+--------------------------------------------------------------------------------------+
-| bootstrap-tools  | none                 |  Builds the set of native tools needed by the vpp build system to                    |
-|                  |                      |  build images. Example: vppapigen. In a full cross compilation case might include    |
-|                  |                      |  include "make", "git", "find", and "tar                                             |  
-+------------------+----------------------+--------------------------------------------------------------------------------------+  
-| install-tools    | PLATFORM             | Builds the tool chain for the indicated <platform>. Not used in vpp builds           |
-+------------------+----------------------+--------------------------------------------------------------------------------------+  
-| distclean        | none                 | Roto-rooters everything in sight: toolchains, images, and so forth.                  |
-+------------------+----------------------+--------------------------------------------------------------------------------------+  
-| install-deb      | PLATFORM and TAG     | Build Debian packages comprising components listed in <platform>_root_packages,      |
-|                  |                      | using compile / link options defined by TAG.                                         |
-+------------------+----------------------+--------------------------------------------------------------------------------------+  
-| install-rpm      | PLATFORM and TAG     | Build RPMs comprising components listed in <platform>_root_packages,                 |
-|                  |                      | using compile / link options defined by TAG.                                         |
-+------------------+----------------------+--------------------------------------------------------------------------------------+  
-
-Additional build-root/Makefile environment variable settings
-------------------------------------------------------------
-
-These variable settings may be of use:
-
-+----------------------+------------------------------------------------------------------------------------------------------------+
-| ENV Variable         | Notes                                                                                                      |
-+======================+======================+=====================================================================================+
-| BUILD_DEBUG=vx       | Directs Makefile et al. to make a good-faith effort to show what's going on in excruciating detail.        |
-|                      | Use it as follows: "make ... BUILD_DEBUG=vx". Fairly effective in Makefile debug situations.               |
-+----------------------+------------------------------------------------------------------------------------------------------------+  
-| V=1                  | print detailed cc / ld command lines. Useful for discovering if -DFOO=11 is in the command line or not     |
-+----------------------+------------------------------------------------------------------------------------------------------------+  
-| CC=mygcc             | Override the configured C-compiler                                                                         |
-+----------------------+------------------------------------------------------------------------------------------------------------+  
-
-.../build-root/config.site
---------------------------
-
-The contents of .../build-root/config.site override individual autoconf /
-automake default variable settings. Here are a few sample settings related to
-building a full toolchain:
-
-::
-
-    # glibc needs these setting for cross compiling 
-    libc_cv_forced_unwind=yes
-    libc_cv_c_cleanup=yes
-    libc_cv_ssp=no
-
-Determining the set of variables which need to be overridden, and the
-override values is a matter of trial and error. It should be
-unnecessary to modify this file for use with fd.io vpp.
-
-.../build-data/platforms.mk
----------------------------
-
-Each repo group includes the platforms.mk file, which is included by
-the main Makefile. The vpp/build-data/platforms.mk file is not terribly
-complex. As of this writing, .../build-data/platforms.mk file accomplishes two
-tasks.
-
-First, it includes vpp/build-data/platforms/\*.mk:
-
-::
-
-    # Pick up per-platform makefile fragments
-    $(foreach d,$(SOURCE_PATH_BUILD_DATA_DIRS),	\
-      $(eval -include $(d)/platforms/*.mk))
-
-This collects the set of platform definition makefile fragments, as discussed above.
-
-Second, platforms.mk implements the user-visible "install-deb" target.
-
-.../build-data/packages/\*.mk
------------------------------
-
-Each component needs a makefile fragment in order for the build system
-to recognize it. The per-component makefile fragments vary
-considerably in complexity. For a component built with GNU autoconf /
-automake which does not depend on other components, the make fragment
-can be empty. See .../build-data/packages/vpp.mk for an uncomplicated
-but fully realistic example.
-
-Here are some of the important variable settings in per-component makefile fragments:
-
-+----------------------+------------------------------------------------------------------------------------------------------------+
-| Variable             | Notes                                                                                                      |
-+======================+======================+=====================================================================================+
-| xxx_configure_depend |  Lists the set of component build dependencies for the xxx component. In plain English: don't try to       |
-|                      |  configure this component until you've successfully built the indicated targets. Almost always,            |
-|                      |  xxx_configure_depend will list a set of "yyy-install" targets. Note the pattern:                          |
-|                      |  "variable names contain underscores, make target names contain hyphens"                                   |
-+----------------------+------------------------------------------------------------------------------------------------------------+  
-| xxx_configure_args   | (optional) Lists any additional arguments to pass to the xxx component "configure" script.                 |
-|                      | The main Makefile %-configure rule adds the required settings for --libdir, --prefix, and                  |
-|                      | --host (when cross-compiling)                                                                              |
-+----------------------+------------------------------------------------------------------------------------------------------------+  
-| xxx_CPPFLAGS         | Adds -I stanzas to CPPFLAGS for components upon which xxx depends.                                         |
-|                      | Almost invariably "xxx_CPPFLAGS = $(call installed_includes_fn, dep1 dep2 dep3)", where dep1, dep2, and    |
-|                      | dep3 are listed in xxx_configure_depend. It is bad practice to set "-g -O3" here. Those settings           |
-|                      | belong in a TAG.                                                                                           |
-+----------------------+------------------------------------------------------------------------------------------------------------+  
-| xxx_LDFLAGS          | Adds -Wl,-rpath -Wl,depN stanzas to LDFLAGS for components upon which xxx depends.                         |
-|                      | Almost invariably "xxx_LDFLAGS = $(call installed_lib_fn, dep1 dep2 dep3)", where dep1, dep2, and          |
-|                      | dep3 are listed in xxx_configure_depend. It is bad manners to set "-liberty-or-death" here.                |
-|                      | Those settings belong in Makefile.am.                                                                      |
-+----------------------+------------------------------------------------------------------------------------------------------------+  
-
-When dealing with "irritating" components built with raw Makefiles
-which only work when building in the source tree, we use a specific
-strategy in the xxx.mk file. 
-
-The strategy is simple for those components: We copy the source tree
-into .../vpp/build-root/build-xxx. This works, but completely defeats
-dependency processing. This strategy is acceptable only for 3rd party
-software which won't need extensive (or preferably any) modifications.
-
-Take a look at .../vpp/build-data/packages/dpdk.mk. When invoked, the
-dpdk_configure variable copies source code into $(PACKAGE_BUILD_DIR),
-and performs the BSD equivalent of "autoreconf -i -f" to configure the
-build area. The rest of the file is similar: a bunch of hand-rolled
-glue code which manages to make the dpdk act like a good vpp build
-citizen even though it is not. 
diff --git a/docs/reference/buildsystem/index.rst b/docs/reference/buildsystem/index.rst
deleted file mode 100644
index f7c512e255a..00000000000
--- a/docs/reference/buildsystem/index.rst
+++ /dev/null
@@ -1,11 +0,0 @@
-.. _buildsystem:
-
-Build System
-============
-
-This reference guide describes the vpp build system in detail
-
-.. toctree::
-
-    mainmakefile
-    buildrootmakefile
diff --git a/docs/reference/buildsystem/mainmakefile.md b/docs/reference/buildsystem/mainmakefile.md
deleted file mode 100644
index ddf0661942f..00000000000
--- a/docs/reference/buildsystem/mainmakefile.md
+++ /dev/null
@@ -1,3 +0,0 @@
-Introduction to the top-level Makefile
-======================================
-
diff --git a/docs/reference/index.rst b/docs/reference/index.rst
index 48b5170d69c..23ddecdc280 100644
--- a/docs/reference/index.rst
+++ b/docs/reference/index.rst
@@ -7,9 +7,7 @@ Reference
 .. toctree::
    :maxdepth: 2
 
+   vppvagrant/index.rst
    readthedocs/index.rst
    github/index.rst
-   vppvagrant/index.rst
-   buildsystem/index.rst
-   multiarch/index.rst
    cmdreference/index.rst
diff --git a/docs/reference/multiarch/index.rst b/docs/reference/multiarch/index.rst
deleted file mode 100644
index 48065b8a8e2..00000000000
--- a/docs/reference/multiarch/index.rst
+++ /dev/null
@@ -1,11 +0,0 @@
-.. _multiarch:
-
-Multi-architecture support
-==========================
-
-This reference guide describes how to use the vpp muli-architecture support scheme
-
-.. toctree::
-   :maxdepth: 1
-
-   nodefns
diff --git a/docs/reference/multiarch/nodefns.rst b/docs/reference/multiarch/nodefns.rst
deleted file mode 100644
index ad68385d6c5..00000000000
--- a/docs/reference/multiarch/nodefns.rst
+++ /dev/null
@@ -1,160 +0,0 @@
-Multi-Architecture Graph Node Cookbook
-======================================
-
-In the context of graph node dispatch functions, it's easy enough to
-use the vpp multi-architecture support setup. The point of the scheme
-is simple: for performance-critical nodes, generate multiple CPU
-hardware-dependent versions of the node dispatch functions, and pick
-the best one at runtime.
-
-The vpp scheme is simple enough to use, but details matter.
-
-100,000 foot view
------------------
-
-We compile entire graph node dispatch function implementation files
-multiple times. These compilations give rise to multiple versions of
-the graph node dispatch functions. Per-node constructor-functions
-interrogate CPU hardware, select the node dispatch function variant to
-use, and set the vlib_node_registration_t ".function" member to the
-address of the selected variant.
-
-Details
--------
-
-Declare the node dispatch function as shown, using the VLIB\_NODE\_FN macro. The
-name of the node function **MUST** match the name of the graph node. 
-
-:: 
-
-    VLIB_NODE_FN (ip4_sdp_node) (vlib_main_t * vm, vlib_node_runtime_t * node,
-                                 vlib_frame_t * frame)
-    {
-      if (PREDICT_FALSE (node->flags & VLIB_NODE_FLAG_TRACE))
-        return ip46_sdp_inline (vm, node, frame, 1 /* is_ip4 */ ,
-    			    1 /* is_trace */ );
-      else
-        return ip46_sdp_inline (vm, node, frame, 1 /* is_ip4 */ ,
-    			    0 /* is_trace */ );
-    }   
-
-We need to generate *precisely one copy* of the
-vlib_node_registration_t, error strings, and packet trace decode function.
-
-Simply bracket these items with "#ifndef CLIB_MARCH_VARIANT...#endif":
-
-::
-
-    #ifndef CLIB_MARCH_VARIANT
-    static u8 *
-    format_sdp_trace (u8 * s, va_list * args)
-    {
-       <snip>
-    }
-    #endif
-
-    ...
-
-    #ifndef CLIB_MARCH_VARIANT
-    static char *sdp_error_strings[] = {
-    #define _(sym,string) string,
-      foreach_sdp_error
-    #undef _
-    };
-    #endif
-
-    ...
-
-    #ifndef CLIB_MARCH_VARIANT
-    VLIB_REGISTER_NODE (ip4_sdp_node) =
-    {
-      // DO NOT set the .function structure member.
-      // The multiarch selection __attribute__((constructor)) function
-      // takes care of it at runtime
-      .name = "ip4-sdp",
-      .vector_size = sizeof (u32),
-      .format_trace = format_sdp_trace,
-      .type = VLIB_NODE_TYPE_INTERNAL,
-
-      .n_errors = ARRAY_LEN(sdp_error_strings),
-      .error_strings = sdp_error_strings,
-
-      .n_next_nodes = SDP_N_NEXT,
-
-      /* edit / add dispositions here */
-      .next_nodes =
-      {
-        [SDP_NEXT_DROP] = "ip4-drop",
-      },
-    };
-    #endif
-
-To belabor the point: *do not* set the ".function" member! That's the job of the multi-arch
-selection \_\_attribute\_\_((constructor)) function
-
-Always inline node dispatch functions
--------------------------------------
-
-It's typical for a graph dispatch function to contain one or more
-calls to an inline function. See above. If your node dispatch function
-is structured that way, make *ABSOLUTELY CERTAIN* to use the
-"always_inline" macro:
-
-::
-
-    always_inline uword
-    ip46_sdp_inline (vlib_main_t * vm, vlib_node_runtime_t * node, 
-                 vlib_frame_t * frame,
-    		 int is_ip4, int is_trace)
-    { ... }
-
-Otherwise, the compiler is highly likely NOT to build multiple
-versions of the guts of your dispatch function. 
-
-It's fairly easy to spot this mistake in "perf top." If you see, for
-example, a bunch of functions with names of the form
-"xxx_node_fn_avx2" in the profile, *BUT* your brand-new node function
-shows up with a name of the form "xxx_inline.isra.1", it's quite likely
-that the inline was declared "static inline" instead of "always_inline".
-
-Add the required Makefile.am content
-------------------------------------
-
-If the component in question already sets a "multiversioning_sources"
-variable, simply add the indicated .c file to the list. If not, add
-the required boilerplate:
-
-::
-
-    if CPU_X86_64
-    sdp_multiversioning_sources =			\
-    	sdp/node.c				\
-    	sdp/sdp_slookup.c
-
-    if CC_SUPPORTS_AVX2
-    ###############################################################
-    # AVX2
-    ###############################################################
-    libsdp_plugin_avx2_la_SOURCES = $(sdp_multiversioning_sources)
-    libsdp_plugin_avx2_la_CFLAGS =					\
-    	$(AM_CFLAGS)  @CPU_AVX2_FLAGS@				\
-    	-DCLIB_MARCH_VARIANT=avx2
-    noinst_LTLIBRARIES += libsdp_plugin_avx2.la
-    sdp_plugin_la_LIBADD += libsdp_plugin_avx2.la
-    endif
-
-    if CC_SUPPORTS_AVX512
-    ###############################################################
-    # AVX512
-    ###############################################################
-    libsdp_plugin_avx512_la_SOURCES = $(sdp_multiversioning_sources)
-    libsdp_plugin_avx512_la_CFLAGS =				\
-    	$(AM_CFLAGS) @CPU_AVX512_FLAGS@				\
-    	-DCLIB_MARCH_VARIANT=avx512
-    noinst_LTLIBRARIES += libsdp_plugin_avx512.la
-    sdp_plugin_la_LIBADD += libsdp_plugin_avx512.la
-    endif
-    endif
-
-A certain amount of cut-paste-modify is currently required. Hopefully
-we'll manage to improve the scheme in the future.