Topics

[RFC PATCH 01/11] ovs-bpf: add documentation and configuration.

William Tu
 

From: Joe Stringer <joe@...>

The patch add bpf installation guide and configuration
for linking to libbpf library.

Co-authored-by: William Tu <u9012063@...>
Co-authored-by: Yifeng Sun <pkusunyifeng@...>
---
Documentation/automake.mk | 1 +
Documentation/index.rst | 2 +-
Documentation/intro/install/bpf.rst | 142 ++++++++++++++++++++++++++++++++++
Documentation/intro/install/index.rst | 1 +
Makefile.am | 11 ++-
acinclude.m4 | 39 ++++++++++
bpf/.gitignore | 4 +
configure.ac | 1 +
8 files changed, 196 insertions(+), 5 deletions(-)
create mode 100644 Documentation/intro/install/bpf.rst
create mode 100644 bpf/.gitignore

diff --git a/Documentation/automake.mk b/Documentation/automake.mk
index 2b202cb2a836..18fad0608174 100644
--- a/Documentation/automake.mk
+++ b/Documentation/automake.mk
@@ -10,6 +10,7 @@ DOC_SOURCE = \
Documentation/intro/why-ovs.rst \
Documentation/intro/install/index.rst \
Documentation/intro/install/bash-completion.rst \
+ Documentation/intro/install/bpf.rst \
Documentation/intro/install/debian.rst \
Documentation/intro/install/documentation.rst \
Documentation/intro/install/distributions.rst \
diff --git a/Documentation/index.rst b/Documentation/index.rst
index ddffa3a62d4e..05199108e05a 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -59,7 +59,7 @@ vSwitch? Start here.
:doc:`intro/install/windows` |
:doc:`intro/install/xenserver` |
:doc:`intro/install/dpdk` |
- :doc:`Installation FAQs <faq/releases>`
+ :doc:`intro/install/bpf`

- **Tutorials:** :doc:`tutorials/faucet` |
:doc:`tutorials/ovs-advanced` |
diff --git a/Documentation/intro/install/bpf.rst b/Documentation/intro/install/bpf.rst
new file mode 100644
index 000000000000..a8610c9bcd31
--- /dev/null
+++ b/Documentation/intro/install/bpf.rst
@@ -0,0 +1,142 @@
+..
+ Licensed under the Apache License, Version 2.0 (the "License"); you may
+ not use this file except in compliance with the License. You may obtain
+ a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+ License for the specific language governing permissions and limitations
+ under the License.
+
+ Convention for heading levels in Open vSwitch documentation:
+
+ ======= Heading 0 (reserved for the title in a document)
+ ------- Heading 1
+ ~~~~~~~ Heading 2
+ +++++++ Heading 3
+ ''''''' Heading 4
+
+ Avoid deeper levels because they do not render well.
+
+======================
+Open vSwitch with BPF
+======================
+
+This document describes how to build and install Open vSwitch using an BPF
+datapath.
+
+.. warning::
+ The BPF support of Open vSwitch is considered 'experimental'.
+
+Build requirements
+------------------
+
+In addition to the requirements described in :doc:`general`, building Open
+vSwitch with DPDK will require the following:
+
+- LLVM 3.7.1 or later
+
+- Clang 3.7.1 or later
+
+- iproute-dev 4.6 or later
+
+- Linux kernel 4.10 or later
+
+ The following Kconfig options must be enabled to run the BPF datapath:
+
+``_CONFIG_BPF=y``
+``_CONFIG_BPF_SYSCALL=y``
+``_CONFIG_NET_CLS_BPF=m``
+``_CONFIG_NET_ACT_BPF=m``
+
+ The following optional Kconfig options are also recommended:
+
+``_CONFIG_BPF_JIT=y``
+``_CONFIG_HAVE_BPF_JIT=y``
+
+- Linux-tools from a recent Linux kernel
+
+Installing
+----------
+
+OVS can be installed using different methods. For OVS to use BPF datapath, it
+has to be configured with BPF support (``--with-bpf``).
+
+#. Clone a recent version of Linux net-next tree::
+
+ $ git clone git://git.kernel.org/pub/scm/linux/kernel/git/davem/net-next.git
+
+#. Go into the Linux source directory and build libbpf in the tools directory::
+
+ $ cd linux/
+ $ make -C tools/lib/bpf/
+
+#. Ensure the standard OVS requirements, described in
+ :ref:`general-build-reqs`, are installed
+
+#. Bootstrap, if required, as described in :ref:`general-bootstrapping`
+
+#. Configure the package using the ``--with-bpf`` flag::
+
+ $ ./configure --with-bpf=$LINUX_TOOLS
+
+ where ``LINUX_TOOLS`` is the path to the Linux tools/ directory that was
+ compiled in step 2.
+
+ .. note::
+ While ``--with-bpf`` is required, you can pass any other configuration
+ option described in :ref:`general-configuring`.
+
+#. Build and install OVS, as described in :ref:`general-building`
+
+Additional information can be found in :doc:`general`.
+
+Setup
+-----
+
+Before running OVS, you must ensure that the BPF filesystem is available::
+
+ # mount -t bpf none /sys/fs/bpf
+ # mkdir -p /sys/fs/bpf/ovs
+
+ .. note::
+ We should get rid of this requirement on users, and just robustly ensure
+ that the filesystem is available and prepared correctly (or do so if it
+ is not).
+
+Open vSwitch should be started as described in :doc:`general`.
+
+ .. note::
+ Depending on how OVS was installed, the BPF datapath binary may or may
+ not be available. Check the logs when running OVS, if it complains about
+ not finding bpf/datapath.o, look for this file in your OVS build tree and
+ copy/symlink it across. Probably it's supposed to live in
+ /usr/share/openvswitch/bpf/datapath.o.
+
+If the linux-tools package is not installed with libbpf.so, then ensure
+that this library is available via your library path::
+
+ $ export LD_LIBRARY_PATH=${LINUX_TOOLS}/lib/bpf:$LD_LIBRARY_PATH
+
+When adding a bridge to Open vSwitch, specify the datapath type as bpf::
+
+ $ ovs-vsctl add-br br0 -- set bridge br0 datapath_type=bpf
+
+To validate that the bridge has successfully instantiated, you can use the
+ovs-bpfctl utility::
+
+ # ovs-bpfctl show
+
+Limitations
+------------
+
+- The BPF datapath is a work in progress and has a limited set of support
+ for matching and actions.
+
+Bug Reporting
+-------------
+
+Please report problems to bugs@....
diff --git a/Documentation/intro/install/index.rst b/Documentation/intro/install/index.rst
index 3193c736cf17..e063548f2bb3 100644
--- a/Documentation/intro/install/index.rst
+++ b/Documentation/intro/install/index.rst
@@ -45,6 +45,7 @@ Installation from Source
xenserver
userspace
dpdk
+ bpf

Installation from Packages
--------------------------
diff --git a/Makefile.am b/Makefile.am
index 6d39d96cb47a..21e27fa32965 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -97,6 +97,7 @@ dist_pkgdata_SCRIPTS =
dist_sbin_SCRIPTS =
dist_scripts_SCRIPTS =
dist_scripts_DATA =
+dist_bpf_DATA =
INSTALL_DATA_LOCAL =
UNINSTALL_LOCAL =
man_MANS =
@@ -115,6 +116,7 @@ sbin_SCRIPTS =
scripts_SCRIPTS =
completion_SCRIPTS =
scripts_DATA =
+bpf_DATA =
SUFFIXES =
check_DATA =
check_SCRIPTS =
@@ -128,6 +130,7 @@ endif
scriptsdir = $(pkgdatadir)/scripts
completiondir = $(sysconfdir)/bash_completion.d
pkgconfigdir = $(libdir)/pkgconfig
+bpfdir = $(pkgdatadir)/bpf

# This ensures that files added to EXTRA_DIST are always distributed,
# even if they are inside an Automake if...endif conditional block that is
@@ -226,7 +229,7 @@ config-h-check:
@cd$(srcdir); \
if test -e .git && (git --version) >/dev/null 2>&1 && \
git --no-pager grep -L '#include <config\.h>' `git ls-files | grep '\.c$$' | \
- grep -vE '^datapath|^lib/sflow|^third-party|^datapath-windows|^python'`; \
+ grep -vE '^bpf|^datapath|^lib/sflow|^third-party|^datapath-windows|^python'`; \
then \
echo "See above for list of violations of the rule that"; \
echo "every C source file must #include <config.h>."; \
@@ -247,7 +250,7 @@ printf-check:
@cd$(srcdir); \
if test -e .git && (git --version) >/dev/null 2>&1 && \
git --no-pager grep -n -E -e '%[-+ #0-9.*]*([ztj]|hh)' --and --not -e 'ovs_scan' `git ls-files | grep '\.[ch]$$' | \
- grep -vE '^datapath|^lib/sflow|^third-party'`; \
+ grep -vE '^bpf|^datapath|^lib/sflow|^third-party'`; \
then \
echo "See above for list of violations of the rule that"; \
echo "'z', 't', 'j', 'hh' printf() type modifiers are"; \
@@ -290,7 +293,7 @@ check-endian:
@iftest -e $(srcdir)/.git && (git --version) >/dev/null 2>&1 && \
(cd $(srcdir) && git --no-pager grep -l -E \
-e 'BIG_ENDIAN|LITTLE_ENDIAN' --and --not -e 'BYTE_ORDER' | \
- $(EGREP) -v '^datapath/'); \
+ $(EGREP) -v '^bpf/|^datapath/'); \
then \
echo "See above for list of files that misuse LITTLE""_ENDIAN"; \
echo "or BIG""_ENDIAN. Please use WORDS_BIGENDIAN instead."; \
@@ -315,7 +318,7 @@ thread-safety-check:
if test -e .git && (git --version) >/dev/null 2>&1 && \
grep -n -f build-aux/thread-safety-blacklist \
`git ls-files | grep '\.[ch]$$' \
- | $(EGREP) -v '^datapath|^lib/sflow|^third-party'` /dev/null \
+ | $(EGREP) -v '^bpf|^datapath|^lib/sflow|^third-party'` /dev/null \
| $(EGREP) -v ':[ ]*/?\*'; \
then \
echo "See above for list of calls to functions that are"; \
diff --git a/acinclude.m4 b/acinclude.m4
index bf790fe72d87..257de4e178a8 100644
--- a/acinclude.m4
+++ b/acinclude.m4
@@ -341,6 +341,45 @@ AC_DEFUN([OVS_CHECK_DPDK], [
AM_CONDITIONAL([DPDK_NETDEV], test "$DPDKLIB_FOUND" = true)
])

+AC_DEFUN([OVS_CHECK_BPF], [
+ AC_ARG_WITH([bpf],
+ [AC_HELP_STRING([--with-bpf=/path/to/linux/tools/],
+ [Specify the linux tools directory])],
+ [have_bpf=yes])
+
+ AC_MSG_CHECKING([whether bpf datapath is enabled])
+ if test "$have_bpf" != yes || test "$with_bpf" = no; then
+ AC_MSG_RESULT([no])
+ have_bpf=no
+ else
+ AC_MSG_RESULT([yes])
+ CFLAGS="$CFLAGS -I${with_bpf}/lib -I${with_bpf}/include/uapi"
+ LDFLAGS="$LDFLAGS -L${with_bpf}/lib/bpf"
+ AC_SEARCH_LIBS([elf_begin],[elf],[],
+ [AC_MSG_ERROR([unable to find libelf, install the dependency package])])
+
+ have_bpf=no
+ AC_COMPILE_IFELSE(
+ [AC_LANG_PROGRAM([#include <bpf/libbpf.h>],
+ [struct bpf_map;
+ struct bpf_map_def;
+ struct bpf_prog_prep_result;])],
+ [AC_COMPILE_IFELSE(
+ [AC_LANG_PROGRAM([#include <iproute2/bpf_elf.h>], [])],
+ [have_bpf=yes],
+ [AC_MSG_ERROR([unable to find iproute2 >= 4.6.0])])],
+ [unable to find libbpf])
+ fi
+
+ AM_CONDITIONAL([HAVE_BPF], [test "$have_bpf" = yes])
+ if test "$have_bpf" = yes; then
+ AC_DEFINE([HAVE_BPF], [1],
+ [Define to 1 if BPF is available.])
+ BPF_LDADD="-lbpf -lelf"
+ AC_SUBST([BPF_LDADD])
+ fi
+])
+
dnl OVS_GREP_IFELSE(FILE, REGEX, [IF-MATCH], [IF-NO-MATCH])
dnl
dnl Greps FILE for REGEX. If it matches, runs IF-MATCH, otherwise IF-NO-MATCH.
diff --git a/bpf/.gitignore b/bpf/.gitignore
new file mode 100644
index 000000000000..1a5ee8e7bc33
--- /dev/null
+++ b/bpf/.gitignore
@@ -0,0 +1,4 @@
+/Makefile
+/Makefile.in
+*.o
+/distfiles
diff --git a/configure.ac b/configure.ac
index 4d7bd8d754d0..0c2bca29969f 100644
--- a/configure.ac
+++ b/configure.ac
@@ -80,6 +80,7 @@ AC_SEARCH_LIBS([timer_create], [rt])
AC_SEARCH_LIBS([pthread_create], [pthread])
AC_FUNC_STRERROR_R

+OVS_CHECK_BPF
OVS_CHECK_ESX
OVS_CHECK_WIN64
OVS_CHECK_WIN32
--
2.7.4