[ovs-dev,RFCv4,4/4] afxdp netdev: add documentation and configuration.

Message ID 1554158812-44622-5-git-send-email-u9012063@gmail.com
State New
Headers show
Series
  • AF_XDP netdev support for OVS
Related show

Commit Message

William Tu April 1, 2019, 10:46 p.m.
The patch add bpf installation guide and configuration
for linking to libbpf library.

Signed-off-by: William Tu <u9012063@gmail.com>
---
 Documentation/automake.mk             |   1 +
 Documentation/index.rst               |   1 +
 Documentation/intro/install/bpf.rst   | 182 ++++++++++++++++++++++++++++++++++
 Documentation/intro/install/index.rst |   1 +
 4 files changed, 185 insertions(+)
 create mode 100644 Documentation/intro/install/bpf.rst

Patch

diff --git a/Documentation/automake.mk b/Documentation/automake.mk
index 082438e09a33..72c58002a234 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 46261235c732..72b1eda80aae 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -59,6 +59,7 @@  vSwitch? Start here.
   :doc:`intro/install/windows` |
   :doc:`intro/install/xenserver` |
   :doc:`intro/install/dpdk` |
+  :doc:`intro/install/bpf` |
   :doc:`Installation FAQs <faq/releases>`
 
 - **Tutorials:** :doc:`tutorials/faucet` |
diff --git a/Documentation/intro/install/bpf.rst b/Documentation/intro/install/bpf.rst
new file mode 100644
index 000000000000..5f38db368c27
--- /dev/null
+++ b/Documentation/intro/install/bpf.rst
@@ -0,0 +1,182 @@ 
+..
+      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/XDP/AF_XDP
+================================
+
+This document describes how to build and install Open vSwitch using an BPF
+datapath.
+
+.. warning::
+  The AF_XDP support of Open vSwitch is considered 'experimental'.
+
+Build requirements
+------------------
+
+In addition to the requirements described in :doc:`general`, building Open
+vSwitch with AF_XDP will require the following:
+
+- Latest libbpf from kernel source tree (kernel 5.0.0 or later)
+
+- Linux kernel 4.19 or later
+
+  The following Kconfig options must be enabled to run the AF_XDP netdev:
+
+``_CONFIG_BPF=y``
+``_CONFIG_BPF_SYSCALL=y``
+``_CONFIG_XDP_SOCKETS=y``
+
+  The following optional Kconfig options are also recommended:
+
+``_CONFIG_BPF_JIT=y``
+``_CONFIG_HAVE_BPF_JIT=y``
+``_CONFIG_XDP_SOCKETS_DIAG=y``
+
+- Linux-tools from a recent Linux kernel
+
+Installing
+----------
+
+OVS can be installed using different methods. For OVS to use AF_XDP netdev, it
+has to be configured with LIBBPF support.
+
+#. Clone a recent version of Linux bpf-next tree::
+
+   $ git clone git://git.kernel.org/pub/scm/linux/kernel/git/bpf/bpf-next.git
+
+#. Go into the Linux source directory and build libbpf in the tools directory::
+
+    $ cd bpf-next/
+    $ make -C tools/lib/bpf/
+    $ cd tools/lib/bpf/
+    $ make install
+
+#. 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::
+
+       $ ./configure
+
+   where ``LINUX_TOOLS`` is the path to the Linux tools/ directory that was
+   compiled in step 2.
+
+   .. note::
+     Make sure the ldconfig is properly set-up to point to the libbpf.so
+
+#. Build and install OVS, as described in :ref:`general-building`
+
+Additional information can be found in :doc:`general`.
+
+Setup
+-----
+
+Before running OVS with AF_XDP, make sure the libbpf and libelf are set-up right::
+
+    # ldd vswitchd/ovs-vswitchd
+
+   .. note::
+     For example, you should see:
+     libbpf.so => /lib/x86_64-linux-gnu/libbpf.so (0x00007eff2fc0a000)
+     libelf.so.1 => /usr/lib/x86_64-linux-gnu/libelf.so.1 (0x00007eff2f9f2000)
+
+Open vSwitch should be started using userspace datapath as described in :doc:`general`::
+
+    # ovs-vswitchd --disable-system
+    # ovs-vsctl -- add-br br0 -- set Bridge br0 datapath_type=netdev
+
+   .. note::
+     OVS AF_XDP netdev is using the userspace datapath, the same datapath
+     as used by OVS-DPDK.  So it requires --disable-system for ovs-vswitchd
+     and datapath_type=netdev when adding a new bridge.
+
+When adding a AF_XDP netdev port to the bridge, specify the netdev type as afxdp::
+
+    # using namespace and veth peer as an example
+    # ip link add p0 type veth peer name afxdp-p0
+    # ip link set p0 netns at_ns0
+    # ip link set dev afxdp-p0 up
+    # ovs-vsctl add-port br0 afxdp-p0 -- \
+                set interface afxdp-p0 external-ids:iface-id="p0" type="afxdp"
+
+To validate that the bridge has successfully instantiated, you can use the
+ovs-vsctl utility::
+
+    # ovs-vsctl show
+
+Or enable afxdp debugging by::
+
+    # ovs-appctl vlog/set netdev_afxdp::dbg
+
+An end-to-end AF_XDP netdev test can be started by running, with failed test
+results saved at tests/system-afxdp-testsuite.dir/<test number>/::
+
+    # make check-afxdp
+    # cat tests/system-afxdp-testsuite.dir/06/system-afxdp-testsuite.log
+
+Example Script
+--------------
+
+Below is a script using namespaces and veth peer::
+
+    #!/bin/bash
+    # ovs-vswitchd --no-chdir --pidfile -vvconn -vofproto_dpif -vunixctl --disable-system --detach
+    # ovs-vsctl -- add-br br0 -- set Bridge br0 \
+    # protocols=OpenFlow10,OpenFlow11,OpenFlow12,OpenFlow13,OpenFlow14,OpenFlow15 \
+    # fail-mode=secure datapath_type=netdev
+    # ovs-vsctl -- add-br br0 -- set Bridge br0 datapath_type=netdev
+
+    # ip netns add at_ns0
+    # ovs-appctl vlog/set netdev_afxdp::dbg
+
+    # ip link add p0 type veth peer name afxdp-p0
+    # ip link set p0 netns at_ns0
+    # ip link set dev afxdp-p0 up
+    # ovs-vsctl add-port br0 afxdp-p0 -- \
+    #  set interface afxdp-p0 external-ids:iface-id="p0" type="afxdp"
+
+    # ip netns exec at_ns0 sh << NS_EXEC_HEREDOC
+    # ip addr add "10.1.1.1/24" dev p0
+    # ip link set dev p0 up
+    # NS_EXEC_HEREDOC
+
+    # ip netns add at_ns1
+    # ip link add p1 type veth peer name afxdp-p1
+    # ip link set p1 netns at_ns1
+    # ip link set dev afxdp-p1 up
+    # ovs-vsctl add-port br0 afxdp-p1 -- \
+    #    set interface afxdp-p1 external-ids:iface-id="p1" type="afxdp"
+    # ip netns exec at_ns1 sh << NS_EXEC_HEREDOC
+    # ip addr add "10.1.1.2/24" dev p1
+    # ip link set dev p1 up
+    # NS_EXEC_HEREDOC
+
+    # ip netns exec at_ns0 ping -i .2 10.1.1.2
+
+Bug Reporting
+-------------
+
+Please report problems to bugs@openvswitch.org.
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
 --------------------------