@@ -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 \
@@ -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` |
new file mode 100644
@@ -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.
@@ -45,6 +45,7 @@ Installation from Source
xenserver
userspace
dpdk
+ bpf
Installation from Packages
--------------------------
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