From patchwork Mon Apr 1 22:46:52 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: William Tu X-Patchwork-Id: 1073465 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Authentication-Results: ozlabs.org; spf=pass (mailfrom) smtp.mailfrom=openvswitch.org (client-ip=140.211.169.12; helo=mail.linuxfoundation.org; envelope-from=ovs-dev-bounces@openvswitch.org; receiver=) Authentication-Results: ozlabs.org; dmarc=fail (p=none dis=none) header.from=gmail.com Authentication-Results: ozlabs.org; dkim=fail reason="signature verification failed" (2048-bit key; unprotected) header.d=gmail.com header.i=@gmail.com header.b="BsjVaybx"; dkim-atps=neutral Received: from mail.linuxfoundation.org (mail.linuxfoundation.org [140.211.169.12]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ozlabs.org (Postfix) with ESMTPS id 44Y6wX6CcFz9sSV for ; Tue, 2 Apr 2019 09:49:32 +1100 (AEDT) Received: from mail.linux-foundation.org (localhost [127.0.0.1]) by mail.linuxfoundation.org (Postfix) with ESMTP id BB4562286; Mon, 1 Apr 2019 22:47:38 +0000 (UTC) X-Original-To: dev@openvswitch.org Delivered-To: ovs-dev@mail.linuxfoundation.org Received: from smtp1.linuxfoundation.org (smtp1.linux-foundation.org [172.17.192.35]) by mail.linuxfoundation.org (Postfix) with ESMTPS id BE659226A for ; Mon, 1 Apr 2019 22:47:36 +0000 (UTC) X-Greylist: whitelisted by SQLgrey-1.7.6 Received: from mail-wr1-f41.google.com (mail-wr1-f41.google.com [209.85.221.41]) by smtp1.linuxfoundation.org (Postfix) with ESMTPS id E0FD27A6 for ; Mon, 1 Apr 2019 22:47:35 +0000 (UTC) Received: by mail-wr1-f41.google.com with SMTP id r4so14084999wrq.8 for ; Mon, 01 Apr 2019 15:47:35 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=from:to:subject:date:message-id:in-reply-to:references; bh=wdGFyeSqeD9atTsW0mC/VyqK8L+Z4F/d2EK9yXiOqf0=; b=BsjVaybxGq5A67deGFH4tPj2xLmsLIkMfW2KxYqPwvqJHUAYIQKK4fjgDT7aOR+2Jg EymyjotMfQAmk7FWQfju6qWY/N7OzaV48c+6w8LF8D+GVrD3SsJo+JBI8u63+FsRFsrx 1k7gQ/sOP1OdvZigXWlNDEdPyq5Kzc0LBNEFrAzZDMCBT7Y72NaY3obZB4wRYyYOy91B CcaL6e9f1nqrf+IWjEMd30kGcGjZB/RlDPRARm7im2pgw1ZIWgh+5u4YzOEsbtVcEbvO PIl9R4heHPGJeg0lYr5zDIBStyk3Y3J0ALFBF5JbMwtWdkKqK33Vv9WdXICJQ+IUp3Bj O8bg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:subject:date:message-id:in-reply-to :references; bh=wdGFyeSqeD9atTsW0mC/VyqK8L+Z4F/d2EK9yXiOqf0=; b=O1rZ9WgQ+l6whbtlyOEwaWZnJBWFlZY8nSayHWTbi7oT+Brzhx5LmKbxIzs1TEnw8U oTgYx6bhz1SScrGL8QrDrldx0sq+81H1iJ0UlIImkQL9nYRA9+ITY3wwAAxhO8tUlyiZ T/bjX5RE9Ce/qnctw4eAbbajQR+e3xSVUlabc0MuTcy0sJfPuEA57q+8nh0gpuwxkXd9 fAczXjLyCEzuoZZkPLqNhmCOvmCFf5hjX4BCC9PXPlmfroZaDRUQ//ZhtwAOEDsOTwtu VMUn4Q69wuGLJkyPbErsNuMBUuP2l3RRbMqg2JAfOsFGDwymVl8JwR3wVDKcGnoDFVB4 WGDg== X-Gm-Message-State: APjAAAXP0qXcvXqLQiUVFhLOmcHGxs9ItCyWSkVoqCchlr0duBVY368K Ty4R7CAYJUY+WZ9mg8bMjsD+Zd7A X-Google-Smtp-Source: APXvYqx7fIH2+pgwzkNmeiDo6Mp02vLRSlweA5An15bJBJLHnZmDcNxcxFuiAn2DEb3oVGl8INZO1w== X-Received: by 2002:a5d:63c5:: with SMTP id c5mr42613869wrw.82.1554158854326; Mon, 01 Apr 2019 15:47:34 -0700 (PDT) Received: from sc9-mailhost2.vmware.com ([66.170.99.2]) by smtp.gmail.com with ESMTPSA id w9sm27720055wmi.0.2019.04.01.15.47.32 (version=TLS1_2 cipher=ECDHE-RSA-AES128-SHA bits=128/128); Mon, 01 Apr 2019 15:47:33 -0700 (PDT) From: William Tu To: dev@openvswitch.org, trozet@redhat.com, bmcfall@redhat.com, echaudro@redhat.com, magnus.karlsson@gmail.com, bjorn.topel@gmail.com, tuc@vmware.com Date: Mon, 1 Apr 2019 15:46:52 -0700 Message-Id: <1554158812-44622-5-git-send-email-u9012063@gmail.com> X-Mailer: git-send-email 2.7.4 In-Reply-To: <1554158812-44622-1-git-send-email-u9012063@gmail.com> References: <1554158812-44622-1-git-send-email-u9012063@gmail.com> X-Spam-Status: No, score=-1.7 required=5.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID,DKIM_VALID_AU,FREEMAIL_ENVFROM_END_DIGIT,FREEMAIL_FROM, RCVD_IN_DNSWL_NONE autolearn=no version=3.3.1 X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on smtp1.linux-foundation.org Subject: [ovs-dev] [PATCH RFCv4 4/4] afxdp netdev: add documentation and configuration. X-BeenThere: ovs-dev@openvswitch.org X-Mailman-Version: 2.1.12 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , MIME-Version: 1.0 Sender: ovs-dev-bounces@openvswitch.org Errors-To: ovs-dev-bounces@openvswitch.org The patch add bpf installation guide and configuration for linking to libbpf library. Signed-off-by: William Tu --- 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 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 ` - **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//:: + + # 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 --------------------------